GitHub Vita Lite - Wolff's Store
Code / README | Releases | Issues
WolffsRoom/DeltaruneVita / docs

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/vita-probe/ — ponte com o hardware do Vita

Alvo de build ativo (CMakeLists.txt, target PLAYABLE_RUNNER, ligado por padrão).

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)

  1. Lê a instalação Steam/Windows legítima em SteamFiles/DELTARUNE.
  2. Copia o data.win de cada capítulo (sem rename).
  3. Reestrutura o diretório de áudio (streaming via OpenAL a partir do ux0:).
  4. 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)

  1. Roda um container Docker com a imagem atamanenko/vitasdk-softfp (VitaSDK pré-instalado).
  2. Compila third_party/vitaGL-nosplash (libvitaGL.a).
  3. Roda CMake + arm-vita-eabi toolchain sobre src/vita-probe (que também compila o Butterscotch via file(GLOB ...)).
  4. Linka estaticamente contra as libs oficiais da Sony (libSceGxm, libSceDisplay, libSceCtrl, etc).
  5. vita-elf-create converte o .elf para .velf; vita-make-fself assina/empacota como eboot.bin.
  6. vita-pack-vpk junta eboot.bin, param.sfo, dados e ícones da LiveArea em artifacts/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:

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:

  1. reconhecer exatamente a revisão de entrada (tamanho e fingerprint);
  2. aplicar somente uma transformação pequena e previamente validada pelo projeto;
  3. trabalhar em arquivo temporário, validar o resultado e fazer a troca atômica;
  4. preservar o original para recuperação se houver falta de espaço, desligamento ou incompatibilidade;
  5. nunca incluir um data.win comercial 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)

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/)

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:

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.