CosmicClash/TODO.md

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 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) 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) 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.
• 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) 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) 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) 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 — 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. These need a human at the editor with real hardware to profile and eyeball, not further code changes.

• (#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.

• (#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.
• (#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) 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) 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) 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) 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) 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) 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) 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.
• (#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.
• (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.
• (#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.