Refactor: Decouple RHI into Subsystems

.github/workflows/build.yml

@@ -21,7 +21,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     timeout-minutes: 30
     steps:
     - uses: actions/checkout@v4
@@ -55,7 +55,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     timeout-minutes: 15
     steps:
     - uses: actions/checkout@v4
@@ -72,12 +72,14 @@ jobs:
 
     - name: Run unit tests
       run: nix develop --command zig build test
+      env:
+        ZIG_GLOBAL_CACHE_DIR: ${{ github.workspace }}/.zig-cache-global
 
   integration-test:
     permissions:
       contents: read
       id-token: write
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     timeout-minutes: 30
     steps:
     - uses: actions/checkout@v4
@@ -92,9 +94,37 @@ jobs:
         restore-prefixes-first-match: nix-${{ runner.os }}-
         paths: ~/.cache/nix
 
+    - name: Start headless Wayland compositor
+      run: |
+        mkdir -p /tmp/runtime-runner
+        chmod 700 /tmp/runtime-runner
+        export XDG_RUNTIME_DIR=/tmp/runtime-runner
+        nix develop --command weston --socket=headless --backend=headless-backend.so --width=1280 --height=720 &
+        echo "WAYLAND_DISPLAY=headless" >> $GITHUB_ENV
+        echo "XDG_RUNTIME_DIR=/tmp/runtime-runner" >> $GITHUB_ENV
+        sleep 5 # Wait for Weston to start up properly
+
     - name: Run integration smoke test
       env:
+        ZIG_GLOBAL_CACHE_DIR: ${{ github.workspace }}/.zig-cache-global
+      run: |
+        nix develop --command zig build test-integration
+
+    - name: Run world load smoke test (headless)
+      env:
+        ZIG_GLOBAL_CACHE_DIR: ${{ github.workspace }}/.zig-cache-global
         XDG_RUNTIME_DIR: /tmp/runtime-runner
+        WAYLAND_DISPLAY: headless
+        VK_ICD_FILENAMES: /run/opengl-driver/share/vulkan/icd.d/lvp_icd.x86_64.json
+        # Skip presentation and use dry-run mode to avoid driver crashes in CI
+        # Using build option -Dskip-present=true to guarantee it's baked in
+        # 3 frames is enough to test multi-frame synchronization logic in dry-run
+        ZIGCRAFT_SMOKE_FRAMES: "3"
+        ZIGCRAFT_SAFE_MODE: "1"
       run: |
-        mkdir -p $XDG_RUNTIME_DIR
-        xvfb-run -a nix develop --command zig build test-integration
+        # Find the actual path to the mesa driver and validation layers in the nix store
+        LVP_PATH=$(nix build --no-link --print-out-paths nixpkgs#mesa.drivers)/share/vulkan/icd.d/lvp_icd.x86_64.json
+        LAYER_PATH=$(nix build --no-link --print-out-paths nixpkgs#vulkan-validation-layers)/share/vulkan/explicit_layer.d
+        export VK_ICD_FILENAMES=$LVP_PATH
+        export VK_LAYER_PATH=$LAYER_PATH
+        nix develop --command zig build run -Dsmoke-test=true -Dskip-present=true

.github/workflows/opencode-pr.yml

@@ -8,7 +8,7 @@ jobs:
   opencode:
     # Don't run on draft PRs; do run when they become ready_for_review.
     if: ${{ github.event.pull_request.draft == false }}
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     permissions:
       id-token: write
       contents: write

.github/workflows/opencode-triage.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   triage:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     permissions:
       id-token: write
       contents: write

.github/workflows/opencode.yml

@@ -13,7 +13,7 @@ jobs:
       startsWith(github.event.comment.body, '/oc') ||
       contains(github.event.comment.body, ' /opencode') ||
       startsWith(github.event.comment.body, '/opencode')
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     permissions:
       id-token: write
       contents: write

.github/workflows/repo-automation.yml

@@ -14,7 +14,7 @@ permissions:
 jobs:
   label-pr:
     if: github.event_name == 'pull_request_target'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     steps:
       - name: Label PR
         uses: actions/labeler@v6
@@ -25,7 +25,7 @@ jobs:
 
   label-issue:
     if: github.event_name == 'issues'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.gitignore

@@ -1,11 +1,13 @@
 zig-cache/
 .zig-cache/
+.zig-cache-new/
 zig-out/
 blocks-temp/
 libs/zig-image/
 result
 .direnv/
 *-profile*
+test_output.txt
 .env
 .env.*
 !.env.example

assets/shaders/vulkan/sky.frag

@@ -65,7 +65,7 @@ float getVolShadow(vec3 p, float viewDepth) {
 
     if (proj.x < 0.0 || proj.x > 1.0 || proj.y < 0.0 || proj.y > 1.0 || proj.z > 1.0) return 1.0;
 
-    return texture(uShadowMaps, vec4(proj.xy, float(layer), proj.z - 0.002));
+    return texture(uShadowMaps, vec4(proj.xy, float(layer), proj.z + 0.002));
 }
 
 // Raymarched God Rays (Phase 4)

assets/shaders/vulkan/terrain.frag

@@ -111,7 +111,7 @@ float findBlocker(vec2 uv, float zReceiver, int layer) {
         for (int j = -1; j <= 1; j++) {
             vec2 offset = vec2(i, j) * searchRadius;
             float depth = texture(uShadowMapsRegular, vec3(uv + offset, float(layer))).r;
-            if (depth < zReceiver) {
+            if (depth > zReceiver) {
                 blockerDepthSum += depth;
                 numBlockers++;
             }
@@ -168,7 +168,7 @@ float calculateShadow(vec3 fragPosWorld, float nDotL, int layer) {
     float avgBlockerDepth = findBlocker(projCoords.xy, currentDepth, layer);
     if (avgBlockerDepth == -1.0) return 0.0; // No blockers
 
-    float penumbraSize = (currentDepth - avgBlockerDepth) / avgBlockerDepth;
+    float penumbraSize = (avgBlockerDepth - currentDepth) / max(avgBlockerDepth, 0.0001);
     float filterRadius = penumbraSize * 0.01; // Adjust multiplier for softness
     filterRadius = clamp(filterRadius, 0.0005, 0.005); // Min/max blur
 
@@ -196,7 +196,7 @@ float getVolShadow(vec3 p, float viewDepth) {
 
     if (proj.x < 0.0 || proj.x > 1.0 || proj.y < 0.0 || proj.y > 1.0 || proj.z > 1.0) return 1.0;
 
-    return texture(uShadowMaps, vec4(proj.xy, float(layer), proj.z - 0.002));
+    return texture(uShadowMaps, vec4(proj.xy, float(layer), proj.z + 0.002));
 }
 
 // Raymarched God Rays (Phase 4)

build.zig

@@ -8,6 +8,12 @@ pub fn build(b: *std.Build) void {
     const enable_debug_shadows = b.option(bool, "debug_shadows", "Enable debug shadow visualization resources") orelse false;
     options.addOption(bool, "debug_shadows", enable_debug_shadows);
 
+    const smoke_test = b.option(bool, "smoke-test", "Enable automated smoke test mode (auto-loads world and exits)") orelse false;
+    options.addOption(bool, "smoke_test", smoke_test);
+
+    const skip_present = b.option(bool, "skip-present", "Skip presentation (headless mode) to avoid driver crashes") orelse false;
+    options.addOption(bool, "skip_present", skip_present);
+
     const zig_math = b.createModule(.{
         .root_source_file = b.path("libs/zig-math/math.zig"),
         .target = target,

flake.nix

@@ -67,13 +67,15 @@
             pkgs.zls
             pkgs.pkg-config
             pkgs.glslang
+            pkgs.weston
           ];
 
           buildInputs = [
             pkgs.sdl3
             pkgs.vulkan-loader
             pkgs.vulkan-headers
             pkgs.vulkan-validation-layers
+            pkgs.mesa.drivers
           ];
 
           shellHook = ''

src/engine/audio/backend.zig

@@ -46,3 +46,36 @@ pub const IAudioBackend = struct {
         self.vtable.setCategoryVolume(self.ptr, category, volume);
     }
 };
+
+pub const DummyAudioBackend = struct {
+    backend: IAudioBackend,
+
+    pub fn init() DummyAudioBackend {
+        return .{
+            .backend = .{
+                .ptr = undefined,
+                .vtable = &VTABLE,
+            },
+        };
+    }
+
+    fn update(_: *anyopaque) void {}
+    fn setListener(_: *anyopaque, _: Vec3, _: Vec3, _: Vec3) void {}
+    fn playSound(_: *anyopaque, _: *const types.SoundData, _: types.PlayConfig) types.VoiceHandle {
+        return .{ .id = 0, .generation = 0 };
+    }
+    fn stopVoice(_: *anyopaque, _: types.VoiceHandle) void {}
+    fn stopAll(_: *anyopaque) void {}
+    fn setMasterVolume(_: *anyopaque, _: f32) void {}
+    fn setCategoryVolume(_: *anyopaque, _: types.SoundCategory, _: f32) void {}
+
+    const VTABLE = IAudioBackend.VTable{
+        .update = update,
+        .setListener = setListener,
+        .playSound = playSound,
+        .stopVoice = stopVoice,
+        .stopAll = stopAll,
+        .setMasterVolume = setMasterVolume,
+        .setCategoryVolume = setCategoryVolume,
+    };
+};

src/engine/audio/system.zig

@@ -10,7 +10,9 @@ const log = @import("../core/log.zig");
 
 pub const AudioSystem = struct {
     allocator: std.mem.Allocator,
-    backend: *sdl_backend.SDLAudioBackend,
+    backend: backend_pkg.IAudioBackend,
+    backend_ptr: ?*anyopaque = null, // To free if we allocated it
+    dummy_backend: ?backend_pkg.DummyAudioBackend = null,
     manager: manager_pkg.SoundManager,
 
     // Config
@@ -20,16 +22,26 @@ pub const AudioSystem = struct {
     pub fn init(allocator: std.mem.Allocator) !*AudioSystem {
         log.log.info("Initializing Audio System...", .{});
 
-        const config = sdl_backend.AudioConfig{};
-        const backend_inst = try sdl_backend.SDLAudioBackend.create(allocator, config);
-
         const self = try allocator.create(AudioSystem);
+        errdefer allocator.destroy(self);
+
         self.* = .{
             .allocator = allocator,
-            .backend = backend_inst,
+            .backend = undefined,
             .manager = manager_pkg.SoundManager.init(allocator),
         };
 
+        const config = sdl_backend.AudioConfig{};
+        if (sdl_backend.SDLAudioBackend.create(allocator, config)) |backend_inst| {
+            self.backend = backend_inst.backend;
+            self.backend_ptr = @ptrCast(backend_inst);
+        } else |err| {
+            log.log.warn("Failed to initialize SDL Audio Backend: {}. Falling back to dummy backend.", .{err});
+            self.dummy_backend = backend_pkg.DummyAudioBackend.init();
+            self.backend = self.dummy_backend.?.backend;
+            self.enabled = false;
+        }
+
         // Create some default test sounds
         _ = try self.manager.createTestSound("test_tone");
 
@@ -45,14 +57,17 @@ pub const AudioSystem = struct {
     pub fn deinit(self: *AudioSystem) void {
         self.stopAll();
         self.manager.deinit();
-        self.backend.destroy();
+        if (self.backend_ptr) |ptr| {
+            const backend_inst: *sdl_backend.SDLAudioBackend = @ptrCast(@alignCast(ptr));
+            backend_inst.destroy();
+        }
         self.allocator.destroy(self);
     }
 
     /// Update the audio backend. Should be called once per frame.
     pub fn update(self: *AudioSystem) void {
         if (!self.enabled) return;
-        self.backend.backend.update();
+        self.backend.update();
     }
 
     /// Update the listener's 3D position and orientation.
@@ -61,23 +76,23 @@ pub const AudioSystem = struct {
     /// listener_up: Up vector (normalized).
     pub fn setListener(self: *AudioSystem, listener_pos: Vec3, listener_fwd: Vec3, listener_up: Vec3) void {
         if (!self.enabled) return;
-        self.backend.backend.setListener(listener_pos, listener_fwd, listener_up);
+        self.backend.setListener(listener_pos, listener_fwd, listener_up);
     }
 
     /// Set the master volume (applied to all sounds).
     /// volume: 0.0 to 1.0
     pub fn setMasterVolume(self: *AudioSystem, volume: f32) void {
         if (!self.enabled) return;
         const clamped = std.math.clamp(volume, 0.0, 1.0);
-        self.backend.backend.setMasterVolume(clamped);
+        self.backend.setMasterVolume(clamped);
     }
 
     /// Set volume for a specific category (Music, SFX, Ambient).
     /// volume: 0.0 to 1.0
     pub fn setCategoryVolume(self: *AudioSystem, category: types.SoundCategory, volume: f32) void {
         if (!self.enabled) return;
         const clamped = std.math.clamp(volume, 0.0, 1.0);
-        self.backend.backend.setCategoryVolume(category, clamped);
+        self.backend.setCategoryVolume(category, clamped);
     }
 
     /// Play a sound by name (2D, no spatialization).
@@ -91,7 +106,7 @@ pub const AudioSystem = struct {
         }
 
         if (self.manager.getSound(handle)) |sound| {
-            return self.backend.backend.playSound(sound, .{});
+            return self.backend.playSound(sound, .{});
         }
         return null;
     }
@@ -104,7 +119,7 @@ pub const AudioSystem = struct {
         if (handle == types.InvalidSoundHandle) return null;
 
         if (self.manager.getSound(handle)) |sound| {
-            return self.backend.backend.playSound(sound, .{
+            return self.backend.playSound(sound, .{
                 .is_spatial = true,
                 .position = pos,
             });
@@ -115,11 +130,12 @@ pub const AudioSystem = struct {
     /// Stop a specific voice handle.
     pub fn stop(self: *AudioSystem, handle: types.VoiceHandle) void {
         if (!self.enabled) return;
-        self.backend.backend.stopVoice(handle);
+        self.backend.stopVoice(handle);
     }
 
     /// Stop all currently playing sounds.
     pub fn stopAll(self: *AudioSystem) void {
-        self.backend.stopAllVoices();
+        if (!self.enabled) return;
+        self.backend.stopAll();
     }
 };

src/engine/ecs/systems/render.zig

@@ -16,9 +16,9 @@ pub const RenderSystem = struct {
     rhi: *RHI,
     missing_transform_logged: bool,
 
-    pub fn init(rhi: *RHI) RenderSystem {
-        const buffer = rhi.*.createBuffer(@sizeOf(@TypeOf(wireframe.line_vertices)), .vertex);
-        rhi.*.uploadBuffer(buffer, std.mem.asBytes(&wireframe.line_vertices));
+    pub fn init(rhi: *RHI) !RenderSystem {
+        const buffer = try rhi.*.createBuffer(@sizeOf(@TypeOf(wireframe.line_vertices)), .vertex);
+        try rhi.*.uploadBuffer(buffer, std.mem.asBytes(&wireframe.line_vertices));
 
         return .{
             .buffer_handle = buffer,

src/engine/graphics/atmosphere_system.zig

@@ -30,11 +30,11 @@ pub const AtmosphereSystem = struct {
         };
         const cloud_indices = [_]u16{ 0, 1, 2, 0, 2, 3 };
 
-        self.cloud_vbo = rhi_instance.createBuffer(@sizeOf(@TypeOf(cloud_vertices)), .vertex);
-        self.cloud_ebo = rhi_instance.createBuffer(@sizeOf(@TypeOf(cloud_indices)), .index);
+        self.cloud_vbo = try rhi_instance.createBuffer(@sizeOf(@TypeOf(cloud_vertices)), .vertex);
+        self.cloud_ebo = try rhi_instance.createBuffer(@sizeOf(@TypeOf(cloud_indices)), .index);
 
-        rhi_instance.uploadBuffer(self.cloud_vbo, std.mem.asBytes(&cloud_vertices));
-        rhi_instance.uploadBuffer(self.cloud_ebo, std.mem.asBytes(&cloud_indices));
+        try rhi_instance.uploadBuffer(self.cloud_vbo, std.mem.asBytes(&cloud_vertices));
+        try rhi_instance.uploadBuffer(self.cloud_ebo, std.mem.asBytes(&cloud_indices));
 
         return self;
     }