[MED] Improve error context - Add file:line information and descriptive error messages

[MichaelFisher1997]

Problem

Many functions in the codebase use Zig's error unions with generic error types, making it difficult to trace the origin of errors. Long try chains can obscure where errors actually occur.

Current State

Example from app.zig:

const rhi = try rhi_vulkan.createRHI(allocator, wm.window, null, ...);
errdefer rhi.deinit();
try rhi.init(allocator, null);

When an error occurs, you only see the error type (e.g., error.OutOfMemory) without context about which specific call failed.

Proposed Solution

Improve error handling in two ways:

Option 1: Rich Error Types

Create error structs with context including file, line, and message.

Option 2: Logging with Context

Add detailed logging at error sites using @src() for file:line info.

Option 3: Zig Error Return Traces

Use @errorReturnTrace() in debug builds to capture stack traces.

Specific Areas to Improve

• App.init() - Add context for each subsystem initialization
• World.init() - Distinguish between storage, streamer, renderer init failures
• ChunkMesh.build() - Report which chunk failed meshing
• RHI operations - Include resource type and size in errors
• Shader compilation - Include shader name and error message

Benefits

• Faster debugging when errors occur
• Clearer error messages for users
• Easier to diagnose issues in production

Acceptance Criteria

• Critical initialization paths have detailed error logging
• Error messages include file and line information
• Debug builds include full stack traces
• Document error handling strategy
• Tests still pass

Related Files

• src/game/app.zig
• src/world/world.zig
• src/engine/core/log.zig
• src/engine/graphics/rhi.zig

Estimated Effort

Medium (requires auditing all error paths)

[opencode-agent]

Based on my analysis of the codebase, here's my assessment:

Classification

Feature Request - Enhancement to improve error debugging capabilities.

Analysis

Current State: The codebase extensively uses Zig's error unions with generic error types (e.g., error.OutOfMemory, RhiError). Looking at App.init() in src/game/app.zig:83-334, there are long chains of try statements where failures provide no context about which subsystem failed.

Proposed Solutions Assessment:

1. Option 2 (Logging with @src()) is most idiomatic for Zig and easiest to implement
2. Option 3 (@errorReturnTrace()) already works in debug builds but needs documentation
3. Option 1 (Rich error structs) adds complexity that may not be necessary

Scope Assessment: Should Break Into Sub-Issues

This issue spans 5+ independent subsystems and should be split for manageable implementation:

Suggested Sub-Issues:

1. Roadmapv3 #1 - Core Error Context Infrastructure (src/engine/core/log.zig)

   • Add log.errContext() helper using @src()
   • Include file:line in error log format
   • Add RhiError context extensions

2. feat: implement layered noise worldgen with multi-noise biomes #2 - App Initialization Error Context (src/game/app.zig)

   • Add context logging around each subsystem init (RHI, audio, UI, etc.)
   • Distinguish between WindowManager, RHI, and resource pack failures

3. feat: voxel engine with worldgen, async streaming, and render stability #3 - World System Error Context (src/world/world.zig)

   • Distinguish between ChunkStorage, WorldStreamer, WorldRenderer init failures
   • Add chunk coordinates to ChunkMesh.build() errors

4. feat: worm cave system with connected underground networks #4 - RHI Error Context (src/engine/graphics/rhi*.zig)

   • Include resource type (buffer/texture/shader) and size in error messages
   • Add shader name to compilation errors

5. code quality #5 - Documentation & Debug Builds

   • Document error handling strategy in AGENTS.md
   • Ensure @errorReturnTrace() is mentioned for debug builds

Benefits of splitting: Each sub-issue can be reviewed independently, tested separately, and implemented in parallel. The acceptance criteria can be distributed across issues.

Would you like me to help create these sub-issues, or would you prefer to tackle this as a single PR with multiple commits?

opencode session  |  github run