Phase 3: WorldStreamer SRP Extraction

[MichaelFisher1997]

Phase 3: WorldStreamer SRP Extraction

Goal

Split src/world/world_streamer.zig into smaller responsibilities so chunk lifecycle, LOD, and GPU acceleration can evolve independently.

Why this matters

WorldStreamer currently manages queues, predictive loading, uploads, LOD coordination, save integration, and GPU block-buffer orchestration. It is the largest SRP risk in the world pipeline.

Parallel Tasks

Issue 3.1: Extract the chunk queue and upload coordinator

• Type: refactor / solid
• Scope: src/world/world_streamer.zig
• Problem: generation, meshing, upload queues, and job handlers are all owned by one module.
• Work:
  • Create a focused coordinator for generation/meshing/upload progression
  • Move processGenJob, processMeshJob, and processUploads into that coordinator
  • Keep the same chunk state machine and worker pool behavior
• Acceptance criteria:
  • Queue management is separated from LOD and GPU concerns
  • Chunk generation still reaches renderable through the same states
• Parallel-safe: yes

Issue 3.2: Extract the LOD and predictive-loading coordinator

• Type: refactor / solid
• Scope: src/world/world_streamer.zig, src/world/lod_manager.zig
• Problem: predictive loading and render-distance logic are mixed into queue orchestration.
• Work:
  • Move PlayerMovement and related priority weighting into a dedicated coordinator
  • Isolate all lod_manager interactions behind a small API
  • Keep render-distance clamping behavior unchanged
• Acceptance criteria:
  • LOD decisions are no longer embedded in the chunk queue code
  • Changing render distance still triggers the expected rescan behavior
• Parallel-safe: yes

Issue 3.3: Extract the GPU acceleration coordinator

• Type: refactor / solid
• Scope: src/world/world_streamer.zig, src/world/gpu_block_buffer.zig, src/world/gpu_mesher.zig
• Problem: GPU upload and compute-meshing concerns are intermixed with chunk lifecycle logic.
• Work:
  • Move gpu_block_buffer and gpu_mesher ownership into a dedicated helper/coordinator
  • Keep upload fallback behavior for CPU meshing intact
  • Preserve safe-mode and GPU fallback logic
• Acceptance criteria:
  • GPU acceleration code is separated from the core queue coordinator
  • CPU fallback still functions when GPU meshing is disabled or unavailable
• Parallel-safe: yes

Dependencies

• Phase 2 should be stable before major world-system reshaping, but the tasks do not directly depend on it

Verification

• nix develop --command zig build test
• nix develop --command zig build test-integration

[github-actions]

Based on my analysis of the codebase:

Classification: Feature Request / Refactor (SRP extraction)

Validation:

The issue accurately identifies the problem: world_streamer.zig (647 lines) violates Single Responsibility Principle by conflating:

1. Chunk queue orchestration (gen_queue, mesh_queue, upload_queue)
2. Predictive loading (PlayerMovement at lines 74-130)
3. LOD coordination (interaction with LODManager at lines 351-358, 275, 316)
4. GPU acceleration (direct GpuBlockBuffer/GpuMesher handling in processUploads at lines 361-416)

The three sub-issues are well-scoped and parallel-safe as noted. Key observations:

• 3.1: processGenJob (lines 461-509), processMeshJob (lines 512-578), and processUploads (lines 361-416) share the WorldStreamer context but have distinct lifecycle concerns that can be separated via a coordinator interface.

• 3.2: PlayerMovement is embedded in WorldStreamer but used independently by LODManager (velocity calculation at lines 352-356). Extracting a PredictiveLoadCoordinator would clarify the dependency direction.

• 3.3: GPU meshing logic in processUploads has two paths (GPU path at 368-389, CPU fallback at 390-412). The fallback at line 391 (data.mesh.upload) suggests this was the original design; preserving it is critical.

Risk: The chunk state machine (lines 6-14 in comments) spans all three extraction areas. Ensure state transitions remain atomic across coordinator boundaries during the refactor.

Scope: Appropriate - three focused extractors, no cross-cutting concerns. No sub-division needed.

opencode session  |  github run