VOXEL_ENGINE.md
6709 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, tall grass, ash grass & flowers (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 (GBA / HD-2D) and CPU-baked tile relief |
voxel_hd2d_shader.c/h |
HD-2D 30 FPS post-processing shaders (box downsample, bright-pass, Kawase bloom, DoF composite) |
voxel_pointlights.c/h |
Dynamic point lights for street lamps, cave lanterns & battle glow |
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= 104 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, recording the exact(sAsyncAtlasGen, sAsyncAtlasExt)the worker computed against so uncovered chunks rebuild immediately after an atlas extension). - 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 the dirty rows of
the active slot and visible same-primary neighbours are written directly (
WriteAtlasRowsDirect) on the same frame so animations stay synchronised across map borders (sSlotPendingPrimarycatches up neighbours returning into view). Secondary tiles of other slots are not refreshed from VRAM (VRAM holds only the current map's secondary tileset).
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.