Files
tidewall/docs/GDD.md
T
claudeandClaude Opus 5.5 8a6fb93b50 M2: The rising tide
The tide now runs every match, from the drop on, and water flows along the
terrain instead of standing everywhere under one level.

- Tide (src/sim/tide.gd): Tuning.TIDE_PHASES as a schedule of holds and
  rises. Level, forecast (each hold announces its level), stage, drowning
  rate, surge timing and the time limit are pure functions of the tick.
- SafeGround (src/sim/safe_ground.gd): safe ground from elevation on an 8 m
  grid, and per-island planned levels. A phase's level is lowered, when it
  must be, to just under the top of the largest piece of land still dry when
  the phase begins; every phase still rises at least TIDE_MIN_RISE_METRES and
  the last keeps its table level.
- Flood (src/sim/flood.gd): a 4 m grid aligned with building cells. Water
  reaches cells from the world's edge through ground under the sea and edges
  no breakwater stack seals. Cut-off ground stays dry until overtopped or
  breached, then fills at BREACH_FLOW_METRES_PER_SECOND. Incremental: only
  the edges where water stopped are re-tested, once a second.
- Players, drowning and structure wear use the local water. Breakwaters wear
  by head and fail past BREAKWATER_MAX_HEAD; a breach floods what's behind.
- Storm surges: each phase's `surge` damage hits pieces near the water when
  its rise begins.
- Sudden death after the last rise, then a time limit. Match breaks ties
  (most health, highest feet, earliest join) at the limit and when the last
  players fall together, so every match ends with a winner.

Tests: test_tide (18) covers the schedule and forecasts, planned levels,
overtopping, a sealed ring, breach and fill rate, spill-over, pressure wear
and head failure, dry pieces, surges, drowning under the real tide, sudden
death, the time limit and simultaneous eliminations. test_island's 100-seed
sweep now checks that every phase leaves safe ground reachable on foot from
the whole main landmass within the phase's time (closest margin 14 s).
A full rise with 24 bots measured p99 1.5 ms, max 1.9 ms per tick.

Closes #25

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:48:41 -05:00

326 lines
17 KiB
Markdown

# Tidewall game design
Tidewall is a third-person build-and-survive battle royale for Linux. Up to 24 players
or bots land on a procedurally generated island. They scavenge, fight and build while
the sea rises in phases and takes the low ground. The last player or team alive wins.
Every gameplay number is a named constant in the single tuning table,
[`src/sim/tuning.gd`](../src/sim/tuning.gd). This document refers to those constants by
name, so it can't drift from the game. To change a number, edit that file.
## What makes Tidewall distinct
- **The rising sea.** There is no circle closing in from the outside. The danger is a
water level that everybody can see and that rises on a published schedule.
- **Elevation is safe ground.** The map's shape decides where the fight goes. Valleys
flood first, ridges become islands, and the last land is the highest land. Reading
the terrain is a core skill.
- **Breakwaters hold back water.** A sealed ring of breakwater keeps ground below sea
level dry for a while. Water pressure wears them down, and enemies can breach them.
A breach floods everything behind it. A defended low-ground fort is a real and
risky strategy.
- **Seafaring folk art.** The look is weathered and hand-made, built on tarred wood,
rope, net floats and salt-faded paint. See [ORIGINALITY.md](ORIGINALITY.md).
## Core loop
1. **Launch.** A packet ship sails a straight line past the island. Each player picks
a moment to leave by lifeline mortar and steers a gull-kite to the ground.
2. **Scavenge.** Search wrecks, fishing huts and lighthouses for weapons and supplies.
Harvest driftwood, stone and salvage iron with the boathook.
3. **Read the tide.** Check the next flood line and decide where to be.
4. **Build and fight.** Raise cover, climb, wall off a position, or seal a breakwater.
5. **Climb or hold.** Move uphill with the water, or defend what you built.
6. **Last one standing wins.** Teams win when no other team has a living member.
## Match sizes
| Mode | Players | Constants |
|---|---|---|
| Solo | 24 players | `SOLO_PLAYERS` |
| Duos | 12 teams of 2 | `DUO_TEAMS`, `DUO_TEAM_SIZE` |
### Match flow
The server runs matches back to back, in [`src/sim/match.gd`](../src/sim/match.gd):
1. **Lobby.** Players join. Once `MATCH_MIN_PLAYERS` are in, it waits
`MATCH_LOBBY_SECONDS` for more, or counts down at once when full.
2. **Countdown.** `MATCH_COUNTDOWN_SECONDS`. If too many leave, it goes back to the lobby.
3. **Drop.** Bots fill the empty places, everyone boards the barge and loot is placed.
4. **Play.** Ends when at most one team has anyone standing.
5. **Results.** Finishing places and the winners stay up for `MATCH_RESULTS_SECONDS`,
then bots leave and the server goes back to the lobby with a new island.
Leaving during the drop or play counts as being eliminated where you stood. Joining
during a match waits in the lobby for the next one. Every timer can be changed per
server through `MatchRules`. Match 0 uses the server's seed; later matches derive theirs
from it, so a whole session can be replayed from one seed.
Bots fill empty slots. Offline play is a local server filled with bots, the same game
code as online play. A downed duo partner can be revived, within `REVIVE_SECONDS`.
## The island
Every match is a new island, generated from the match seed by
[`src/sim/island.gd`](../src/sim/island.gd). The server and every client build it from the
seed alone, and compare `Island.heightmap_hash()`, so terrain is never sent.
- About a kilometre across (`ISLAND_RADIUS_METRES`), in the `WORLD_SIZE_METRES` square,
with open sea all round for the packet ship's approach.
- Elevation bands suit the tide: beach up to `ISLAND_BEACH_TOP`, wet flat marsh up to
`ISLAND_MARSH_TOP`, forest up to `ISLAND_FOREST_TOP`, then highland, and summit ground
from `ISLAND_SUMMIT_BAND`.
- Land rises from the coast over a broad dome, so each tide phase takes a ring of the
island rather than all the low ground at once.
- Two to four summits (`ISLAND_MIN_SUMMITS`, `ISLAND_MAX_SUMMITS`), at least
`ISLAND_SUMMIT_SPACING_METRES` apart and joined by lower ridges. The tallest stands
between `ISLAND_PEAK_MIN` and `ISLAND_PEAK_MAX`, always below `ISLAND_MAX_HEIGHT`, so the
last tide covers it. Late fights happen on several hills, not one.
- The worldgen test sweeps 100 seeds: land covers 30 to 70% of the world, at least two
distinct high points, 85% of land walkable, and no more than 3% of dry land cut off
from the main landmass at the first two sea levels.
`tools/island_map.gd` draws a top-down map of any seed, with a contour at each tide level.
### Points of interest
Every island gets 10 to 16 places worth landing at (`POI_KINDS`, `POI_MIN_TOTAL`,
`POI_MAX_TOTAL`), at least `POI_SPACING_METRES` apart, placed from the seed by
[`src/sim/poi_set.gd`](../src/sim/poi_set.gd):
| Kind | Sited | Built from |
|---|---|---|
| Hilltop shrine | On a summit | Open-fronted stone shrine with a painted roof, cairns |
| Lighthouse | Near the coast, raised ground | Stone tower, keeper's room, stair to a loft, light chamber |
| Dock | On the shore, facing open water | Plank pier on posts reaching deep water, net shed |
| Salt works | Flat beach or marsh | Evaporation pans behind low walls, boiling house |
| Quarry | Highland | Cut stone blocks, lifting frame, tool shed |
| Fishing hamlet | Forest band | Three or four huts round a yard, net-drying rack |
Each is assembled from modular parts (walls with doors, plinths, steps, roofs, stairs).
Loot spawn markers sit on their floors, for the loot system, and a test walks a player
from open ground into every interior.
### Props
About 3,000 props cover each island, placed from the seed by
[`src/sim/prop_set.gd`](../src/sim/prop_set.gd) at a density set per elevation band in
`PROP_DENSITY`, with groves and clearings in the forest. They keep
`PROP_POI_CLEARANCE` from every point of interest, its loot markers and its walking
routes.
| Prop | Found | Harvests |
|---|---|---|
| Pine | Forest and highland | Driftwood |
| Scrub | Marsh, forest, everywhere a little | Driftwood |
| Boulder | Highland and summits | Stone |
| Wreck | Beached hulls on the shore | Salvage iron |
| Crate | Washed up on beaches | Driftwood |
Each prop has the health in `PROP_KINDS` and blocks players with one box. When it is
destroyed its box goes at once. Both server and client place the same props from the
seed, so only damage is match state.
### The drop
Every match starts with the drop, simulated in [`src/sim/drop.gd`](../src/sim/drop.gd).
A carrier crosses the island at `BARGE_ALTITUDE` on a straight route drawn from the seed.
The route passes within `BARGE_CENTRE_JITTER` of the middle and always crosses at least
`BARGE_MIN_LAND_METRES` of dry land. Players ride it until they press jump, then fall,
steering at `FREEFALL_STEER_SPEED`, up to `FREEFALL_MAX_SPEED`. Jump opens the sail, and
it opens by itself `WING_AUTO_DEPLOY_HEIGHT` above the ground or water. Under the sail
they sink at `GLIDE_FALL_SPEED` and steer at `GLIDE_SPEED`, and touch down without damage.
Anyone still aboard at the end of the route is thrown off. The carrier's name and look,
sky barge or the packet ship and mortar of the core loop above, are open in #72.
## Tide phases
`TIDE_PHASES` is an ordered list of phases. Each one sets:
- `hold`: seconds the water stays still, with the next flood line shown on the map;
- `rise`: seconds the water takes to reach the new level;
- `level`: the sea height in metres at the end of the rise;
- `drown_dps`: damage per second to anyone in water above their head.
The tide starts with the drop. Each island plans its own levels from its terrain
(`SafeGround`): a phase's table level is lowered, if it must be, to
`TIDE_SAFE_MARGIN_METRES` under the top of the largest piece of land still dry when the
phase begins, while every phase still rises at least `TIDE_MIN_RISE_METRES`. So safe
ground never vanishes from under the main landmass early. The island sweep checks, over
100 seeds, that every phase that leaves land leaves it within reach of the whole main
landmass on foot within the phase's hold and rise.
**Flooding.** Water only reaches ground it can flow to ([`src/sim/flood.gd`](../src/sim/flood.gd)):
from the world's edge, across 4 m cells whose lowest ground is under the sea, and over
cell edges no breakwater seals. Low ground cut off by higher land or a breakwater ring
stays dry until the sea overtops what holds it back or a breakwater breaks. Then the
water pours in and the cut-off ground fills at `BREACH_FLOW_METRES_PER_SECOND` until it
is level with the sea. Water never drains. Players, drowning and the wear on pieces all
use the water where they are, not the sea level.
**Storm surges.** When a phase's rise begins, its `surge` damage hits once every built
piece whose base is less than `TIDE_SURGE_HEIGHT_METRES` above the water that reaches it.
**Sudden death.** When the last rise ends, everyone still standing loses
`TIDE_SUDDEN_DEATH_DPS` health a second, armor or not. After
`TIDE_SUDDEN_DEATH_SECONDS` the match ends whatever happens. If several players are still
standing then, or the last ones fall on the same tick, the winner is the one with the most
health, then the highest feet, then the earliest to join. So every match has a winner
within the tide's total time plus sudden death.
The last phase raises the sea above the highest ground, so every match ends. Players
standing in shallow water wade and slow down. Underwater, they lose breath over
`BREATH_SECONDS`, and then take the phase's `drown_dps`. Swimming is slow and leaves a
player unable to build or fire. Players swim where the water over the floor is at least
`SWIM_DEPTH`, floating head-out at `SWIM_FLOAT_DEPTH`; crouch dives and jump kicks out of
the water. Swimming spends stamina (`SWIM_STAMINA_SECONDS`, faster when sprint-swimming),
which comes back on land. A swimmer with no stamina slips under and starts losing breath,
so a long swim out to sea can drown. Landing in deep water does no fall damage. Water flows along the terrain, so low ground that is
cut off from the sea stays dry until something opens a path.
## Building
Harvested materials are driftwood, stone and salvage iron, each capped at `MATERIAL_CAP`.
Pieces snap to a grid of `GRID_CELL_METRES` cells.
| Piece | Purpose |
|---|---|
| Wall | Cover and enclosure |
| Floor | Bridges and platforms |
| Ramp | Fast elevation |
| Roof | Overhead cover |
| **Breakwater** | Keeps water out; the only piece water can't pass |
`BUILD_PIECES` holds what each piece costs. `MATERIALS` holds each material's `health`
and `build_seconds`, and materials trade speed for strength. A piece goes up quickly but
reaches full health only after its `build_seconds` have passed. Pieces with no connection
to the ground collapse.
**Health and collapse.** A new piece starts at `BUILD_START_HEALTH_FRACTION` of its
material's health and gains the rest evenly over `build_seconds`, so a fresh iron wall
is briefly weaker than a finished driftwood one. Damage taken while building stays
taken. The boathook does `HARVEST_DAMAGE` to pieces and gives nothing back. A piece is
grounded when it touches the terrain or a fixed solid such as a pier deck (props don't
count; they can be felled). Every piece needs a path through touching pieces to a
grounded one, or it collapses, and collapses cascade. Pieces with their base under the
sea wear each second: `TIDE_STRUCTURE_DPS` for most, and for breakwaters
`BREAKWATER_WEAR_PER_METRE` per metre of water over the base, failing at once past
`BREAKWATER_MAX_HEAD`.
**Placing.** Build mode (Q) shows a ghost of the selected piece where it would go:
sea green if it can be placed, rust red if not. The look direction snaps to a quarter
turn. Walls and breakwaters go on the edge of your own cell in that direction; floors,
ramps and roofs go in the next cell, or in your own cell when you look well down. Ramps
rise away from you. Pieces snap up and down to levels `BUILD_LEVEL_METRES` (half a cell)
apart, choosing the level nearest your feet, or a whole cell higher when you look well
up. A wall built over lower ground gets a skirt down to the terrain, so there is no gap
underneath. The server places a piece only if it is in range (`BUILD_RANGE`), its slot
(and the same slot half a cell up or down) is empty, it wouldn't trap a player, you can
afford it, and it touches the terrain or another piece. A player standing in the low
step of a new floor or ramp is lifted onto it. Holding fire places up to 10 pieces a
second (`BUILD_INTERVAL_TICKS`). Ramps are stairs of `RAMP_STEPS` steps underneath,
drawn as a sloped deck.
**Harvesting.** Holding fire with the boathook swings once every `1 / fire_rate` seconds.
A swing reaches the boathook's `range_max` plus `HARVEST_REACH_SLACK` from the eye, and
hits the nearest standing prop it passes within `HARVEST_AIM_SLACK` of, unless terrain or
a solid is in the way. Each hit does `HARVEST_DAMAGE` to the prop and gives
`HARVEST_PER_HIT` of the prop's material, up to `MATERIAL_CAP`. A player at the cap still
damages props. The server works all of this out itself; a client only says "fire".
**Breakwaters.** Each holds up to `BREAKWATER_MAX_HEAD` metres of water above its base.
Every second under pressure it loses `BREAKWATER_WEAR_PER_METRE` health per metre of
head. Weapons damage it normally. When one fails, the water level equalises through
the gap at `BREACH_FLOW_METRES_PER_SECOND`.
## Weapons and items
`WEAPONS` holds damage, fire rate, magazine size, reload time, range falloff, spread,
ammunition and rarity. Every weapon besides the boathook takes an inventory slot.
| Name | Role |
|---|---|
| Boathook | Melee and harvesting; always carried, never in a slot |
| Fowling Piece | Close-range spread of shot |
| Rivet Repeater | Fast, short-range automatic |
| Dock Carbine | Mid-range automatic |
| Signal Revolver | Accurate sidearm |
| Whaler's Longgun | Long-range single shot; a heavy ball that drops with distance |
| Harpoon Gun | Slow, heavy bolt; tears through built pieces |
| Line Thrower | Fires a line and yanks you towards where it lands |
| Powder Keg | Thrown explosive; damages structures heavily |
Weapons come in four quality tiers, from `WEAPON_TIERS`: Rusted, Seaworthy,
Brass-Fitted and Captain's. Better tiers hit harder and reload faster.
Ammunition (`AMMO`) is carried apart from the slots: birdshot, cartridges, heavy balls,
harpoons and lines, each up to its own cap.
Consumables are in `ITEMS`. Fire with one held starts using it, and it takes effect
after its use time. Changing slot, sprinting or swimming interrupts it and nothing is
used up; taking damage doesn't. An item that would do nothing can't be started.
| Name | Effect |
|---|---|
| Sailcloth Bandage | Restores some health, up to 75 |
| Brine Tonic | Restores a lot of health, slowly |
| Tar Patch | Adds a little armor, quickly |
| Cork Vest | Adds a lot of armor |
### Loot
Loot is rolled once per match from the seed, when the match places it, so the same seed
always gives the same loot and nothing depends on who gets somewhere first. Every loot
marker at a point of interest holds either a **sea chest** or **floor loot**. Chests are
likelier in exposed, high places (shrines, lighthouses) than in hamlets, and their
weapons roll their tier twice and keep the better one. A chest always holds a weapon
with its ammunition, a consumable and a spare ammunition pickup. Interact opens a chest
in reach and spills what it holds; a pickup that is nearer is taken first.
**Washed-up crates** on the beaches each hold one roll of their own table, spilled when
the crate is broken by any means.
Tables live in `LOOT_SOURCES`: per location, the chance of a chest, how many floor rolls,
weights for weapon, consumable, ammunition or nothing, and tier weights. Within a
category, rarer items are picked less often (`LOOT_RARITY_WEIGHTS`). If a match's rolls
leave fewer weapons at points of interest than `LOOT_MIN_POI_WEAPONS` (one per player in
a full lobby), extra weapon rolls are added to floor spots, so no match is starved. The
loot test checks all of this over 1,000 seeds.
A player has `PLAYER_MAX_HEALTH` health, up to `PLAYER_MAX_ARMOR` armor, which takes
damage first, and `INVENTORY_SLOTS` slots. The top `HEAD_HEIGHT` of the body takes
each weapon's headshot multiplier.
## Controls
Rebindable. Defaults for keyboard and mouse:
| Action | Default |
|---|---|
| Move | W A S D |
| Jump | Space |
| Crouch | Left Ctrl |
| Sprint | Left Shift |
| Fire / harvest / place | Left mouse |
| Aim | Right mouse |
| Reload | R |
| Interact | E |
| Build mode | Q |
| Next / previous piece | Mouse wheel |
| Cycle material | T |
| Inventory slots | 1 to 5 |
| Map | M |
Gamepad support is planned with the accessibility work in v0.6.
## Out of scope for v1.0
- Monetization of any kind: no store, currency, battle pass or loot boxes.
- Accounts, ranked play, global matchmaking or anti-cheat beyond server authority.
- Modes other than solo and duos, or teams larger than 2.
- Vehicles, or swimming combat.
- Platforms other than Linux, and mobile or VR.
- Voice chat.
- User-made maps or mods.