From 0052624662edde98d2e4522a90d3b1593d8604e1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 9 Nov 2026 17:12:59 -0500 Subject: [PATCH] F2: Game design document and originality rules Add docs/GDD.md and docs/ORIGINALITY.md, with every gameplay number held in the single tuning table, src/sim/tuning.gd. The GDD refers to numbers by constant name so it can't drift from the game. Closes #2 Co-Authored-By: Claude Opus 5.5 --- docs/GDD.md | 132 ++++++++++++++++++++++++++++++++++++++++ docs/ORIGINALITY.md | 41 +++++++++++++ src/sim/tuning.gd | 104 +++++++++++++++++++++++++++++++ test/sim/test_tuning.gd | 25 ++++++++ 4 files changed, 302 insertions(+) create mode 100644 docs/GDD.md create mode 100644 docs/ORIGINALITY.md create mode 100644 src/sim/tuning.gd create mode 100644 test/sim/test_tuning.gd diff --git a/docs/GDD.md b/docs/GDD.md new file mode 100644 index 0000000..0d0d087 --- /dev/null +++ b/docs/GDD.md @@ -0,0 +1,132 @@ +# 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` | + +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`. + +## 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 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. 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. Each boathook hit harvests `HARVEST_PER_HIT` material. + +**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 and rarity. + +| Name | Role | +|---|---| +| Boathook | Melee and harvesting; always carried | +| Fowling Piece | Close-range spread | +| Dock Carbine | Mid-range automatic | +| Signal Revolver | Accurate sidearm | +| Whaler's Longgun | Long-range, single shot | +| Line Thrower | Fires a line to pull yourself to a surface | +| Powder Keg | Thrown explosive; damages structures heavily | + +Items are in `ITEMS`: Sailcloth Bandage restores health, Brine Tonic restores more +health slowly, and Cork Vest adds armor, up to `PLAYER_MAX_ARMOR`. A player has +`PLAYER_MAX_HEALTH` health and `INVENTORY_SLOTS` carried item slots. + +## 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. diff --git a/docs/ORIGINALITY.md b/docs/ORIGINALITY.md new file mode 100644 index 0000000..8092dec --- /dev/null +++ b/docs/ORIGINALITY.md @@ -0,0 +1,41 @@ +# Originality rules + +Binding on all Tidewall work: code, data, art, audio, text and tools. + +Tidewall works in the build-and-survive battle royale genre. Genre conventions and +general mechanics, such as many players on one shrinking map, scavenging and building +cover, are free for anyone to use. Particular expression is not, and Tidewall has its +own. + +## Never + +1. Use or imitate the **names, characters, art, audio, maps, emotes, item names, UI + layouts or overall look** of any commercial game. +2. Use **reference images or assets** taken from a commercial game, for any purpose, + including as a guide that gets discarded later. +3. **Name another commercial game** in code, data, assets or UI. Documents may say + "the genre". They don't need to say more than that. +4. Add **third-party art, audio, fonts or sample packs**, whatever their licence. +5. Add **third-party code or Godot addons**. If one is truly needed, raise it on the + issue with `needs-eric` first. + +## Always + +1. **Generate or hand-write every asset** with scripts in this repository: headless + Blender, procedural textures, or synthesized sound. +2. **Record provenance.** Generated assets name their generator script in the + manifest at `assets/PROVENANCE.md`, created when the first asset lands. +3. **Keep Tidewall's identity**, and check new work against it: + - the rising sea as the thing that ends the match; + - elevation as the measure of safe ground; + - breakwaters that hold back water; + - weathered seafaring folk art, including salt-faded paint, rope, tarred wood, + net floats and hand-lettered signs. +4. **Use Godot's bundled default font** if a font is needed. If it can't do the job, + stop and raise the issue with `needs-eric`. + +## When in doubt + +If something would make a player say "that's from that other game", redesign it until +it wouldn't. The audit in the v1.0 Release milestone checks the repository against +this document. diff --git a/src/sim/tuning.gd b/src/sim/tuning.gd new file mode 100644 index 0000000..490a40b --- /dev/null +++ b/src/sim/tuning.gd @@ -0,0 +1,104 @@ +## The one table of gameplay numbers. See docs/GDD.md for what they mean. +## Using constants means a typo is a parse error instead of a silent default. +class_name Tuning +extends RefCounted + +# Simulation +const TICK_RATE_HZ: int = 30 + +# Match sizes +const SOLO_PLAYERS: int = 24 +const DUO_TEAMS: int = 12 +const DUO_TEAM_SIZE: int = 2 +const REVIVE_SECONDS: float = 6.0 + +# Player +const PLAYER_MAX_HEALTH: int = 100 +const PLAYER_MAX_ARMOR: int = 100 +const BREATH_SECONDS: float = 12.0 +const INVENTORY_SLOTS: int = 5 + +# Movement, in metres and seconds +const WALK_SPEED: float = 4.0 +const SPRINT_SPEED: float = 6.5 +const WADE_SPEED: float = 2.5 +const SWIM_SPEED: float = 2.0 +const CROUCH_SPEED: float = 2.0 +const JUMP_VELOCITY: float = 7.5 +const GRAVITY: float = 20.0 + +# The tide. `hold` and `rise` are seconds, `level` is metres above the starting sea, +# `drown_dps` is damage per second underwater once breath runs out. The last level +# must exceed ISLAND_MAX_HEIGHT, so that every match ends. +const ISLAND_MAX_HEIGHT: float = 70.0 +const TIDE_PHASES: Array[Dictionary] = [ + {"hold": 150.0, "rise": 60.0, "level": 8.0, "drown_dps": 2}, + {"hold": 100.0, "rise": 50.0, "level": 18.0, "drown_dps": 4}, + {"hold": 80.0, "rise": 45.0, "level": 30.0, "drown_dps": 6}, + {"hold": 60.0, "rise": 40.0, "level": 42.0, "drown_dps": 8}, + {"hold": 45.0, "rise": 35.0, "level": 54.0, "drown_dps": 12}, + {"hold": 30.0, "rise": 30.0, "level": 64.0, "drown_dps": 16}, + {"hold": 20.0, "rise": 40.0, "level": 75.0, "drown_dps": 25}, +] + +# Building +const GRID_CELL_METRES: float = 4.0 +const MATERIAL_CAP: int = 500 +const HARVEST_PER_HIT: int = 15 +## Material units each piece costs. Health and build time come from MATERIALS. +const BUILD_PIECES: Dictionary = { + "wall": {"cost": 10}, + "floor": {"cost": 10}, + "ramp": {"cost": 10}, + "roof": {"cost": 10}, + "breakwater": {"cost": 30}, +} +const MATERIALS: Dictionary = { + "driftwood": {"health": 150, "build_seconds": 2.0}, + "stone": {"health": 300, "build_seconds": 5.0}, + "salvage_iron": {"health": 500, "build_seconds": 9.0}, +} +const BREAKWATER_MAX_HEAD: float = 6.0 +const BREAKWATER_WEAR_PER_METRE: float = 2.0 +const BREACH_FLOW_METRES_PER_SECOND: float = 1.5 + +# Weapons. Falloff is linear from full damage at `range_full` to `falloff_min` +# (a fraction of damage) at `range_max`. +const WEAPONS: Dictionary = { + "boathook": { + "damage": 20, "fire_rate": 1.5, "magazine": 0, "reload": 0.0, + "range_full": 2.5, "range_max": 2.5, "falloff_min": 1.0, "rarity": 0, + }, + "fowling_piece": { + "damage": 9, "pellets": 9, "fire_rate": 1.1, "magazine": 6, "reload": 4.0, + "range_full": 6.0, "range_max": 25.0, "falloff_min": 0.2, "rarity": 1, + }, + "dock_carbine": { + "damage": 27, "fire_rate": 6.0, "magazine": 30, "reload": 2.4, + "range_full": 40.0, "range_max": 120.0, "falloff_min": 0.5, "rarity": 1, + }, + "signal_revolver": { + "damage": 38, "fire_rate": 2.2, "magazine": 6, "reload": 2.0, + "range_full": 30.0, "range_max": 80.0, "falloff_min": 0.5, "rarity": 0, + }, + "whalers_longgun": { + "damage": 105, "fire_rate": 0.5, "magazine": 1, "reload": 2.6, + "range_full": 120.0, "range_max": 350.0, "falloff_min": 0.7, "rarity": 2, + }, + "line_thrower": { + "damage": 0, "fire_rate": 0.6, "magazine": 3, "reload": 3.0, + "range_full": 45.0, "range_max": 45.0, "falloff_min": 1.0, "rarity": 2, + }, + "powder_keg": { + "damage": 80, "structure_damage": 400, "blast_radius": 6.0, "fuse": 3.0, + "fire_rate": 0.8, "magazine": 1, "reload": 0.0, + "range_full": 0.0, "range_max": 30.0, "falloff_min": 1.0, "rarity": 2, + }, +} + +# Consumables +const ITEMS: Dictionary = { + "sailcloth_bandage": {"heal": 25, "use_seconds": 3.0, "stack": 6}, + "brine_tonic": {"heal": 60, "use_seconds": 8.0, "stack": 3}, + "cork_vest": {"armor": 50, "use_seconds": 5.0, "stack": 2}, +} diff --git a/test/sim/test_tuning.gd b/test/sim/test_tuning.gd new file mode 100644 index 0000000..463bc4f --- /dev/null +++ b/test/sim/test_tuning.gd @@ -0,0 +1,25 @@ +extends TestCase + + +func test_final_tide_covers_the_island() -> void: + var last: Dictionary = Tuning.TIDE_PHASES[Tuning.TIDE_PHASES.size() - 1] + assert_true(float(last["level"]) > Tuning.ISLAND_MAX_HEIGHT, "the sea must end every match") + + +func test_tide_only_rises() -> void: + var previous: float = 0.0 + for phase: Dictionary in Tuning.TIDE_PHASES: + assert_true(float(phase["level"]) > previous, "levels must increase") + previous = float(phase["level"]) + + +func test_match_sizes() -> void: + assert_eq(Tuning.SOLO_PLAYERS, 24) + assert_eq(Tuning.DUO_TEAMS * Tuning.DUO_TEAM_SIZE, 24) + + +func test_every_weapon_defines_the_shared_fields() -> void: + for id: String in Tuning.WEAPONS: + var weapon: Dictionary = Tuning.WEAPONS[id] + for field: String in ["damage", "fire_rate", "magazine", "range_full", "range_max", "rarity"]: + assert_true(weapon.has(field), "%s is missing %s" % [id, field])