- Layer rows can name a floor cover, soft pockets and a sea row. The underworld uses ash for both, and every cave cell at or below WORLD_BOTTOM + 28 is lava: a sea that is held in on every side, so it doesn't flow when woken. - Emberite ore in basalt (about 1.5% of the layer): glows, group level 4, so no current pickaxe (maxlevel 3) digs it. It waits for the top pre-hard-mode pickaxe in v0.5. - Ruined towers move to the structure framework (#24). Tests: 3 new cases in tests/underworld.lua (emberite tool gate, the lava sea, ash floors/pockets and ore share); the layer tests accept the underworld's ash. 109/109 pass, no ERROR lines. Closes #25 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Strata: design notes
Strata is a 2D, side-view sandbox adventure built on the Luanti engine. Its mechanics are inspired by Terraria. All content is original: names, creatures, bosses, items, art and audio are our own. We borrow genre mechanics (dig, build, craft, fight, progress through gear tiers), not Terraria's characters, assets, or specific designs.
1. What makes Terraria work (research summary)
| Pillar | How Terraria does it | What we take from it |
|---|---|---|
| Side-view sandbox | 2D tile world with foreground blocks and a separate background wall layer. Walls matter for housing and for which monsters spawn. | A gameplay plane plus a wall layer behind it. |
| Finite, layered world | Small, medium and large worlds (about 4200, 6400 and 8400 tiles wide). Layers run Space → Surface → Underground → Cavern → Underworld. Biomes sit side by side horizontally. | Vertical layers that get harder and darker with depth, and horizontal biomes. A finite world width is a later option. |
| Progression by gear tiers | Ore tiers (copper/tin → iron/lead → silver → gold → …) unlock better tools, which can mine the next ore. Bosses gate the next tier. | Ore and tool tiers (cracky levels), with bosses as gates. |
| Station crafting | No grid. Recipes are shown as a list, filtered by what you carry and which stations (Work Bench, Furnace, Anvil, …) are nearby. | Implemented: station-based recipe list. |
| Combat | Swing arcs, knockback, i-frames, contact damage, ranged/magic/summoner classes, health and mana. | Contact damage, knockback and i-frames to start; weapon classes later. |
| NPCs & housing | NPCs move into valid houses (walls, door, light, table, chair) when conditions are met. They run shops and services. | A housing validator and an NPC framework. |
| Bosses & events | Bosses are summoned by items or triggered by conditions. Events include blood moons and invasions. Beating the world boss flips the world into "Hardmode". | A boss framework, events, and a world-state switch after the main boss. |
| Exploration rewards | Underground cabins, chests, life crystals (+max HP), rare accessories. | Structures, loot tables, and permanent upgrades. |
| Day/night | Peaceful days with slimes. Nights bring zombies and flying eyes. | Day/night spawn tables. |
2. How Luanti is bent into 2D
Luanti is a 3D voxel engine. Strata turns it into a 2D side-scroller like this:
-
Gameplay plane (z = 0). All blocks, players and creatures live here. Avatars and mobs are locked to it every step.
-
Wall layer (z = 1). Background walls, removed with a hammer. Where there is no wall, an invisible backdrop node sits here. It is pointable, so the crosshair always has something to aim at, and right-click places a block on the plane in front of it.
-
Shadow slab (z = −30…−1 and 2…8). Invisible nodes that don't pass sunlight. They sit in front of and behind underground areas so daylight fades with depth (light 15 at the surface, 0 by about 20 blocks down). Without them the open air in front of the plane would light every cave.
-
Camera rig. Luanti has no server-side way to place the camera freely (
set_camera, client 5.12+, only picks first- or third-person; see #8). Each player is therefore attached to an invisible camera entityCAMERA_DIST(44 by default, settingstrata_camera_distance) nodes in front of the plane, because the client ignores attachment offsets for the local player's camera. The player's left/right/jump keys drive a physics avatar entity (anupright_sprite). The mouse pans the view a little, up toLOOK_LIMIT(enough to reachREACHaround an off-centre avatar), which is how the crosshair aims. The FOV is derived from the distance so the plane always showsVIEW_HEIGHT(21.5) nodes top to bottom: about 28° at 44. The further back the camera, the less the view turns to aim (about 11° to the edge of reach at 44, 22° at the old 22) and the less perspective distortion (#71). The camera's mapblock is 3 blocks in front of the plane's, so with the defaultactive_block_range(4) mobs and timers run about ±40 nodes either side of the player, still wider than the screen. -
Avatar appearance (
strata_player/appearance.lua). The avatar's frame comes from a one-row sprite sheet ([sheet, mirrored with[transformFX): idle, 4 walk frames paced by distance, jump, fall and 2 swing frames while dig or place is held. Textures are re-sent only when the frame changes. The wielded item is a non-physicalwielditementity attached to the avatar; it pivots around the shoulder and sweeps an arc during a swing. The avatar faces the way it last walked, except while dig or place is held: then it faces the aimed x (strata.aim_x, from the look yaw and the camera's position), so the item is always swung at what is being used. Names of other players are per-viewer HUD waypoints above their avatars, because an entity nametag would also show players their own name.strata.objects_in_cellonly counts physical entities, so the held item never blocks building. -
Camera follow. The camera entity is not attached to the avatar. Each step it sets a velocity towards a goal, so the client interpolates it: x leads the avatar by up to
LOOK_AHEADin the walking direction, and y followsstrata.camera_focus_y. Standing on something re-centres y; in the air y only moves once the avatar leaves a deadzone that is larger than a full jump upwards and small downwards.strata_smooth_camera = falserestores the rigid attachment. A hand check in the client is still needed for how it feels. -
Teleports, joins and respawns go through
strata.teleport(name, pos). The client fetches mapblocks around the camera only a few at a time, so a long jump would show sky and holes for seconds.strata.teleportcovers the screen with a black HUD image, emergesstrata.view_area(pos)(the visible rectangle on the plane and wall layer plus the space out to the camera), moves the avatar, pushes those mapblocks withsend_mapblock, and fades back in. -
Reach.
core.is_protectedis overridden so players can only dig or place on z ∈ {0, 1}, within 5.5 nodes of their avatar. -
One-way platforms. Platform nodes are
walkable = false, so the engine never collides with them. Each step, the avatar and creatures callstrata.platform_step(), which usesstrata.platform_landing()to check whether their feet crossed a platform top while falling. If they did, the entity is snapped onto the top and its gravity is switched off (strata.platform_support()) so it doesn't sink between server steps. Rising entities pass through. S (or sneak) on a platform ignores platforms forDROP_TIMEand drops through. -
Feedback (
strata_core/feedback.lua). Nodes get a sound set (stone, dirt, wood, leaves) fromstrata.node_sounds; nodes registered without sounds get one from their dig group after all mods load. The client plays dig/dug sounds and its own dust for the digger, so the server adds break particles textured from the node, spawned just in front of the plane, for everyone. Customon_placehandlers (walls, torches, doors) callstrata.play_place_sound. The avatar plays the footstep of the node under it on two of its walk frames. On damage the avatar flashes red (strata.flash, a short texture mod) and other players hearplayer_damage/player_falling_damageat the avatar; the hurt player hears the engine's own copy. Sounds are heard from the camera,CAMERA_DISTaway, so they usestrata.SOUND_HEAR_DISTANCE(CAMERA_DIST + 18) and full gain. -
Item pickup (
strata_player/pickup.lua).__builtin:itemis re-registered with a wrappedon_step: items are kept on the plane, and the nearest avatar withinMAGNET_RADIUS(3) with inventory room pulls the item in with physics off and takes it withinPICKUP_RADIUS.core.item_dropthrows items out of the avatar, facing its way, and they can't be picked up forDROP_DELAY. Item entities are static-saved, so a headless test must forceload its blocks or they deactivate. -
Inventory helpers (
strata_crafting/inventory.lua). The server can't change the selected hotbar slot, so smart tool select swaps stacks: when a dig starts, the item in the inventory with the shortestcore.get_dig_paramstime moves into the wielded slot, and the two slots are swapped back once dig has been released forSWAP_BACK_DELAY, if nothing moved meanwhile. It's on by default, with a checkbox on the inventory screen (player metastrata:smart_tool). Quick stack moves backpack items (slots 11–40) into chests within 6 nodes that already hold that item; Sort merges and orders the backpack. The hotbar is never touched by either. -
Placement support. A block a player places on the plane needs a supporting block next to it (left, right, above, below) or a background wall behind it. A wall needs a wall next to it, or a block on the plane in front of it or beside that cell. Platforms and doors count as support, torches don't. Torches mount on the floor, then a block to the left or right (
torch_left/torch_right, a flat plate facing the camera), then a wall behind, and drop as an item when that support is dug. Only player placement is checked;set_nodeis unrestricted and blocks don't fall when their support goes (placement.lua). -
Custom 2D mapgen. Uses
singlenode. Terrain, caves, ores, pockets, biomes and trees are all functions of (x, y) only, generated with Lua VoxelManip.mg.node_at(x, y)andmg.wall_at(x, y)give what a cell should hold, and the selftests compare the generated map against them. -
Biomes (
strata_mapgen,mg.biome_list). Biomes sit side by side along x: forest, desert, snow and jungle.mg.biome_at(x)picks one from two 1D noises: heat (biome: snow at the cold end, desert at the hot end) and humidity (jungle where it's wet and neither). Each biome row names its surface and fill nodes, the wall behind the fill, the stone and wall that replace the layer's in the surface and underground layers (snow: ice, desert: sandstone), its soft pockets, its tree (mg.trees: oak, frostpine, redheart), extra ores and a surface spawn table. The cavern layer and below ignore biomes, and the stone dither at the cavern top doubles as the biome's lower edge. WithinSPAWN_FOREST(64) columns of x = 0 it is always forest, and the other biomes fade in over the next 192, so a new player starts somewhere gentle.strata.spawn_candidates(y, tod, x)uses the biome's table on the surface layer. Trees are registered withstrata.register_tree: the trunk names its leaves and canopy reach, andstrata.fell_treeclears both. Every trunk drops plain wood for now. -
World size (
strata_mapgen, #23). New worlds are finite by default: settingstrata_world_size= small, medium (default) or large (2000, 3200 or 4200 columns, centred on x = 0), or infinite. The size is fixed at creation and kept in mod storage; a world without a stored size that already hasenv_meta.txtwas made before #23 and stays infinite. Every plane cell at|x| >= mg.world_halfisstrata_core:world_edge, an invisible, walkable, undiggable node, so nothing passes it at any depth;core.is_protectedalso refuses cells past the edge and creatures don't spawn there (mg.in_world(x)). The lastOCEAN_WIDTH(220) columns are the ocean biome (mg.ocean_biome, kept out ofmg.biome_listbecause infinite worlds never have it).mg.ocean_t(x)runs from 0 at the zone's inner edge to 1 at the world edge: over the firstBEACH_SHAREthe land eases to a sand beach atSEA_LEVEL + 3, then the sea floor falls toUNDERGROUND_TOP + 3(still the surface layer, so swimming keeps the real sky). Sea water fills cells up toSEA_LEVELonly past the beach, where the floor never rises outwards, so the generated sea is held in and doesn't flow. Tests run infinite and switch size withmg.set_world_size. -
Cavern biomes (
strata_mapgen,mg.cavern_biome_list, #70). Inside the cavern layer,mg.cavern_biome_at(x, y)picks a biome per cell from two 2D noises (cavern_biome,grotto), so cavern biomes are patches in both x and y: glimmer grove (mycel turf floors, glowing glimmercaps, giant umbrel mushrooms), prism gallery (glowing prism clusters on floors and roofs) and drowned grotto (silt floors, dripvine chains up to 4 long, a much lower pool threshold), with plain slate cavern between them. A row names itsfloor(replaces stone under open cave),flora(on a solid floor),ceilingchain (the roof cell's biome decides),mushroom,poolthreshold andspawns(strata.spawn_candidatesreads it when given x). All of it except mushrooms is part ofmg.node_at. Mushrooms are rooted on one candidate column per 8 (mg.mushrooms(box),mg.mushroom_cells(m)), grown in a pass like trees: the stalk fills its cells, the cap only air. Umbrel is amg.treesrow, so its stalk fells like a trunk and drops wood. Flora (strata_core/caverns.lua,strata.register_flora) glows, can be walked through, and drops when the block holding it is dug; a hanging chain goes all at once (strata.flora_held). Glowspores from glimmercaps make torches with wood, so a base underground can be lit without gel. -
Vertical layers (
strata_mapgen,mg.layers). The world is a stack of layers by absolute y: surface (down to y = −20), underground (to −300), cavern (to −900) and underworld (to −1000), with unbreakable bedrock frommg.WORLD_BOTTOMdown. Each layer is one table row: its stone and wall nodes, tunnel width and cavern threshold, ore table, background colour and spawn table.mg.layer_at(y)returns the row for a height; spawning (strata.spawn_candidates) and the sky (strata.update_layer_sky) read it, and music and biome effects should too. Boundaries aren't ruled lines: stone and walls dither overBLENDrows (mg.material_layer) and cave sizes ease overCAVE_BLENDrows (mg.cave_params). Stone gets harder with depth (stonecracky = 3, slate 2, basalt 1), so slate is slow with a copper pickaxe and basalt needs iron. Below the surface layer the player's sky becomes the layer's flat colour with no sun, moon, stars or clouds; that is what shows where a background wall is missing. The depths are tuned so a straight shaft to the underworld is about 3 minutes of digging with a copper pickaxe, which a selftest measures. Underworld (#25): open basalt caverns floored with ash (a layer row'sfloor, which replaces stone under open cave) with ash pockets (pocket), and a lava sea: every cave cell at or below the layer'ssearow (WORLD_BOTTOM + 28) is lava, so the sea is held in on every side and doesn't flow. Emberite ore glows and has grouplevel = 4; every pickaxe so far hasmaxlevel = 3, so it waits for the top pre-hard-mode pickaxe (v0.5). Ruined towers come with the structure framework (#24). -
2D liquids (
strata_core/liquids.lua, #22). Engine liquids flow in 3D and would leak towards the camera, so water and lava are plainlevelednodeboxes (liquidtype = "none") with a level of 1..64 in param2, moved by Strata's own cellular simulation on z = 0 only. EverySIM_STEP(0.15 s) each active cell reacts with a touching liquid it reacts with (lava next to water becomes ashglass), falls up to 3 rows into open air or tops up the cell below, then shares its level evenly with lower neighbours left and right. Settled water has neighbours within one level unit of each other. Volume is conserved; blocks placed into liquid (it isbuildable_to) displace it. Cells wake when placed, when a neighbour changes, when a block next to them is dug or placed (register_on_dignode/on_placenode), and through an LBM when their block loads with somewhere to flow. Code that changes plane cells withset_nodeshould callstrata.liquid_wake(pos). Lava is viscous (moves every 4th tick) and glows. Buckets (3 iron bars at an anvil) take a cell holding at least half a level and pour a full one into the plane cell in front of the pointed wall or backdrop. Mapgen fills cave cells with the layer'sliquidwhere thepoolnoise is high for the whole run of cells down to a solid floor (at most 6 rows), so most generated pools sit still: water in the surface, underground and cavern layers, lava in the underworld (mg.pool_liquid). -
Swimming (
strata_player/swim.lua). Each liquid def carries the avatar physics: gravity factor, walk-speed factor, sink speed cap and swim-up speed while jump is held (a bigger hop with the head above the surface, to climb out). Landing in a liquid cancels fall damage. The avatar has its own breath (10 bubbles, a HUD statbar shown only while it's below full; the engine breath bar is hidden because the hidden player body never gets wet): water uses one bubble per 0.7 s, then drowning deals 20 HP/s. Lava deals 60 HP/s. Damage is applied in 0.5 s ticks.
Known limitations of the rig
- Aiming is done by panning the camera, not by moving a free cursor. Up to at least 5.16 the engine has no API that separates the camera from the look direction, so #7 is parked until it does. A HUD cursor driven by look deltas was rejected: every re-centre would twitch the camera.
- The camera mode (C key) can only be locked when both server and client are
5.12+ (
strata.lock_camera_mode). On 5.10 and 5.11, pressing C breaks the view until it's pressed back to first person. - Zoom is off (
zoom_fov = 0) and the minimap is off through HUD flags. Fly, noclip and fast have no effect, because an attached player's client doesn't move itself./teleportis replaced so it moves the avatar. - Server-side movement means input latency equals network latency. That's fine in singleplayer and on a LAN. Client-side prediction would need engine/CSM work.
- The engine's own fall damage, breath and node damage act on the hidden player body, so Strata reimplements what it needs on the avatar.
3. Mod layout
| Mod | Responsibility |
|---|---|
strata_core |
Shared strata namespace and constants, terrain/wall nodes, materials, tools, tree felling. building.lua: one-way platforms. furniture.lua: strata.register_door (3-cell doors, one node per cell, opened by right-click or by an avatar walking into them (strata.open_door_ahead; creatures can't), won't close on an entity, group door for housing later) and strata.register_chest (40-slot node inventory, can't be dug while full, reach-checked). placement.lua: support rules for blocks and walls, torches and wall-mounted torches. feedback.lua: node sound sets, break particles, strata.flash. liquids.lua: strata.register_liquid, water, lava, ashglass, the 2D liquid simulation, buckets. caverns.lua: cavern floor covers, strata.register_flora, glowing flora, the umbrel mushroom |
strata_mapgen |
2D world generator (strata.mapgen.surface_y(x), etc.) |
strata_player |
Avatar entity, camera rig, movement, fall damage, spawn/respawn, reach rules. appearance.lua: avatar animation frames, held item, name tags, footsteps, hurt feedback. pickup.lua: item magnet and drops from the avatar. swim.lua: liquid physics, breath, drowning and lava damage |
strata_crafting |
strata.register_recipe, station detection, the inventory/crafting screen. inventory.lua: smart tool select, quick stack, sort |
strata_mobs |
Creatures (Green Slime), spawning, contact damage and i-frames |
4. Conventions
- Code: Lua, tabs,
core.*API, LGPL-2.1-or-later. - Media: textures from
tools/gen_textures.py(CC BY-SA 4.0 placeholders), sounds fromtools/gen_sounds.py(synthesized, CC0). Real art and audio replace them later; every sound's source is listed inCREDITS.md. - Every gameplay number lives in a named constant at the top of its file.
- Tests are headless:
tests/run.shstarts a dedicated server on a throwaway world with thestrata_selftestworldmod, which emerges an area, asserts invariants (mapgen, light, registries, entities) and shuts down. New systems get selftest cases. CI (.gitea/workflows/test.yml) runs luacheck and the selftest on Luanti 5.10.