Files
tidewall/docs/GDD.md
T
claudeandClaude Opus 5.5 aa797580a7 #72: The packet ship, the lifeline mortar and the gull-kite
Eric chose option B on #72. The drop is now the GDD's launch:

- A packet ship sails a seeded straight line past the island, offshore,
  as close in as it can while keeping 45 m of open water from any land
  (eight-way probes; up to 32 headings, then the four world sides).
- Jump fires the lifeline mortar along the look heading. How high the
  player aims sets the charge (-10 to 45 degrees: 16 to 110 m/s over
  the ground; every shot climbs at 75 m/s). The climb can't be steered
  and the kite can't open until the arc tops out. Riders still aboard at
  the end are fired towards the middle of the island.
- Drop.reach() mirrors the fall for both ways down (kite at the top, or
  a fall with the kite opening by itself); bots, the soak and autoplay
  clients and the tutorial pilot aim with Drop.aim_charge().
- Bots fire at their landing spot once abeam of it, when in easy reach
  at their own staggered moment, or just before the route ends, and open
  the kite early only when the spot is beyond the rest of a fall.
- Art: VesselModels.ship() (two-masted packet, tanned square sails, a
  salt-white boot-top, a bowsprit and the mortar on its bed, mirrored to
  face the island), the figure's gull-kite (figure.py), and a lifeline
  cord from the muzzle to each player still climbing.
- Renamed barge to ship and wing-sail to gull-kite throughout code,
  tests, captures, docs and the tutorial text. make match now defaults to
  seed 2, where the scripted player still harvests and builds.

Closes #72

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 12:49:21 -05:00

21 KiB

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. 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.

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:

  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 packet ship 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. They pick a landing spot, loot, fight, bandage themselves and keep ahead of the tide, knowing only what a player would. They come in three difficulties, easy, normal and hard, which differ in reaction time, sight range and aim; a server mixes them unless told otherwise. Bots build too: once armed, they gather with the boathook (crates included) when nothing more pressing is going on. In a fight they put up a wall when shot from ambush, while reloading or when worn down, wall themselves off to heal instead of running when badly hurt, and build ramps up to someone on a cliff or a steep rise. At the last stand they ring their spot with breakwaters. They don't use powder kegs or the line thrower. 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. In duos (M7) bots never target their teammate, crawl toward it when downed, and go to a downed teammate within BOT_REVIVE_METRES to revive it when they aren't in a fight.

Duos rules (M7). Teams are set by Match and held on each player (SimEntity.team), so the simulation enforces them: Weapons.damage_player refuses damage between teammates from every weapon, the boathook and blasts. A player whose health runs out with a teammate standing goes down (DOWNED_HEALTH, bleeding one point every DOWNED_BLEED_INTERVAL_TICKS, crawling at DOWNED_CRAWL_SPEED); a standing teammate within REVIVE_RANGE holding interact for REVIVE_SECONDS brings them back with REVIVE_HEALTH. Downed players are eliminated when their health runs out again or when no teammate is left standing, credited to whoever downed them.

The island

Every match is a new island, generated from the match seed by 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:

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 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. A packet ship sails past the island on a straight route drawn from the seed, its deck SHIP_DECK_HEIGHT above the sea. The route runs as close in as it can while keeping SHIP_COAST_CLEARANCE of open water between itself and any land, so it never crosses the island. Players ride it until they press jump, which fires them inland by lifeline mortar along the way they face. How high they aim sets the charge: from MORTAR_PITCH_LOW_DEGREES (or lower) to MORTAR_PITCH_HIGH_DEGREES (or higher) the shot's speed over the ground runs from MORTAR_MIN_SPEED to MORTAR_MAX_SPEED, and every shot climbs at MORTAR_RISE_SPEED. Nothing steers the climb. Over the top of the arc they fall, steering at FREEFALL_STEER_SPEED, up to FREEFALL_MAX_SPEED. Jump opens the gull-kite, and it opens by itself KITE_AUTO_DEPLOY_HEIGHT above the ground or water. Under the kite they sink at GLIDE_FALL_SPEED and steer at GLIDE_SPEED, and touch down without damage. A full charge with the kite opened at the top carries about a kilometre, further than any land lies from any route (test_drop checks 60 seeds). Anyone still aboard at the end of the route is fired towards the middle of the island. Eric chose this launch in #72 over the sky barge first built for W7.

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): 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 (B) 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

Powder kegs (B8, src/sim/explosives.gd) are thrown, not fired. Fire throws one from the stack, lobbed (THROW_LIFT) at the keg's projectile_speed. It drops down anything it strikes, rests where it lands, falls again if what it rests on goes, and blows fuse seconds after the throw. The blast reaches blast_radius, measured to the nearest point of each body, piece or prop:

  • terrain, built pieces, props and fixed solids shield what is behind them; players don't, and a player whose body middle or head is in sight is hit;
  • damage falls off linearly from all of it at the middle to BLAST_EDGE_FACTOR at the edge, times the keg's tier;
  • players take damage, armor first, credited to the thrower, who takes BLAST_SELF_FACTOR of their own;
  • pieces and props take structure_damage, so a keg can open a breakwater and let the sea in.

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.

Balance

The balance targets are checked by make balance over at least BALANCE_MIN_MATCHES bot-only matches of SOLO_PLAYERS players (H3):

  • the median match, from the ship sailing to the last player standing, lasts between BALANCE_MEDIAN_MINUTES_MIN and BALANCE_MEDIAN_MINUTES_MAX minutes;
  • no one weapon takes more than BALANCE_MAX_WEAPON_SHARE of the eliminations made with weapons, the boathook included.

Every match ends within the tide's total time plus sudden death, which the tide table keeps under BALANCE_MEDIAN_MINUTES_MAX. Findings and the changes they led to are in BALANCE.md.

Controls

Rebindable in Settings → Controls (src/client/key_bindings.gd holds the defaults). Keys are matched by position. Defaults for keyboard and mouse:

Action Default
Move W A S D
Jump; fire the mortar from the ship; open the gull-kite Space
Crouch; dive when swimming Left Ctrl
Sprint Left Shift
Use, fire, harvest or place Left mouse
Aim Right mouse
Reload R
Pick up or open E
Drop the held item G
Boathook 1
Inventory slots 2 to 6
Build mode B
In build mode: wall, floor, ramp, roof, breakwater 1 to 5
In build mode: next material Tab
Chart M
Pause menu (not rebindable) Escape

Gamepad support is issue A13.

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.