VulkanModNeoForge

English

VulkanMod NeoForge is a client-side Minecraft mod that replaces the game's default OpenGL rendering pipeline with a true, native Vulkan implementation. It is a port of the original VulkanMod — a Fabric/Quilt mod — to the NeoForge mod loader, specifically targeting Minecraft 1.21.

Unlike wrapper solutions such as Zink, VulkanMod does not simply layer Vulkan over OpenGL. Instead, it intercepts Minecraft's OpenGL calls in real time and translates them directly into Vulkan operations, providing a genuine rendering engine replacement that leverages modern GPU features and reduces CPU overhead.

The mod is fully localized in Chinese for the configuration interface and in-game messages, making it easier for Chinese-speaking players to adjust settings and understand prompts. Special thanks to the VulkanMod Translations project by scully06 for providing the Chinese localization resource pack.

The original VulkanMod is an experimental project that introduces a brand new Vulkan-based voxel rendering engine to Minecraft Java Edition, aiming to replace the default OpenGL 3.2 renderer and improve performance. VulkanMod NeoForge brings this engine to the NeoForge ecosystem.

Key Features

• Complete Rendering Engine Replacement – Intercepts OpenGL calls and translates them to Vulkan operations in real time
• True Native Vulkan – Not a wrapper; directly uses Vulkan APIs for rendering
• Target Platform – Minecraft 1.21 with NeoForge 21.0.167+
• Current Version – 0.5.1-dev+3
• License – LGPL-3.0
• GPU Requirement – Vulkan 1.2 support or higher
• Chinese Localization – Full Chinese translation for the config screen and UI

Technical Highlights

• Direct GL Class Replacement – Replaces Minecraft's OpenGL classes (such as GL11, GL14, GL15, etc.) at the bytecode level, redirecting all rendering calls to the Vulkan backend without performance‑heavy interception layers.
• Vulkan instance, device, and swapchain lifecycle management
• Memory allocation via Vulkan Memory Allocator (VMA)
• Real-time GLSL to SPIR-V shader conversion via ShaderC
• Chunk-based terrain rendering optimization
• Multiple chunk culling algorithms
• Indirect draw mode to reduce CPU overhead
• Native Wayland support
• GPU selector

VKNConfig – Boot‑time Configuration

VKNConfig is a low‑level configuration system that applies settings before the mod fully initializes. Unlike the in‑game graphics options (saved in vulkanmod_settings.json), VKNConfig controls boot‑time behaviors that affect how the mod loads and interacts with NeoForge.

The configuration is stored in config/vkn-boot-config.json and includes three key options:

• forceReapplyGLMixins – Forces the re‑application of GL mixins. Useful for mod compatibility or debugging.
• useVulkanTransformers – Enables or disables the Vulkan transformer pipeline. Disabling may reduce performance but can help with certain crashes.
• hideVulkanLibs – Hides the internal Vulkan library modules from the in‑game mod list, keeping the mods screen clean.

These settings are read at startup. If the file does not exist, it is automatically created with default values. The hideVulkanLibs option, when enabled, removes the "vulkan‑libs" entries from the mod list via reflection, ensuring they do not appear in the UI.

System Boundaries

Manages:

• Vulkan instance, device, and swapchain lifecycle
• Memory allocation via VMA
• GLSL to SPIR-V shader conversion
• Chunk-based terrain rendering optimization
• OpenGL compatibility layers for GUI and post-processing

Does Not Manage:

• Minecraft game logic, ticks, or entity AI
• Networking or server-side operations
• NeoForge mod bus events unrelated to rendering

Important Notes

• This mod is client-side only.
• Mods that make direct OpenGL calls may crash the game.
• Shader support is still under development.
• This is a complete rewrite of the rendering engine, not a compatibility layer.

简体中文

VulkanMod NeoForge 是一款客户端 Minecraft 模组，将游戏默认的 OpenGL 渲染管线替换为真正原生的 Vulkan 实现。该项目是原版 VulkanMod —— 一款 Fabric/Quilt 模组 —— 针对 NeoForge 模组加载器的移植版本，专门支持 Minecraft 1.21。

与 Zink 等封装方案不同，VulkanMod 并非简单地在 Vulkan 上覆盖 OpenGL，而是实时拦截 Minecraft 的 OpenGL 调用并直接翻译为 Vulkan 操作，提供了真正的渲染引擎替换，充分利用现代 GPU 特性并降低 CPU 开销。

该模组的配置界面和游戏内提示信息已完整汉化，方便中文玩家调整设置和理解各项功能。特别感谢 VulkanMod Translations 项目（作者 scully06）提供的汉化资源包。

原版 VulkanMod 是一个实验性项目，为 Minecraft Java 版引入了全新的基于 Vulkan 的体素渲染引擎，旨在替代默认的 OpenGL 3.2 渲染器以提升性能。VulkanMod NeoForge 将此引擎带到了 NeoForge 生态。

主要特性

• 完整的渲染引擎替换 – 实时拦截 OpenGL 调用并转换为 Vulkan 操作
• 真正的原生 Vulkan – 非封装，直接使用 Vulkan API 进行渲染
• 目标平台 – Minecraft 1.21 搭配 NeoForge 21.0.167+
• 当前版本 – 0.5.1-dev+3
• 开源协议 – LGPL-3.0
• GPU 要求 – 支持 Vulkan 1.2 或更高版本
• 中文汉化 – 配置界面和 UI 已完整翻译为中文

技术亮点

• 直接的 GL 类替换 – 在字节码层面直接替换 Minecraft 的 OpenGL 类（如 GL11、GL14、GL15 等），将所有渲染调用重定向至 Vulkan 后端，避免性能损耗严重的拦截层。
• Vulkan 实例、设备和交换链生命周期管理
• 通过 Vulkan Memory Allocator (VMA) 进行内存分配
• 通过 ShaderC 实现 GLSL 到 SPIR-V 的实时着色器转换
• 基于区块的地形渲染优化
• 多重区块剔除算法
• 间接绘制模式以减少 CPU 开销
• 原生 Wayland 支持
• GPU 选择器

VKNConfig —— 启动时配置

VKNConfig 是一个在模组完全初始化之前就生效的底层配置系统。它与游戏内的图形设置（保存在 vulkanmod_settings.json 中）不同，VKNConfig 控制的是影响模组加载过程本身以及模组与 NeoForge 交互方式的启动时行为。

配置文件位于 config/vkn-boot-config.json，包含以下三个关键选项：

• forceReapplyGLMixins：强制重新应用 GL Mixin。可用于解决模组兼容性问题或进行调试。
• useVulkanTransformers：启用或禁用 Vulkan 转换器管线。禁用可能会降低性能，但有助于解决某些崩溃问题。
• hideVulkanLibs：在游戏内的模组列表中隐藏内部的 Vulkan 库模块，保持模组列表整洁。

这些设置在游戏启动时读取。如果配置文件不存在，会自动创建并填入默认值。当 hideVulkanLibs 选项启用时，模组会通过反射将“vulkan‑libs”相关的模组条目从列表中移除，使其不在 UI 中显示。

系统边界

负责管理：

• Vulkan 实例、设备和交换链生命周期
• 通过 VMA 进行内存分配
• GLSL 到 SPIR-V 的着色器转换
• 基于区块的地形渲染优化
• 面向 GUI 和后期处理的 OpenGL 兼容层

不负责管理：

• Minecraft 游戏逻辑、Tick 或实体 AI
• 网络或服务端操作
• 与渲染无关的 NeoForge 模组总线事件

重要注意事项

• 本模组仅限客户端使用。
• 直接调用 OpenGL 的模组可能导致游戏崩溃。
• 着色器支持仍在开发中。
• 这是对渲染引擎的完全重写，而非兼容层。