From e7cc87460eee9b677987e240d42337665441521e Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 22:40:24 +0200 Subject: [PATCH 1/9] docs(CH-034): propose Rumble user documentation Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- .clue/id-ledger.yaml | 7 +++- changes/CH-033-rumble-docs/open-questions.md | 11 ++++++ changes/CH-033-rumble-docs/proposal.md | 41 ++++++++++++++++++++ changes/CH-033-rumble-docs/tasks.md | 21 ++++++++++ 4 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 changes/CH-033-rumble-docs/open-questions.md create mode 100644 changes/CH-033-rumble-docs/proposal.md create mode 100644 changes/CH-033-rumble-docs/tasks.md diff --git a/.clue/id-ledger.yaml b/.clue/id-ledger.yaml index 1a984f768..6461205ce 100644 --- a/.clue/id-ledger.yaml +++ b/.clue/id-ledger.yaml @@ -4,7 +4,7 @@ counters: ARCH: "26" C: "4" CAP: "17" - CH: "32" + CH: "33" G: "2" GTD: "1" IDR: "4" @@ -669,6 +669,11 @@ entries: - id: CH-032-tasks kind: opaque state: live + - id: CH-033 + kind: numeric + state: reserved + prefix: CH + component: "33" - id: G-001 kind: numeric state: live diff --git a/changes/CH-033-rumble-docs/open-questions.md b/changes/CH-033-rumble-docs/open-questions.md new file mode 100644 index 000000000..502488f8c --- /dev/null +++ b/changes/CH-033-rumble-docs/open-questions.md @@ -0,0 +1,11 @@ +--- +id: CH-033-open-questions +type: open-questions +status: open +links: [CH-033] +title: Open questions for CH-033 +--- + +# CH-033 — Open questions + +No contract question is open. The design doc (`docs/design/rumble/user-documentation.md`) describes a fuller document set than M-009 promises; this change deliberately ships only the plan's literal commitment (one quickstart per audience) and records that boundary in the proposal's Non-goals, rather than treating it as a blocking question. diff --git a/changes/CH-033-rumble-docs/proposal.md b/changes/CH-033-rumble-docs/proposal.md new file mode 100644 index 000000000..441e484f0 --- /dev/null +++ b/changes/CH-033-rumble-docs/proposal.md @@ -0,0 +1,41 @@ +--- +id: CH-033 +type: change +status: open +links: [P-003, M-009, CAP-014, CAP-015, CAP-016] +title: Publish Rumble user documentation +--- + +# CH-033 — Publish Rumble user documentation + +## What + +Publish one quickstart per Rumble audience — bot author, battle contributor, moderator — under `web/docs/rumble/`, wired into the Tank Royale docs site navigation. + +## Why + +P-003/M-009 is the last open milestone in the Rumble plan. M-005 through M-008 and M-010 are all done, and PDR-005 deliberately sequenced M-009 after M-010 (GUI TwinDuel), which has since shipped in 1.1.0. The three Rumble repositories (`rumble-bots`, `rumble-data`, `rumble-client`) and the GUI are functioning, but nothing tells a newcomer how to participate. + +## Route + +Recommended route: full. Publishing these guides fulfills a plan promise (M-009 moves from `todo` to `done`), which is an accepted-contract change under the routing rule even though no acceptance criterion or capability changes. Discovery would change the route only if the guides turn out to require no plan bookkeeping change at all, which is not the case here. + +## Plan + +Serves [P-003/M-009](../../docs/plans/P-003-rumble.md). No CAP-014/015/016 acceptance criterion changes; the guides describe existing, already-accepted behavior. + +## Scope + +- `web/docs/rumble/bot-author-guide.md` — quickstart from template to a merged, ranked-eligible bot in `rumble-bots`: official Bot API requirement, SPDX license field, local `validate_bot.py` run, PR flow, ownership/versioning basics, slots. +- `web/docs/rumble/client-guide.md` — quickstart for running the Rumble client: one-time client registration PR in `rumble-data`, build/Docker-dev-image instructions reflecting the client's actual current state (no published release or production image yet), configuration, practice vs. ranked mode, submitting results. +- `web/docs/rumble/moderator-guide.md` — quickstart for the moderator role as it exists today: reviewing bot and client-registration PRs, using `bans.json`/`exclusions.json`/`disqualifiedBots`, and links to each repository's own `GOVERNANCE.md` as the authoritative operations reference (no separate `rumble-data/docs/moderator-handbook.md` exists yet, so this guide does not claim one does). +- `web/docs/rumble/index.md` — short landing page linking the three guides and the live dashboard, so the docs site has one entry point. +- Wire the four pages into `web/docs/.vitepress/config.mts` (nav + sidebar section). +- Update `docs/plans/P-003-rumble.md` to mark M-009 done, with evidence, in the digest. + +## Non-goals + +- A full `rumble-data/docs/moderator-handbook.md`, a separate `onboarding.md`, or a `faq.md` — the design doc's fuller document set (`docs/design/rumble/user-documentation.md`) remains the aspirational target; this change ships only the plan's literal M-009 commitment (one quickstart per audience). +- Any change to `rumble-bots`, `rumble-data`, or `rumble-client` repository content. +- Claiming a published client container, native release, or production Docker image exists — the client guide describes the real current build/run path. +- New or changed acceptance criteria, capabilities, or ADRs. diff --git a/changes/CH-033-rumble-docs/tasks.md b/changes/CH-033-rumble-docs/tasks.md new file mode 100644 index 000000000..426365dcf --- /dev/null +++ b/changes/CH-033-rumble-docs/tasks.md @@ -0,0 +1,21 @@ +--- +id: CH-033-tasks +type: tasks +status: open +links: [CH-033] +title: Task breakdown for CH-033 +--- + +# CH-033 — Tasks + +- [x] Reserve CH-033 and branch from the accepted tip of `main` +- [x] Confirm M-009's scope, dependencies (PDR-005), and the real current state of `rumble-bots`, `rumble-data`, `rumble-client` +- [x] Capture the full-route proposal and selected documentation scope +- [ ] Commit and push the proposal, then open the required draft PR before implementation +- [ ] Write `web/docs/rumble/bot-author-guide.md` +- [ ] Write `web/docs/rumble/client-guide.md` +- [ ] Write `web/docs/rumble/moderator-guide.md` +- [ ] Write `web/docs/rumble/index.md` +- [ ] Wire the four pages into `web/docs/.vitepress/config.mts` nav and sidebar +- [ ] Build the docs site locally and confirm the new pages render and navigate correctly +- [ ] Digest: mark M-009 done in `docs/plans/P-003-rumble.md` with evidence, delete the change workspace From c09c34ad20c361cb168bf574d3b93d8454d70a40 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 22:48:09 +0200 Subject: [PATCH 2/9] docs(CH-034): publish Rumble user documentation Add bot-author, battle-contributor, and moderator quickstarts under web/docs/rumble/, plus a landing page, wired into the VitePress nav and sidebar. The client guide documents the client's actual current pre-release state (build from source / dev Docker image) rather than an aspirational published-container flow. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- changes/CH-033-rumble-docs/tasks.md | 14 ++++----- web/docs/.vitepress/config.mts | 12 +++++++- web/docs/rumble/bot-author-guide.md | 47 ++++++++++++++++++++++++++++ web/docs/rumble/client-guide.md | 48 +++++++++++++++++++++++++++++ web/docs/rumble/index.md | 19 ++++++++++++ web/docs/rumble/moderator-guide.md | 24 +++++++++++++++ 6 files changed, 156 insertions(+), 8 deletions(-) create mode 100644 web/docs/rumble/bot-author-guide.md create mode 100644 web/docs/rumble/client-guide.md create mode 100644 web/docs/rumble/index.md create mode 100644 web/docs/rumble/moderator-guide.md diff --git a/changes/CH-033-rumble-docs/tasks.md b/changes/CH-033-rumble-docs/tasks.md index 426365dcf..00ccf03d7 100644 --- a/changes/CH-033-rumble-docs/tasks.md +++ b/changes/CH-033-rumble-docs/tasks.md @@ -11,11 +11,11 @@ title: Task breakdown for CH-033 - [x] Reserve CH-033 and branch from the accepted tip of `main` - [x] Confirm M-009's scope, dependencies (PDR-005), and the real current state of `rumble-bots`, `rumble-data`, `rumble-client` - [x] Capture the full-route proposal and selected documentation scope -- [ ] Commit and push the proposal, then open the required draft PR before implementation -- [ ] Write `web/docs/rumble/bot-author-guide.md` -- [ ] Write `web/docs/rumble/client-guide.md` -- [ ] Write `web/docs/rumble/moderator-guide.md` -- [ ] Write `web/docs/rumble/index.md` -- [ ] Wire the four pages into `web/docs/.vitepress/config.mts` nav and sidebar -- [ ] Build the docs site locally and confirm the new pages render and navigate correctly +- [x] Commit and push the proposal, then open the required draft PR before implementation +- [x] Write `web/docs/rumble/bot-author-guide.md` +- [x] Write `web/docs/rumble/client-guide.md` +- [x] Write `web/docs/rumble/moderator-guide.md` +- [x] Write `web/docs/rumble/index.md` +- [x] Wire the four pages into `web/docs/.vitepress/config.mts` nav and sidebar +- [x] Build the docs site locally and confirm the new pages render and navigate correctly - [ ] Digest: mark M-009 done in `docs/plans/P-003-rumble.md` with evidence, delete the change workspace diff --git a/web/docs/.vitepress/config.mts b/web/docs/.vitepress/config.mts index 7c18736ce..042a51c99 100644 --- a/web/docs/.vitepress/config.mts +++ b/web/docs/.vitepress/config.mts @@ -27,7 +27,8 @@ export default withMermaid(defineConfig({ { text: 'Home', link: '/' }, { text: 'Articles', link: '/articles/intro' }, { text: 'Tutorial', link: '/tutorial/getting-started' }, - { text: 'API', link: '/api/apis' } + { text: 'API', link: '/api/apis' }, + { text: 'Rumble', link: '/rumble/index' } ], sidebar: [ @@ -103,6 +104,15 @@ export default withMermaid(defineConfig({ { text: 'Custom Game Setup', link: '/articles/custom-game-setup' }, { text: 'Team Strategies', link: '/articles/team-strategies' }, ] + }, + { + text: 'Rumble', + items: [ + { text: 'Overview', link: '/rumble/index' }, + { text: 'Bot Author Quickstart', link: '/rumble/bot-author-guide' }, + { text: 'Battle Contributor Quickstart', link: '/rumble/client-guide' }, + { text: 'Moderator Quickstart', link: '/rumble/moderator-guide' }, + ] } ], diff --git a/web/docs/rumble/bot-author-guide.md b/web/docs/rumble/bot-author-guide.md new file mode 100644 index 000000000..876f52b38 --- /dev/null +++ b/web/docs/rumble/bot-author-guide.md @@ -0,0 +1,47 @@ +# Bot author quickstart + +This is the fastest path from nothing to a ranked-eligible bot in the [Rumble](index.md) catalog. + +## Requirements + +- Your bot must be built on an **official Tank Royale Bot API** (Java, C#, Python, or TypeScript). Custom frameworks or hand-rolled protocol implementations are not eligible for ranked Rumble — see [the APIs](../api/apis.md) if you haven't built a bot yet, and the [tutorial](../tutorial/getting-started.md) for a walkthrough. +- Bots run **directly from source**, exactly like the [sample bots](../articles/installing-sample-bots.md) — nothing is precompiled or uploaded as a binary. +- Your bot's platform-specific dependencies are limited to the official Bot API package plus the standard library (for TypeScript: the official npm package with a committed lockfile). + +## 1. Write your bot + +Develop and test it locally against the sample bots first, using Robocode's normal [GUI battle setup](../articles/gui-battle-setup.md) — this is "practice mode": nothing you run locally is ever submitted anywhere. + +## 2. Lay it out for submission + +`rumble-bots` uses the same booter directory convention as any Tank Royale bot: a directory holding `.json` (booter config), `.sh` and `.cmd` (boot scripts), and your source. Copy [the bot submission template](https://github.com/robocode-dev/rumble-bots/blob/main/.github/PULL_REQUEST_TEMPLATE/bot-submission.md) into `bots///` in your fork of [`rumble-bots`](https://github.com/robocode-dev/rumble-bots). + +## 3. Declare a license + +Every bot needs an explicit license — add a `license` field with one of these SPDX identifiers to your bot's config JSON: `MIT`, `Apache-2.0`, `BSD-3-Clause`, or `GPL-3.0-or-later`. Submitting a PR certifies you have the right to publish the code under that license. + +## 4. Validate locally + +Run the validator before opening a PR, so you catch problems before CI does: + +```shell +python scripts/validate_bot.py --root . --owner --smoke +``` + +It checks your directory structure, that only source files are present, dependency allowlist compliance, and that the bot boots and connects the way the booter will run it. + +## 5. Open the pull request + +Open a PR against `rumble-bots`. Validation CI re-runs the same checks; a moderator then reviews the PR (first-time authors get a stricter look). Once merged, your bot is added to the generated `bots/index.json` catalog and enters ranked matchmaking. + +## Ownership and versioning, briefly + +- The first merged PR for a bot name **reserves that name for you**, identified by your forge account. Only your registered accounts can submit new versions of your own bots. +- Published versions are immutable — changing your source means bumping the version. Only the latest version of a bot stays in the ranked pool; older versions stay in history. +- Each owner has a limited number of active bot slots (5 at launch). Version bumps are free; a new bot name consumes a slot. + +Full submission, ownership, licensing, and moderation rules live in [`rumble-bots`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-bots/blob/main/CONTRIBUTING.md). + +## Next steps + +Once your bot is merged, watch it climb the [dashboard](https://robocode-dev.github.io/rumble-data/) as ranked battles run. Running a [client](client-guide.md) yourself gives your own bots priority in matchmaking. diff --git a/web/docs/rumble/client-guide.md b/web/docs/rumble/client-guide.md new file mode 100644 index 000000000..e3cc241ad --- /dev/null +++ b/web/docs/rumble/client-guide.md @@ -0,0 +1,48 @@ +# Battle contributor quickstart + +The Rumble client runs local ranked battles against the published [Rumble](index.md) catalog and submits every completed result automatically. This guide covers the [`rumble-client`](https://github.com/robocode-dev/rumble-client) repository as it stands today: there is no published container image or native release yet, so running it means building it from source. + +## 1. Register once + +Before a client can submit ranked results, its forge account must be registered. Open a pull request against [`rumble-data`](https://github.com/robocode-dev/rumble-data) adding `clients/.json`, whose `account` field matches the filename and whose `clientIds` lists the stable client identifier(s) you'll use. A moderator reviews this once; after it's merged, issues from your account and client ID are accepted. + +## 2. Build the client + +You need JDK 17 and a local Tank Royale checkout containing Runner support (BR-049) alongside your `rumble-client` checkout, then: + +```shell +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale build +``` + +On PowerShell, quote the property: `.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" build`. + +Alternatively, build the development Docker image: `docker build --tag rumble-client:dev .`, then drive it with `docker/rumble.sh` (or `docker/rumble.ps1`). The Docker launchers expose only your configuration file and state directory to the container, with a read-only root filesystem, dropped capabilities, resource limits, and no network for the runtime check — this is the isolation boundary for running bot code you didn't write, including your ranked opponents' bots. + +Run `./gradlew run --args="--check-runtimes"` to confirm you have Java 17, .NET 8 SDK, Python 3.12, and Node.js 22 available; it never installs anything for you. + +## 3. Configure + +Copy `rumble-client.example.json` to `rumble-client.json`. Ranked mode requires your registered `clientId`; practice mode may omit it. The optional `workDirectory` sets where the local cache, journal, and replay evidence live (default `.rumble-client` next to the config file). Never commit `rumble-client.json` or any token. + +## 4. Sync, run, submit + +```shell +./gradlew run --args="--validate-config" # check local settings +./gradlew run --args="--sync" # resolve the catalog, engine pin, and matchmaking advice +./gradlew run --args="--run" # run one pinned ranked battle, keep local replay evidence +./gradlew run --args="--submit" # post pending results to the rumble-data issue inbox +``` + +`--sync` validates the engine pin and your client registration and prepares an immutable, hash-verified bot cache at the catalog's exact source commit. `--run` selects a battle using a recorded random seed, prioritizing under-sampled pairings involving your own bots. `--submit` reads a `RUMBLE_CLIENT_TOKEN` environment variable at runtime — use a GitHub fine-grained personal access token scoped to read/write Issues on `rumble-data` only, nothing else. The client tracks posted batches locally and only drops them once their receipt comment appears on the closed issue; an identical retry is acknowledged idempotently rather than double-submitted. + +## Practice vs. ranked + +Practice runs never create a ranked record or submission — use them freely while developing. Ranked runs require your registered `clientId` and always attempt submission. + +## What happens after you submit + +Your batch becomes a GitHub issue on `rumble-data` labelled `result-submission`. An automated workflow validates each result independently, commits accepted ones as immutable JSON facts, regenerates the leaderboard and pairings, comments a receipt on the issue, and closes it. The full contract — envelope shape, per-participant fields, and rejection reasons — is in [`rumble-data`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-data/blob/main/CONTRIBUTING.md). Back up your `workDirectory`'s replay evidence yourself; `rumble-data` never stores replays. + +## Next steps + +Back your battle contributions with your own bots — see [Submit a bot](bot-author-guide.md) — and watch results land on the [dashboard](https://robocode-dev.github.io/rumble-data/). diff --git a/web/docs/rumble/index.md b/web/docs/rumble/index.md new file mode 100644 index 000000000..c2004b504 --- /dev/null +++ b/web/docs/rumble/index.md @@ -0,0 +1,19 @@ +# Tank Royale Rumble + +Rumble is the community ranked ladder for Tank Royale. Bots live in a public, reviewed catalog, contributors run local clients that fight ranked battles and submit results automatically, and a static dashboard tracks rankings from those results. + +Rumble runs entirely on GitHub across three repositories, with no central server and no secrets to operate: [`rumble-bots`](https://github.com/robocode-dev/rumble-bots) (the bot catalog), [`rumble-data`](https://github.com/robocode-dev/rumble-data) (results and rankings), and [`rumble-client`](https://github.com/robocode-dev/rumble-client) (the battle runner contributors use). + +## Get started + +- **[Submit a bot](bot-author-guide.md)** — write a bot with an official Bot API, get it reviewed, and enter it into the ranked pool. +- **[Run battles](client-guide.md)** — pull the client, register once, and fight ranked battles that submit themselves. +- **[Moderate](moderator-guide.md)** — review submissions and keep the ladder healthy. + +## Rankings + +The live leaderboard, pairings, and every ranked result are published from [`rumble-data`](https://github.com/robocode-dev/rumble-data): see the [dashboard](https://robocode-dev.github.io/rumble-data/). + +## Current status + +Rumble supports the **1v1**, **TwinDuel** (2v2), and **Melee** ranked formats. The client is still pre-release: there is no published container image or native distribution yet, so running battles today means building the client from source. See [Run battles](client-guide.md) for the exact steps. diff --git a/web/docs/rumble/moderator-guide.md b/web/docs/rumble/moderator-guide.md new file mode 100644 index 000000000..cd41ed737 --- /dev/null +++ b/web/docs/rumble/moderator-guide.md @@ -0,0 +1,24 @@ +# Moderator quickstart + +[Rumble](index.md) moderation happens entirely through pull-request review and a few reviewable JSON files — there is no separate moderation tool. This page covers the moderator role as it exists today; each repository's own `GOVERNANCE.md` is the authoritative reference. + +## What you review + +- **Bot submissions** in [`rumble-bots`](https://github.com/robocode-dev/rumble-bots) — validation CI must be green before you look; review focuses on structure, the declared SPDX license, and anything the forbidden-API scan flagged (a flag is advisory, not an auto-reject — false positives happen). First-time authors get a stricter look; established authors with clean history may qualify for auto-merge on version bumps of their own bots. +- **Client registrations** and other ordinary code or policy changes in [`rumble-data`](https://github.com/robocode-dev/rumble-data) — one moderator approval merges a `clients/.json` addition or any other reviewable change; CI is the only writer of accepted results and generated projections on `main`. + +Full submission and review rules: [`rumble-bots`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-bots/blob/main/CONTRIBUTING.md) and [`GOVERNANCE.md`](https://github.com/robocode-dev/rumble-bots/blob/main/GOVERNANCE.md). + +## Handling problems + +Everything below is a pull request against the relevant repository, explained in that PR's description — there's no hidden admin surface. + +- **Dispute a result** — add its `battleId` to `rumble-data`'s `exclusions.json`. Aggregation omits it from the leaderboard while keeping the fact itself, so the audit trail never disappears. +- **Ban an account** — add it to `rumble-data`'s `bans.json` (blocks future submissions and quarantines past ones on the next aggregation) and, if the account owns bots, flip them to `disqualified` via `rumble-bots`'s governance process. Bans can be temporary or permanent; nothing is deleted, so lifting a ban restores everything on the next recompute. +- **Confusable or suspicious bot names** — the validator flags near-duplicate skeletons (leetspeak and Unicode-confusable folding) automatically; use judgment on whether it's imitation or coincidence. + +## Operations + +`rumble-data`'s ingestion workflow is triggered by labelled issues and a schedule; if scheduled workflows go dormant after inactivity, re-enable them (an incoming labelled issue also wakes the system). Monthly, the first drain compacts facts older than three months into rollups and archives the individual records. Quarterly, moderators run the fork drill: fork the repository, enable its workflows and Pages, run aggregation locally, and record the result — this is what keeps the system's bus-factor promise honest. Details: [`rumble-data`'s `GOVERNANCE.md`](https://github.com/robocode-dev/rumble-data/blob/main/GOVERNANCE.md). + +There is not yet a standalone moderator handbook beyond each repository's `GOVERNANCE.md` — if you're stepping into this role, those two files plus this page are the complete current reference. From 9ba12ca8fcd2a39ec6180d05a0c9a8157238f2b6 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 22:49:10 +0200 Subject: [PATCH 3/9] docs(CH-034): digest Rumble documentation Mark P-003/M-009 done and P-003 completed (its last open milestone), regenerate the plans README index, and delete the change workspace. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- changes/CH-033-rumble-docs/open-questions.md | 11 ------ changes/CH-033-rumble-docs/proposal.md | 41 -------------------- changes/CH-033-rumble-docs/tasks.md | 21 ---------- docs/plans/P-003-rumble.md | 6 ++- docs/plans/README.md | 2 +- 5 files changed, 5 insertions(+), 76 deletions(-) delete mode 100644 changes/CH-033-rumble-docs/open-questions.md delete mode 100644 changes/CH-033-rumble-docs/proposal.md delete mode 100644 changes/CH-033-rumble-docs/tasks.md diff --git a/changes/CH-033-rumble-docs/open-questions.md b/changes/CH-033-rumble-docs/open-questions.md deleted file mode 100644 index 502488f8c..000000000 --- a/changes/CH-033-rumble-docs/open-questions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: CH-033-open-questions -type: open-questions -status: open -links: [CH-033] -title: Open questions for CH-033 ---- - -# CH-033 — Open questions - -No contract question is open. The design doc (`docs/design/rumble/user-documentation.md`) describes a fuller document set than M-009 promises; this change deliberately ships only the plan's literal commitment (one quickstart per audience) and records that boundary in the proposal's Non-goals, rather than treating it as a blocking question. diff --git a/changes/CH-033-rumble-docs/proposal.md b/changes/CH-033-rumble-docs/proposal.md deleted file mode 100644 index 441e484f0..000000000 --- a/changes/CH-033-rumble-docs/proposal.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: CH-033 -type: change -status: open -links: [P-003, M-009, CAP-014, CAP-015, CAP-016] -title: Publish Rumble user documentation ---- - -# CH-033 — Publish Rumble user documentation - -## What - -Publish one quickstart per Rumble audience — bot author, battle contributor, moderator — under `web/docs/rumble/`, wired into the Tank Royale docs site navigation. - -## Why - -P-003/M-009 is the last open milestone in the Rumble plan. M-005 through M-008 and M-010 are all done, and PDR-005 deliberately sequenced M-009 after M-010 (GUI TwinDuel), which has since shipped in 1.1.0. The three Rumble repositories (`rumble-bots`, `rumble-data`, `rumble-client`) and the GUI are functioning, but nothing tells a newcomer how to participate. - -## Route - -Recommended route: full. Publishing these guides fulfills a plan promise (M-009 moves from `todo` to `done`), which is an accepted-contract change under the routing rule even though no acceptance criterion or capability changes. Discovery would change the route only if the guides turn out to require no plan bookkeeping change at all, which is not the case here. - -## Plan - -Serves [P-003/M-009](../../docs/plans/P-003-rumble.md). No CAP-014/015/016 acceptance criterion changes; the guides describe existing, already-accepted behavior. - -## Scope - -- `web/docs/rumble/bot-author-guide.md` — quickstart from template to a merged, ranked-eligible bot in `rumble-bots`: official Bot API requirement, SPDX license field, local `validate_bot.py` run, PR flow, ownership/versioning basics, slots. -- `web/docs/rumble/client-guide.md` — quickstart for running the Rumble client: one-time client registration PR in `rumble-data`, build/Docker-dev-image instructions reflecting the client's actual current state (no published release or production image yet), configuration, practice vs. ranked mode, submitting results. -- `web/docs/rumble/moderator-guide.md` — quickstart for the moderator role as it exists today: reviewing bot and client-registration PRs, using `bans.json`/`exclusions.json`/`disqualifiedBots`, and links to each repository's own `GOVERNANCE.md` as the authoritative operations reference (no separate `rumble-data/docs/moderator-handbook.md` exists yet, so this guide does not claim one does). -- `web/docs/rumble/index.md` — short landing page linking the three guides and the live dashboard, so the docs site has one entry point. -- Wire the four pages into `web/docs/.vitepress/config.mts` (nav + sidebar section). -- Update `docs/plans/P-003-rumble.md` to mark M-009 done, with evidence, in the digest. - -## Non-goals - -- A full `rumble-data/docs/moderator-handbook.md`, a separate `onboarding.md`, or a `faq.md` — the design doc's fuller document set (`docs/design/rumble/user-documentation.md`) remains the aspirational target; this change ships only the plan's literal M-009 commitment (one quickstart per audience). -- Any change to `rumble-bots`, `rumble-data`, or `rumble-client` repository content. -- Claiming a published client container, native release, or production Docker image exists — the client guide describes the real current build/run path. -- New or changed acceptance criteria, capabilities, or ADRs. diff --git a/changes/CH-033-rumble-docs/tasks.md b/changes/CH-033-rumble-docs/tasks.md deleted file mode 100644 index 00ccf03d7..000000000 --- a/changes/CH-033-rumble-docs/tasks.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: CH-033-tasks -type: tasks -status: open -links: [CH-033] -title: Task breakdown for CH-033 ---- - -# CH-033 — Tasks - -- [x] Reserve CH-033 and branch from the accepted tip of `main` -- [x] Confirm M-009's scope, dependencies (PDR-005), and the real current state of `rumble-bots`, `rumble-data`, `rumble-client` -- [x] Capture the full-route proposal and selected documentation scope -- [x] Commit and push the proposal, then open the required draft PR before implementation -- [x] Write `web/docs/rumble/bot-author-guide.md` -- [x] Write `web/docs/rumble/client-guide.md` -- [x] Write `web/docs/rumble/moderator-guide.md` -- [x] Write `web/docs/rumble/index.md` -- [x] Wire the four pages into `web/docs/.vitepress/config.mts` nav and sidebar -- [x] Build the docs site locally and confirm the new pages render and navigate correctly -- [ ] Digest: mark M-009 done in `docs/plans/P-003-rumble.md` with evidence, delete the change workspace diff --git a/docs/plans/P-003-rumble.md b/docs/plans/P-003-rumble.md index d3c4b8c82..111330af4 100644 --- a/docs/plans/P-003-rumble.md +++ b/docs/plans/P-003-rumble.md @@ -1,7 +1,7 @@ --- id: P-003 type: plan -status: active +status: completed links: [G-001] title: Tank Royale Rumble provenance: inferred @@ -21,6 +21,8 @@ The milestones mirror the design's Change Proposal Roadmap in order. Each milest | M-007 | `rumble-data` repository live | Result inbox drained by CI into immutable raw facts; aggregation produces leaderboard, pairings, and matches-needed projections; dashboard published on Pages | done | CH-011; [robocode-dev/rumble-data#4](https://github.com/robocode-dev/rumble-data/pull/4) merged on 2026-08-03, providing catalog synchronization and ranked advice for every V1 game type | | M-008 | Rumble client runs ranked battles | After the official Tank Royale 1.1.0 release, the client pulls the bot catalog and matchmaking advice, runs a ranked battle, and its submitted result lands in `rumble-data` via issue-ops with no human in the loop | done | CH-032; [rumble-data#11](https://github.com/robocode-dev/rumble-data/issues/11) accepted the client journal and `f25c02f20e2938545563a0d2a017e53e9a208a7e` published its immutable facts and projections | | M-010 | GUI supports TwinDuel | The GUI game-type dialog can select and start the `TwinDuel` preset using the common game-type contract; it is shipped in Tank Royale 1.1.0 | done | CH-013; CAP-017/GTD-001 and GUI acceptance evidence | -| M-009 | Rumble documentation published | User guides live under `/web/docs/rumble/` with one quickstart per audience: bot author, battle contributor, moderator | todo | | +| M-009 | Rumble documentation published | User guides live under `/web/docs/rumble/` with one quickstart per audience: bot author, battle contributor, moderator | done | CH-033; `web/docs/rumble/{bot-author-guide,client-guide,moderator-guide,index}.md`, wired into the VitePress nav and sidebar | M-006 and M-007 both depend only on M-005 and may proceed in parallel; M-008 depends on the `rumble-bots` catalog, the `rumble-data` engine/matchmaking files, the official Tank Royale 1.1.0 release, and merged BR-049 Runner support available through a local build during development; distributing the ranked client depends on a published Battle Runner artifact containing BR-049. M-010 depends only on M-005's common game-type contract and is shipped in Tank Royale 1.1.0; M-009 follows the settled client and GUI interfaces. + +All six milestones are done: P-003 is complete. Rumble's fuller published document set described in [`docs/design/rumble/user-documentation.md`](../design/rumble/user-documentation.md) — a separate `rumble-data` moderator handbook, an `onboarding.md`, and a `faq.md` — remains a candidate for future work but is not a plan promise; nothing here blocks it. diff --git a/docs/plans/README.md b/docs/plans/README.md index f967dcfbe..d4d05db08 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -9,5 +9,5 @@ Every change proposal names the plan item it serves, or explicitly declares itse - [P-001 — Cliewen adoption](P-001-cliewen-adoption.md) · `active` - [P-002 — TypeScript Bot API reaches npm](P-002-typescript-bot-api-npm.md) · `completed` -- [P-003 — Tank Royale Rumble](P-003-rumble.md) · `active` +- [P-003 — Tank Royale Rumble](P-003-rumble.md) · `completed` From e49b42c02f550c1e8f1bc0fa2d136b4205cfb774 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 22:50:03 +0200 Subject: [PATCH 4/9] docs(CH-034): reconcile design overview with shipped M-009 scope Note in ARCH-025 that the shipped quickstarts diverge deliberately from the design's fuller aspirational document set (moderator handbook, onboarding.md, faq.md remain future work). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- docs/design/rumble/user-documentation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/design/rumble/user-documentation.md b/docs/design/rumble/user-documentation.md index 08d32fd1d..0cc79eddf 100644 --- a/docs/design/rumble/user-documentation.md +++ b/docs/design/rumble/user-documentation.md @@ -13,6 +13,8 @@ reversal-cost: low > **Status: DRAFT** - design direction captured. > Part of the [Tank Royale Rumble umbrella design](./README.md). +**Implementation note (CH-033, P-003/M-009):** the plan promised one quickstart per audience under `/web/docs/rumble/`, which now exists as `bot-author-guide.md`, `client-guide.md`, `moderator-guide.md`, and an `index.md` landing page. The moderator guide lives under `/web/docs/rumble/` rather than as a separate `rumble-data/docs/moderator-handbook.md`, since no such handbook exists yet; it links to each repository's `GOVERNANCE.md` instead. `onboarding.md` and `faq.md` below remain aspirational — folded into the shipped guides for now, not yet split out as their own documents. + ## Scope The documentation the rumble ships for its users: what documents exist, who they serve, where they live, and the onboarding journeys they support. The other design documents describe how the system works; this one describes how a person finds out what to do. Documentation is participation infrastructure: every workflow that lacks a guide costs participants, and the rumble's health is measured in participants. From 2ffca034775d83aaf62b93cc15d3707be21ee1f4 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 22:53:05 +0200 Subject: [PATCH 5/9] docs(CH-034): apply review advisories to Rumble docs Use idiomatic VitePress directory-index links (/rumble/ instead of /rumble/index) and avoid the "2v2" phrasing docs/design/rumble/README.md asks writers to avoid for TwinDuel. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- web/docs/.vitepress/config.mts | 4 ++-- web/docs/rumble/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/web/docs/.vitepress/config.mts b/web/docs/.vitepress/config.mts index 042a51c99..d3f17db03 100644 --- a/web/docs/.vitepress/config.mts +++ b/web/docs/.vitepress/config.mts @@ -28,7 +28,7 @@ export default withMermaid(defineConfig({ { text: 'Articles', link: '/articles/intro' }, { text: 'Tutorial', link: '/tutorial/getting-started' }, { text: 'API', link: '/api/apis' }, - { text: 'Rumble', link: '/rumble/index' } + { text: 'Rumble', link: '/rumble/' } ], sidebar: [ @@ -108,7 +108,7 @@ export default withMermaid(defineConfig({ { text: 'Rumble', items: [ - { text: 'Overview', link: '/rumble/index' }, + { text: 'Overview', link: '/rumble/' }, { text: 'Bot Author Quickstart', link: '/rumble/bot-author-guide' }, { text: 'Battle Contributor Quickstart', link: '/rumble/client-guide' }, { text: 'Moderator Quickstart', link: '/rumble/moderator-guide' }, diff --git a/web/docs/rumble/index.md b/web/docs/rumble/index.md index c2004b504..ca54b47ca 100644 --- a/web/docs/rumble/index.md +++ b/web/docs/rumble/index.md @@ -16,4 +16,4 @@ The live leaderboard, pairings, and every ranked result are published from [`rum ## Current status -Rumble supports the **1v1**, **TwinDuel** (2v2), and **Melee** ranked formats. The client is still pre-release: there is no published container image or native distribution yet, so running battles today means building the client from source. See [Run battles](client-guide.md) for the exact steps. +Rumble supports the **1v1**, **TwinDuel** (twin-team), and **Melee** ranked formats. The client is still pre-release: there is no published container image or native distribution yet, so running battles today means building the client from source. See [Run battles](client-guide.md) for the exact steps. From 59e5c442773f5ab6809e721850a66fb166ca8fe8 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 23:05:37 +0200 Subject: [PATCH 6/9] docs(CH-034): remove internal AC reference from public client guide BR-049 is an internal Battle Runner acceptance-criterion identity that means nothing to end users. Replace it with a plain-language description of what the local Tank Royale checkout needs to contain. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- web/docs/rumble/client-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/docs/rumble/client-guide.md b/web/docs/rumble/client-guide.md index e3cc241ad..ea457dc7d 100644 --- a/web/docs/rumble/client-guide.md +++ b/web/docs/rumble/client-guide.md @@ -8,7 +8,7 @@ Before a client can submit ranked results, its forge account must be registered. ## 2. Build the client -You need JDK 17 and a local Tank Royale checkout containing Runner support (BR-049) alongside your `rumble-client` checkout, then: +You need JDK 17 and a local Tank Royale checkout (the Battle Runner support Rumble needs is on `main`, not yet in an official release) alongside your `rumble-client` checkout, then: ```shell ./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale build From a88d0f122bbff8f7fab164c5114a8818713b6aa8 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Thu, 3 Sep 2026 23:49:06 +0200 Subject: [PATCH 7/9] docs(CH-034): point client guide at rumble-client's README, not duplicate it Trim the battle-contributor quickstart to the one step that happens in a different repository (client registration in rumble-data) and hand off to the rumble-client README for everything else, so build and run instructions live in one place next to the code they describe (robocode-dev/rumble-client#9 rewrites that README as a complete, working Docker quickstart and closes a real gap where the hardened launchers never grew --run/--submit support). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A2CS5LTRShejMcfuWrGh1H --- web/docs/rumble/client-guide.md | 39 +++------------------------------ web/docs/rumble/index.md | 2 +- 2 files changed, 4 insertions(+), 37 deletions(-) diff --git a/web/docs/rumble/client-guide.md b/web/docs/rumble/client-guide.md index ea457dc7d..3b804dbbb 100644 --- a/web/docs/rumble/client-guide.md +++ b/web/docs/rumble/client-guide.md @@ -1,47 +1,14 @@ # Battle contributor quickstart -The Rumble client runs local ranked battles against the published [Rumble](index.md) catalog and submits every completed result automatically. This guide covers the [`rumble-client`](https://github.com/robocode-dev/rumble-client) repository as it stands today: there is no published container image or native release yet, so running it means building it from source. +The Rumble client runs local ranked battles against the published [Rumble](index.md) catalog and submits every completed result automatically. Full setup and usage instructions live in the [`rumble-client` README](https://github.com/robocode-dev/rumble-client#tank-royale-rumble-client) — that's the single source of truth for running the client, kept next to its own Dockerfile and launcher scripts so it never drifts from what's actually there. This page covers the one step that happens in a different repository, then hands you off. ## 1. Register once Before a client can submit ranked results, its forge account must be registered. Open a pull request against [`rumble-data`](https://github.com/robocode-dev/rumble-data) adding `clients/.json`, whose `account` field matches the filename and whose `clientIds` lists the stable client identifier(s) you'll use. A moderator reviews this once; after it's merged, issues from your account and client ID are accepted. -## 2. Build the client +## 2. Build, configure, and run -You need JDK 17 and a local Tank Royale checkout (the Battle Runner support Rumble needs is on `main`, not yet in an official release) alongside your `rumble-client` checkout, then: - -```shell -./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale build -``` - -On PowerShell, quote the property: `.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" build`. - -Alternatively, build the development Docker image: `docker build --tag rumble-client:dev .`, then drive it with `docker/rumble.sh` (or `docker/rumble.ps1`). The Docker launchers expose only your configuration file and state directory to the container, with a read-only root filesystem, dropped capabilities, resource limits, and no network for the runtime check — this is the isolation boundary for running bot code you didn't write, including your ranked opponents' bots. - -Run `./gradlew run --args="--check-runtimes"` to confirm you have Java 17, .NET 8 SDK, Python 3.12, and Node.js 22 available; it never installs anything for you. - -## 3. Configure - -Copy `rumble-client.example.json` to `rumble-client.json`. Ranked mode requires your registered `clientId`; practice mode may omit it. The optional `workDirectory` sets where the local cache, journal, and replay evidence live (default `.rumble-client` next to the config file). Never commit `rumble-client.json` or any token. - -## 4. Sync, run, submit - -```shell -./gradlew run --args="--validate-config" # check local settings -./gradlew run --args="--sync" # resolve the catalog, engine pin, and matchmaking advice -./gradlew run --args="--run" # run one pinned ranked battle, keep local replay evidence -./gradlew run --args="--submit" # post pending results to the rumble-data issue inbox -``` - -`--sync` validates the engine pin and your client registration and prepares an immutable, hash-verified bot cache at the catalog's exact source commit. `--run` selects a battle using a recorded random seed, prioritizing under-sampled pairings involving your own bots. `--submit` reads a `RUMBLE_CLIENT_TOKEN` environment variable at runtime — use a GitHub fine-grained personal access token scoped to read/write Issues on `rumble-data` only, nothing else. The client tracks posted batches locally and only drops them once their receipt comment appears on the closed issue; an identical retry is acknowledged idempotently rather than double-submitted. - -## Practice vs. ranked - -Practice runs never create a ranked record or submission — use them freely while developing. Ranked runs require your registered `clientId` and always attempt submission. - -## What happens after you submit - -Your batch becomes a GitHub issue on `rumble-data` labelled `result-submission`. An automated workflow validates each result independently, commits accepted ones as immutable JSON facts, regenerates the leaderboard and pairings, comments a receipt on the issue, and closes it. The full contract — envelope shape, per-participant fields, and rejection reasons — is in [`rumble-data`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-data/blob/main/CONTRIBUTING.md). Back up your `workDirectory`'s replay evidence yourself; `rumble-data` never stores replays. +Everything else — building the Docker image, configuring `rumble-client.json`, and running `validate` / `runtimes` / `sync` / `run` / `submit` — is in the [`rumble-client` README](https://github.com/robocode-dev/rumble-client#tank-royale-rumble-client). Follow its Quickstart in order; it's the same one whether you got here from this page or found the repository directly. ## Next steps diff --git a/web/docs/rumble/index.md b/web/docs/rumble/index.md index ca54b47ca..9ddde6e5f 100644 --- a/web/docs/rumble/index.md +++ b/web/docs/rumble/index.md @@ -16,4 +16,4 @@ The live leaderboard, pairings, and every ranked result are published from [`rum ## Current status -Rumble supports the **1v1**, **TwinDuel** (twin-team), and **Melee** ranked formats. The client is still pre-release: there is no published container image or native distribution yet, so running battles today means building the client from source. See [Run battles](client-guide.md) for the exact steps. +Rumble supports the **1v1**, **TwinDuel** (twin-team), and **Melee** ranked formats. The client is still pre-release: there is no published container image on a registry yet, so running battles today means building the image yourself with `docker build`. See [Run battles](client-guide.md) for the exact steps. From d418237f62de740d762b3beba373397e74120f2a Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Fri, 4 Sep 2026 21:59:37 +0200 Subject: [PATCH 8/9] docs(CH-034): improve Rumble onboarding guides --- web/docs/rumble/bot-author-guide.md | 121 +++++++++++++++++----- web/docs/rumble/client-guide.md | 149 ++++++++++++++++++++++++++-- web/docs/rumble/index.md | 76 ++++++++++++-- web/docs/rumble/moderator-guide.md | 65 +++++++++--- 4 files changed, 354 insertions(+), 57 deletions(-) diff --git a/web/docs/rumble/bot-author-guide.md b/web/docs/rumble/bot-author-guide.md index 876f52b38..2a340bbfe 100644 --- a/web/docs/rumble/bot-author-guide.md +++ b/web/docs/rumble/bot-author-guide.md @@ -1,47 +1,118 @@ -# Bot author quickstart +# Submit a bot to the Rumble -This is the fastest path from nothing to a ranked-eligible bot in the [Rumble](index.md) catalog. +This guide takes a bot that already works in Tank Royale and puts it into the [Rumble](index.md) ranked catalog. You need a GitHub account, Git, Python 3, and the runtimes used by the bots in your catalog checkout. CI has all four supported runtimes. -## Requirements +If you have not written a bot yet, start with the [Tank Royale tutorial](../tutorial/getting-started.md) and the list of [official Bot APIs](../api/apis.md). Test the bot against sample bots with the normal [GUI battle setup](../articles/gui-battle-setup.md) before submitting it. Local GUI battles are private practice; they never affect the Rumble rankings. -- Your bot must be built on an **official Tank Royale Bot API** (Java, C#, Python, or TypeScript). Custom frameworks or hand-rolled protocol implementations are not eligible for ranked Rumble — see [the APIs](../api/apis.md) if you haven't built a bot yet, and the [tutorial](../tutorial/getting-started.md) for a walkthrough. -- Bots run **directly from source**, exactly like the [sample bots](../articles/installing-sample-bots.md) — nothing is precompiled or uploaded as a binary. -- Your bot's platform-specific dependencies are limited to the official Bot API package plus the standard library (for TypeScript: the official npm package with a committed lockfile). +## Before you submit -## 1. Write your bot +Ranked bots must meet these rules: -Develop and test it locally against the sample bots first, using Robocode's normal [GUI battle setup](../articles/gui-battle-setup.md) — this is "practice mode": nothing you run locally is ever submitted anywhere. +- Use the official Tank Royale Bot API for Java, C#, Python, or TypeScript. +- Run directly from source through the normal Tank Royale booter scripts. +- Depend only on the official Bot API package and the platform's standard library. TypeScript bots must also commit their lockfile. +- Include no compiled programs, archives, generated dependency directories, custom protocol clients, process launchers, or raw socket code. +- Declare one of the permitted licenses: `MIT`, `Apache-2.0`, `BSD-3-Clause`, or `GPL-3.0-or-later`. -## 2. Lay it out for submission +The complete rules live in the [`rumble-bots` contribution guide](https://github.com/robocode-dev/rumble-bots/blob/main/CONTRIBUTING.md). -`rumble-bots` uses the same booter directory convention as any Tank Royale bot: a directory holding `.json` (booter config), `.sh` and `.cmd` (boot scripts), and your source. Copy [the bot submission template](https://github.com/robocode-dev/rumble-bots/blob/main/.github/PULL_REQUEST_TEMPLATE/bot-submission.md) into `bots///` in your fork of [`rumble-bots`](https://github.com/robocode-dev/rumble-bots). +## 1. Fork and clone the catalog -## 3. Declare a license +A fork is your own GitHub copy of a repository. A pull request, usually shortened to PR, asks the Rumble moderators to merge your changes into the public catalog. -Every bot needs an explicit license — add a `license` field with one of these SPDX identifiers to your bot's config JSON: `MIT`, `Apache-2.0`, `BSD-3-Clause`, or `GPL-3.0-or-later`. Submitting a PR certifies you have the right to publish the code under that license. +Fork [`robocode-dev/rumble-bots`](https://github.com/robocode-dev/rumble-bots), then clone your fork and create a branch: -## 4. Validate locally +```shell +git clone https://github.com//rumble-bots.git +cd rumble-bots +git switch -c add- +``` + +Replace the angle-bracket placeholders with your GitHub account and bot name. + +## 2. Add your bot source + +Copy your working bot into the folder for its language: + +```text +bots/ +└── / + └── / + ├── .json + ├── .sh + ├── .cmd + └── source files +``` + +Use `java`, `csharp`, `python`, or `typescript` for ``. The directory name, config filename, and bot `name` must match exactly. Existing entries in [`bots/`](https://github.com/robocode-dev/rumble-bots/tree/main/bots) are useful working examples. + +Add a `license` field to the bot's JSON configuration, for example: + +```json +{ + "name": "MyBot", + "version": "1.0.0", + "authors": ["Your name"], + "description": "What my bot does.", + "platform": "JVM", + "programmingLang": "Java 17", + "gameTypes": ["1v1", "melee", "twinduel"], + "license": "Apache-2.0" +} +``` -Run the validator before opening a PR, so you catch problems before CI does: +This example uses Java; keep the correct platform and language values from your working bot configuration. The license applies to the complete bot directory. By opening the PR, you certify that you have the right to publish the source under that license. + +## 3. Validate the submission + +Run the same validator used by CI: ```shell -python scripts/validate_bot.py --root . --owner --smoke +python scripts/validate_bot.py --root . --owner --smoke +``` + +The validator checks the directory layout, license, dependencies, source-only rules, ownership, and boot scripts. The smoke check also starts the source entry point. Fix every reported problem before opening the PR. + +## 4. Open the pull request + +Commit and push your branch, then open a PR against `robocode-dev/rumble-bots`: + +```shell +git add bots// +git commit -m "Add " +git push --set-upstream origin add- +``` + +Use the repository's bot-submission checklist in the PR description. CI runs the validator again, and a moderator reviews the submission. A green check is required, but it does not replace review. + +When the PR is merged, CI adds the bot to the generated catalog. `rumble-data` synchronizes that catalog at 23 minutes past every UTC hour. The bot then appears on the [dashboard](https://robocode-dev.github.io/rumble-data/) and waits for its first ranked battles. + +## Submit a TwinDuel team + +A TwinDuel team is its own catalog entry. Its `teamMembers` field contains exactly two member slots backed by active bot versions: + +```json +{ + "name": "MyTwinTeam", + "version": "1.0.0", + "authors": ["Your name"], + "license": "Apache-2.0", + "teamMembers": ["MyFirstBot 1.0.0", "MySecondBot 1.0.0"] +} ``` -It checks your directory structure, that only source files are present, dependency allowlist compliance, and that the bot boots and connects the way the booter will run it. +Put the team under one of the recognized platform folders. Its directory contains only `.json`; it has no source or boot scripts of its own. Both slots may name the same bot version for a true twin team. The slots may also name bots written with different Bot API languages, in which case the catalog publishes the team platform as `Mixed`. A team cannot contain another team, and every member must be an active individual bot. -## 5. Open the pull request +Member versions are part of the team identity. If either member gets a new version, submit a new team version that names the updated members. -Open a PR against `rumble-bots`. Validation CI re-runs the same checks; a moderator then reviews the PR (first-time authors get a stricter look). Once merged, your bot is added to the generated `bots/index.json` catalog and enters ranked matchmaking. +## Ownership, versions, and slots -## Ownership and versioning, briefly +The first merged PR for a bot or team name reserves that name for your GitHub account. Only that account, or another account registered to the same owner, may submit later versions. -- The first merged PR for a bot name **reserves that name for you**, identified by your forge account. Only your registered accounts can submit new versions of your own bots. -- Published versions are immutable — changing your source means bumping the version. Only the latest version of a bot stays in the ranked pool; older versions stay in history. -- Each owner has a limited number of active bot slots (5 at launch). Version bumps are free; a new bot name consumes a slot. +Published source versions are immutable. When the source changes, increase the version in the bot configuration and submit it again. The latest version becomes active; older results remain in history but no longer determine the current rank. -Full submission, ownership, licensing, and moderation rules live in [`rumble-bots`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-bots/blob/main/CONTRIBUTING.md). +Each owner may have five active catalog entries by default. An individual bot or a TwinDuel team each uses one slot. Updating an existing entry to a new version does not consume another slot. -## Next steps +## Help your bot get ranked -Once your bot is merged, watch it climb the [dashboard](https://robocode-dev.github.io/rumble-data/) as ranked battles run. Running a [client](client-guide.md) yourself gives your own bots priority in matchmaking. +New entries need battle samples before their ranking means much. Community clients prefer matchups with too few samples, so coverage improves automatically as contributors run battles. You can also [run a Rumble client](client-guide.md) and list your own entries in `myBots`; the client then gives useful matchups involving them priority. diff --git a/web/docs/rumble/client-guide.md b/web/docs/rumble/client-guide.md index 3b804dbbb..ca95c3f9f 100644 --- a/web/docs/rumble/client-guide.md +++ b/web/docs/rumble/client-guide.md @@ -1,15 +1,148 @@ -# Battle contributor quickstart +# Run ranked Rumble battles -The Rumble client runs local ranked battles against the published [Rumble](index.md) catalog and submits every completed result automatically. Full setup and usage instructions live in the [`rumble-client` README](https://github.com/robocode-dev/rumble-client#tank-royale-rumble-client) — that's the single source of truth for running the client, kept next to its own Dockerfile and launcher scripts so it never drifts from what's actually there. This page covers the one step that happens in a different repository, then hands you off. +The Rumble has no central machine running every fight. Community members donate computer time by running the Rumble client locally. The client downloads the reviewed bot catalog, chooses a useful matchup, runs the battle, keeps replay evidence on your computer, and submits the result for validation. -## 1. Register once +You do not need to own a bot to contribute battles. If you do own one, you can ask the client to prefer under-sampled matchups involving it. -Before a client can submit ranked results, its forge account must be registered. Open a pull request against [`rumble-data`](https://github.com/robocode-dev/rumble-data) adding `clients/.json`, whose `account` field matches the filename and whose `clientIds` lists the stable client identifier(s) you'll use. A moderator reviews this once; after it's merged, issues from your account and client ID are accepted. +## What works today -## 2. Build, configure, and run +The native client can synchronize, run one ranked battle, and submit its result. You currently build it from source because there is no published production client image. The development Docker image contains all four bot runtimes, but its launcher scripts currently expose only configuration validation, runtime checks, and synchronization. Use the native path below for ranked `run` and `submit` commands. -Everything else — building the Docker image, configuring `rumble-client.json`, and running `validate` / `runtimes` / `sync` / `run` / `submit` — is in the [`rumble-client` README](https://github.com/robocode-dev/rumble-client#tank-royale-rumble-client). Follow its Quickstart in order; it's the same one whether you got here from this page or found the repository directly. +The client accepts a practice-mode configuration, but `--run` currently executes ranked battles only. Use the [Tank Royale GUI](../articles/gui-battle-setup.md) for local practice battles. -## Next steps +## What you need -Back your battle contributions with your own bots — see [Submit a bot](bot-author-guide.md) — and watch results land on the [dashboard](https://robocode-dev.github.io/rumble-data/). +- A GitHub account. +- Git and JDK 17. +- Java 17, .NET 8 SDK, Python 3.12, and Node.js 22 if you run natively. The client may select bots from any supported language. +- Two sibling source checkouts: [`tank-royale`](https://github.com/robocode-dev/tank-royale) and [`rumble-client`](https://github.com/robocode-dev/rumble-client). + +The runtime check reports exactly what is missing and does not install or change anything. + +## 1. Register your client + +Each battle contributor registers once so result submissions can be tied to a GitHub account. Fork [`robocode-dev/rumble-data`](https://github.com/robocode-dev/rumble-data), then add `clients/.json`: + +```json +{ + "schemaVersion": 1, + "account": "your-github-account", + "clientIds": ["your-github-account-desktop-01"] +} +``` + +The filename and `account` must match your GitHub account exactly. Choose a stable `clientId` for each computer you plan to use. Open a PR with this file; a moderator reviews and merges it. Ranked submissions from that account and client ID are accepted after the registration reaches `main`. + +## 2. Build the client + +Clone the two repositories beside each other: + +```text +work/ +├── tank-royale/ +└── rumble-client/ +``` + +From `rumble-client`, build against the adjacent Tank Royale checkout. + +On Linux or macOS: + +```shell +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale build +``` + +On PowerShell: + +```powershell +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" build +``` + +## 3. Create your configuration + +Copy `rumble-client.example.json` to `rumble-client.json`, then edit the copy. Do not commit it. + +```json +{ + "schemaVersion": 1, + "botsRepo": "https://github.com/robocode-dev/rumble-bots", + "dataRepo": "https://github.com/robocode-dev/rumble-data", + "clientId": "your-github-account-desktop-01", + "myBots": ["MyBot"], + "gameTypes": ["1v1"], + "battlesPerSession": 50, + "mode": "ranked", + "workDirectory": ".rumble-client" +} +``` + +Use the registered ID from step 1. `myBots` may be empty; otherwise, list the names of your active bots or teams without version numbers. The client prioritizes useful matchups involving them. Set `gameTypes` to the format you want to run. During the current source-build phase, use one game type per configuration; each `--run` invocation runs one battle. + +`workDirectory` holds the bot cache, ranked journal, and replay evidence. Keep that directory private and backed up. + +## 4. Check and synchronize + +On Linux or macOS: + +```shell +./gradlew run --args="--check-runtimes" +./gradlew run --args="--validate-config" +./gradlew run --args="--sync" +``` + +On PowerShell: + +```powershell +.\gradlew.bat run --args="--check-runtimes" +.\gradlew.bat run --args="--validate-config" +.\gradlew.bat run --args="--sync" +``` + +Synchronization verifies your registration, the current engine behavior version, the catalog source hashes, and the matchmaking advice. It prepares an immutable local cache of the exact bot sources used for ranked battles. If synchronization refuses to continue, follow its diagnostic instead of bypassing the check. + +## 5. Run a ranked battle + +On Linux or macOS: + +```shell +./gradlew run --args="--run" +``` + +On PowerShell: + +```powershell +.\gradlew.bat run --args="--run" +``` + +The command chooses one valid matchup, runs all rounds for that game type, and appends the completed result to the local journal. An aborted, incomplete, or incompatible battle is not submittable. Replay evidence stays under `.rumble-client/evidence`; it is never uploaded automatically. + +## 6. Submit completed results + +Create a fine-grained GitHub personal access token limited to the `robocode-dev/rumble-data` repository with read and write access to Issues. It must not have permission to change repository contents, branches, releases, packages, or Pages. + +Supply the token only to the submission process. On Linux or macOS: + +```shell +export RUMBLE_CLIENT_TOKEN='' +./gradlew run --args="--submit" +unset RUMBLE_CLIENT_TOKEN +``` + +On PowerShell: + +```powershell +$env:RUMBLE_CLIENT_TOKEN = '' +.\gradlew.bat run --args="--submit" +Remove-Item Env:RUMBLE_CLIENT_TOKEN +``` + +The client posts pending journal records through the `rumble-data` issue inbox. The ingestion workflow validates each result, publishes accepted facts, and replies with receipts. Records remain retryable until the client observes their successful receipts, so an interrupted submission does not lose them. + +Never put the token in `rumble-client.json`, a shell script, Git, an issue, or a log. + +## Keep contributing + +Repeat `--run` to produce more battles and `--submit` to send pending results. You can change `gameTypes` between sessions. The client uses published matchmaking advice to cover new and under-sampled matchups; that advice is guidance rather than a reservation, so two clients may safely run the same matchup. + +Accepted results usually reach the [dashboard](https://robocode-dev.github.io/rumble-data/) within minutes. A scheduled ingestion sweep runs twice an hour if the immediate GitHub event is delayed. + +For command and implementation details, see the [`rumble-client` README](https://github.com/robocode-dev/rumble-client#tank-royale-rumble-client). diff --git a/web/docs/rumble/index.md b/web/docs/rumble/index.md index 9ddde6e5f..6113b673c 100644 --- a/web/docs/rumble/index.md +++ b/web/docs/rumble/index.md @@ -1,19 +1,75 @@ # Tank Royale Rumble -Rumble is the community ranked ladder for Tank Royale. Bots live in a public, reviewed catalog, contributors run local clients that fight ranked battles and submit results automatically, and a static dashboard tracks rankings from those results. +Writing a bot is one thing. Finding out how good it really is takes a lot of battles against a lot of opponents. -Rumble runs entirely on GitHub across three repositories, with no central server and no secrets to operate: [`rumble-bots`](https://github.com/robocode-dev/rumble-bots) (the bot catalog), [`rumble-data`](https://github.com/robocode-dev/rumble-data) (results and rankings), and [`rumble-client`](https://github.com/robocode-dev/rumble-client) (the battle runner contributors use). +Tank Royale Rumble is the community-run ranked competition for Robocode Tank Royale. It follows the tradition of RoboRumble and LiteRumble from classic Robocode: submit your bot, let it fight across the shared ladder, study the results, and come back with a better version. If you are serious about Robocoding, this is where you put your code to the test. -## Get started +You do not steer a tank during a Rumble battle. You write the program that controls it. Rumble clients run the battles automatically and publish the results, so rankings come from the same bot code fighting many different opponents. -- **[Submit a bot](bot-author-guide.md)** — write a bot with an official Bot API, get it reviewed, and enter it into the ranked pool. -- **[Run battles](client-guide.md)** — pull the client, register once, and fight ranked battles that submit themselves. -- **[Moderate](moderator-guide.md)** — review submissions and keep the ladder healthy. +## The Rumble loop -## Rankings +1. Build a bot with one of the official Tank Royale Bot APIs. +2. Practice locally in the Tank Royale GUI until your bot behaves the way you want. +3. Submit its source code to the reviewed Rumble bot catalog. +4. Community members run Rumble clients on their own computers. The clients choose useful matchups, run ranked battles, and submit the results. +5. The dashboard combines the accepted results into rankings. +6. Learn from the results, improve your bot, and submit a new version. -The live leaderboard, pairings, and every ranked result are published from [`rumble-data`](https://github.com/robocode-dev/rumble-data): see the [dashboard](https://robocode-dev.github.io/rumble-data/). +The cycle never really ends. A bot that dominates today may meet a smarter opponent tomorrow. -## Current status +## Choose how you want to participate -Rumble supports the **1v1**, **TwinDuel** (twin-team), and **Melee** ranked formats. The client is still pre-release: there is no published container image on a registry yet, so running battles today means building the image yourself with `docker build`. See [Run battles](client-guide.md) for the exact steps. +| I want to... | Start here | +|--------------|------------| +| Enter my bot in the rankings | [Submit a bot](bot-author-guide.md) | +| Donate computer time and run ranked battles | [Run a Rumble client](client-guide.md) | +| See which bots are winning | [Open the live dashboard](https://robocode-dev.github.io/rumble-data/) | +| Help review submissions and keep the competition fair | [Moderate the Rumble](moderator-guide.md) | + +You can submit a bot without running a client, and you can run a client without owning a bot. Many competitors do both because the client gives matchups involving their own bots priority when more samples are needed. + +## Ranked game types + +Each game type has its own leaderboard. + +| Game type | What fights | Rounds | Battlefield | +|-----------|-------------|--------|-------------| +| **1v1** | Two individual bots | 35 | 800 x 600 | +| **TwinDuel** | Two teams with two bots on each team | 75 | 800 x 800 | +| **Melee** | Ten individual bots at once | 35 | 1000 x 1000 | + +TwinDuel is the classic twin-team format, not a general team category. Mini, micro, nano, and other code-size classes from classic Robocode are not part of the Tank Royale Rumble because source-size limits do not compare cleanly across Java, C#, Python, and TypeScript. + +## How the system works + +The Rumble has three public GitHub repositories: + +- [`rumble-bots`](https://github.com/robocode-dev/rumble-bots) is the reviewed, source-only bot catalog. +- [`rumble-client`](https://github.com/robocode-dev/rumble-client) runs battles on contributors' computers. +- [`rumble-data`](https://github.com/robocode-dev/rumble-data) accepts results, calculates the rankings, and publishes the dashboard. + +There is no central battle server. Clients download the same pinned bot catalog and game settings, run battles locally, and send completed results through GitHub issues. Automation validates each result before it becomes part of the ranking data. The raw accepted results remain in Git, so the leaderboard can be rebuilt and checked by anyone. + +### Catalog + +The catalog is the list of bots and TwinDuel teams allowed in ranked battles. Every entry has an owner, a version, and a hash of its reviewed source. A new source version is a new ranked identity; only the latest active version appears on the current leaderboard. + +### Matchups and samples + +A matchup is a set of opponents that fought each other. One completed battle is one sample of that matchup. The client prefers new and under-sampled matchups, which helps new bots receive a meaningful rank and keeps older rankings fresh. + +### Rankings and APS + +The main ranking number is APS, or Average Percentage Score. For each matchup, Rumble calculates the percentage of the total score earned by a bot or team. It averages repeated battles of that matchup, then averages across all of the entry's matchups. Higher APS is better. + +A new bot or version starts with no battle samples, so its first position can move sharply. The ranking settles as it fights more opponents. When a game-observable engine change starts a new behavior version, the current leaderboard uses only results from that new epoch. Earlier results stay in the public data history, but they are not mixed with battles played under different rules. + +## When rankings update + +An incoming result submission starts the ingestion workflow as soon as GitHub applies its `result-submission` label. A scheduled sweep also runs at 17 and 47 minutes past every UTC hour in case an event was delayed. Accepted results regenerate the leaderboard, and GitHub Pages publishes the changed dashboard after the data commit. In normal operation, a result appears within minutes; the scheduled sweep is the fallback, not a guaranteed deadline. + +The bot catalog synchronizes at 23 minutes past every UTC hour. A newly merged bot normally reaches the dashboard after that synchronization, then waits for clients to produce its first ranked battles. + +## Current availability + +Bot submission, ranked battle execution, result ingestion, and the dashboard work end to end. The Rumble client does not yet have a published production container image, so battle contributors currently build it from source and use the native command line. The [client guide](client-guide.md) shows the exact supported path and calls out the parts of the Docker workflow that are still under development. diff --git a/web/docs/rumble/moderator-guide.md b/web/docs/rumble/moderator-guide.md index cd41ed737..6b0f94522 100644 --- a/web/docs/rumble/moderator-guide.md +++ b/web/docs/rumble/moderator-guide.md @@ -1,24 +1,61 @@ -# Moderator quickstart +# Moderate the Rumble -[Rumble](index.md) moderation happens entirely through pull-request review and a few reviewable JSON files — there is no separate moderation tool. This page covers the moderator role as it exists today; each repository's own `GOVERNANCE.md` is the authoritative reference. +Rumble moderators protect a fair, reviewable competition. They review bot submissions and client registrations, handle disputes, and keep the GitHub automation healthy. There is no hidden admin panel: moderation happens through pull requests and the policy files in `rumble-bots` and `rumble-data`. -## What you review +The repository policies remain authoritative. This guide explains the normal workflow and points to those policies when judgment is required. -- **Bot submissions** in [`rumble-bots`](https://github.com/robocode-dev/rumble-bots) — validation CI must be green before you look; review focuses on structure, the declared SPDX license, and anything the forbidden-API scan flagged (a flag is advisory, not an auto-reject — false positives happen). First-time authors get a stricter look; established authors with clean history may qualify for auto-merge on version bumps of their own bots. -- **Client registrations** and other ordinary code or policy changes in [`rumble-data`](https://github.com/robocode-dev/rumble-data) — one moderator approval merges a `clients/.json` addition or any other reviewable change; CI is the only writer of accepted results and generated projections on `main`. +## Review a bot submission -Full submission and review rules: [`rumble-bots`'s `CONTRIBUTING.md`](https://github.com/robocode-dev/rumble-bots/blob/main/CONTRIBUTING.md) and [`GOVERNANCE.md`](https://github.com/robocode-dev/rumble-bots/blob/main/GOVERNANCE.md). +Bot submissions arrive as pull requests in [`rumble-bots`](https://github.com/robocode-dev/rumble-bots). -## Handling problems +1. Wait for validation CI to pass. Never merge a submission with a failing check. +2. Confirm that the pull request changes only the author's bot or team entry and does not edit generated catalog files. +3. Check that the directory contains source rather than binaries, generated dependencies, archives, or unrelated files. +4. Confirm that the bot uses an official Bot API and declares an allowed SPDX license. +5. Review restricted-code diagnostics and suspicious or confusable names. Ask the author to resolve anything unclear before approval. +6. For an existing bot name, confirm that the submitting GitHub account owns it and that the version increased when source changed. +7. For a TwinDuel team, confirm that it has two member slots backed by active individual bot versions and contains only its team JSON. Repeated member identities are valid within one twin team. -Everything below is a pull request against the relevant repository, explained in that PR's description — there's no hidden admin surface. +First-time authors deserve a closer look. Owners with a history of clean submissions may qualify for auto-merge on later version bumps, as described in [`rumble-bots/GOVERNANCE.md`](https://github.com/robocode-dev/rumble-bots/blob/main/GOVERNANCE.md). -- **Dispute a result** — add its `battleId` to `rumble-data`'s `exclusions.json`. Aggregation omits it from the leaderboard while keeping the fact itself, so the audit trail never disappears. -- **Ban an account** — add it to `rumble-data`'s `bans.json` (blocks future submissions and quarantines past ones on the next aggregation) and, if the account owns bots, flip them to `disqualified` via `rumble-bots`'s governance process. Bans can be temporary or permanent; nothing is deleted, so lifting a ban restores everything on the next recompute. -- **Confusable or suspicious bot names** — the validator flags near-duplicate skeletons (leetspeak and Unicode-confusable folding) automatically; use judgment on whether it's imitation or coincidence. +## Review a client registration -## Operations +Client registrations arrive as pull requests in [`rumble-data`](https://github.com/robocode-dev/rumble-data). -`rumble-data`'s ingestion workflow is triggered by labelled issues and a schedule; if scheduled workflows go dormant after inactivity, re-enable them (an incoming labelled issue also wakes the system). Monthly, the first drain compacts facts older than three months into rollups and archives the individual records. Quarterly, moderators run the fork drill: fork the repository, enable its workflows and Pages, run aggregation locally, and record the result — this is what keeps the system's bus-factor promise honest. Details: [`rumble-data`'s `GOVERNANCE.md`](https://github.com/robocode-dev/rumble-data/blob/main/GOVERNANCE.md). +1. Confirm that the PR adds `clients/.json` and does not change result facts or generated projections. +2. Check that the filename and `account` exactly match the submitting GitHub account. +3. Check that `clientIds` is a non-empty list of stable, non-empty identifiers. +4. Require the Verify Rumble data workflow to pass. +5. Merge after one moderator approval. -There is not yet a standalone moderator handbook beyond each repository's `GOVERNANCE.md` — if you're stepping into this role, those two files plus this page are the complete current reference. +Ordinary code, catalog, ban, exclusion, and policy changes in `rumble-data` follow the same green-CI and one-approval rule. CI is the only writer of accepted facts and generated projections on `main`. + +## Handle disputes and abuse + +Every action below is a reviewed pull request with the reason recorded in its description. Preserve the facts; change whether they count. + +### Exclude a disputed result + +Add its `battleId` to `rumble-data/exclusions.json`. The next aggregation omits it from rankings without deleting the accepted fact. Removing the exclusion restores it on a later recomputation. + +### Ban an account + +Add the GitHub account to `rumble-data/bans.json`. Future submissions are rejected, and earlier facts from that account stop contributing when projections are regenerated. + +If the account owns catalog entries, update `rumble-bots/bots/banned.json` as well. The generated catalog excludes disqualified bots, but their existing result facts remain in history. Bans may be temporary or permanent. + +### Resolve a suspicious name or submission + +The validator detects identical normalized name skeletons and restricted code constructs. Treat the diagnostic as a reason to inspect the submission, not as proof of bad intent. Resolve impersonation, name squatting, unsafe code, licensing complaints, account recovery, and appeals under [`rumble-bots/GOVERNANCE.md`](https://github.com/robocode-dev/rumble-bots/blob/main/GOVERNANCE.md). + +## Keep the automation healthy + +Result submissions normally trigger ingestion when GitHub applies the `result-submission` label. A scheduled fallback runs at 17 and 47 minutes past every UTC hour. Catalog synchronization runs at 23 minutes past every UTC hour. The Pages workflow publishes dashboard changes after accepted data is pushed. + +If GitHub disables scheduled workflows after repository inactivity, re-enable them. A newly labelled result issue also wakes the ingestion workflow, but moderators should not rely on incoming traffic as the only health check. + +Once a month, follow the `rumble-data` compaction procedure for facts older than three full months. It must produce verified rollups without changing the generated projections before the individual facts move to the archive branch. + +Once each quarter, run the fork drill: fork the repositories, enable their workflows and Pages, run validation and aggregation locally, and record the result in a governance issue. The drill proves that another maintainer can recover the Rumble from its public repositories and documentation. + +Operational details and decision authority live in [`rumble-data/GOVERNANCE.md`](https://github.com/robocode-dev/rumble-data/blob/main/GOVERNANCE.md) and [`rumble-bots/GOVERNANCE.md`](https://github.com/robocode-dev/rumble-bots/blob/main/GOVERNANCE.md). From e7093c8551f8da082f4d70bcd81221b34ba609d0 Mon Sep 17 00:00:00 2001 From: "Flemming N. Larsen" Date: Sat, 5 Sep 2026 20:00:44 +0200 Subject: [PATCH 9/9] docs(CH-034): correct Rumble guide details found in review Six corrections to the shipped Rumble guides, each verified against the code or data that the guide describes: - Bot submission tree puts source under src/, matching the booter convention in the design and the boot scripts of the live catalog bots, which invoke "$SCRIPT_DIR/src/". - Team teamMembers name member directories, not "Name Version". BotBooter.bootTeamMember resolves each string with parentPath.resolve(botName) and BotIdentityReader treats it as a member directory name; the versioned form is what the generated catalog carries. The versioning paragraph is reworded to match. - Client guide carries -PtankRoyaleSource and --no-configuration-cache on every Gradle invocation, not only the build. Without the property the composite build is skipped and Gradle tries to resolve Battle Runner 1.2.0, which is unreleased, so --sync, --run and --submit all fail. - Client guide states the consequence of listing several game types: RumbleClient takes the alphabetically first entry, so a multi-type configuration silently runs only 1v1. Also notes that battlesPerSession is unused by the current commands. - Moderator ban procedure points at bannedAccounts and disqualifiedBots in rumble-data/bans.json. The previously named rumble-bots/bots/banned.json does not exist. - Removes long dashes from the two paragraphs this change added to P-003 and ARCH-025. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0132M9BMK7BuCAeCN31xBUNv --- docs/design/rumble/user-documentation.md | 2 +- docs/plans/P-003-rumble.md | 2 +- web/docs/rumble/bot-author-guide.md | 13 ++++++------ web/docs/rumble/client-guide.md | 26 ++++++++++++++---------- web/docs/rumble/moderator-guide.md | 4 ++-- 5 files changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/design/rumble/user-documentation.md b/docs/design/rumble/user-documentation.md index a7121be4a..148814296 100644 --- a/docs/design/rumble/user-documentation.md +++ b/docs/design/rumble/user-documentation.md @@ -13,7 +13,7 @@ reversal-cost: low > **Status: DRAFT** - design direction captured. > Part of the [Tank Royale Rumble umbrella design](./README.md). -**Implementation note (CH-034, P-003/M-009):** the plan promised one quickstart per audience under `/web/docs/rumble/`, which now exists as `bot-author-guide.md`, `client-guide.md`, `moderator-guide.md`, and an `index.md` landing page. The moderator guide lives under `/web/docs/rumble/` rather than as a separate `rumble-data/docs/moderator-handbook.md`, since no such handbook exists yet; it links to each repository's `GOVERNANCE.md` instead. `onboarding.md` and `faq.md` below remain aspirational — folded into the shipped guides for now, not yet split out as their own documents. +**Implementation note (CH-034, P-003/M-009):** the plan promised one quickstart per audience under `/web/docs/rumble/`, which now exists as `bot-author-guide.md`, `client-guide.md`, `moderator-guide.md`, and an `index.md` landing page. The moderator guide lives under `/web/docs/rumble/` rather than as a separate `rumble-data/docs/moderator-handbook.md`, since no such handbook exists yet; it links to each repository's `GOVERNANCE.md` instead. `onboarding.md` and `faq.md` below remain aspirational: folded into the shipped guides for now, not yet split out as their own documents. ## Scope diff --git a/docs/plans/P-003-rumble.md b/docs/plans/P-003-rumble.md index 808c69ba0..856ced21f 100644 --- a/docs/plans/P-003-rumble.md +++ b/docs/plans/P-003-rumble.md @@ -25,4 +25,4 @@ The milestones mirror the design's Change Proposal Roadmap in order. Each milest M-006 and M-007 both depend only on M-005 and may proceed in parallel; M-008 depends on the `rumble-bots` catalog, the `rumble-data` engine/matchmaking files, the official Tank Royale 1.1.0 release, and merged BR-049 Runner support available through a local build during development; distributing the ranked client depends on a published Battle Runner artifact containing BR-049. M-010 depends only on M-005's common game-type contract and is shipped in Tank Royale 1.1.0; M-009 follows the settled client and GUI interfaces. -All six milestones are done: P-003 is complete. Rumble's fuller published document set described in [`docs/design/rumble/user-documentation.md`](../design/rumble/user-documentation.md) — a separate `rumble-data` moderator handbook, an `onboarding.md`, and a `faq.md` — remains a candidate for future work but is not a plan promise; nothing here blocks it. +All six milestones are done: P-003 is complete. Rumble's fuller published document set described in [`docs/design/rumble/user-documentation.md`](../design/rumble/user-documentation.md) (a separate `rumble-data` moderator handbook, an `onboarding.md`, and a `faq.md`) remains a candidate for future work but is not a plan promise; nothing here blocks it. diff --git a/web/docs/rumble/bot-author-guide.md b/web/docs/rumble/bot-author-guide.md index 2a340bbfe..08953937a 100644 --- a/web/docs/rumble/bot-author-guide.md +++ b/web/docs/rumble/bot-author-guide.md @@ -41,10 +41,11 @@ bots/ ├── .json ├── .sh ├── .cmd - └── source files + └── src/ + └── source files ``` -Use `java`, `csharp`, `python`, or `typescript` for ``. The directory name, config filename, and bot `name` must match exactly. Existing entries in [`bots/`](https://github.com/robocode-dev/rumble-bots/tree/main/bots) are useful working examples. +Use `java`, `csharp`, `python`, or `typescript` for ``. The directory name, config filename, and bot `name` must match exactly. Source files belong under `src/`, and the boot scripts point at the entry point there, for example `"$SCRIPT_DIR/src/MyBot.py"`. Existing entries in [`bots/`](https://github.com/robocode-dev/rumble-bots/tree/main/bots) are useful working examples. Add a `license` field to the bot's JSON configuration, for example: @@ -89,7 +90,7 @@ When the PR is merged, CI adds the bot to the generated catalog. `rumble-data` s ## Submit a TwinDuel team -A TwinDuel team is its own catalog entry. Its `teamMembers` field contains exactly two member slots backed by active bot versions: +A TwinDuel team is its own catalog entry. Its `teamMembers` field contains exactly two member slots, each naming an active bot by its directory name: ```json { @@ -97,13 +98,13 @@ A TwinDuel team is its own catalog entry. Its `teamMembers` field contains exact "version": "1.0.0", "authors": ["Your name"], "license": "Apache-2.0", - "teamMembers": ["MyFirstBot 1.0.0", "MySecondBot 1.0.0"] + "teamMembers": ["MyFirstBot", "MySecondBot"] } ``` -Put the team under one of the recognized platform folders. Its directory contains only `.json`; it has no source or boot scripts of its own. Both slots may name the same bot version for a true twin team. The slots may also name bots written with different Bot API languages, in which case the catalog publishes the team platform as `Mixed`. A team cannot contain another team, and every member must be an active individual bot. +Put the team under one of the recognized platform folders. Its directory contains only `.json`; it has no source or boot scripts of its own. Both slots may name the same bot for a true twin team. The slots may also name bots written with different Bot API languages, in which case the catalog publishes the team platform as `Mixed`. A team cannot contain another team, and every member must be an active individual bot. -Member versions are part of the team identity. If either member gets a new version, submit a new team version that names the updated members. +The generated catalog entry records the exact member versions that were active when it was published, so member versions are part of the published team identity. Bump the team's own `version` whenever you change which bots it names. ## Ownership, versions, and slots diff --git a/web/docs/rumble/client-guide.md b/web/docs/rumble/client-guide.md index ca95c3f9f..5aab98f24 100644 --- a/web/docs/rumble/client-guide.md +++ b/web/docs/rumble/client-guide.md @@ -75,26 +75,30 @@ Copy `rumble-client.example.json` to `rumble-client.json`, then edit the copy. D } ``` -Use the registered ID from step 1. `myBots` may be empty; otherwise, list the names of your active bots or teams without version numbers. The client prioritizes useful matchups involving them. Set `gameTypes` to the format you want to run. During the current source-build phase, use one game type per configuration; each `--run` invocation runs one battle. +Use the registered ID from step 1. `myBots` may be empty; otherwise, list the names of your active bots or teams without version numbers. The client prioritizes useful matchups involving them. + +Set `gameTypes` to the single format you want to run. During the current source-build phase, list exactly one game type: `--run` picks the alphabetically first entry and runs that one, so listing several formats silently runs only `1v1` and never the others. To cover another format, change `gameTypes` and run again. Each `--run` invocation runs one battle; the example file's `battlesPerSession` is not used by the current commands. `workDirectory` holds the bot cache, ranked journal, and replay evidence. Keep that directory private and backed up. ## 4. Check and synchronize +Every Gradle invocation needs the same two arguments as the build in step 2. `-PtankRoyaleSource` is what makes the client compile and run against your adjacent Tank Royale checkout; without it Gradle tries to download a Battle Runner release that does not exist yet, and the command fails to resolve its dependencies. `--no-configuration-cache` is required because the project enables the configuration cache by default. + On Linux or macOS: ```shell -./gradlew run --args="--check-runtimes" -./gradlew run --args="--validate-config" -./gradlew run --args="--sync" +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale run --args="--check-runtimes" +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale run --args="--validate-config" +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale run --args="--sync" ``` On PowerShell: ```powershell -.\gradlew.bat run --args="--check-runtimes" -.\gradlew.bat run --args="--validate-config" -.\gradlew.bat run --args="--sync" +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" run --args="--check-runtimes" +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" run --args="--validate-config" +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" run --args="--sync" ``` Synchronization verifies your registration, the current engine behavior version, the catalog source hashes, and the matchmaking advice. It prepares an immutable local cache of the exact bot sources used for ranked battles. If synchronization refuses to continue, follow its diagnostic instead of bypassing the check. @@ -104,13 +108,13 @@ Synchronization verifies your registration, the current engine behavior version, On Linux or macOS: ```shell -./gradlew run --args="--run" +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale run --args="--run" ``` On PowerShell: ```powershell -.\gradlew.bat run --args="--run" +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" run --args="--run" ``` The command chooses one valid matchup, runs all rounds for that game type, and appends the completed result to the local journal. An aborted, incomplete, or incompatible battle is not submittable. Replay evidence stays under `.rumble-client/evidence`; it is never uploaded automatically. @@ -123,7 +127,7 @@ Supply the token only to the submission process. On Linux or macOS: ```shell export RUMBLE_CLIENT_TOKEN='' -./gradlew run --args="--submit" +./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale run --args="--submit" unset RUMBLE_CLIENT_TOKEN ``` @@ -131,7 +135,7 @@ On PowerShell: ```powershell $env:RUMBLE_CLIENT_TOKEN = '' -.\gradlew.bat run --args="--submit" +.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" run --args="--submit" Remove-Item Env:RUMBLE_CLIENT_TOKEN ``` diff --git a/web/docs/rumble/moderator-guide.md b/web/docs/rumble/moderator-guide.md index 6b0f94522..75c57603b 100644 --- a/web/docs/rumble/moderator-guide.md +++ b/web/docs/rumble/moderator-guide.md @@ -40,9 +40,9 @@ Add its `battleId` to `rumble-data/exclusions.json`. The next aggregation omits ### Ban an account -Add the GitHub account to `rumble-data/bans.json`. Future submissions are rejected, and earlier facts from that account stop contributing when projections are regenerated. +Add the GitHub account to `bannedAccounts` in `rumble-data/bans.json`. Future submissions are rejected, and earlier facts from that account stop contributing when projections are regenerated. -If the account owns catalog entries, update `rumble-bots/bots/banned.json` as well. The generated catalog excludes disqualified bots, but their existing result facts remain in history. Bans may be temporary or permanent. +If the account owns catalog entries, add those entries to `disqualifiedBots` in the same file. The generated catalog excludes disqualified bots, but their existing result facts remain in history. Bans may be temporary or permanent. ### Resolve a suspicious name or submission