Oculus Community Port

Oculus 社区移植版

非官方客户端 Forge 移植版 — 公开测试版

本项目并非 Oculus、Iris、Forge、Mojang、Microsoft、Sodium、Embeddium、OptiFine 或任何光影包开发者的官方发布版本。

Oculus 社区移植版是由社区独立维护的 Forge 延续项目，沿用 Oculus/Iris 光影包架构。

支持的版本

这两个 Minecraft 版本使用不同的 JAR 文件。请下载与当前实例 Minecraft 版本完全匹配的文件。

0.3.0-beta.1 是首个公开测试版。它显著改进了光影包加载、兼容性、GLSL 预处理、故障恢复、安全性、构建质量以及 Forge 帧图渲染。

在 AMD Radeon 集成显卡测试中，BSL v10.1.1 和 Complementary Reimagined r5.7.1 均成功激活并执行了兼容的 world0/final 渲染流程。

此测试版比最初的 Alpha 版本实用、稳定得多，但尚未成为完整的 Iris/Oculus 世界渲染器。报告画面差异前，请先阅读下方的测试版限制。

仅限客户端

• 仅将此模组安装在玩家客户端的 mods 文件夹中。
• 请勿将其安装在专用服务器上。
• 服务器无需安装 Oculus 社区移植版。
• 此模组不会添加方块、物品、实体、配方、维度、命令或服务端玩法机制。

运行要求

• 上方列出的任一受支持 Minecraft、Forge 和 Java 版本组合
• 兼容 OpenGL 的图形后端
• 实例的 shaderpacks 文件夹中需包含光影包 ZIP 文件或文件夹
• 不得安装 OptiFine

模组可以安全检测到 Vulkan，但在此测试版中使用 Vulkan 时会禁用光影包渲染。

功能

光影包加载与兼容性

• 可发现光影包文件夹和 ZIP 压缩包，无需解压。
• 支持将活动程序放在 shaders/world0 目录下的光影包。
• 继续支持较旧的根目录 shaders 全屏布局。
• 可展开受限的着色器 include 文件。
• 支持正确的条件式 GLSL 预处理。
• 可处理常见的旧版声明和以逗号分隔的 uniform。
• 支持兼容的旧版全屏顶点着色器。
• 提供常见的颜色、深度、阴影颜色和噪声纹理别名。
• 提供 BSL 和 Complementary Reimagined 已测试版本所需的额外最终渲染流程 uniform。
• 可检测不受支持的活动采样器、uniform、输出和着色器功能。
• 报告清晰的兼容性错误，而不会悄悄替换为不安全的值。

渲染与稳定性

• 使用 Forge 的现代帧图和 Minecraft 当前的 GPU 设备。
• 按确定顺序执行兼容的 deferred*、composite* 和 final 全屏阶段。
• 为现代复杂光影包使用保守且兼容的 world0/final 路径。
• 支持已识别的主颜色和主深度别名。
• 更新常用的帧、时间、世界、天气、摄像机、雾、天空和视图 uniforms。
• 以事务方式替换光影包。
• 替换光影包失败时，不会再立即销毁当前可用的光影状态。
• 保留最近一次成功准备的光影源代码。
• 请求替换失败时，资源重新加载后会重新编译最近一次成功准备的光影。
• 当前光影渲染通道失败时，可安全恢复原版渲染。
• 可在经过测试的 AMD Radeon 环境中处理窗口和全屏尺寸调整。
• 安全清理被替换的渲染管线和 uniform 缓冲区。
• 支持正常关闭世界和游戏。

光影包安全性

光影包被视为不可信的本地输入。加载器会防范以下风险：

• 路径遍历和绝对路径
• 目录形式的光影包内的符号链接
• 格式错误的 ZIP 归档
• 重复的 ZIP 条目
• 单个文件过大
• 目录或归档过大
• 压缩比过高
• 累计解压数据过多
• 无效的 UTF-8 光影源代码
• 包含循环
• 包含深度或数量过多
• 光影源代码展开后过大

性能设计

渲染器包含多项效率优化：

• 不会每帧都访问光影包文件。
• 不会每帧都预处理光影。
• 不会每帧都编译光影。
• 按尺寸缓存稳定的渲染目标描述。
• uniform 数据使用映射环形缓冲区。
• 多阶段全屏渲染在两个颜色目标之间交替进行。
• 兼容的 N 阶段管线现在只执行 N mod 2 次全屏纹理复制，而不是 N 次。
• 整个有序阶段序列会重复使用同一个命令编码器。
• 禁用光影时，不会编译或执行任何光影包程序。

尚未完成受控的平均 FPS 或 1% Low 基准对比。因此，此 Beta 版不会声称 FPS 有实测提升。

已测试的光影包

Beta 验证期间使用了以下版本的光影包：

• BSL v10.1.1
• Complementary Reimagined r5.7.1

这些光影包兼容的 world0/final 渲染通道，均已在两个受支持的 Minecraft 版本上成功完成准备、启用和执行。

此测试确认了兼容的最终阶段可以启用；并不表示这些光影包的所有视觉效果都已实现，也不表示输出在视觉效果上已与 Iris 或原版 Oculus 完全一致。

验证

Beta 版本通过以下测试进行了验证：

• 在 Minecraft 1.21.11 上通过 16 项自动兼容性和安全性测试
• 在 Minecraft 26.2 上通过 16 项自动兼容性和安全性测试
• 使用 --warning-mode all 完成完整 Gradle 构建
• 准备并启用 BSL v10.1.1 光影包
• 准备并启用 Complementary Reimagined r5.7.1 光影包
• 窗口和全屏尺寸调整
• 反复启用和禁用光影测试
• 30 秒实时渲染压力测试
• 故意尝试替换为不受支持的光影包
• 最近一次成功光影的恢复
• 正常关闭世界和游戏

实时测试使用的硬件：

• AMD Ryzen 5 5625U
• AMD Radeon 集成显卡
• OpenGL 4.6
• 16 GB DDR4 内存

生成的文件也使用 Microsoft Defender 进行了扫描，检测结果为零。

Beta 版的重要限制

目前还不是完整的 Iris/Oculus 世界渲染器。

以下主要功能尚未实现：

• 地形与区块 gbuffer 着色器路由
• 半透明地形 gbuffer 路由
• 实体与方块实体着色器路由
• 粒子着色器路由
• 手部、手持物品与覆盖层着色器路由
• 由资源包控制的天空渲染
• 由资源包控制的云层与天气渲染
• 由资源包控制的水体与世界几何阶段
• 真实的阴影贴图世界渲染
• 完整的附加 colortex 目标系统
• 完整的 depthtex 目标系统
• 前一帧与历史记录目标
• 法线与高光贴图
• 资源包提供的自定义贴图
• 完整的 OptiFine/Iris 属性系统
• 光影配置文件与配置表达式
• 完整的矩阵与 uniform 模型
• Vulkan 光影包渲染

由于存在这些限制：

• 当活动渲染阶段需要不受支持的资源时，部分光影包仍会无法运行。
• 部分成功启用的光影包，其视觉效果可能比在完整 Iris 或 Oculus 下更接近原版。
• 对 BSL 和 Complementary 的测试仅确认了兼容的最终渲染阶段可正常启用，并不代表视觉效果完全一致。
• 请勿宣传此 Beta 版支持所有 OptiFine 光影包。

安装

1. 安装受支持的 Minecraft 与 Forge 组合之一。
2. Minecraft 1.21.11 使用 Java 21；Minecraft 26.2 使用 Java 25。
3. 下载对应的 0.3.0-beta.1 正式版 JAR。
4. 将正式版 JAR 放入客户端的 mods 文件夹。
5. 不要将 -sources.jar 放入 mods 文件夹。
6. 启动一次 Minecraft。
7. 将光影包 ZIP 文件或目录放入实例的 shaderpacks 文件夹。
8. 打开 模组 → Oculus Community Port → 配置。
9. 选择一个光影包。
10. 启用光影并保存配置。

兼容性说明

• OptiFine：不兼容。使用此模组前请先移除它。
• OpenGL：支持的光影后端。
• Vulkan：可以检测到，但已禁用光影包渲染。
• 专用服务器：请勿在服务器端安装此模组。
• 其他 Forge 模组：在继续扩大测试范围的同时，尽力保持兼容。
• 资源包：尽力保持兼容。
• Rubidium、Embeddium 和 Sodium：不会伪造或捆绑当前并不存在的 Forge 依赖。

问题反馈

请向社区移植版反馈问题，不要联系原版 Oculus 或 Iris 的开发者：

https://github.com/Khaliiid0/Oculus-Community-Port/issues

请提供以下信息：

• logs/latest.log
• Minecraft 版本
• Forge 版本
• Java 版本
• Oculus Community Port 版本
• GPU 型号与驱动版本
• 当前使用的图形后端
• 光影包名称与确切版本
• 已安装的模组列表
• 准确的复现步骤
• 适用时提供截图

源代码与许可证

Oculus Community Port 仅依据GNU Lesser General Public License 第 3 版（LGPL-3.0-only）进行分发。

• 社区移植版源码：
  https://github.com/Khaliiid0/Oculus-Community-Port

• Oculus 原始项目：
  https://github.com/Asek3/Oculus

• Iris 项目：
  https://github.com/IrisShaders/Iris

每个已发布的二进制文件都必须提供对应的源码。

这是一个经过大幅修改的非官方社区分支，与原始项目、光影包开发者、Mojang、Microsoft 或 Forge 均无关联，也未获得他们的认可。