[Audit][High] GpuMesher waits on in_flight_fences before FrameManager initialization completes, causing indefinite hang

[MichaelFisher1997]

🔍 Module Scanned

(automated audit scan)

📝 Summary

calls on at line 168, but these fences may not be initialized if the GpuMesher is created before the FrameManager initializes the fence array in . If the fence at is null (zero), can either return immediately with (causing premature GPU reads of uninitialized memory) or hang indefinitely depending on driver behavior, leading to a hard hang of the game.

📍 Location

• File:
• Function/Scope:

🔴 Severity: High

• Critical: Crashes, data corruption, security vulnerabilities, GPU device loss

💥 Impact

If is initialized before has initialized its fence array (which happens in at line 60 of ), then will be null. Calling with a null fence handle causes undefined behavior:

• Best case: Returns immediately with , causing GpuMesher to read uninitialized result buffer data before GPU writes complete
• Worst case: Driver hangs indefinitely, freezing the game with no error logged

This can happen in any flow where GPU meshing is enabled but the GpuMesher is created before the FrameManager's fences are initialized.

🔎 Evidence

In :

In , fences are initialized:

In , fences are set to null during context creation:

If is created before runs (or if fails before the fence loop completes), the fences remain null. The null handle is then passed directly to , which is undefined behavior in Vulkan.

🛠️ Proposed Fix

Add a null-check guard in before waiting on the fence:

Alternatively, initialize the fence array in with valid (but unsignaled) fence handles, rather than null. This ensures the fence is always valid even before is called.

✅ Acceptance Criteria

• handles uninitialized fences gracefully without hanging
• No hangs observed when GPU meshing is enabled and game starts
• The fix has been verified with Zig 0.16.0 + SDL3 Dev Environment
  Compiler: 0.16.0
  assets/shaders/vulkan/ssao.frag
  assets/shaders/vulkan/ui_tex.frag
  assets/shaders/vulkan/sky.vert
  assets/shaders/vulkan/ssao.vert
  assets/shaders/vulkan/ssao_blur.frag
  assets/shaders/vulkan/water.frag
  assets/shaders/vulkan/debug_shadow.vert
  assets/shaders/vulkan/shadow.vert
  assets/shaders/vulkan/terrain.frag
  assets/shaders/vulkan/lpv_inject.comp
  assets/shaders/vulkan/culling.comp
  assets/shaders/vulkan/water.vert
  assets/shaders/vulkan/taa.frag
  assets/shaders/vulkan/ui.frag
  assets/shaders/vulkan/bloom_downsample.vert
  assets/shaders/vulkan/bloom_upsample.vert
  assets/shaders/vulkan/debug_shadow.vert
  assets/shaders/vulkan/fxaa.vert
  assets/shaders/vulkan/post_process.vert
  assets/shaders/vulkan/shadow.vert
  assets/shaders/vulkan/sky.vert
  assets/shaders/vulkan/ssao.vert
  assets/shaders/vulkan/taa.vert
  assets/shaders/vulkan/terrain.vert
  assets/shaders/vulkan/ui.vert
  assets/shaders/vulkan/ui_tex.vert
  assets/shaders/vulkan/water.vert
  assets/shaders/vulkan/bloom_downsample.frag
  assets/shaders/vulkan/bloom_upsample.frag
  assets/shaders/vulkan/debug_shadow.frag
  assets/shaders/vulkan/fxaa.frag
  assets/shaders/vulkan/g_pass.frag
  assets/shaders/vulkan/post_process.frag
  assets/shaders/vulkan/shadow.frag
  assets/shaders/vulkan/sky.frag
  assets/shaders/vulkan/ssao.frag
  assets/shaders/vulkan/ssao_blur.frag
  assets/shaders/vulkan/taa.frag
  assets/shaders/vulkan/terrain.frag
  assets/shaders/vulkan/terrain_debug.frag
  assets/shaders/vulkan/ui.frag
  assets/shaders/vulkan/ui_tex.frag
  assets/shaders/vulkan/water.frag
  assets/shaders/vulkan/culling.comp
  assets/shaders/vulkan/depth_pyramid.comp
  assets/shaders/vulkan/lpv_inject.comp
  assets/shaders/vulkan/lpv_propagate.comp
  assets/shaders/vulkan/mesh.comp
  assets/shaders/vulkan/depth_pyramid.comp
  assets/shaders/vulkan/taa.vert
  assets/shaders/vulkan/ui_tex.vert
  assets/shaders/vulkan/debug_shadow.frag
  assets/shaders/vulkan/ui.vert
  assets/shaders/vulkan/shadow.frag
  assets/shaders/vulkan/g_pass.frag
  assets/shaders/vulkan/terrain.vert
  assets/shaders/vulkan/sky.frag
  assets/shaders/vulkan/mesh.comp
  assets/shaders/vulkan/lpv_propagate.comp
• A warning is logged when fences are not yet initialized, aiding debugging

📚 References

• undefined behavior with null handles: section 4.1.1 of Vulkan specification
• FrameManager initialization:
• GpuMesher fence usage:
• Context factory initialization:

[github-actions]

Comment on issue #736:

This is a valid bug. The analysis correctly identifies the issue:

Root cause confirmed: In gpu_mesher.zig:168, vkWaitForFences is called on in_flight_fences[prev_fi], but if GpuMesher.process() is called before FrameManager.init() completes (or if the fence array is zero-initialized via @memset in rhi_context_factory.zig:157), the fence handle could be null.

Why it's a real bug: FrameManager.init() initializes fences at lines 58-61 via vkCreateFence, but rhi_context_factory.zig:157 explicitly sets all in_flight_fences to null during context creation (via @memset). If FrameManager.init() hasn't run yet (or fails partway), those fences remain null. Passing a null fence to vkWaitForFences is undefined behavior per the Vulkan spec.

Fix direction: Add a null-check before vkWaitForFences in finalizeCompletedMeshes(). The proposed fix at line 168 should guard against null fences:

const fence = self.vk_ctx.frames.in_flight_fences[prev_fi];
if (fence == null) return; // or log warning
_ = c.vkWaitForFences(self.vk_ctx.vulkan_device.vk_device, 1, &fence, ...);

Alternatively, initialize fences to valid (unsignaled) handles in FrameManager.init() before the loop so they're never null.

Severity: High - confirmed. A null fence can cause indefinite hang or premature reads of uninitialized memory.
Duplicates: No duplicate issues found in the open queue.

opencode session  |  github run