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

277 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.