arquitetura.md
16588 bytes · Original / download
Arquitetura
Estado atual: retomada da v0.74-5 solicitada pelo usuario. A reinicializacao apos a introducao documentada abaixo foi removida. Heap e boot voltaram a base; detalhes em retomada da v0.74-5.
v0.74-10: boot Modern-GL após introdução usa restart_into_chapter(0), isolando o contexto AvPlayer/VitaGL do contexto gráfico do menu. A reentrada explícita impede loop. Motivo e limites.
Visão dos componentes do DeltaruneVita e como eles se encaixam. Para o histórico narrativo do desenvolvimento (o que foi tentado, o que falhou, o que funcionou), veja PROGRESS.md.
Visão geral do pipeline
Arquivos oficiais Steam/PC (data.win por capítulo)
↓ scripts/prepare-windows-data.ps1
data/prepared/deltarune/deltarunevita/ (data.win por capítulo + áudio)
↓ scripts/build-butterscotch-probe.ps1 (Docker + VitaSDK)
Butterscotch (VM GameMaker) + VitaGL + OpenAL + controles do Vita
↓ vita-elf-create + vita-make-fself + vita-pack-vpk
Deltarune.vpk (eboot.bin + param.sfo + dados)
Não há dependência de APK Android nem de emulação — os dados são lidos diretamente do formato
Windows/Steam (data.win), copiado como data.win por capítulo durante a preparação (sem rename).
Desde a otimização de textura (v0.65+), há um sub-pipeline opcional de pré-processamento de atlas
antes do empacotamento: scripts/preprocess_data.py (invoca src/ButterscotchPreprocessor-main,
Kotlin, para gerar atlas 2048×2048 em data/preprocessed/) → scripts/build-2048-pvr-cache.ps1
(usa PVRTexToolCLI para comprimir os atlas em .pvr, saída em data/pvr/) →
scripts/validate-pvr-assets.ps1 (valida os .pvr gerados). Esse pipeline é o que alimenta o
cache de textura RGBA4444/atlas grande descrito acima, na seção "Gestão de memória e cache de
texturas".
Componentes principais
src/butterscotch/ — motor GameMaker (fork vendored)
Fork local de ButterscotchRunner/Butterscotch, uma reimplementação open source do runner de bytecode do GameMaker: Studio (compatível com WADs versão 8–17, base Undertale v1.08 / GMS 1.4.1804), estendida e corrigida para rodar Deltarune no Vita.
src/data_win.c— leitor de chunks dodata.win.src/vm.c,src/vm_builtins.c— VM de bytecode e funções builtin do GML (arquivo mais extenso do projeto; é onde builtins faltantes são implementados conforme aparecem nos logs).src/runner.c— loop principal do jogo (step/draw, eventos).src/instance.c,src/spatial_grid.c,src/event_table.c,src/collision.h— instâncias de objetos, colisão e agendamento de eventos.src/gl_common/,src/gl_legacy/— backends de renderização.gl_legacy_renderer.cé o renderer usado no Vita (ver seção VitaRenderer abaixo).src/audio/openal/— backend de áudio via OpenAL (usado pelovita-probe).vendor/— bibliotecas de terceiros vendored (bzip2, md5, sha1, base64, stb, miniaudio, mojoal).- Sem subpasta dedicada para Vita — a integração específica de plataforma vive em
src/vita-probe/.
src/vita-probe/ — ponte com o hardware do Vita
Alvo de build ativo (CMakeLists.txt, target PLAYABLE_RUNNER, ligado por padrão).
source/playable_main.c— entrada principal; inicialização do VitaGL, ajuste de RAM, cache de texturas, tratamento de NPOT, integração com o loop do Butterscotch.source/vita_settings.c/.h— menu de configurações in-game (vídeo, áudio, controles, PT-BR/EN).source/vita_video.c/.h— inicialização de vídeo/resolução (vglInitExtended).source/vita_borders.c/.h— bordas/overlay do console por capítulo e área.source/vitagl_probe.c— alvo de build separado (VITAGL_PROBE, opcional) para diagnóstico isolado do VitaGL, sem o runner completo.source/main.c— terceiro alvo, parser mínimo dedata.wincomdebugScreen.c, sem runner.
O CMake usa file(GLOB ...) para juntar as fontes do Butterscotch (../butterscotch/src/*.c,
gl_common, gl_legacy, image, audio/openal) com as fontes do vita-probe e libs vendored
(bzip2, md5, sha1, base64), linkando estaticamente contra libvitaGL.a e as stubs oficiais da Sony
(SceGxm, SceCtrl, SceDisplay, SceAudio, etc.) e kubridge.
Detalhes fixos de build atuais (src/vita-probe/CMakeLists.txt):
- TITLE ID: DELT00001
- param.sfo: ATTRIBUTE2=12 (necessário para o VPK final funcionar corretamente)
- Versão-base: config/version.txt. scripts/build-butterscotch-probe.ps1 calcula o número interno do build, injeta PORT_BUILD_VERSION e o CMake deriva a versão do pacote da mesma fonte. Ver também
vita_create_vpk do CMake — mantenha os dois sincronizados ao lançar uma versão.
VitaRenderer — decisão arquitetural chave
O renderer legado original do Butterscotch usava modo imediato do OpenGL (glBegin/glEnd), o que
gera um comando por sprite. O Parameter Buffer do Vita é limitado, e salas cheias de objetos (ex.:
áreas com muitas árvores) estouravam esse buffer e faziam objetos sumirem.
Solução: batching de vértices/índices com buffers pré-alocados e glDrawElements/glDrawArrays
em vez de chamadas imediatas por primitiva. Sprites e retângulos foram migrados primeiro; depois
fontes, tiles, linhas, triângulos e blits de surfaces. Essa migração foi o ponto decisivo que permitiu
o seletor de capítulos rodar em hardware real (v00.17).
// Buffer de índices pré-alocado, usado para descarregar milhares de sprites de uma vez na GPU
static uint16_t vitaIndices[65536];
glDrawElements(GL_TRIANGLES, vitaIndexCount, GL_UNSIGNED_SHORT, vitaIndices);
Gestão de memória e cache de texturas
Texturas 2048×2048 vindas do PC enchem a VRAM do Vita rapidamente. Existe um cache com limite
dinâmico que monitora o uso e despeja páginas de textura antigas quando o limite é atingido
(vitaEvictTexturePage()). O limite global atual do cache de texturas é 192 MiB.
O pool gráfico do VitaGL foi ajustado ao longo do projeto (começou maior, foi reduzido para liberar RAM para o próprio Deltarune) e a stack principal foi aumentada para 4 MiB (o padrão de 256 KiB não era suficiente durante a preparação de shaders).
Suporte a mods e NPOT
Mods (ex.: tradução PT-BR, gerados com UndertaleModTool) costumam ter texturas NPOT (Non-Power-Of-Two,
ex.: 2000×2000). O hardware do Vita não suporta GL_REPEAT para texturas NPOT — a textura fica
invisível. A correção detecta se a textura é POT e força GL_CLAMP_TO_EDGE quando não é:
bool is_pot = ((w & (w - 1)) == 0) && ((h & (h - 1)) == 0);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, is_pot ? GL_REPEAT : GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, is_pot ? GL_REPEAT : GL_CLAMP_TO_EDGE);
Troca de capítulos
O seletor usa a função game_change do GameMaker. O Butterscotch registra a solicitação, mas quem
trata a troca é o main do vita-probe: ele grava o capítulo solicitado, reinicia o próprio
eboot e abre diretamente o data.win correspondente. O reinício libera os recursos do seletor
antes de carregar capítulos que passam de 200 MB — isso evita fragmentação/uso excessivo de memória
que ocorreria tentando trocar de capítulo sem reiniciar o processo.
Convenção de nome de arquivo: data.win (sem rename para game.droid)
Até a v0.63, o pipeline renomeava data.win para game.droid em cada capítulo (herança da época em
que o projeto ainda mirava o formato usado pelo port Android/APK). Essa renomeação foi removida: o
engine (playable_main.c, main.c, vitagl_probe.c) agora procura chapterN/data.win diretamente,
tanto para o carregamento normal do capítulo quanto para o override de mod
(mods/<nome>/chapterN/data.win). Os scripts de preparação (prepare-windows-data.ps1,
prepare-vita-mods.ps1) e os patchers (desktop e web) foram atualizados para copiar/extrair os
arquivos como data.win, sem nenhum passo de rename. Isso simplifica o pipeline de mods: o
conteúdo de um .zip de tradução pode ser extraído sem transformação antes de cair em
deltarunevita/mods/<nome>/.
third_party/vitaGL-nosplash/
Fork vendored de Rinnegatamante/vitaGL (variante
"no splash"), com libvitaGL.a pré-compilado no repositório. Não é um git submodule — é código
vendored com .git próprio. Compilado via Makefile próprio (NO_SPLASHSCREEN=1 NO_DEBUG=1
SOFTFP_ABI=1) como etapa do build Docker.
Pipeline de dados
scripts/prepare-windows-data.ps1 (atual)
- Lê a instalação Steam/Windows legítima em
SteamFiles/DELTARUNE. - Copia o
data.winde cada capítulo (sem rename). - Reestrutura o diretório de áudio (streaming via OpenAL a partir do
ux0:). - Gera a saída em
data/prepared/deltarune/deltarunevita/.
Não popula mods/ — mods de idioma (ex.: PT-BR) não fazem parte do preparo de dados padrão; são
baixados sob demanda pelo usuário através dos patchers (ver api.md).
scripts/prepare-vita-mods.ps1
Empacota mods (ex.: tradução PT-BR de Teiarruma/deltarune-ptbr)
a partir de mods/PTBR, copiando data.win por capítulo sem rename. Uso opcional, para
desenvolvimento/teste local de um mod sem depender do download automático do patcher.
scripts/build-butterscotch-probe.ps1 (build atual)
- Roda um container Docker com a imagem
atamanenko/vitasdk-softfp(VitaSDK pré-instalado). - Compila
third_party/vitaGL-nosplash(libvitaGL.a). - Roda CMake +
arm-vita-eabitoolchain sobresrc/vita-probe(que também compila o Butterscotch viafile(GLOB ...)). - Linka estaticamente contra as libs oficiais da Sony (
libSceGxm,libSceDisplay,libSceCtrl, etc). vita-elf-createconverte o.elfpara.velf;vita-make-fselfassina/empacota comoeboot.bin.vita-pack-vpkjuntaeboot.bin,param.sfo, dados e ícones da LiveArea emartifacts/current/Deltarune-v<versão>.vpk.
O build de VitaSDK roda a imagem Docker diretamente via docker run dentro do script PowerShell.
Os antigos stubs genéricos Dockerfile/compose*.yaml, que não participavam desse pipeline,
foram removidos na organização da v0.78.
Atualizações de arquivos do jogo pelo Runner
O overlay de carregamento reserva três estados distintos:
LOADING / textures: leitura de caches já preparados;GENERATING / textures: criação local de RGBA4444 ou BC3 ausente;UPDATING / game files: aplicação futura de uma migração versionada nos dados do jogo.
O terceiro estado não autoriza uma reconstrução genérica de data.win no Vita. O Runner possui um
parser, mas não contém o compilador GML, o empacotador de atlas nem o serializador completo usados
pelo UndertaleModTool/DeltaBuilder. Portanto, uma atualização embarcada deve seguir este contrato:
- reconhecer exatamente a revisão de entrada (tamanho e fingerprint);
- aplicar somente uma transformação pequena e previamente validada pelo projeto;
- trabalhar em arquivo temporário, validar o resultado e fazer a troca atômica;
- preservar o original para recuperação se houver falta de espaço, desligamento ou incompatibilidade;
- nunca incluir um
data.wincomercial completo no VPK.
Correções que podem ser expressas no próprio Runner devem continuar como ajustes em memória, sem
reescrever o arquivo do usuário. Repacking de atlas, injeção de sprites e recompilação de GML
continuam no DeltaBuilder/Patcher de PC. A tela UPDATING / game files só deve aparecer quando uma
migração compatível realmente existir e estiver sendo aplicada.
Código legado (não usado no build ativo)
src/legacy/soloader/— abordagem anterior via SoLoader (wrapper de.soAndroid). Ainda referenciado porscripts/build-deltarune.ps1, que está desatualizado/não é o pipeline atual.src/legacy/yoyoloader/— abordagem ainda mais antiga via YoYo Loader (launcher/patcher de APK). Não referenciado por nenhum script de build atual.config/yyl.cfg— configuração residual do YoYo Loader, obsoleta.tools/yoyoloader-builder/— ferramentas de empacotamento VPK da era YoYo Loader, git-ignorado, mantido apenas por arqueologia.
Esses caminhos existem por motivos históricos (ver PROGRESS.md) e não devem ser usados como referência para novo trabalho, exceto se o objetivo for entender por que a abordagem foi abandonada.
Ferramentas auxiliares (tools/)
UndertaleModTool/,UndertaleModToolCLI/— GUI e CLI headless do UndertaleModTool, usadas para inspecionar/editardata.windurante investigação de bugs e preparação de mods.nxrune-analysis/— scripts de análise (ExportRoomIndex.csx) para engenharia reversa de GML.nxrune-chapter-1-5/— patches xdelta por capítulo + utilitárioxdelta.exe.vita-parse-core/— utilitário Python (elf.py,core.py) para analisarpsp2core/ELF ao investigar crashes no hardware real.
Formato dos dados no Vita
ux0:data/deltarune/
├── config.ini
├── save/
└── deltarunevita/
├── chapter0/ … chapter5/ (data.win + assets por capítulo)
├── music/
├── borders/
└── mods/
Log persistente: ux0:data/deltarune/deltarunevita/butterscotch-probe.log.
Correções Modern-GL de setembro de 2026
A build de diagnóstico 0.74-4 registra as etapas de quadros lentos no log persistente sem exigir overlay de desenvolvimento. Contadores Modern de lotes/primitivas agora refletem os envios reais; tempos CPU de buffer/submissão não devem ser confundidos com execução GPU. O diagnóstico não insere fences adicionais no renderizador.
A revisão 0.74 substitui o limite rígido do cache por um alvo de retenção e preserva salas vizinhas quando há espaço. O build VitaGL usa destinos compartilhados para superfícies de mesma dimensão até 512 pixels de largura; a troca dessa flag exige build limpo da biblioteca. Reservas internas de uniforms são verificadas antes de recorte/limpeza.
Na mesma revisão, layer_destroy passa a remover camadas do editor e suas
instâncias, além das dinâmicas. A camada é destacada do array antes de executar
Destroy/Clean Up, pois esses eventos podem alterar o próprio array. Isso permite
que as condições originais do Chapter 5 retirem decoração e colisões do festival.
Somente a cópia runtime é liberada; os dados da sala continuam disponíveis para
reentrada.
A revisão v0.73-25 documenta o ciclo de vida das superfícies no VitaGL, a restauração do framebuffer após cópia e a política de cache Modern-GL. Destinos de renderização precisam atualizar a marca de uso GPU, assim como samplers. Fontes têm prioridade sob demanda; a admissão de atlas considera RAM, PHY e CDRAM e a coleta forçada acompanha expulsões pendentes.
Arquivos temporários e de pesquisa
Investigações e arquivos intermediários não devem ser criados na raiz do projeto. O projeto reserva:
scratch/: trabalho temporário descartável, testes rápidos e arquivos que podem ser removidos sem preservação;research/: dumps, comparações, exportações e material de investigação que pode ser útil durante uma análise, mas não integra o produto final.
As duas pastas são ignoradas pelo Git. IAs e ferramentas auxiliares devem utilizá-las por padrão e mover arquivos para src/, scripts/, docs/, data/ ou outro diretório permanente somente quando o material passar a fazer parte real do projeto.
Criação e vídeo v0.74-5
Ordem de criação depth/layer: PreCreate → struct opcional → Create. Chapter 5 limita PHYCONT do VitaGL a 4 MiB para permitir buffers externos do SceAvPlayer. Ver análise.
Seguimento de memória e startup (14/09 à noite)
Chapter 5 reserva PHYCONT integralmente ao decoder (pedidos de 3+21 MiB). Startup desabilita áudio até a primeira apresentação, respeitando a preferência ao restaurar. Loading isola programa, unidades de textura e VBO. Getters de dimensões de tilemap ausente retornam -1. Evidências.