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/<name>.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

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.