# Dramatic Shape Voxel Mod The overworld as a 3D diorama. Terrain is extruded into real geometry, occlusion comes from a depth buffer rather than a y-sort, characters stand as leaning sprite slabs, a shadow map throws real cast shadows across whatever they land on, and an optional tilt-shift pass sells the miniature-model look. Purely presentational. Nothing here reaches collision, movement, triggers or scripts — it changes what the world *looks* like and nothing about what it *is*. Battles, menus and cutscenes are untouched; only the free-roam overworld draws differently. ## Using it | control | does | | --- | --- | | `6`, or the **VOXEL** options row | OFF → 15 → 35 → 50 → 75 → OFF (camera pitch) | | `9`, or the **T-SHIFT** options row | OFF → 1 → 2 → 3 → OFF (miniature blur) | | the **V-GRID** options row | OFF / ON — a one-pixel wireframe on every voxel | | the **V-CURVE** options row | OFF → 1 → 2 → 3 — bend the world over the horizon | 75 degrees is a rung the engine's flat **TILT** could not have: it projects the world canvas as one rigid plane, which degenerates into a horizon line down there, where real geometry only gets more of itself to show. V-CURVE is the *curved world* — every vertex pushed down by the square of its horizontal distance from the camera's focus, so the ground under you stays flat and the map bends away over a near horizon. It is not a fisheye: a fisheye is a lens, a screen-space warp that bends straight lines everywhere and resamples every pixel to do it. This bends the geometry, so lines near the camera stay straight and the art stays crisp. Both pipeline levels persist in `save.options.pipelines`, and V-GRID and V-CURVE in `save.options.modOptions.DRAMATIC_SHAPE` — the same place the mod manager's own settings page for this mod reads, so each row is one setting in two places. VOXEL and the engine's **TILT** are two answers to the same question, so switching one on switches the other off. Without shader or depth-canvas support the rows still cycle but the world stays 2D — the mode reports itself unavailable and the engine keeps the vanilla path. ## How it is built This is a *rendering pipeline* mod (see `docs/modding.md`). `main.lua` registers two records in the engine's `render_pipelines` registry and writes almost nothing else — the ladder, the options rows, the hotkeys, persistence and the free-roam gate are all engine plumbing driven from those records: - **`voxel`** — a `drawWorld` pipeline. Replaces the world pass with a rendered 3D scene and returns it as one window-resolution canvas. - **`tiltshift`** — a `worldPresent` pipeline. Post-processes the finished world *before* the UI composites, so the diorama blurs and the text boxes in front of it stay crisp. Everything else lives in `lib/`, loaded through the mod's own namespace (`V.require`) rather than `package.path`, which a mod directory is not on: | module | role | | --- | --- | | `Voxel3D` | the 3D pass: shader, depth buffer, camera, projection | | `ShadowMap` | the sun's own pass: what it cannot see is in shadow | | `WorldCurve` | the curved world: the Animal Crossing horizon | | `VoxelGrid` | the wireframe toggle | | `ModSetting` | a setting of this mod's own: ladder, store, options row | | `Mat4` | the 4x4 matrix math the camera and model transforms need | | `VoxelState` | the camera angle and its ease; the engine owns the level | | `VoxelScene` | assembles one frame: shadows, terrain, characters, grass | | `ChunkMesher` | a map's block layer → a terrain mesh, cached per map | | `Structures` | flood-fills drawn things and decides how tall each is | | `Buildings` | a profiled building sprite → a voxel model, band by band | | `TileShape` | resolves every tile to an extrusion class and art mode | | `TerrainAtlas` | the texture geometry samples: SGB palette bakes, and the animated water/flower tiles | | `SpriteBillboards` | a sprite frame → a leaning slab with side relief | | `VoxelModels` | the carved character models in `assets/voxels/` | | `TiltShift` | the two-pass separable blur and saturation lift | `data/voxel_heights.lua` is the hand-authored shape profile: listing a tile there pins its height and art mode over the automatic detector, and its `buildings` section names whole building sprites to voxelize band by band (`assets/docs/buidling_to_voxel/` is the pipeline; `assets/docs/buildings/` catalogues the drawings). Another mod can pin its own tiles by shipping the same file, and can replace a character's model with `overrides/voxels/.lua` — models resolve through the engine's asset search path before falling back to ours. `tools/build_voxels.py` is what carved `assets/voxels/` out of the overworld sprite sheets. `tools/building_voxels.py` is the reference implementation of the building voxelizer — it builds the same models offline, asserts their geometry and renders isometric previews, and its voxel and shell counts are what `lib/Buildings.lua` is checked against. ## Engine seams it relies on The mod reads a few engine internals (hence `"permissions": ["engine_internals"]`), all of them deliberate read-only seams: - `Player:pose()` / `NPC:pose()` — the sheet, position, facing and step phase a frame renders to, so 2D and 3D can never disagree about a pose. - `SpriteRenderer:resolveImage()` and `SpriteRenderer.STAND/WALK` — the live sprite image and frame tables, so palette modes and sprite-replacing mods apply to the geometry with no second copy of the logic. - `TileRenderer.recolorSample` — the exact shade cutoffs the 2D palette shader uses, so baked terrain lands on the same colours as flat tiles. - `TileRenderer.animFrame()` / `.atlasImageData()` / `.defaultAnimatedTiles()` — the tile-animation clock, the pixels behind the atlas texture, and the vanilla water/flower spec. A static mesh cannot overdraw animated cells the way the tile layer does, so it animates the texture instead, and these are what let it do that on the engine's own clock and colours. Only `defaultAnimatedTiles` is required. The other two are OPTIONAL and read guarded, because an engine build is free not to carry them — this one does not carry either. Missing `animFrame` freezes the tile clock at step 0 (terrain stops animating in voxel mode; everything else is unaffected). Missing `atlasImageData` costs nothing where the mod baked the atlas itself, falls back to the tileset art where the engine is drawing that art unmodified, and skips animating a RED++ per-map bake, whose pixels are unreachable without the seam. None of the three may ever be called unguarded: a throw inside `drawWorld` costs the player the whole pipeline for the session, not one frame of moving water. ## Tests ```sh luajit mods/DRAMATIC_SHAPE/tests/dramatic_shape_test.lua ``` Runs headless: the mod loads, both pipelines land in the registry with the shape the engine dispatches on, the ladders and persistence round-trip, and the whole thing stays inert on a machine with no 3D support.