Files
claudeandClaude Opus 5.5 779fbe8c30
test / test (push) Successful in 1m59s
Underworld: ash floors and pockets, a lava sea, emberite ore
- 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>
2026-11-15 01:34:48 -05:00

20 KiB
Raw Permalink Blame History

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 entity CAMERA_DIST (44 by default, setting strata_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 (an upright_sprite). The mouse pans the view a little, up to LOOK_LIMIT (enough to reach REACH around an off-centre avatar), which is how the crosshair aims. The FOV is derived from the distance so the plane always shows VIEW_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 default active_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-physical wielditem entity 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_cell only 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_AHEAD in the walking direction, and y follows strata.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 = false restores 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.teleport covers the screen with a black HUD image, emerges strata.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 with send_mapblock, and fades back in.

  • Reach. core.is_protected is 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 call strata.platform_step(), which uses strata.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 for DROP_TIME and drops through.

  • Feedback (strata_core/feedback.lua). Nodes get a sound set (stone, dirt, wood, leaves) from strata.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. Custom on_place handlers (walls, torches, doors) call strata.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 hear player_damage/player_falling_damage at the avatar; the hurt player hears the engine's own copy. Sounds are heard from the camera, CAMERA_DIST away, so they use strata.SOUND_HEAR_DISTANCE (CAMERA_DIST + 18) and full gain.

  • Item pickup (strata_player/pickup.lua). __builtin:item is re-registered with a wrapped on_step: items are kept on the plane, and the nearest avatar within MAGNET_RADIUS (3) with inventory room pulls the item in with physics off and takes it within PICKUP_RADIUS. core.item_drop throws items out of the avatar, facing its way, and they can't be picked up for DROP_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 shortest core.get_dig_params time moves into the wielded slot, and the two slots are swapped back once dig has been released for SWAP_BACK_DELAY, if nothing moved meanwhile. It's on by default, with a checkbox on the inventory screen (player meta strata: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_node is 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) and mg.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. Within SPAWN_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 with strata.register_tree: the trunk names its leaves and canopy reach, and strata.fell_tree clears both. Every trunk drops plain wood for now.

  • World size (strata_mapgen, #23). New worlds are finite by default: setting strata_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 has env_meta.txt was made before #23 and stays infinite. Every plane cell at |x| >= mg.world_half is strata_core:world_edge, an invisible, walkable, undiggable node, so nothing passes it at any depth; core.is_protected also refuses cells past the edge and creatures don't spawn there (mg.in_world(x)). The last OCEAN_WIDTH (220) columns are the ocean biome (mg.ocean_biome, kept out of mg.biome_list because 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 first BEACH_SHARE the land eases to a sand beach at SEA_LEVEL + 3, then the sea floor falls to UNDERGROUND_TOP + 3 (still the surface layer, so swimming keeps the real sky). Sea water fills cells up to SEA_LEVEL only 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 with mg.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 its floor (replaces stone under open cave), flora (on a solid floor), ceiling chain (the roof cell's biome decides), mushroom, pool threshold and spawns (strata.spawn_candidates reads it when given x). All of it except mushrooms is part of mg.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 a mg.trees row, 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 from mg.WORLD_BOTTOM down. 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 over BLEND rows (mg.material_layer) and cave sizes ease over CAVE_BLEND rows (mg.cave_params). Stone gets harder with depth (stone cracky = 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's floor, which replaces stone under open cave) with ash pockets (pocket), and a lava sea: every cave cell at or below the layer's sea row (WORLD_BOTTOM + 28) is lava, so the sea is held in on every side and doesn't flow. Emberite ore glows and has group level = 4; every pickaxe so far has maxlevel = 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 plain leveled nodeboxes (liquidtype = "none") with a level of 1..64 in param2, moved by Strata's own cellular simulation on z = 0 only. Every SIM_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 is buildable_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 with set_node should call strata.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's liquid where the pool noise 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. /teleport is 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 from tools/gen_sounds.py (synthesized, CC0). Real art and audio replace them later; every sound's source is listed in CREDITS.md.
  • Every gameplay number lives in a named constant at the top of its file.
  • Tests are headless: tests/run.sh starts a dedicated server on a throwaway world with the strata_selftest worldmod, 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.