GitHub Vita Lite - Wolff's Store
Code / README | Releases | Issues
WolffsRoom/pokeemerald-vita-3ds / docs

ARCHITECTURE.md

6985 bytes · Original / download

Architecture

How the port is put together and what happens in one frame. Thread rules are in THREADS.md, the GPU passes in RENDERING.md.

Layers

┌────────────────────────────────────────────────────────────────────────────┐
│ Game: pret/pokeemerald decompilation                                       │
│   src/*.c, include/, data/, sound/, asm/, graphics/                        │
│   Compiled with -DPORTABLE -DNONMATCHING -DMODERN=1 -DUBFIX -DPLATFORM_VITA│
│   ~17 game files carry small Vita hooks under #ifdef                       │
├────────────────────────────────────────────────────────────────────────────┤
│ GBA hardware emulation             src/platform/                           │
│   sdl2.c          main(), threads, 60 Hz clock, saves, config, RTC         │
│   gba_fast_draw*.c software GBA PPU (scanline renderer, 3 cores, NEON)     │
│   widescreen.c    288-px lines: what fills the margins in each scene       │
│   bios.c dma.c cgb_audio.c mods/mod_manager.c                              │
├─────────────────────────────────────┬──────────────────────────────────────┤
│ Voxel 3D world   src/platform/voxel │ Vita features      src/platform/vita │
│   world, chunks, meshes, atlas,     │   controls, intro stage, day/night,  │
│   buildings, trees, relief, signs,  │   extras, Nuzlocke, telemetry;       │
│   lighting, weather, entities,      │   the UI itself: src/platform/ui     │
│   3D battle, depth of field         │                                      │
│                                     │                                      │
├─────────────────────────────────────┴──────────────────────────────────────┤
│ VitaSDK 2026.08 · vitaGL · SDL2 (audio device, threads, timers)            │
└────────────────────────────────────────────────────────────────────────────┘

The game never talks to the Vita directly. It writes emulated GBA registers, VRAM, OAM and palettes in RAM; the platform layer reads them back to draw, and supplies the services the GBA hardware did (VBlank, DMA, timers, sound mixing, flash saves, the real-time clock).

Boot

main() in src/platform/sdl2.c:

  1. Pins itself to Core 0 (VitaPlatform_PinCurrentThread), creates ux0:data/POKEVITA/, sets the clocks (vita_platform.c: CPU 444, bus 222, GPU 222, GPU crossbar 166 MHz).
  2. Initialises vitaGL with vglInitWithCustomSizes (8 MB GXM pool, 40 MB RAM, 88 MB CDRAM, 8 MB physically contiguous) at 960×544.
  3. Reads pokeemerald.cfg and settings.txt, opens the save, starts audio (48 kHz stereo).
  4. VoxelRenderer_Init() and Ui_Init() decode the heavy assets once.
  5. Starts the AgbMain thread (4 MB stack, Core 1), which runs the original game loop.
  6. Enters the presentation loop.

One frame

Core 1 (AgbMain)                      Core 0 (MainThread)                 Core 2
────────────────                      ───────────────────                 ──────
game logic for one GBA frame
Ui_Tick(): new UI draw list
VBlankIntrWait():
  VBlank handler, m4a mixer → audio
  publish entity snapshot
  post sFrameReadySem  ──────────────► wait for it (one post at 60 FPS,
  pace to 60.00 Hz on the                two at 30 FPS in 3D)
  audio buffer                         read input
                                       choose a path:
                                        · 3D field / battle →
                                          VoxelRenderer_RenderFrame()   ◄─ chunk computed since
                                        · else → VDraw() +                 the last swap
                                          RenderGameTexture()              (VoxelChunkWorker)
                                       Ui_Render(): the new UI on top
                                       vglSwapBuffers(), then hand the  ─► next chunk
                                       next chunk to the worker            DrawWorker1/2: GBA
                                                                           scanlines (2D and
                                                                           the overlay)

The 3D world renders at 30 FPS by default (voxelFps; 60 FPS is an option), the game logic and audio always at 60 Hz, and every rendered frame shows the latest game frame. Which path is taken is decided in sdl2.c from VoxelWorld_IsMapAvailable() (field callbacks, shop buy menu) and VoxelWorld_IsBattleMapAvailable() (BattleMainCB2).

Where to find things

Topic Code Document
Thread ownership, snapshot, map lock voxel_entities.c, overworld.c, sdl2.c THREADS.md
vitaGL passes, DoF, 2D overlay voxel/voxel_renderer.c RENDERING.md
16:9 handling of GBA screens widescreen.c, src/platform/vita/vita_stage.c SCENES_16_9.md
Voxel world src/platform/voxel/ VOXEL_ENGINE.md
User interface src/platform/ui/ VITA_UI.md
Build and packaging CMakeLists.txt, build_vita.*, vita/ BUILD.md
Data files assets/, tools/ui2/, tools/ui_gen/gen_intro_margins.py ASSETS.md
Logs, telemetry, crash dumps src/platform/vita/vita_perf.c, src/platform/vita/vita_platform.c DEBUGGING.md

Runtime files (ux0:data/POKEVITA/)

File Written by Content
saves/pokeemerald*.sav sdl2.c Saves, 128 KB GBA flash layout; slot 1–3
pokeemerald.cfg sdl2.c StoreConfigFile Platform settings (filter, widescreen, buttons, 3D on/off, FPS cap…)
settings.txt src/platform/vita/vita_extras.c QoL extras and voxel options (VitaExtras_GetFast)
debug.log VITA_LOG Boot and error log
perf_summary.txt, perf_frames.csv src/platform/vita/vita_perf.c Per-frame telemetry
ui_stall.log src/platform/ui/ui_stall.c New UI stalls over 100 ms, and which core held the frame