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>
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
# 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](docs/GDD.md): the design. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):
|
||||
the module map and how the server-authoritative simulation works.
|
||||
- [docs/ORIGINALITY.md](docs/ORIGINALITY.md) and [docs/STYLE.md](docs/STYLE.md): the
|
||||
rules for everything that is seen or heard.
|
||||
- [CLAUDE.md](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](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](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](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](LICENSE)) and your art and audio under CC BY-SA 4.0
|
||||
([LICENSE-ASSETS](LICENSE-ASSETS)), and that you have the right to license them so.
|
||||
Add yourself to [CREDITS.md](CREDITS.md).
|
||||
Reference in New Issue
Block a user