Files
tidewall/CONTRIBUTING.md
T
claudeandClaude Opus 5.5 36d474695a R3: Player, server and contributor documentation
- docs/PLAY.md is now the player guide: install from the tarball or .deb,
  starting a match, controls, how a match goes, settings files and
  troubleshooting, ahead of the graphics and tested-configuration sections.
- docs/SERVER.md: quick start, every option, ports, being found, logs,
  Docker and systemd, memory, and what was checked.
- CONTRIBUTING.md (engine setup, rules, commits, licence of contributions)
  and CREDITS.md.
- README: status and known limitations as they are.
- GDD controls table matched to the real defaults (B, Tab, G, 1 to 6).

Running the documented commands from an unpacked release found two bugs,
fixed here:
- `tidewall --connect=HOST` ignored the option unless it came after `--`.
  ClientConfig.game_args() now takes the game's own options from the
  engine's arguments when there is no `--`; tested.
- A headless run with no mode printed a line and never exited; it quits now.

The renderer option is given as the pair the capture tests use
(`--rendering-method gl_compatibility --rendering-driver opengl3`) in the
docs, the tarball README and the man page. The Join menu only searching the
LAN is documented and filed as #82.

Closes #62

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 08:30:16 -05:00

4.5 KiB

Contributing to Tidewall

Thanks for helping. Tidewall is GPL-3.0-or-later code with CC BY-SA 4.0 art and audio, made with Godot 4.7.2 and typed GDScript, with no third-party addons or assets.

Issues and changes go through the repository at https://gitea.eom.dev/claude/tidewall. Open an issue before starting anything large, so it can be fitted to the roadmap in the milestones.

Setting up

You need Linux on x86_64, git, make, bash, python3 and curl. Docker is needed only for the rendering captures and the package checks.

  1. Clone the repository.

  2. Download the Godot 4.7.2 stable Linux x86_64 editor (Godot_v4.7.2-stable_linux.x86_64.zip) and export templates (Godot_v4.7.2-stable_export_templates.tpz) from the official Godot release page. From the repository root, with both files in ~/Downloads, check them against the pinned sums, unpack the editor into tools/godot/ and put the templates beside it:

    (cd ~/Downloads && sha512sum -c "$OLDPWD/tools/engine.upstream.sha512")
    mkdir -p tools/godot
    unzip ~/Downloads/Godot_v4.7.2-stable_linux.x86_64.zip -d tools/godot
    cp ~/Downloads/Godot_v4.7.2-stable_export_templates.tpz tools/godot/
    tools/godot.sh --verify
    

    tools/godot/ is git-ignored. No other version is supported: the build pins this one by its SHA-512 (tools/engine.sha512).

  3. Run the checks:

    make check
    

    That verifies the engine, parses every script and runs every test headless, about 12 minutes on a desktop CPU. It must pass before every push.

tools/godot.sh always adds --headless, so nothing opens a window. To play from a source checkout on your own display, run the engine directly: tools/godot/Godot_v4.7.2-stable_linux.x86_64 --path .

Where things are

  • docs/GDD.md: the design. docs/ARCHITECTURE.md: the module map and how the server-authoritative simulation works.
  • docs/ORIGINALITY.md and docs/STYLE.md: the rules for everything that is seen or heard.
  • CLAUDE.md: working notes, including every make target with what it does and how long it takes.
  • src/sim/: the simulation. It must not depend on rendering, audio or UI; a test enforces this. src/server/, src/net/, src/bots/, src/client/, src/ui/, src/audio/ and src/app/ are the rest.
  • src/sim/tuning.gd: every gameplay number, and nowhere else.
  • test/: the tests, mirroring src/.
  • tools/: scripts for the build, checks, captures, art and audio.

Rules for changes

  • Typed GDScript. Untyped declarations are errors.
  • Determinism. All randomness in the simulation comes from the seeded streams in docs/ARCHITECTURE.md. A match must replay to the same state hash from its seed and command log.
  • Tests. Add tests for what you build: a file named test_*.gd under test/ with a class extending TestCase. Any engine or script error during a test fails it unless the test calls expect_error(). Run one group with tools/run_tests.sh --root=res://test/sim, or one test with tools/run_tests.sh --filter=name.
  • Visual changes come with a capture made after the change, with tools/capture.sh <scenario> captures/<name>.png (Docker, software rendering, about a minute). Look at it before you send it. Software rendering shows what is drawn, never how fast; don't report frame rates from it.
  • Art and audio are made by scripts in this repository: Blender run headless from tools/models/, synthesis in tools/audio/, shaders and meshes in code. Record how each new file was made in assets/PROVENANCE.md. Never add third-party art, audio, fonts, sample packs, code or addons.
  • Originality. Never name, copy or imitate another commercial game's names, characters, art, audio, maps, item names or UI. Read docs/ORIGINALITY.md first.
  • The repository is public. Never commit secrets, internal hostnames, private network details or personal data.

Commits

One commit per issue where practical, with a short summary line, a body saying what changed and why, and Closes #N for the issue it finishes. Keep make check green on every commit.

Licence of contributions

By contributing you agree that your code is licensed under GPL-3.0-or-later (LICENSE) and your art and audio under CC BY-SA 4.0 (LICENSE-ASSETS), and that you have the right to license them so. Add yourself to CREDITS.md.