Iris/Oculus & GeckoLib Compat — a mod to fix animations with shaders in Minecraft

Iris/Oculus & GeckoLib Compat — a mod to fix animations with shaders in Minecraft

Iris/Oculus & GeckoLib Compat (also known as GeckoAnimFix) is a small client-side mod for Minecraft that fixes one specific bug: when entity shadows are enabled in a shader pack, the animations of mobs and other entities built on the GeckoLib library stop playing. Custom creatures freeze in a single pose — and look like statues in the middle of the world.

Where the bug comes from

The GeckoLib library is a widely used tool for more complex 3D models and skeletal animation of mobs. Dozens of mods with their own creatures use it: for walk cycles, breathing, weapon swings, aggressive poses, and so on. Rendering an entity in Minecraft is actually performed several times per frame — separately for the main image and separately to build the shadow map. The animation should update on only one of these passes.

When a shader pack adds entity shadows (the Entity Shadows option), the mob model is drawn again, this time for the shader pass. In older versions of GeckoLib, the model's animation state breaks on this extra pass — the frame gets stuck. Without a shader, or with entity shadows turned off, the bug does not appear.

What exactly the mod does

GeckoAnimFix adds a small adjustment to GeckoLib's behavior — one that keeps a mob's animation cycle from being reset on the extra render pass triggered by shader shadows. Entities keep playing their animations normally, regardless of which particular shader is enabled in Iris or Oculus.

The mod works automatically — once the .jar file lands in the mods/ folder, it needs no additional configuration. No commands, new blocks, or in-game menus appear: the player only notices that previously broken mobs are moving normally again.

How to set it up

The installation procedure is standard for the corresponding loader — the .jar file is placed in the mods/ folder together with the GeckoLib library and the shader mod (Iris or Oculus). The mod creates no separate service files in the game.

One detail worth paying attention to: the mod version must exactly match the Minecraft version and the loader. A build for Forge will not run on Fabric and vice versa, even if the game version number is the same. On the Modrinth page, the file list marks separately for each game version which loader a specific .jar supports.

Conclusion

Iris/Oculus & GeckoLib Compat closes one narrow task: it brings the animations of custom mobs in Minecraft back to life when the user does not want to give up the shadows in their shader pack. It makes the most sense for playing on old modpacks 1.18.2–1.19.4 and early 1.20, where GeckoLib did not yet include its own fix. The limitation is clear: for fresh versions of GeckoLib the mod is already redundant and may even interfere with mods that have complex animation. The alternative is a simple update of the GeckoLib library itself to 4.x or newer; this makes a separate fix unnecessary but requires compatible versions of the rest of the mods in the build.