CosmicClash/TODO.md

TODO

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:

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

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

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

• Decide the join-signing design for the Phase 8 root blocker. No real deployment can advance a match past PROCESS_READY today because nothing calls the (fully built and tested) assignment-publishing path in production — it needs a join-signing key shared between allocator and game server, roster-digest computation, and per-player authorization construction, deliberately flagged rather than built pending this decision. See multiplayer-next.md §0 ("the actual current root blocker") and §8.31.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Give Phase 8.48 its own Compose smoke fixture so the allocated-mode flow stops depending on compose.phase6-smoke.yml's hardcoded port, first-come slots, and --max-matches=2. multiplayer-next.md §0 task table.
• 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.