Loading SPIR-V Vulkan shaders in a Fabric mod (VulkanMod)

[Gajaweera112]

Hi everyone 👋
I’m working on a Vulkan-based shader loader mod for Minecraft Java Edition using Fabric + VulkanMod, and I’d like some guidance from people familiar with Vulkan or Minecraft rendering internals.

What I’m trying to do

I want to load precompiled SPIR-V shaders (.spv) at runtime and create Vulkan shader modules that can be used in a custom render pipeline (similar to how OptiFine/Iris handle GLSL, but via Vulkan).

The shaders compile correctly using glslc, and validation tools report no issues.

---

Expected behavior

• SPIR-V files load from resources
• vkCreateShaderModule succeeds
• Shader modules are usable in a Vulkan pipeline

---

Actual behavior

vkCreateShaderModule fails at runtime with an error similar to:

VK_ERROR_INVALID_SHADER_NV
or
VK_ERROR_INVALID_SHADER

This happens even though:

• The SPIR-V validates successfully with spirv-val
• The same shader works in standalone Vulkan test apps

---

Environment

• OS: Linux (Wayland)
• Minecraft: Java Edition 1.20.x
• Mod Loader: Fabric
• Vulkan Integration: VulkanMod
• Java: 21
• GPU: Intel / AMD (tested on both)
• Shader Compiler: glslc

---

Relevant code (simplified)

ByteBuffer spirv = loadShader("shaders/world0/terrain.vert.spv");

VkShaderModuleCreateInfo createInfo =
    VkShaderModuleCreateInfo.calloc()
        .sType(VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO)
        .pCode(spirv);

LongBuffer pShaderModule = memAllocLong(1);

int result = vkCreateShaderModule(device, createInfo, null, pShaderModule);

The ByteBuffer is direct, aligned, and its size is a multiple of 4.

---

What I’ve tried so far

• ✔️ Verified SPIR-V version compatibility
• ✔️ Ensured correct entry point (main)
• ✔️ Checked descriptor layouts
• ✔️ Enabled Vulkan validation layers
• ✔️ Tested multiple GPUs
• ❌ Still fails inside Minecraft + VulkanMod

---

Questions

1. Are there additional constraints on SPIR-V when used inside Minecraft’s Vulkan renderer?
2. Does VulkanMod impose pipeline layout or shader interface requirements that differ from standard Vulkan?
3. Is there a known issue with Intel/AMD drivers when loading SPIR-V in this context?
4. Would it be safer to translate GLSL → SPIR-V at runtime, instead of shipping precompiled shaders?

---

Goal

I’m aiming to build a modern, Vulkan-native shader ecosystem for Minecraft, with:

• Hot-reloadable shaders
• Cross-GPU compatibility
• High performance and low CPU overhead

Any insights, examples, or pointers to existing implementations would be hugely appreciated 🙏

Thanks in advance!

Guidelines

• I have read and understood this category's guidelines before making this post.

[AnujaGajaweera]

“Does VulkanMod impose pipeline layout or shader interface requirements that differ from standard Vulkan?”

Yes — indirectly.
VulkanMod does not invent a new Vulkan specification, but it operates inside Minecraft’s existing rendering architecture, which imposes constraints that standard standalone Vulkan apps do not have.

In practice, this means your SPIR-V can be perfectly valid Vulkan, yet still fail inside VulkanMod.

---

🧠 The Core Issue: You’re Not the Vulkan “Owner”

In a normal Vulkan application:

• You own the instance
• You own the device
• You define descriptor sets
• You define pipeline layouts
• You control render passes

In VulkanMod:

• Minecraft owns the render graph
• VulkanMod translates OpenGL-style assumptions into Vulkan
• Pipelines, descriptor layouts, and push constants may already exist
• Your shader must match what VulkanMod expects, not what Vulkan allows

This is the key mental shift.

---

⚠️ Common SPIR-V Mismatches That Cause vkCreateShaderModule or Pipeline Failures

1️⃣ Descriptor set & binding expectations

VulkanMod often assumes fixed descriptor sets similar to Minecraft’s GL pipeline:

Typical expectations:

layout(set = 0, binding = 0) uniform sampler2D DiffuseSampler;
layout(set = 0, binding = 1) uniform sampler2D Lightmap;

If your SPIR-V:

• Uses set = 1+
• Uses dynamic bindings
• Reorders bindings
• Uses unused bindings

👉 Pipeline creation may fail after shader module creation, or validation may flag it.

---

2️⃣ Push constant layout mismatches

Minecraft-style shaders often rely on uniform buffers, not push constants.

If your shader contains:

layout(push_constant) uniform Push {
    mat4 mvp;
};

…but VulkanMod:

• Does not declare push constants
• Or declares a different size

👉 Vulkan validation will allow it, but VulkanMod’s pipeline layout will not.

---

3️⃣ Entry point and stage assumptions

VulkanMod typically expects:

• Entry point: main
• One stage per module
• No specialization constants unless explicitly supported

Using:

• Multiple entry points
• Non-main entry points
• Stage interfaces not matching Minecraft’s vertex format

👉 Can break silently or fail at runtime.

---

4️⃣ GLSL → SPIR-V version issues

Even if spirv-val passes, driver + mod + shader version combinations matter.

Safe baseline:

glslc --target-env=vulkan1.1

Avoid:

• Vulkan 1.3 features
• Mesh shaders
• Advanced subgroup ops
• Descriptor indexing extensions

Minecraft’s rendering model does not expose these.

---

🧩 Why the Same Shader Works in Standalone Vulkan

Standalone Vulkan apps:

• Explicitly define descriptor layouts
• Explicitly define pipeline layouts
• Explicitly match shader interfaces

In VulkanMod:

• Layouts may be predefined
• You must conform to them
• You often don’t see them directly

So your shader is valid — it’s just incompatible with the host pipeline.

---

✅ Practical Recommendations

✔ Mirror Minecraft / Iris / OptiFine conventions

Study how existing Minecraft shaders define:

• Descriptor sets
• Uniform buffers
• Vertex inputs

Treat Vulkan as the backend, not the API you design against.

---

✔ Start with minimal shaders

Test with:

#version 450
layout(location = 0) out vec4 color;
void main() {
    color = vec4(1.0);
}

If that fails, the issue is not your shader logic — it’s integration.

---

✔ Validate pipeline layout compatibility

If possible:

• Log descriptor set layouts VulkanMod creates
• Compare them to your shader reflection output (spirv-cross)

Mismatch = failure.

---

✔ Prefer runtime GLSL → SPIR-V (if supported)

Some modders avoid this entire class of issues by:

• Keeping GLSL
• Letting VulkanMod control compilation
• Ensuring layouts match automatically

Precompiled SPIR-V is less forgiving.

---

📌 Final Answer (TL;DR)

• VulkanMod follows standard Vulkan, but inside Minecraft’s rendering constraints
• Your SPIR-V must match existing pipeline layouts
• Descriptor sets, bindings, and push constants must align exactly
• Valid SPIR-V ≠ usable SPIR-V in VulkanMod

You are targeting a Vulkan backend for a GL-era engine — compatibility matters more than correctness.

[staniszewskaklaudia04-afk]

xcvvvvvvvvvvvvvvvvvvvvvvvvvvvv

[staniszewskaklaudia04-afk]

****iigknb_ v[repg.hklho ,f.,hoty te,fjeejhet t r r r r r r i0ijok4oooo4jjkdnhmsv se3oo43q0iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii-;llllllllllllllllllllllllllllllllllllllllllllll jrhrj_