VOXEL_ENGINE.md
6233 bytes · Original / download
Voxel engine
The 3D overworld ("diorama") is drawn from the live GBA map state: the game still runs its
2D field logic, and src/platform/voxel/ turns the current map and its neighbours into 3D
geometry every frame. The logic comes from pokeemerald-multiplatform's voxel renderer and
Emerald 3DS (see NOTICE.md); the GPU code is written for vitaGL.
Modules
| File | Role |
|---|---|
voxel_world.c/h |
Logical map view: map instances (current map + connected maps) with their offsets, layout swaps, tile/metatile queries. VoxelWorld_IsMapAvailable decides when the 3D path runs |
voxel_camera.c/h |
Follow camera, pure state and math (no GL). Shift on map changes |
voxel_atlas.c/h |
Metatile atlas: composes GBA tiles into texture pages; tracks animated metatiles per page |
voxel_mesh_builder.c/h |
CPU geometry for one chunk: ground rows, cliffs, seam skirts, water |
voxel_relief.c/h |
Terrain relief read from relief.bin: cliffs, stairs, sea rocks |
voxel_regions.c/h |
Precomputed role of each cell (4 bits per cell), from regions.bin |
voxel_building.c/h |
Buildings modelled from their own drawing (buildings.bin), with a texture page LRU |
voxel_tree.c/h |
General-tileset trees: trunk on the ground, cutout crown (trees.rgba5551) |
voxel_sign.c/h |
Signposts and street lamps with pixel-masked geometry (signposts.bin) |
voxel_lighting.c/h |
Sun from the in-game clock, baked into vertex colours; cast shadows; face shading |
voxel_grade.c/h |
Colour grade (slightly more saturated GBA art) |
voxel_entities.c/h |
Player, NPC and follower billboards from the entity snapshot; cast shadows |
voxel_sprite_slots.c/h |
Slots of the sprite atlas used by the billboards |
voxel_battle.c/h |
The 3D battle stage built from the map the battle started on |
voxel_swoop.c/h |
The transition between the voxel field and 2D screens |
voxel_arena.c/h |
Fixed memory blocks claimed once (no fragmentation) |
3ds_field_view.c/h |
The part of the overworld shown, in metatiles, for map objects |
voxel_tuning.h |
Tuning values: chunk area, build budgets, pacing, atmosphere, DoF |
voxel_renderer.c/h |
Everything GPU-side: chunk cache, I/O worker, atlas upload, passes, weather, DoF, overlay. See RENDERING.md |
3ds_*.h, port_*.h, voxel_file.h, voxel_unswizzle.h |
Compatibility shims kept from the 3DS code (logging, platform, file access, Morton unswizzle for 3DS-format pages) |
Chunks
- The world is split into chunks of
CHUNK_SIZE= 8×8 metatiles. Up toMAX_CHUNKS= 64 chunk slots are cached, each with its own GL vertex buffer; the geometry lives only there. - A build has three phases:
PrepareChunkJob(Core 0: the chunk's window and the atlas slot of every map it touches),ComputeChunkJob(geometry and lighting intosChunkStaging, no GL) andCommitChunkJob(Core 0: building pages, slot, VBO upload). - Per frame: frustum-cull candidate chunks (widened by how far each chunk's buildings reach)
and draw the built ones. Visible holes are built on
Core 0; every other build (chunks about to enter the view, dated chunks, pre-warming ahead of
the movement) goes to
VoxelChunkWorkeron Core 2, one per frame. See RENDERING.md for the policy and THREADS.md for the worker. - A chunk is rebuilt when its content hash changes (scripts changing tiles, doors, the sun
moving). The hash is compared once per world epoch (
sWorldEpoch, bumped on those changes), so chunks off screen at the time are checked when they come back into view. - Chunks used in the current or previous frame are never evicted.
- Lighting is most of a build (rays and contact AO); a chunk costs ~6 ms on average and up to ~35 ms on mountains (logs/sesion 27).
Atlas
- Metatile pages are composed by
VoxelAtlas_JobStepintoVOXEL_ATLAS_SLOTS= 5 LRU slots, so neighbouring maps with other tilesets keep their textures. A slot used by a chunk on screen is marked used every frame, so the LRU never recomposes it for another tileset while visible. - When the current map changes during play (a crossing), its slot is extended over several frames
(
AtlasExtend_*, 1.5 ms a frame): the slot keeps serving meanwhile, since an extension keeps every metatile where it was, and its tile animation waits until the end. Warps extend at once. - Animated tiles (water, flowers, shores) are re-read from BG VRAM and only the dirty rows of the active slot are uploaded, through a spare texture per page (RENDERING.md, "Textures rewritten at run time"). Other slots must not be refreshed from VRAM: VRAM holds only the current map's tileset (refreshing them corrupted neighbouring terrain).
Map changes
Crossing into a connected map: Core 1 rebuilds the layout under sMapMutationLock; Core 0
keeps drawing the previous instances and snapshot, then VoxelCamera_Shift re-bases the camera
and VoxelWorld_GetInstanceOffset aligns entities that are still in the old map's
coordinates. Cached chunks are not rebuilt nor re-uploaded: ShiftChunkCoordinates moves their
grid position and their drawOffsetX/Z, a translation applied when they are drawn. Chunk
geometry lives only in the VBOs; a single staging buffer (sChunkStaging) holds the chunk being
built. NPCs of connected maps are spawned ahead of the border
(event_object_movement.c, TrySpawnObjectEvents). See THREADS.md.
Data files
All under assets/voxel/, packed into the VPK as app0:voxel/. Their generators are not in
this repository; see ASSETS.md.
Tuning values
Everything that changes how the 3D world looks or how its work is paced is in
src/platform/voxel/voxel_tuning.h: the chunk area around
the camera, build budgets and pre-warming, the chunk worker switch, atlas and texture pacing,
colour grade and haze, fog, weather, motes and the depth-of-field bands. Capacities that size
buffers (chunk vertex caps, slot counts, FBO sizes) stay next to their structures in
voxel_renderer.c, and structured data (weather kinds, fog banks, light tables) stays with the
code that reads it.