TSSBOT-web/docs/superpowers/specs/2026-06-21-3d-replay-view-design.md

3D Replay View — Design

Date: 2026-06-21 App: tssbot.web (React frontend + Node server.cjs + Rust/Python upstream)

Goal

Add a 2D/3D toggle to the game-detail Replay panel. The existing 2D minimap replayer stays the default; a new 3D view (ported from the standalone REPLAY_VIEWER three.js app) renders the same replay in an orbitable 3D scene. Both views share one clock, the ticket bar, the battle log, and the team side panels, so switching between them is seamless in real time.

Requirements

1. Toggle labelled 2D / 3D next to the "Replay" heading, 2D by default, sitting alongside the existing Ground/Air toggle.
2. The 3D renderer is pure: only its <canvas>. No name labels, no axis lines, no map guide lines, no on-canvas controls/legend.
3. Keep the existing team side panels (winners/losers legends).
4. Clicking a side-panel row focuses that unit in 3D (camera flies to it and it glows). In 2D, click behaves the same as hover (no new behavior).
5. Keep the ticket bar on top and battle log below, both synced to the shared clock regardless of active view.
6. The Ground/Air toggle controls both views.
7. 3D uses real height (Y) from the replay data.

Data flow

Pipeline today: replay_data.json[.gz] (raw, path rows [t, x, y, z]) → python -m BOT.render_replay <replay> <out.json> (in GitHub/BOTS/TSSBOT) → replay_canvas.json (2D: path points {t, x, z}, plus levelCoords, tankMapCoords, mapCoords, fullMapLevel, players, kills, captureAreas, captureState, tickets, teamNames, winnerSlot) → cached + served at GET /api/tss/games/:id/replay-canvas → ReplayCanvasEngine (in frontend/src/ReplayCanvas.jsx).

The raw rows already carry y (confirmed: e.g. [29031, -10218.59, 69.74, -2626.99]); the renderer drops it. The map coords needed by 3D are already in replay_canvas.json.

Change

render_replay.py: include y in each emitted canvas path point (add a y field, e.g. {t, x, y, z}). Backwards compatible — the 2D engine reads only t/x/z. Cached JSONs without y regenerate on next mtime mismatch; until then 3D falls back to y = 0.

Runtime flow

• ReplayCanvasPanel.jsx fetches /api/tss/games/:id/replay-canvas once and builds ReplayCanvasEngine with the data object.
• The engine eagerly constructs both the 2D canvas and a hidden ReplayCanvas3D view from the same data.
• engine._tick advances currentTime and calls activeView.setTime(currentTime). Scrubber input does the same. Ticket bar + battle log update from currentTime independent of the active view.
• engine.setViewMode('2d'|'3d') toggles visibility of the 2D canvas vs the 3D container, sets activeView, calls the new view's setTime/setMode/ resize, and preserves play state + time → seamless swap.
• engine.setMode('ground'|'air') updates 2D coords (unchanged) and calls view3d.setMode(mode).
• rc-row click → engine.focus(playerId) → routed to activeView.focus. 3D flies the camera to the unit and glows it; 2D focus is a no-op.

Components

1. BOT/render_replay.py (in GitHub/BOTS/TSSBOT)

Emit y per canvas path point. Single-field additive change at the point where path points are serialized for the canvas JSON.

2. frontend/src/ReplayCanvas3D.js (new)

The ported three.js renderer as a UI-less class.

• Constructor (container, data): builds renderer, scene, camera, OrbitControls into container; resolves map info from data (levelCoords/tankMapCoords/mapCoords/fullMapLevel) the same way the standalone viewer's resolveMapInfo does; builds map plane, tank/marker entities, path lines, kill lines, capture zones; starts its own requestAnimationFrame loop for camera damping + rendering (it renders continuously but only changes unit positions when setTime is called).
• Methods:
  • setTime(t) — place all entities/markers/kill-lines/zones at game time t (same interpolation/death-freeze logic as the standalone viewer).
  • setMode('ground'|'air') — swap coords/map image + rebuild scene extents.
  • focus(playerId) — move camera target to that player's current entity and apply the path glow / dim-others effect.
  • setHighlight(playerId|null) — optional, mirror hover highlight (best effort; may reuse focus glow without camera move). MVP: focus only.
  • resize() — match container size.
  • dispose() — stop loop, dispose geometries/materials/renderer, remove canvas.
• Stripped vs standalone viewer: remove name-label sprites, axis lines, map guide lines/annotations, the on-canvas play/speed/scrub controls, the active list / hover panel / meta panel DOM, and the replay-select. Keep: map plane + texture, tank model + sphere fallback, path lines, kill lines, capture zones, death-freeze, path glow + camera focus, Shift-to-boost camera movement, the Plane*-mesh removal fix, and the capture/heading/freeze fixes already made.
• Entity identity: each 3D entity carries its playerId (from data) so focus(playerId) can find the currently-live entity for that player.
• Model asset: the tank .obj and map images. 3D loads the tank model from a static path served by the app (copy REPLAY_VIEWER/public/models/t34/ into tssbot.web/frontend/public/models/t34/ or equivalent served dir). Map images come from the existing minimap endpoint (/api/match/minimap/<level> and ?type=full), the same URLs the 2D engine uses.

3. frontend/src/ReplayCanvas.jsx — ReplayCanvasEngine

• Add a center child container for the 3D canvas next to the 2D <canvas>.
• New state: this._viewMode = '2d', this.view3d = null, this.activeView.
• In init() (after map data is ready), eagerly construct ReplayCanvas3D.
• setViewMode(mode): show/hide canvases, set activeView, push current currentTime + ground/air mode to the newly active view, resize() it.
• In _tick and scrubber handler: when _viewMode === '3d', call view3d.setTime(currentTime) instead of (or in addition to) the 2D render(). 2D render() is skipped while 3D is active for perf.
• setMode(mode): keep existing 2D behavior, also view3d?.setMode(mode).
• focus(playerId): call activeView.focus?.(playerId).
• rc-row click listener → this.focus(pid).
• destroy(): also view3d?.dispose().

4. frontend/src/ReplayCanvas.jsx — ReplayCanvasPanel

• State adds viewMode: '2d'.
• Render a 2D/3D toggle (mirroring rc-mode-toggle styling) next to the "Replay" <h2>, always visible once status === 'ready'.
• switchView(mode) → engine.setViewMode(mode) + setState.
• If WebGL is unavailable, disable the 3D button (dimmed, tooltip) and stay 2D.

5. Styles

• .rc-view-toggle / .rc-view-btn (reuse .rc-mode-toggle look).
• Center stacking so the 2D <canvas> and 3D container occupy the same slot (one hidden via class).

Error handling

• Missing y (stale cache): 3D uses y = 0 → flat scene, no crash.
• No WebGL: 3D button disabled; panel stays 2D.
• Model/texture load failure: 3D falls back to sphere markers / untextured map (already handled in the standalone viewer's loaders).

Testing / verification

Manual, since this is interactive visual UI:

• 2D view byte-for-byte unchanged when 3D is never opened.
• Toggle 2D⇄3D mid-playback: time, play/pause, and ticket/battle-log stay in sync; no jump.
• Ground/Air toggle affects both views (use a game with aircraft).
• Clicking a side row in 3D flies the camera + glows that unit; in 2D it matches hover.
• vite build compiles.
• One game regenerated through render_replay includes y.

Out of scope (YAGNI)

• Persistent 2D click-focus / 2D recenter (explicitly declined).
• Name labels / legend inside the 3D canvas.
• Lazy-loading three.js (eager chosen).
• Backfilling height into all cached replay_canvas.json (regenerate on demand).