Oculus社区移植版

Oculus社区移植版

非官方的Oculus Forge延续版本，具备安全的着色器包加载和实验性全屏着色器渲染功能。

杂项

Oculus 社区移植版

非官方客户端 Forge 移植版 —— 实验性 Alpha 版本

本项目并非 Oculus、Iris、Forge、Mojang、Microsoft、Sodium、Embeddium 或 OptiFine 的官方发布版本。

Oculus 社区移植版是一个独立维护的 Oculus/Iris 着色器包架构移植版，面向 Minecraft Java 版 26.2 和 Minecraft Forge 65.1.0。

该项目为 Minecraft 26.2 带来了着色器包发现、安全的资源包加载、配置、旧版着色器适配、GPU 编译以及现代 Forge 帧图后处理功能。其目的是基于当前渲染引擎正确重建 Oculus，而不是通过兼容性存根隐藏已移除的 API。

仅限客户端

此模组仅限客户端。

  • 将其安装到玩家客户端的 mods 文件夹中。
  • 请勿将其安装在专用服务器上。
  • 服务器不需要 Oculus 社区移植版。
  • 它不会添加方块、物品、实体、配方、维度、命令或服务器游戏机制。
  • 其配置、着色器包、渲染管线及 GPU 资源完全保留在客户端。

需求

需求项 版本
Minecraft Java 版 26.2
Minecraft Forge 65.1.0
Java 25
图形后端 OpenGL
运行端 仅限客户端

此 Alpha 版本不需要外部 Rubidium、Embeddium 或 Sodium 模组。

当前功能

着色器包管理

  • 发现着色器包目录和 ZIP 文件
  • 无需解压即可读取 ZIP 包
  • 支持包内 shaders 文件夹周围包含单个包装目录
  • 保存所选择的包和启用状态
  • 提供 Forge 模组列表配置界面
  • 无需完全重启游戏即可重载所选的着色器资源
  • 在 latest.log 中报告包准备和着色器编译失败信息

可用的着色器管线

  • 使用 Forge 现代的 AddFramePassEvent 帧图集成
  • 通过 Minecraft 当前活跃的 GPU 设备编译着色器
  • 按确定性顺序执行兼容的全屏阶段：
    • deferred
    • deferred1 至 deferred15
    • composite
    • composite1 至 composite15
    • final
  • 支持为每个全屏阶段匹配相应的旧版 .vsh 顶点着色器
  • 当缺少 .vsh 时，提供现代全屏顶点着色器
  • 适配常见的旧版 GLSL 结构，例如：
    • varying
    • texture2D
    • texture2DLod
    • gl_FragColor
    • gl_FragData[0]
    • ftransform()
    • gl_MultiTexCoord0
  • 支持已识别的主颜色和主深度采样器别名
  • 按顺序执行多个兼容的后处理阶段

Uniform 支持

当前兼容层可更新常见的旧版值，包括：

  • 视图宽度、视图高度和宽高比
  • 帧时间、帧计数器和帧时间计数器
  • 世界时间和世界天数
  • 降雨强度和湿润度
  • 摄像机及前一帧摄像机位置
  • 眼部高度和眼部介质
  • 近平面和远平面距离
  • 太阳角度
  • 屏幕亮度
  • 雾颜色和天空颜色

Minecraft 26.2 渲染安全性

  • 检测当前活跃的图形后端
  • 仅允许在受支持的 OpenGL 路径上运行着色器包渲染
  • 在 Vulkan 上自动禁用着色器渲染
  • 绝不尝试在 Vulkan 上原样运行 OpenGL 风格的着色器包代码
  • 将从 Minecraft 26.2 的反向深度表示中识别出的后处理深度采样转换为旧版包所期望的前向深度值
  • 在替换和关闭期间关闭模组拥有的映射 GPU 缓冲区
  • 在源适配、编译或运行时着色器失败后恢复原版渲染

着色器包输入安全

着色器包被视为不受信任的本地输入。加载器包含以下防护措施：

  • ZIP 路径遍历和绝对路径
  • 目录符号链接逃逸
  • 格式错误的 ZIP 文件
  • 重复的 ZIP 条目
  • 过大的文件和归档文件
  • 过高的压缩比
  • 无效的 UTF-8 着色器源代码
  • 递归包含及包含循环
  • 过度的包含深度或数量
  • 过度的扩展后着色器源代码

性能设计

该 Alpha 版本旨在避免在热渲染路径中执行不必要的工作：

  • 包发现、文件读取和源代码准备不会每帧运行。
  • 着色器程序不会每帧重新编译。
  • 稳定的渲染目标描述符按大小缓存。
  • 常见 uniform 使用映射环形缓冲区。
  • GPU 对象的创建和使用保持在渲染线程上。
  • 着色器源代码和归档读取与逐帧渲染分离。
  • 当着色器禁用时，不会编译或执行任何着色器包程序，Forge/原版世界渲染保持活跃。

与未来 Forge 26.2 优化模组的兼容性将尽可能通过经过验证的公共 API 处理。此构建不会假装存在不可用的 Rubidium 或 Embeddium 26.2 版本，也不会捆绑 Sodium 实现类。

重要 Alpha 限制

这是首个功能性渲染 Alpha 版本，尚不能完全代替生产环境中的 Oculus 或 Iris。

以下主要功能尚未实现：

  • 地形和区块 gbuffer 着色器路由
  • 实体和方块实体 gbuffer 路由
  • 粒子、第一人称手部、手持物品和覆盖层着色器路由
  • 包控制的天空、太阳、月亮、星星、云、天气、水和半透明几何体阶段
  • 阴影贴图世界渲染
  • 额外的 colortex 和 depthtex 附件
  • 法线和高光纹理支持
  • 自定义包纹理和噪声纹理
  • 前一帧/历史渲染目标
  • 完整的 OptiFine/Iris 属性、配置文件、指令、表达式和预处理器模型
  • Vulkan 着色器包渲染

因此，复杂的着色器包可能无法启用或无法呈现其预期的外观。不支持的采样器、uniform、输出和着色器功能将产生诊断信息，而不是悄悄接收伪造的默认数据。只要有可能恢复，就会恢复原版渲染。

请不要宣传此 Alpha 版本支持所有 OptiFine 着色器包。

着色器包兼容性目标

长期目标是与现有的 ShadersMod 和 OptiFine 风格着色器包兼容，而无需包作者重写它们。兼容性正针对 Minecraft 26.2 的现代渲染 API 逐个子系统实现。

目前，轻量级包以及兼容的全屏 deferred/composite/final 程序是支持的测试范围。

安装方法

  1. 安装 Minecraft 26.2。
  2. 安装 Minecraft Forge 65.1.0。
  3. 将启动器配置为使用 Java 25。
  4. 将 oculus-forge-26.2-0.2.0-alpha.1.jar 放入客户端的 mods 文件夹中。
  5. 请勿将 -sources.jar 文件放入 mods 文件夹。
  6. 启动 Minecraft 一次。
  7. 将着色器包 ZIP 文件或目录放入游戏实例的 shaderpacks 目录中。
  8. 打开 模组 → Oculus 社区移植版 → 配置。
  9. 选择一个包，启用着色器，然后保存。

兼容性说明

  • OptiFine： 不兼容。使用此模组前请移除 OptiFine。
  • OpenGL： 受支持的着色器后端。
  • Vulkan： 着色器将自动禁用；Vulkan 着色器渲染未实现。
  • 专用服务器： 请勿在服务器端安装此模组。
  • 其他 Forge 模组： 尽力兼容；请将可复现的冲突报告到此移植版的问题跟踪器。
  • 资源包： 预计可以共存，但完整的资源包测试矩阵尚未完成。
  • 优化模组： 尚未正式验证任何 Forge 26.2 渲染器集成。

问题报告

请向 https://github.com/Khaliiid0/Oculus-Community-Port/issues 报告问题，而不是向原始 Oculus 或 Iris 维护者报告。

请附上以下信息：

  • logs/latest.log
  • Minecraft、Forge、Java 和模组版本
  • GPU 型号和驱动程序
  • 当前活跃的图形后端
  • 着色器包名称和版本
  • 已安装的模组列表
  • 准确的重现步骤

源代码、许可和归属

Oculus 社区移植版根据 GNU LGPL 3.0 仅限版本（LGPL-3.0-only） 分发。

该项目保留了所需的许可、版权、署名和声明文件。每个已发布二进制的相应源代码必须始终保持可从社区移植版的公共源代码仓库获取。

这是一个经过重大修改的非官方社区分支。它与原始 Oculus 或 Iris 贡献者、Minecraft Forge、Mojang、Microsoft、Sodium、Embeddium、OptiFine 或任何着色器包开发者均无关联，也未获得其认可。

项目图标是专门为此社区移植版创建的原创 AI 辅助品牌资产。它不复制原始 Oculus、Iris、Minecraft、Meta、Forge 或 Modrinth 徽标，也不描绘游戏内内容。