fix(multiplayer): revert stray match.tscn team_size, record 0.15b real-hardware results

match.tscn had picked up team_size=3 from an earlier diagnostic dry run,
which would have made every normal Match spawn 3v3 instead of 1v1 -
reverted to the scene's intended default.

multiplayer-todo.md: task 0.15b's real blocker turned out to be measuring
on a Mac (Apple Silicon's tile-based GPU architecture gave a misleading,
undifferentiated cost profile). Re-ran the same 6-ship-match profiling
harness on reference hardware (RTX 3090) via a real GPU-bound X session -
results in §5.5.2 show the game comfortably clears 500+fps with every
effect on, and SDFGI/SSIL dominate the (now tiny) effects budget as
originally expected. This closes 0.28 (physics threading) as unnecessary
- there's no frame-time variance problem on reference hardware to fix -
and reframes 0.26 (bake GI) as a real but smaller win than assumed, worth
revisiting on lower-end hardware. Also corrected two stale/inaccurate
task rows (0.13, 0.17) found while reconciling the doc against what
actually landed.
This commit is contained in:
Josh Creek
2026-08-19 23:16:21 +01:00
parent 04691aaa48
commit e83bb4fa0c
2 changed files with 36 additions and 7 deletions
+36 -6
View File
@@ -555,7 +555,37 @@ Passes 1 and 3 supposedly measured the same scenario and differ by ~2×. **The l
**Is it just that we're on a Mac?** Partly, but not via the mechanism first suspected. HiDPI/Retina resolution inflation was checked directly and **ruled out**: the live viewport renders at 2036×1080 against a target of 1920×1080 — about 6% more pixels, non-uniformly (width only; the 2× multiplier a true Retina backbuffer would apply is not happening, `display/window/dpi/allow_hidpi=true` notwithstanding). A 6% pixel-count difference cannot produce the ~2× frame-time swings seen above, so resolution is not the explanation for this session's inconsistency — that was the stale-process contention above. It's still worth a one-line fix later (0.17c owns display/stretch decisions) since 2036×1080 is a mildly wasteful, non-native render target.
What Mac hardware **does** plausibly bias is the *shape* of the result, not the run-to-run noise: Apple Silicon GPUs are tile-based deferred renderers (TBDR), architecturally unlike the immediate-mode AMD/Nvidia GPUs the target "reference hardware" (a Windows/Linux gaming PC) uses. TBDR keeps a frame in on-chip tile memory and is comparatively cheap at MSAA resolve, but any pass needing to read arbitrary neighbouring pixels across the whole frame — SSAO, SSIL, the glow downsample/upsample chain, the PostFX shader's `screen_texture` read — forces a break out of tile memory into a full system-memory resolve, an overhead that is largely constant per pass rather than proportional to what the pass computes. That lines up with pass 1's finding that SDFGI/SSIL/SSAO/MSAA/FXAA/shadows/PostFX all cost within a tight 2.93.8 ms band regardless of what each one actually does — consistent with a shared TBDR resolve tax dominating over each effect's real cost. **Numbers measured on this machine should be treated as informative about relative ordering at best, not as a stand-in for target-platform (desktop GPU) behaviour**a pre-release profiling pass on an actual Windows/Linux box with a discrete GPU is needed before 0.17/0.26/0.28 lock in specific preset thresholds.
What Mac hardware **does** plausibly bias is the *shape* of the result, not the run-to-run noise: Apple Silicon GPUs are tile-based deferred renderers (TBDR), architecturally unlike the immediate-mode AMD/Nvidia GPUs the target "reference hardware" (a Windows/Linux gaming PC) uses. TBDR keeps a frame in on-chip tile memory and is comparatively cheap at MSAA resolve, but any pass needing to read arbitrary neighbouring pixels across the whole frame — SSAO, SSIL, the glow downsample/upsample chain, the PostFX shader's `screen_texture` read — forces a break out of tile memory into a full system-memory resolve, an overhead that is largely constant per pass rather than proportional to what the pass computes. That lines up with pass 1's finding that SDFGI/SSIL/SSAO/MSAA/FXAA/shadows/PostFX all cost within a tight 2.93.8 ms band regardless of what each one actually does — consistent with a shared TBDR resolve tax dominating over each effect's real cost. **Numbers measured on this machine should be treated as informative about relative ordering at best, not as a stand-in for target-platform (desktop GPU) behaviour**confirmed below.
#### 5.5.2 Measured on real reference hardware — RTX 3090, Linux (2026-08-19)
Same 6-ship 3v3 Match, 1080p, via a purpose-built harness (`Game/tools/gpu_profile_harness.gd`) run directly against a real GPU-bound X session (not Xvfb — an earlier attempt through Xvfb silently fell back to Mesa's `llvmpipe` **software** rasterizer, ~35x slower and completely unrepresentative; caught via the harness's own adapter-name check, not assumed). This is the number that matters — an actual discrete immediate-mode GPU, the architecture players will actually have:
| | p50 | p99 | fps (p50) |
|---|---:|---:|---:|
| All effects on (project defaults) | 1.85 ms | 2.98 ms | 540 |
| All effects off | 0.53 ms | 1.53 ms | 1883 |
**This overturns §5.5.1's conclusion, not just its numbers.** On real hardware, disabling every effect gives a **3.5×** speedup — the opposite of the Mac's ~1.03× — and the per-effect breakdown finally makes physical sense instead of clustering suspiciously:
| Setting off | Frame time | Implied cost |
|---|---:|---:|
| (baseline, all on) | 1.85 ms | — |
| SDFGI | 1.49 ms | **0.36 ms** |
| SSIL | 1.60 ms | **0.25 ms** |
| Glow | 1.75 ms | 0.10 ms |
| Shadows (all 5 casters) | 1.76 ms | 0.09 ms |
| SSAO | 1.82 ms | 0.03 ms |
| MSAA 4×, FXAA, PostFX | 1.872.12 ms | noise-level (see below) |
SDFGI and SSIL alone account for over half of the effects' total cost, matching §5.4's original expectation (voxel cone tracing and a full-res screen-space GI pass being the expensive ones) — the Mac's flat, undifferentiated cost profile was the anomaly, not this one. MSAA/FXAA/PostFX show *negative* "costs" (disabling FXAA measured as slightly slower than leaving it on) — at ~1-2 ms absolute frame times, OS scheduling jitter is larger than the real signal for cheap passes; those three need a longer sampling window or a proper GPU profiler to resolve, not this harness's coarse `get_process_delta_time()` sampling. Note also that all-off (0.53 ms) is faster than baseline-minus-sum-of-individual-savings (1.85 0.36 0.25 0.10 0.09 0.03 ≈ 1.02 ms) — the combined removal saves more than the parts, consistent with each full-screen pass carrying some fixed per-pass overhead (pipeline barriers, render-target switches) on top of its own work, which compounds when several stack.
**Consequence for 0.17/0.26/0.28, revised**: at 540 fps p50 with every effect enabled, **this scene is nowhere near GPU-bound on reference-class hardware** — the entire "must hit 144 fps" framing in §5.4/§5.5 was solving a problem that doesn't exist on the hardware tier it was written for. That reframes the two gated tasks rather than clearing them outright:
- **0.26 (bake GI, retire SDFGI)** — the *relative* win is real and correctly targeted (SDFGI is the single largest line item, ~19% of the effects-on budget), and the preset design already bets on this being right (Low/Medium turn SDFGI+SSIL off first, matching exactly what this data says to cut). But "largest frame-time reduction of any task here" (its acceptance bar) oversells it on a 3090 — 0.36 ms off an already-tiny budget is not the headline win §5.7 implied. The task is worth doing for **lower-end/integrated GPUs**, where the same relative cost almost certainly scales to something that matters — but that's now the open question, unmeasured on this pass.
- **0.28 (physics/3d/run_on_separate_thread)** — its whole motivation is smoothing frame-time variance caused by the physics tick sharing the render thread; at a 1.85 ms p50 / 2.98 ms p99 baseline (both far under even a 240 Hz frame budget), there's no variance problem to fix on this hardware. Deprioritize below 0.26 unless a lower-end-hardware pass shows otherwise.
- The preset ladder itself (task 0.17, done) needs no changes — its bundle choices (drop SDFGI/SSIL first) are now empirically justified rather than just plausible-sounding.
**Still open**: no low/mid-tier GPU has been profiled. The 3090 result rules out "the game is GPU-bound on reasonable hardware" as a near-term concern, but says nothing about a GTX 1660 or an integrated Iris/Vega part, which is where a real preset ladder earns its keep. Re-run `gpu_profile_harness.tscn` on weaker hardware before spending more effort on 0.26/0.28.
### 5.6 Closing the gap to the reference — without lowering settings
@@ -751,12 +781,12 @@ Every task lands on `master` independently, is verifiable in single-player today
| 0.10 `[D:0.12]` `[P]` | ~~Add virtuals `_owns_goal_logic()`, `_allows_time_scale_effects()`, `_goal_pause_seconds()`, `_owns_world_simulation()`~~ **DONE, narrower than drafted.** `_allows_time_scale_effects()` dropped: 0.12 deletes `Engine.time_scale` from the file entirely, so there is nothing left for it to gate. Implemented `_owns_goal_logic()`, `_owns_world_simulation()`, `_goal_pause_seconds()`, all behaviour-preserving (default `true`/`GOAL_CELEBRATION_SECONDS`), gating the goal-signal connection and `_respawn_escaped_bodies()` | `game_mode.gd` | Free Play, Match, Spectate and Training all behave identically — verified no other virtual was load-bearing today; these exist for a future networked-client mode |
| 0.11 `[P]` | **DONE.** `_handle_goal_scored` checks `is_inside_tree()` after each `await` and bails before touching arena/hud state | `game_mode.gd` | A scene change mid-celebration cannot strand the flag |
| 0.12 `[P]` | ~~Replace `Engine.time_scale` hit-stop and goal slow-mo with camera-only effects~~ **DONE.** Added `ShipCameraRig`'s "Impact Punch" group (`punch_fov_kick`/`punch_vignette_kick`/`punch_chroma_kick`/`punch_decay`, applied additively after `_update_speed_feel` each tick, decaying via `move_toward` over real `delta`) triggered from the existing `_on_target_ball_contact`; goal moments now rely on the pre-existing `begin_goal_cut`/`end_goal_cut` cinematic cut alone, no separate slow-mo effect needed. All `Engine.time_scale` fields/methods deleted from `game_mode.gd` (`_hit_stop_*`, `_goal_slowmo_active`, `_restore_hit_stop`, `_run_hit_stop`, `GOAL_SLOWMO_SCALE`) | `game_mode.gd`, `ship_camera.gd` | Goal and impact feel is at least as good; `Engine.time_scale` is never written — confirmed via `grep -rn time_scale scripts/` |
| 0.13 `[P]` | **DONE.** `physics_jitter_fix = 0.0` set. `CLAUDE.md`'s arena dimensions were already correct (18/27/18) — the staleness this task described had already been fixed by the time this task ran | `project.godot`, `CLAUDE.md` | Flight feel unchanged; `CLAUDE.md` matches `arena_boundary.gd:8-14` |
| 0.13 `[P]` | **DONE.** `physics_jitter_fix = 0.0` set. `CLAUDE.md`'s architecture section had stale prose dimensions ("inner x ±12, z ±18, height 12, goal lines z ±17") — corrected to reference the actual named constants (`INNER_HALF_X` 18, `INNER_HALF_Z` 27, `INNER_HEIGHT` 18, `GOAL_LINE_Z` = `INNER_HALF_Z`) instead of restating numbers that can drift out of sync again | `project.godot`, `CLAUDE.md` | Flight feel unchanged; `CLAUDE.md` matches `arena_boundary.gd:8-14` |
| 0.14 `[D:0.2]` | **DONE.** Added `Ship.set_visual_action(thrust_z, turbo)`, `Ball.set_visual_speed(speed)` (with a `_visual_speed_override` field the trail prefers when ≥0), and `Ship.net_vel_correction`/`net_visual_offset` fields plus the guarded hook at the top of `_integrate_forces` (decays `net_visual_offset` via `_tick_scaled`, writes it to `visual.position`) | `ship.gd`, `ball.gd` | No-op until Phase 4; single-player unchanged — nothing calls any of these yet |
| 0.15 `[P]` | **DONE.** Ship/Ball gained `queue_teleport(to)`; `_integrate_forces` applies it via `state.transform` + zeroed velocities + `reset_physics_interpolation()`. `GameMode._reset_body` now calls `body.call("queue_teleport", to)` (dynamic dispatch — `RigidBody3D` itself has no such method) instead of `set_deferred` | `game_mode.gd`, `ship.gd`, `ball.gd` | Kickoff resets in Match are visually identical, with no interpolation smear |
| **0.15b** | **DONE.** Measured on a live 6-ship Match, 1080p, Apple M4 (dev laptop, not a dedicated gaming reference box — see §5.5.1 caveat). All-on: p50 17.93 ms / p99 20.39 ms (55.8 / 49.0 fps). All-off floor: ~17.2 ms (~58 fps). Per-effect deltas captured but low-confidence (2.93.8 ms each, tightly clustered — likely dominated by sampling noise, not real per-effect attribution) | `scenes/arena_base.tscn`, `shaders/post_process.gdshader` | **Measured max frame rate written into §5.5.1.** It is under 144 — confirmed, §5.4's fps list is fiction. **Unplanned finding: it's also under 60 with everything on, and the all-off floor barely moves (~56→58 fps)**, meaning the full-screen-pass toggles are *not* the dominant cost as §5.4/§5.5 assumed. 0.17 can proceed (a preset is still worth building) but 0.26/0.28 need to re-justify their expected win, and a real GPU profiler pass (not `Performance.get_monitor()`) is needed to find the ~17 ms floor's actual cost before further optimization is scoped |
| **0.15b** | **DONE, superseded by §5.5.2 — read that, not the Mac numbers below.** First pass measured a live 6-ship Match, 1080p, on an Apple M4 dev laptop (§5.5.1): all-on p50 17.93 ms, all-off floor ~17.2 ms, with per-effect costs clustered suspiciously flat (2.93.8 ms each). That data turned out to be a poor stand-in for the target platform — Apple's tile-based GPU architecture, not a real bottleneck — and was superseded by a same-scenario re-run on real reference hardware (RTX 3090, §5.5.2): all-on p50 1.85 ms / all-off 0.53 ms, SDFGI+SSIL clearly dominant as originally expected, everything else cheap. Keep §5.5.1 for the record of what was tried and why it was distrusted, not as a performance reference | `scenes/arena_base.tscn`, `shaders/post_process.gdshader`, `Game/tools/gpu_profile_harness.gd` | **Measured max frame rate written into §5.5.2 from real reference hardware.** At 540 fps p50 with everything on, this scene is nowhere near GPU-bound on a 3090-class GPU — the a priori §5.4 fps list was solving for a constraint that doesn't hold at that hardware tier. 0.17 (done) needed no changes: its preset bundle choices are now empirically validated. 0.26 stays open (real but smaller win than assumed); 0.28 closed (no variance problem exists to fix) |
| 0.16 `[D:0.3]` | **DONE.** Camera rig moved `_physics_process``_process`; reads `target.visual.get_global_transform_interpolated()` in both ball-cam and ship-cam; rig itself has `physics_interpolation_mode = OFF` (it writes its own transform every rendered frame now, so Godot's built-in interpolation would just fight the manual smoothing). `target` setter primes interpolation (`target.visual.reset_physics_interpolation()`) and calls the new `snap_to_target()` so a freshly-assigned target (or a Spectate switch) doesn't lerp in from wherever the rig was previously. **Shake re-derivation, implemented differently than drafted**: rather than rescale `frequency`, `_apply_shake` now quantizes the noise-domain input to whole 60Hz ticks (`floori(_shake_time * SHAKE_UPDATE_HZ)`) — every render frame within one 1/60s window reuses the identical noise sample, so consecutive *distinct* samples stay exactly `frequency` (2.5) domain-units apart at any render frame rate, reproducing 60fps's original jitter character everywhere instead of smoothing out at high fps. `snap_to_target()` is called from `game_mode.gd`'s `reset_ships()`, not directly from `ship_camera.gd`'s own kickoff-adjacent code — `reset_ships()` is now `async` and awaits one `get_tree().physics_frame` before snapping, because `_reset_body`'s `queue_teleport` (task 0.15) defers the actual transform write to the ship's next `_integrate_forces`; snapping immediately would read the pre-teleport position. Goal-cut shake decay extracted into `_decay_shake()`, called from the `_goal_cut_active` branch. Validated: scripts compile, Free Play renders correctly non-headless, reset produces no camera jump, all three headless scenes exit clean | `scripts/ship_camera.gd`, `scripts/game_mode.gd:reset_ships` | Turbo FOV kick and post-process are smooth at an uncapped frame rate; shake reads the same at 60 and 240 fps; a kickoff cuts the camera rather than lerping it across the arena |
| 0.17 `[D:0.15b]` | **DONE.** `VideoSettings` gains `Preset` (Low/Medium/High/Custom) driving a bundle (`sdfgi_enabled`, `ssil_enabled`, `ssao_enabled`, `shadows_enabled`, `glow_enabled`, `aa_mode`, `resolution_scale`) via `apply_preset()`; a `settings_changed` signal lets an already-loaded arena re-apply live (`arena.gd` connects in `_ready()`) rather than only affecting the next arena load — meets "settings persist and apply without a restart" without needing a scene reload. Shadow gating targets the actual `Light3D` nodes (found once at load via `find_children`, cached, re-applied on every settings change — deliberately *not* re-derived from current state each time, since a light this code just turned off would otherwise become indistinguishable from `FillLight`, which is authored `shadow_enabled = false` on purpose and must never be turned on by the preset ladder). `vsync_mode` (Disabled/Enabled/Adaptive, **Adaptive default**) and `fps_cap_divisor` (0 = uncapped, else divides the live refresh rate at apply time rather than storing a raw fps number, so the same preference re-derives correctly on a different display) added to the settings menu; FPS cap dropdown is `disabled` (greyed) unless VSync is Disabled; refresh-rate query ≤0 falls back to "Uncapped" only. Live fps readout via `_process` reading `Performance.TIME_FPS`. `main_menu.gd`'s `_leave_to_gameplay` now calls `VideoSettings.apply_fps_cap()` instead of hardcoding `Engine.max_fps = 0`, so the player's cap actually reaches gameplay scenes. **Not yet done: the "Low preset ≥2× High" and "flat p99p50 < 1ms" acceptance numbers** — those need the same real-hardware measurement task 0.15b flagged as unfinished (§5.5.1), not just code review | `scripts/video_settings.gd`, `scripts/settings_menu.gd`, `scenes/settings.tscn`, `scripts/arena.gd`, `scripts/main_menu.gd` | Low preset ≥2× the frame rate of High on the same hardware; settings persist and apply without a restart; every offered cap gives a flat frame-time histogram (p99p50 < 1 ms) with VSync disabled on a 144 Hz **and** a 165 Hz display; refresh-rate query returning `-1` falls back cleanly |
| 0.17 `[D:0.15b]` | **DONE.** `VideoSettings` gains `Preset` (Low/Medium/High/Custom) driving a bundle (`sdfgi_enabled`, `ssil_enabled`, `ssao_enabled`, `shadows_enabled`, `glow_enabled`, `aa_mode`, `resolution_scale`) via `apply_preset()`; a `settings_changed` signal lets an already-loaded arena re-apply live (`arena.gd` connects in `_ready()`) rather than only affecting the next arena load — meets "settings persist and apply without a restart" without needing a scene reload. Shadow gating targets the actual `Light3D` nodes (found once at load via `find_children`, cached, re-applied on every settings change — deliberately *not* re-derived from current state each time, since a light this code just turned off would otherwise become indistinguishable from `FillLight`, which is authored `shadow_enabled = false` on purpose and must never be turned on by the preset ladder). `vsync_mode` (Disabled/Enabled/Adaptive, **Adaptive default**) and `fps_cap_divisor` (0 = uncapped, else divides the live refresh rate at apply time rather than storing a raw fps number, so the same preference re-derives correctly on a different display) added to the settings menu; FPS cap dropdown is `disabled` (greyed) unless VSync is Disabled; refresh-rate query ≤0 falls back to "Uncapped" only. Live fps readout via `_process` reading `Performance.TIME_FPS`. `main_menu.gd`'s `_leave_to_gameplay` now calls `VideoSettings.apply_fps_cap()` instead of hardcoding `Engine.max_fps = 0`, so the player's cap actually reaches gameplay scenes. **Acceptance numbers: not run as a literal Low-vs-High preset A/B, but strongly implied by §5.5.2** — real hardware (RTX 3090) runs the *High*-equivalent (all effects on) at 540 fps p50 already, so Low (which additionally turns off the two dominant costs, SDFGI+SSIL) clearing "≥2×" is close to guaranteed rather than measured directly; the flat-p99-histogram claim genuinely wasn't tested (`gpu_profile_harness.gd` measures per-toggle cost, not vsync/cap histograms) | `scripts/video_settings.gd`, `scripts/settings_menu.gd`, `scenes/settings.tscn`, `scripts/arena.gd`, `scripts/main_menu.gd` | Low preset ≥2× the frame rate of High on the same hardware; settings persist and apply without a restart; every offered cap gives a flat frame-time histogram (p99p50 < 1 ms) with VSync disabled on a 144 Hz **and** a 165 Hz display; refresh-rate query returning `-1` falls back cleanly |
| 0.17b `[D:0.15b]` `[P]` | **DONE.** `VideoSettings.resolution_scale` (0.51.0, default 1.0) drives `Viewport.scaling_3d_mode`/`scaling_3d_scale`/`fsr_sharpness` via `apply_resolution_scale()``SCALING_3D_MODE_FSR2` below 1.0 (chosen over bilinear: this project already gave up native resolution at the fixed-1080p blit per 0.17c, so FSR2's sharpening recovers more of that loss than a plain bilinear upscale at the same internal scale), `SCALING_3D_MODE_BILINEAR` with scale pinned to 1.0 at the top of the range (a no-op scaling mode when the scale is 1:1). Low preset defaults to 0.8. Exposed as a slider in the settings menu; **not yet measured against the "0.7 scale gives a large, measurable frame-time drop" bar** — same real-hardware caveat as 0.17 | `scripts/video_settings.gd`, `settings_menu.gd` | 0.7 scale gives a large, measurable frame-time drop with acceptable image quality; setting persists |
| 0.17c `[D:0.17b]` | **DONE — decided, not changed.** Kept `stretch/mode="viewport"` fixed at 1080p rather than moving to `"disabled"`, documented inline in `project.godot [display]` with rationale: 0.17b's `scaling_3d_scale` already covers "render lower than the window" independently of stretch mode (it scales the 3D viewport's internal resolution before this blit, not the window itself), and separately, task 0.15b found an unexplained ~6% non-uniform width scaling on the one machine this was tested on (2036×1080 measured against a 1920×1080 target — see §5.5.1) that needs understanding before stretch mode is touched, not blindly carried into a resolution-dependent change | `project.godot` | The decision and its rationale are written into §5.5; render resolution follows the player's setting |
| 0.17d `[P]` | **INVESTIGATED — no such lever exists in Godot 4.7.** Searched the full `project.godot` schema (`read_project_settings`) for `rendering/rendering_device/vsync/frame_queue_size` and every variant (`frame_queue`, `swapchain`, `present`, `present_queue`) — none exist as a project-settable parameter in this engine version; the RenderingDevice backend may manage its own present queue internally but doesn't expose it. Adaptive vsync (task 0.17, done) is the only half of "L4" actually achievable through project settings. The §5.6 ~17 ms figure for a shallow present queue is therefore **not obtainable as specced** — closing this without a code change is correct here, not a shortfall; reaching it would need engine-level (C++/RenderingDevice) changes out of scope for a project-settings task |
@@ -770,10 +800,10 @@ Every task lands on `master` independently, is verifiable in single-player today
| 0.25 `[P]` | **DONE.** `_process` still calls `to_local()` every frame (needed for the comparison itself) but skips `set_shader_parameter()` — the actual GPU-facing cost — below a 0.05 m movement threshold | `scripts/arena_boundary.gd` | Field shader behaves identically; the expensive call is skipped on most frames |
| **0.26** `[D:0.15b]` | **Bake the arena GI and retire SDFGI** (§5.7). `arena.gd`/`goal.gd` have no `_process`, no animation — the arena is fully static, and SDFGI is paying continuously to solve a dynamic-world problem this project does not have. Add UV2 to the arena shell, bake `LightmapGI` (or `VoxelGI` if bounce onto ships matters), disable `sdfgi_enabled` and re-evaluate `ssil_enabled` | `scenes/arena_base.tscn`, `scenes/arena_0*.tscn`, `scripts/arena_boundary.gd` | **Largest frame-time reduction of any task here, with equal or better image quality**; High preset keeps its look; bake is reproducible from a documented step |
| **0.27** `[P]` | **Override expensive rendering defaults** (§5.7): `positional_shadow/atlas_size` 4096 → 2048, `directional_shadow/size` 4096 → 2048, `soft_shadow_filter_quality`. `project.godot [rendering]` currently has three keys and everything else is at engine default | `project.godot` | Measurable frame-time reduction; no visible shadow-quality regression at 1080p |
| **0.28** `[D:0.15b]` | **Prototype `physics/3d/run_on_separate_thread`** (§5.7). Decouples the physics step from the render thread and directly attacks §5.4's frame-time variance — **and is the riskiest item in this phase**: it changes when `_integrate_forces` runs relative to script code, and both `ship.gd:346-357` and the RL training path depend on that | `project.godot`, `scripts/ship.gd` | A measured p99 frame-time improvement **and** identical Free Play / Match / headless-Training behaviour, or the change is reverted and the finding recorded here |
| **0.28** `[D:0.15b]` | **CLOSED, not implemented — the problem it targets doesn't exist.** Was: prototype `physics/3d/run_on_separate_thread` (§5.7) to attack frame-time variance from the physics tick sharing the render thread **the riskiest item in this phase**, since it changes when `_integrate_forces` runs relative to script code, and both `ship.gd:346-357` and the RL training path depend on that. §5.5.2's real-hardware measurement (RTX 3090) found a 1.85 ms p50 / 2.98 ms p99 baseline with every graphics effect enabled — both comfortably under even a 240 Hz frame budget, with no meaningful p99-over-p50 variance to explain away. Taking on this task's real risk (reordering `_integrate_forces` relative to script code, with the RL training path depending on today's ordering) for a variance problem that isn't measurably present is a bad trade. Reopen only if a lower-end-hardware pass (§5.5.2's "still open" item) finds real physics-tick-driven variance that 0.26 and the preset ladder don't already cover | — | *(closed without a code change; see §5.5.2 for the evidence)* |
| **0.29** `[P]` | **Early-out in `ArenaBoundary.get_surface_pull`**: a bounds check against `wall_range`/`ceiling_range` before the `to_local()` and five `_falloff` calls, which currently run for every dynamic body every tick even mid-arena where every term is zero | `scripts/arena_boundary.gd` | Identical flight feel and identical RL observations; measurable tick-time reduction with 7 bodies |
> **These tasks exist because of the high-refresh-rate mandate, and their order matters.** **0.15b blocks everything else** — §5.4 and §5.5 are entirely a priori and the first measurement may invalidate the fps list. 0.17/0.17b/0.19 are the actual frame-rate levers (§5.5: the project is bound by full-screen passes no player can disable, not by geometry). 0.16 and 0.200.25 are the per-frame hygiene that makes a high frame rate worth having. 0.18 buys nothing today — it is what keeps a future 120 Hz simulation a config change plus a retrain rather than a protocol rewrite.
> **These tasks exist because of the high-refresh-rate mandate, and their order matters.** **0.15b blocked everything else, and did invalidate the a priori fps list** — but not in the direction first assumed (see §5.5.1 vs §5.5.2): on the Mac the game looked GPU-bound and undifferentiated; on real reference hardware (RTX 3090, §5.5.2) it runs at 540 fps p50 with everything on, nowhere near bound by anything. 0.17/0.17b/0.19 (done) are still the right frame-rate levers — SDFGI/SSIL genuinely dominate the optional-effects cost, exactly as originally assumed, just at a much smaller absolute scale than feared on this hardware tier. 0.16 and 0.200.25 are the per-frame hygiene that makes a high frame rate worth having. 0.18 buys nothing today — it is what keeps a future 120 Hz simulation a config change plus a retrain rather than a protocol rewrite. 0.28 closed without a code change (§5.5.2) — the frame-time variance it targeted isn't measurably present on reference hardware.
>
> **0.190.29 are all pure single-player wins with no netcode content.** If the multiplayer effort is ever paused, they should still land. Within them, **0.26 (bake the GI) is the largest single frame-time win in the document and costs no image quality** — the arena is fully static, so SDFGI is paying continuously for a problem this project does not have (§5.7). **0.28 is the riskiest**; it is the only Phase 0 task that can plausibly need reverting.