Oculus Community Port

Unofficial client-side Forge port — public beta

This project is not an official release of Oculus, Iris, Forge, Mojang, Microsoft, Sodium, Embeddium, OptiFine, or any shader-pack developer.

Oculus Community Port is an independently maintained Forge continuation of the Oculus/Iris shader-pack architecture.

Supported versions

The two Minecraft versions use separate JARs. Download the file whose Minecraft version exactly matches your instance.

Version 0.3.0-beta.1 is the first public beta. It significantly improves shader-pack loading, compatibility, GLSL preprocessing, failure recovery, security, build quality, and Forge frame-graph rendering.

BSL v10.1.1 and Complementary Reimagined r5.7.1 successfully activated and executed their compatible world0/final passes during AMD Radeon integrated-GPU testing.

This beta is much more usable and stable than the original alpha, but it is not yet a complete Iris/Oculus world renderer. Please read the beta limitations below before reporting visual differences.

Client-side only

• Install the mod only in the player's client mods folder.
• Do not install it on a dedicated server.
• The server does not need Oculus Community Port.
• The mod adds no blocks, items, entities, recipes, dimensions, commands, or server-side gameplay mechanics.

Requirements

• One of the supported Minecraft, Forge, and Java combinations listed above
• An OpenGL-compatible graphics backend
• A shader-pack ZIP or directory inside the instance's shaderpacks folder
• OptiFine must not be installed

Vulkan is safely detected, but shader-pack rendering is disabled when using Vulkan in this beta.

Features

Shader-pack loading and compatibility

• Discovers shader-pack directories and ZIP archives without extracting them.
• Supports packs whose active programs are located under shaders/world0.
• Retains support for the older root shaders full-screen layout.
• Expands bounded shader includes.
• Performs proper conditional GLSL preprocessing.
• Handles common legacy declarations and comma-separated uniforms.
• Supports compatible legacy full-screen vertex shaders.
• Provides common color, depth, shadow-color, and noise texture aliases.
• Supplies additional final-pass uniforms required by tested versions of BSL and Complementary Reimagined.
• Detects unsupported active samplers, uniforms, outputs, and shader features.
• Reports clear compatibility errors instead of silently substituting unsafe values.

Rendering and stability

• Uses Forge's modern frame graph and Minecraft's active GPU device.
• Executes compatible deferred*, composite*, and final full-screen stages in deterministic order.
• Uses a conservative compatible world0/final path for modern complex shader packs.
• Supports recognized main-color and main-depth aliases.
• Updates common frame, time, world, weather, camera, fog, sky, and view uniforms.
• Uses transactional shader-pack replacement.
• A failed pack replacement no longer immediately destroys the working shader state.
• Retains the last-known-good prepared shader source.
• Recompiles the last-known-good shader after resource reload when a requested replacement fails.
• Safely restores vanilla rendering if the active shader render pass fails.
• Handles window and fullscreen resizing in the tested AMD Radeon environment.
• Cleans up replaced pipelines and uniform buffers safely.
• Supports clean world and game shutdown.

Shader-pack security

Shader packs are treated as untrusted local input. The loader includes protections against:

• Path traversal and absolute paths
• Symbolic links inside directory packs
• Malformed ZIP archives
• Duplicate ZIP entries
• Oversized individual files
• Oversized directories and archives
• Excessive compression ratios
• Excessive cumulative decompressed data
• Invalid UTF-8 shader source
• Include cycles
• Excessive include depth and count
• Excessively expanded shader source

Performance design

The renderer includes several efficiency improvements:

• Shader-pack disk access does not occur every frame.
• Shader preprocessing does not occur every frame.
• Shader compilation does not occur every frame.
• Stable render-target descriptions are cached by size.
• Uniform data uses mapped ring buffers.
• Multi-stage full-screen rendering ping-pongs between two color targets.
• Compatible N-stage pipelines now perform N mod 2 full-screen texture copies instead of N copies.
• One command encoder is reused for the complete ordered stage sequence.
• When shaders are disabled, no shader-pack program is compiled or executed.

No controlled average-FPS or 1%-low benchmark comparison has been completed. Therefore, this beta does not claim a measured FPS increase.

Tested shader packs

The following shader-pack versions were used during beta validation:

• BSL v10.1.1
• Complementary Reimagined r5.7.1

Their compatible world0/final passes successfully prepared, activated, and executed on both supported Minecraft targets.

This testing confirms compatible final-pass activation. It does not mean that every visual effect from these packs is implemented or that the output has complete visual parity with Iris or the original Oculus.

Validation

Beta builds were validated with:

• 16 automated compatibility and security tests on Minecraft 1.21.11
• 16 automated compatibility and security tests on Minecraft 26.2
• Full Gradle builds using --warning-mode all
• BSL v10.1.1 pack preparation and activation
• Complementary Reimagined r5.7.1 pack preparation and activation
• Window and fullscreen resizing
• Repeated shader enable and disable testing
• 30-second live rendering soaks
• Deliberately unsupported shader-pack replacement
• Last-known-good shader recovery
• Clean world and game shutdown

Hardware used for live testing:

• AMD Ryzen 5 5625U
• Integrated AMD Radeon graphics
• OpenGL 4.6
• 16 GB DDR4 RAM

The produced artifacts were also scanned with Microsoft Defender, which reported zero detections.

Important beta limitations

This is not yet a complete Iris/Oculus world renderer.

The following major systems are still missing:

• Terrain and chunk gbuffer shader routing
• Translucent terrain gbuffer routing
• Entity and block-entity shader routing
• Particle shader routing
• Hand, held-item, and overlay shader routing
• Pack-controlled sky rendering
• Pack-controlled cloud and weather rendering
• Pack-controlled water and world-geometry stages
• Real shadow-map world rendering
• The complete additional colortex target system
• The complete depthtex target system
• Previous-frame and history targets
• Normal and specular textures
• Pack-provided custom textures
• The complete OptiFine/Iris properties system
• Shader profiles and configuration expressions
• The complete matrix and uniform model
• Vulkan shader-pack rendering

Because of these limitations:

• Some shader packs will still fail when an active pass requires an unsupported resource.
• Some successfully activated packs may look closer to vanilla than they do under full Iris or Oculus.
• BSL and Complementary testing confirms compatible final-pass activation, not complete visual parity.
• This beta should not be advertised as supporting every OptiFine shader pack.

Installation

1. Install one of the supported Minecraft and Forge combinations.
2. Use Java 21 for Minecraft 1.21.11 or Java 25 for Minecraft 26.2.
3. Download the matching 0.3.0-beta.1 production JAR.
4. Place the production JAR inside the client's mods folder.
5. Do not place the -sources.jar inside mods.
6. Start Minecraft once.
7. Place shader-pack ZIPs or directories inside the instance's shaderpacks folder.
8. Open Mods → Oculus Community Port → Config.
9. Select a shader pack.
10. Enable shaders and save the configuration.

Compatibility notes

• OptiFine: Incompatible. Remove it before using this mod.
• OpenGL: Supported shader backend.
• Vulkan: Detected, but shader-pack rendering is disabled.
• Dedicated servers: Do not install the mod server-side.
• Other Forge mods: Best-effort compatibility while broader testing continues.
• Resource packs: Best-effort compatibility.
• Rubidium, Embeddium and Sodium: No nonexistent current Forge dependency is fabricated or bundled.

Reporting problems

Report issues to the community port, not to the original Oculus or Iris developers:

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

Please include:

• logs/latest.log
• Minecraft version
• Forge version
• Java version
• Oculus Community Port version
• GPU model and driver version
• Active graphics backend
• Shader-pack name and exact version
• Installed mod list
• Exact reproduction steps
• Screenshots when useful

Source code and license

Oculus Community Port is distributed under the GNU Lesser General Public License version 3 only (LGPL-3.0-only).

• Community port source:
  https://github.com/Khaliiid0/Oculus-Community-Port

• Original Oculus project:
  https://github.com/Asek3/Oculus

• Iris project:
  https://github.com/IrisShaders/Iris

Corresponding source must remain available for every published binary.

This is a substantially modified, unofficial community fork. It is not affiliated with or endorsed by the original projects, shader-pack developers, Mojang, Microsoft, or Forge.