[HIGH] Decompose World struct - Separate streaming, rendering, and LOD concerns

[MichaelFisher1997]

Problem

The World struct in src/world/world.zig (lines 47-63) combines multiple high-level concerns:

• Chunk storage management
• World streaming (loading/unloading)
• Rendering
• LOD (Level of Detail) system
• World generation

This violates SRP and creates tight coupling between these concerns.

Current State

World struct mixes storage, streaming, rendering, LOD, and generation responsibilities.

Proposed Solution

Extract three main subsystems:

1. WorldStreamer - Already exists, but make it the primary interface for streaming
2. WorldRenderer - Already exists, extract from World
3. WorldLOD - New struct to encapsulate LOD manager and renderer

Refactor World to be a facade/coordinator that delegates to these subsystems.

Benefits

• Each subsystem can be tested independently
• Clearer boundaries between streaming, rendering, and LOD
• Easier to modify one concern without affecting others
• Better separation of data (storage) from behavior (streaming/rendering)

Acceptance Criteria

• World struct reduced to coordinator role
• WorldStreamer becomes primary streaming interface
• WorldRenderer fully independent
• WorldLOD encapsulates LOD concerns
• All existing functionality preserved
• Tests still pass

Related Files

• src/world/world.zig
• src/world/world_streamer.zig
• src/world/world_renderer.zig
• src/world/lod_manager.zig
• src/world/lod_renderer.zig

SOLID Principle

Single Responsibility Principle (SRP)

[opencode-agent]

Looking at this issue, I need to analyze the current architecture and validate the concerns raised.

Classification

Type: Feature Request / Architectural Refactoring (SOLID Principle - SRP)

Current State Analysis

After reviewing the code, I can confirm the issue is valid but partially addressed:

What's Already Extracted (Good!)

• ✅ WorldStreamer in src/world/world_streamer.zig - handles async chunk loading/unloading
• ✅ WorldRenderer in src/world/world_renderer.zig - handles chunk rendering and MDI
• ✅ LODManager in src/world/lod_manager.zig - orchestrates multi-level chunk loading
• ✅ LODRenderer in src/world/lod_renderer.zig - handles LOD culling and drawing

Remaining SRP Violations in World struct (src/world/world.zig:47-63)

The World struct still has mixed responsibilities:

1. Direct storage access methods (lines 201-255):

   • getOrCreateChunk(), getBlock(), setBlock(), getChunk()
   • These should delegate to ChunkStorage directly

2. Coordination logic mixed with business logic (lines 257-272):

   • update() manually orchestrates renderer vertex allocator + streamer + LOD manager

3. Dual LOD management (lines 60-63):

   • Both lod_manager and lod_renderer fields with manual lifecycle management

Scope Assessment

This issue should be split into sub-issues because it spans multiple distinct refactoring areas:

Sub-Issue 1: World as Pure Facade

• Remove direct storage access methods from World
• Create a cleaner World API that delegates to subsystems
• Files: src/world/world.zig, src/world/chunk_storage.zig

Sub-Issue 2: LOD Subsystem Consolidation

• Create a unified WorldLOD struct that encapsulates both LODManager and LODRenderer
• Simplify World's LOD initialization and lifecycle
• Files: src/world/world.zig, new src/world/world_lod.zig

Sub-Issue 3: Update Loop Decoupling

• Extract update coordination into a separate system or simplify delegation
• Reduce coupling between World.update() and internal subsystem details
• Files: src/world/world.zig, src/world/world_streamer.zig

Recommendation

The current architecture is 70% complete - subsystems exist and are well-designed. The remaining work is interface cleanup.

Suggested approach:

1. Split this into the 3 sub-issues above for independent review/implementation
2. Each sub-issue can be a separate PR (low risk, easy to test)
3. This preserves the good work already done while addressing the SRP violations

Would you like me to elaborate on any specific subsystem, or shall we proceed with breaking this down into the suggested sub-issues?

opencode session  |  github run