Phase 5: Integration and Polish

[MichaelFisher1997]

Phase 5: Integration and Polish

Goal

Clean up the remaining call sites, move feature toggles closer to the code they control, and document the new ownership model.

Why this matters

The earlier phases only pay off if the rest of the codebase is updated to use the new seams consistently. This phase removes the last old-style dependencies and makes the refactor easy to maintain.

Parallel Tasks

Issue 5.1: Update constructors and call sites to the new ownership model

• Type: refactor / integration
• Scope: src/game/app.zig, src/world/world.zig, src/game/session.zig, and any screen setup paths
• Problem: top-level wiring still assumes the old monolithic ownership model.
• Work:
  • Update object construction to use the extracted coordinators and interfaces
  • Remove stale getters/setters that only exist for old wiring
  • Keep startup and shutdown ordering correct
• Acceptance criteria:
  • The app boots with the new module boundaries
  • No call site depends on removed compatibility paths
• Parallel-safe: yes, but coordinate carefully with the other integration task

Issue 5.2: Move feature toggles into the systems they control

• Type: refactor / solid
• Scope: src/engine/graphics/render_system.zig, render pass structs, and related settings paths
• Problem: render feature flags are still stored at the top level instead of with the pass or system they affect.
• Work:
  • Push disable flags into the relevant pass/system structs
  • Keep environment-variable overrides working
  • Reduce the number of render-system fields whose only job is configuration forwarding
• Acceptance criteria:
  • Feature toggles live closer to the code they control
  • Rendering behavior remains identical when flags are set
• Parallel-safe: yes

Issue 5.3: Add docs and validation notes for the new structure

• Type: docs / maintenance
• Scope: docs/refactoring/solid-audit/*, README.md if needed
• Problem: the refactor needs a durable map so future changes do not reintroduce the same coupling.
• Work:
  • Document the final module boundaries
  • Add a short migration note for future contributors
  • Record the verification commands used for the refactor
• Acceptance criteria:
  • Documentation explains the new dependency boundaries clearly
  • Verification steps are easy to follow
• Parallel-safe: yes

Dependencies

• Requires phases 1 to 4 to be merged or at least mechanically stable

Verification

• nix develop --command zig build test
• nix develop --command zig build
• nix develop --command zig build run for a manual smoke check

[github-actions]

Classification: Feature Request / Refactoring

This is Phase 5 of an ongoing refactoring effort with three parallel tasks. Here's my analysis:

Issue 5.1: Ownership Model Integration

Scope: src/game/app.zig, src/world/world.zig, src/game/session.zig

• Updates top-level wiring to use coordinators/interfaces extracted in phases 1-4
• Removes stale getters/setters

Issue 5.2: Feature Toggles Migration (well-scoped)

The current architecture stores disable flags at RenderSystem level:

• disable_shadow_draw, disable_gpass_draw, disable_ssao, disable_clouds (render_system.zig:50-53)
• Passed via SceneContext to passes (render_graph.zig:77-80)
• Checked in pass execute functions (render_graph.zig:232,256,282,375)

Contrast with newer passes that already follow the target pattern:

• BloomPass, TAAPass, FXAAPass, WaterPass each have enabled: bool fields (render_graph.zig:433,455,477,531)

Suggested implementation for Issue 5.2:

1. Add enabled: bool = true to ShadowPass, GPass, SSAOPass, CloudPass structs
2. Initialize these from env vars in RenderSystem.init (lines 64-86)
3. Change pass execute functions to check if (!self.enabled) return;
4. Remove disable_* fields from SceneContext
5. Remove getter/setter methods from RenderSystem (getDisableShadowDraw, etc.)
6. Update screens/world.zig:316-319 to remove the forwarding

Issue 5.3: Documentation

Existing docs at docs/refactoring/ show PR1 and PR2 but no solid-audit/ directory yet.

Verification Commands (as specified)

nix develop --command zig build test
nix develop --command zig build
nix develop --command zig build run

Scope Assessment: All three tasks are well-scoped, parallelizable, and have clear acceptance criteria. No need to break into sub-issues.

opencode session  |  github run