test / test (push) Successful in 1m59s
- 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>
277 lines
20 KiB
Markdown
277 lines
20 KiB
Markdown
# 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.
|