# TODO **Items here that need a person** — hardware, an external account, a playtest, a design decision — are also tracked as GitHub issues under the [`needs:human`](https://github.com/jcreek/CosmicClash/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs%3Ahuman%22) label, prioritised `P0-blocker` → `P3-low`. The issue is the status; this document and `multiplayer-next.md` remain the detail. Agent-actionable code tasks are deliberately *not* filed as issues — they live in `multiplayer-next.md` §7. Deferred work, in rough priority order. The current architecture (ShipAction/ShipController seam, Arena/GameMode split, code-driven spawning, group-tagged ball/goals) was chosen specifically so these bolt on without rework. ## AI opponent (reinforcement learning) The training pipeline is built — see `TRAINING.md` (self-play PPO via the vendored godot_rl_agents bridge, JSON policy export, in-game GDScript inference, eval ladder). Remaining: - [ ] ([#24](https://github.com/jcreek/CosmicClash/issues/24)) Run the generation-5 handling/intercepts/league/teamplay curriculum described in `TRAINING.md`; promote later checkpoints as `medium`/`hard` only after they clear the match and behaviour gates. The orchestrator now requires three independent paired evaluation seeds for each promotion decision; the current Stage 6 league run remains blocked on its recorded regression/telemetry results. - [ ] ([#25](https://github.com/jcreek/CosmicClash/issues/25)) Extend generation 5's moving aerial-intercept states with wall plays and rebound scenarios after Stage 5 establishes a productive-air-touch baseline. The opt-in wall-play/rebound state generator is now implemented and enabled for the next Stage 6 league command; training evidence is still required. - [x] Design team-credit rewards and paired 2v2 evaluation before enabling the deferred teamplay stage. `team_touch_credit_weight` is zero by default and `evaluate.py --team-size=2` provides the opt-in paired evaluator; Stage 7 remains disabled pending recorded 2v2 behaviour gates. ## Presentation / AAA polish The largest gap between this and a AAA-feeling product is presentation, not code. Sequenced after the above for pragmatic reasons, but this is the highest impact per hour. - [ ] ([#26](https://github.com/jcreek/CosmicClash/issues/26)) **Audio — authored sound design remains open.** A dependency-free procedural `AudioManager` now provides safe UI/countdown/impact/goal hooks, an engine tone pitched/levelled from local thrust and turbo state plus a rising-edge turbo cue, and is wired into kickoff, goal, ball-contact, and menu events; replace the placeholder tones with authored engine/turbo/impact/wall/goal/crowd/music assets after selecting distributable files and mixing them on real hardware. - [ ] ([#27](https://github.com/jcreek/CosmicClash/issues/27)) **Custom font remains open.** A shared real `Theme` resource now styles the HUD/menu surfaces; select and bundle a distributable font so the UI no longer relies on `ThemeDB.fallback_font` at 10-13 px. - [ ] ([#28](https://github.com/jcreek/CosmicClash/issues/28)) **Video settings are implemented; profiling/visual QA remains.** `video_settings.gd` and the settings menu expose graphics presets, AA, vsync, FPS caps, resolution scaling, glow, and brightness, with preset-gated SDFGI/SSIL/SSAO/shadows. The remaining gate is measuring the preset ladder and image quality on low/mid-tier reference hardware in the live editor; no further control wiring is implied by this TODO. ## Multiplayer (long term) The single tracking document is **[`multiplayer-next.md`](multiplayer-next.md)** — architecture decisions, implementation evidence, and the current checklist all in one place. Server-authoritative multiplayer, prediction, ENet dedicated hosting, and the Phase 6 exported-server Docker/CI verification are implemented; the remaining gates are captured there. Phase 7 begins with optional GodotSteam bootstrap and a transport boundary; direct-IP ENet remains fully supported. Graphics controls are now implemented separately through the preset/vsync/FPS-cap/resolution-scale work described above; the remaining graphics gate is real low/mid-tier hardware profiling and visual QA (see §5.5 in the multiplayer tracker). **Tasks 0.1–0.15, 0.18–0.25, 0.27, 0.29 are done** (see the Phase 0 table in `multiplayer-next.md` for what each one actually changed — several deviated from the original plan for concrete GDScript/Godot reasons recorded inline). Remaining, all blocked on **0.15b (profile, on reference hardware, in the live editor — not done)**: 0.16 (camera to `_process`), 0.17/0.17b/0.17c/0.17d (graphics presets, vsync, resolution scaling), **0.26 (bake the arena GI to retire SDFGI — the largest frame-time win available, costs no image quality since the arena is fully static)**, and 0.28 (physics separate-thread prototype, flagged as the riskiest task in the phase). 0.15b is [#21](https://github.com/jcreek/CosmicClash/issues/21). These need a human at the editor with real hardware to profile and eyeball, not further code changes. - [ ] ([#29](https://github.com/jcreek/CosmicClash/issues/29)) Possible v0.2 split-screen: spawn one `ship_camera_rig` + viewport per local player (camera is already outside the ship scene to allow this). Unrelated to online play. ### What's left to actually finish multiplayer (human-actionable) Everything below needs a person — hardware, a design decision, an external account, or hands on a controller — not more code from an agent working alone. Full detail for each is linked; this list exists so nothing falls through the cracks. Ordered roughly as it blocks. Each item is also a GitHub issue (linked inline), labelled `needs:human` plus a `P0-blocker`…`P3-low` priority. Close the issue and tick the box together. **Priority labels say how much something matters; this says what to do first.** They differ: #33 is P2 but belongs before the P0 cluster, because standing the cluster up first means migrating a running one afterwards. #### Do these in order — each unblocks the next 1. **[#31](https://github.com/jcreek/CosmicClash/issues/31) — answer two questions.** Which registry namespace (`ghcr.io/cosmic-clash/*` is in every manifest and no such org exists), and whether packages are public (this repo is private and no manifest declares `imagePullSecrets`). Publishing needs no new credential. **This is the highest-leverage thing on the list**: two answers unblock the whole of Phase 8, and the work behind them is an agent's. 2. **[#33](https://github.com/jcreek/CosmicClash/issues/33) — split the game-server namespace.** Agent work, no decision owed. Before #17 rather than after, so the cluster is stood up on the final topology instead of being migrated later. 3. **[#17](https://github.com/jcreek/CosmicClash/issues/17) — stand up the cluster.** Needs #31's images to exist. Unblocks the production halves of most of Phase 8. 4. **[#32](https://github.com/jcreek/CosmicClash/issues/32) — casual backfill.** Mostly agent work; the design decision is already made. Needs #17 to verify a late roster reaching a running server. 5. **[#22](https://github.com/jcreek/CosmicClash/issues/22) — release gates.** Last: needs the cluster and the App ID. #### Steam, in parallel — long external lead time, start early 6. **[#15](https://github.com/jcreek/CosmicClash/issues/15) — App ID and publisher key.** Valve coordination, so the calendar time is theirs, not yours. The adapter is written and config-gated: sign-in returns 503 until both values are set. 7. **[#16](https://github.com/jcreek/CosmicClash/issues/16) — GodotSteam build templates.** The client-side ticket code is written and needs the custom build to run. #### Unblocked today — nothing is stopping these - **[#19](https://github.com/jcreek/CosmicClash/issues/19)** then **[#18](https://github.com/jcreek/CosmicClash/issues/18)**: the 3v3 gate is the cheaper session to arrange and exercises #18's latency conditions incidentally, so doing it first can settle both. **[#20](https://github.com/jcreek/CosmicClash/issues/20)** needs two machines and the internet, not a cluster. - **[#24](https://github.com/jcreek/CosmicClash/issues/24)** then **[#25](https://github.com/jcreek/CosmicClash/issues/25)**: training runs, independent of everything above. - **[#21](https://github.com/jcreek/CosmicClash/issues/21)**, **[#26](https://github.com/jcreek/CosmicClash/issues/26)**, **[#27](https://github.com/jcreek/CosmicClash/issues/27)**, **[#28](https://github.com/jcreek/CosmicClash/issues/28)**: hardware, audio, font, graphics QA. No dependencies, no ordering between them. - **[#23](https://github.com/jcreek/CosmicClash/issues/23)**, **[#29](https://github.com/jcreek/CosmicClash/issues/29)**: open design questions with no deadline. Neither blocks anything. - [x] ([#14](https://github.com/jcreek/CosmicClash/issues/14)) **Join-signing design decided and implemented.** Resolved as HMAC-SHA256 over the canonical claim bytes with a **key ID inside those bytes**: the allocator signs with one named key while allocated servers hold the set of currently-valid keys, so rotation does not invalidate authorisations already issued for in-flight matches. `allocator.Worker` now publishes the signed roster after binding, and `cmd/allocator` refuses to start without key material. Rotation procedure is in `docs/MATCHMAKING.md` §2; see `multiplayer-next.md` §8.31. Nothing human-only remains here — live verification is covered by [#17](https://github.com/jcreek/CosmicClash/issues/17). - [ ] ([#18](https://github.com/jcreek/CosmicClash/issues/18)) **Phase 4 playtest at ~100 ms RTT** — does the ship/ball feel local, do contact corrections read as bumps or glitches? Every numeric gate is green; this is a feel judgment no metric can answer. `multiplayer-next.md` §0, gate A. - [ ] ([#19](https://github.com/jcreek/CosmicClash/issues/19)) **Phase 5 3v3 gate** — a full 6-player match start to finish, with a mid-match disconnect and a late joiner. Only verified so far at 1v1 plus a two-bot CI match. `multiplayer-next.md` §0, gate B. - [ ] ([#20](https://github.com/jcreek/CosmicClash/issues/20)) **Phase 6 external gate** — run the exported Docker server and clients from separate real machines over the internet, then play a full match (controlled test only, since defect C below is still open). `multiplayer-next.md` §0. - [ ] ([#15](https://github.com/jcreek/CosmicClash/issues/15)) **Acquire a project-owned Steamworks App ID and coordinate with Valve** — hard prerequisite for Phase 7 (browser, verified tickets, bans, production credentials, ticketed Hosted Dedicated Server SDR) and therefore for Phase 8. `multiplayer-next.md` §0, Phase 7; `STEAM.md`. - [ ] ([#16](https://github.com/jcreek/CosmicClash/issues/16)) **Supply custom GodotSteam client/server build templates** and pin them in `steam-dependencies.lock.json` (`COSMIC_CLASH_STEAM_CLIENT_GODOT` / `COSMIC_CLASH_STEAM_SERVER_GODOT`) — `make verify-steam-templates` refuses a stock Godot binary until these exist. `STEAM.md`. - [ ] ([#21](https://github.com/jcreek/CosmicClash/issues/21)) **Reference-hardware profiling (task 0.15b)** in the live editor on real low/mid-tier hardware — blocks 0.16, 0.17/0.17b/0.17c/0.17d, 0.26 (arena GI bake), and 0.28 (physics separate-thread prototype). Covered above; listed again here because it also gates Phase 5.5's graphics QA gate for multiplayer sign-off. - [ ] ([#17](https://github.com/jcreek/CosmicClash/issues/17)) **Stand up the live Kubernetes cluster and Agones deployment** for Phase 8 — provider-portable manifests exist, but nothing has run against a real cluster; needs the provider-specific deployment overlay (network, DNS, secrets) per `docs/MATCHMAKING.md`. - [ ] ([#31](https://github.com/jcreek/CosmicClash/issues/31)) **Build, push and pin the container images the Kubernetes manifests reference.** Every image target builds, but no workflow publishes any of them and all manifest digests are still all-zero placeholders, so `deploy/k8s/base` cannot pull running images. **Only two things need a person**: the `ghcr.io/cosmic-clash/*` namespace in the manifests does not exist (no such org), and this repo is private while no manifest declares `imagePullSecrets`, so package visibility must be chosen. Publishing itself needs no new credential — GHCR accepts the built-in `GITHUB_TOKEN` with `packages: write` — so the workflow, digest pinning and enabling `--require-concrete` are agent work once those two are answered. Blocks [#17](https://github.com/jcreek/CosmicClash/issues/17). - [ ] ([#33](https://github.com/jcreek/CosmicClash/issues/33)) **Move game servers to their own namespace** so `cosmic-clash` can enforce `restricted` again. Agones' Dynamic port policy needs a `hostPort`, which `baseline`/`restricted` forbid, so the whole namespace dropped to `privileged` — including the control plane, which mounts the database DSN, workload secret and Steam publisher key. Deferred until the Agones gate was green so a new failure could not be ambiguous. - [x] (no issue — agent-actionable) **Phase 8.48 has its own Compose smoke fixture.** `compose.allocated-smoke.yml` and `scripts/verify_allocated_compose.sh` are independent of `compose.phase6-smoke.yml` — the script states so explicitly and reuses none of its ports — so the allocated-mode flow no longer inherits that fixture's hardcoded port, first-come slots or `--max-matches=2`. Exercised by `make verify-allocated-compose`. - [ ] ([#23](https://github.com/jcreek/CosmicClash/issues/23)) **Decide the contact-cohort-only client-side shadow world** (open question F in `multiplayer-next.md` §0). A design call about whether contact pairs get a client-side shadow simulation; nothing is blocked on it, and it can stay open indefinitely without holding anything up. - [ ] ([#32](https://github.com/jcreek/CosmicClash/issues/32)) **Implement casual backfill** — proposal, matcher pass, client offer UI and late roster delivery. Listed here because it has an issue, not because it needs you: the roster-delivery design is decided (`docs/MATCHMAKING.md` § Casual) and candidate selection has landed, so the rest is agent work. End-to-end verification needs the cluster ([#17](https://github.com/jcreek/CosmicClash/issues/17)). - [ ] ([#22](https://github.com/jcreek/CosmicClash/issues/22)) **Release-evidence and human sign-off gates for Phase 8 production launch** — once the above are done, someone needs to actually run and sign off the production-shaped checks `multiplayer-next.md` §7 lists as infrastructure/production-dependent. Defect **C** (slot reservation keyed on display name alone — real, demonstrated, exploitable during the 30 s disconnect window) is not its own action item: it is fixed for free by the Steam auth tickets in task 7.4 above, so nothing to do until Steam identity lands.