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

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

Atlas

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.