# GeckoLib: keyframe animation for Minecraft mods

> GeckoLib is an MIT licensed Java animation and rendering engine for Minecraft mods, supporting 3D keyframe animations, more than thirty easings, concurrent animations, sound, particle and event keyframes across Forge, Fabric and NeoForge. It suits modders whose entities need to move believably, and it is the wrong tool if you want to animate the player or the world itself.

**bernie-g/geckolib** — GeckoLib is an animation engine for Minecraft mods, with support for complex 3D keyframe-based animations, numerous easings, concurrent animation support, sound and particle keyframes, event keyframes, math-based animations, and more. Available for all major modloaders.

- Repository: https://github.com/bernie-g/geckolib
- Website: https://geckolib.com
- Stars: 843 · Forks: 166
- Language: Java
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/bernie-g-geckolib

## An animation engine for the models a mod registers

GeckoLib is described as an animation and rendering engine for Minecraft mods, and the repository description spells out the feature set in a single sentence: complex 3D keyframe-based animations, 30+ easings, concurrent animation support, sound and particle keyframes, event keyframes, math-based animations, and more, available for all major modloaders.

The scope is the part to understand first. This is an engine for animating the entities and blocks a mod adds to the game. It is not a general animation system for the player, the camera or the world, and it is not a replacement for the resource pack pipeline that handles ordinary block and item models.

That is a much larger problem than it looks. In vanilla Minecraft, a model is a static set of vertices, and an entity that walks is either a few hard coded rotations or nothing at all. A mod that wants a creature whose limbs move, whose head turns, and which plays a sound at the moment of impact has to build all of that itself. GeckoLib provides the timeline, the curve evaluation and the keyframe types so the mod only has to supply the animation data.

The audience is therefore Minecraft modders, and specifically the ones who have hit the ceiling of what hard coded rotations can do. The project is MIT licensed, its homepage is geckolib.com, the last push to the repository was on 2026-09-27, and there are no GitHub releases, so the version you depend on is a commit rather than a tag.

The project also points at a Discord for questions and help getting started, and a Ko-fi page for donations, which tells you it is a community project with a real support channel rather than a corporate library.

## One common module, three loader specific modules

The repository layout is where the multi loader support is visible.

There is a common directory, and then three sibling directories named fabric, forge and neoforge, alongside a buildSrc directory, a root build.gradle.kts and a settings.gradle.kts, a gradle.properties, a changelog.md and the Gradle wrapper including gradlew and gradlew.bat.

That structure is the standard way of doing this in the Minecraft modding world, and it is worth understanding what it buys and what it costs.

It buys you the freedom to support several loaders from one codebase. The shared logic, the animation engine and the keyframe handling live in common, and each loader module is a thin layer that wires the engine into that loader's entity, renderer and networking APIs. A mod that supports Forge and Fabric does not maintain two copies of its animation code.

It costs you a build that is more complicated than a single Gradle project, with a version catalog in gradle.properties, a settings file that includes the extra modules, and a custom build logic directory. For a mod author who already has a Gradle setup this is unremarkable, and for someone starting from scratch it is a wall of configuration before the first animation plays.

The settings.gradle.kts and buildSrc arrangement is also where loader-specific version pins live, so it is the first file to look at when you want to know which Minecraft versions and loader versions a given commit actually supports. The repository does not publish that mapping as a release matrix, so the build files are the source of truth.

## Sound, particle and event keyframes put timing in the timeline

The keyframe types are what separate GeckoLib from a plain rotation helper, and three of them deserve attention.

A sound keyframe means a sound plays at a point in the animation. A particle keyframe means a particle effect is spawned at a point in the animation. An event keyframe means something happens in code at a point in the animation.

The reason this matters is synchronisation. Consider an attack animation. The arm has to reach forward, the impact sound has to land on the frame where the hitbox connects, and the particle burst has to appear at the same moment. If the sound is triggered by a separate timer in entity code, it drifts relative to the animation, and on a laggy server the timing gets worse. With keyframes, the sound and the particles are part of the same timeline as the movement, so they land together by construction.

The event keyframe generalises the idea. It is the escape hatch for anything the engine does not have a dedicated type for, such as spawning a projectile or changing a block state at a specific frame, without pushing that logic into a parallel tick-based system.

The description also lists math-based animations, which is the other feature that shows up in most requests for a better animation system. Where a keyframe would place a bone at a fixed angle, a math expression computes it, so a limb angle can depend on a sine of the animation time or on a value that changes as the entity moves. That is how you get secondary motion, the small follow-through movement of a tail or a cloth that a purely keyframed rig cannot express.

The other two entries, complex 3D keyframe-based animations and 30+ easings, are about control rather than events. Easings are the curve shapes that decide how a value moves between two keyframes, linear being the naive one. With thirty or more available, a designer can pick the specific motion they want, whether that is a bounce, an elastic overshoot or a slow settle, instead of approximating it with several linear segments.

## Concurrent animation support means several timelines at once

Concurrent animation support is listed as a feature, and it is the one that most directly changes how you structure an entity.

The naive way to animate a multi part model is to have one timeline and one controller that decides, every frame, which pose the whole model should be in. The problem is that different parts of the model often need different timelines running at once. A creature might be walking, with the head independently turning towards a target, while the tail follows the body with a delay, and the jaw opens for an attack that happens mid stride.

If the engine only supports one animation at a time, those cases are forced into a single crowded timeline, and the result is a model that looks correct only in the state the author happened to build it for.

With concurrent animations, each part can be driven by its own controller on its own timeline, and the engine combines them. The head controller does not have to know about the walk cycle, and the tail controller does not have to know about the jaw.

The practical effect is that the authoring becomes local. You decide how the head behaves, and separately how the legs behave, and the combination falls out. For a modder this is the difference between an entity that has a small set of baked poses and one that behaves like a character, and it is the reason the feature is called out separately rather than folded into the keyframe list.

## Blockbench sits at the authoring end of the pipeline

The repository topics are a useful map of the surrounding ecosystem. They list animation, animation-engine, animation-library, animations, blockbench, fabric, fabricmc, fabricmc-mod, forge, forge-mod, java-edition, minecraft and minecraft-mod.

Blockbench appearing there is the signal that this is a tool that plugs into an existing authoring workflow rather than one that replaces it. Blockbench is the model and animation editor that Minecraft modders already use, and the pairing of the two is what makes GeckoLib usable in practice: you author the model and the animation in the editor you already have, and the engine plays back what the editor produced.

That is worth stating because the alternative would be worse. A bespoke in-engine animation editor, with its own timeline widget and its own mesh format, would be a second project of considerable size, and the output would not be interoperable with anything else in the ecosystem. The dependency on an external editor keeps GeckoLib focused on playback and blending.

It also means the pipeline has a hard dependency on the editor's export format, so a change in how the editor writes animations is a change for every mod that uses them. The changelog at the repository root, and the wiki, are where to look for what the current commit expects.

The practical lesson for a new user is simple: install the library according to the wiki, author your animation in the editor you already use, and register the result with the entity. The engine is the playback half of that pipeline, and it does that half well.

## The wiki is the documentation, and GeckoLib 5 is the current line

The README does not try to document the library. It links to a wiki and says the authors spent many hours writing it, so please read it, and it links to a quick reference page for modders on the version 5 documentation path.

That path is the useful detail. The URL for the quick reference sits under a geckolib5 section, which tells you the current major line is GeckoLib 5, and the wiki is versioned in the same way, so you can find the documentation that matches the version you are compiling against rather than the newest prose.

The wiki covers the engine and the setup, and the README fills in the edges around it. There is a Discord for questions and for help getting up and running. There is a Ko-fi page and a Discord server link for supporting the project, and the sponsorship section mentions BisectHosting as a sponsor, along with acknowledgements for YourKit and Cloudsmith, which hosts the package repository.

That Cloudsmith detail has a practical consequence for a modder. GeckoLib is consumed as a dependency from a hosted Maven repository rather than being vendored into your project, so your build needs the repository configured, and a build environment that cannot reach it will fail in a confusing way. If you build in an air gapped CI environment, that is something to confirm early.

The contributing guidance is short and conventional. Pull requests are welcome, and for significant changes the project asks you to open an issue first to discuss what you would like to change. The repository carries a changelog.md alongside the build files, and the MIT licence is in the LICENSE file.

## Conclusion

GeckoLib suits a modder who has a model that moves and wants it to move properly, with keyframes, easings, sound and particle timing handled by a shared engine rather than by hand written entity code, and the fact that it runs on Forge, Fabric and NeoForge from one common module makes it usable from a codebase that supports more than one loader. It does not suit a project animating player animations or world state, since the engine is scoped to the models a mod registers. Before you adopt it, read the wiki quick reference for the GeckoLib 5 line, check that your Minecraft and loader versions are covered by the loader modules in the repository, and note that there are no GitHub releases, so you are tracking the main branch, whose last push was on 2026-09-27.

## FAQ

### What is GeckoLib used for in Minecraft mods?

GeckoLib is an animation and rendering engine for Minecraft mods that provides complex 3D keyframe-based animations, more than thirty easings, concurrent animation support, and sound, particle and event keyframes. It is meant for animating the models a mod adds to the game.

### Which Minecraft modloaders does GeckoLib support?

Forge, Fabric and NeoForge, according to the project description. The repository layout reflects that with a common directory for the shared engine and separate fabric, forge and neoforge modules.

### What are event keyframes in GeckoLib?

Alongside sound and particle keyframes, GeckoLib supports event keyframes, which are points in the animation timeline at which something happens in code. They let timing live in the same timeline as the model movement rather than in a separate tick based system.

### How do I install GeckoLib in a mod project?

The README does not contain the install steps, it points to installation instructions for modders in the wiki, at the GeckoLib 5 quick reference page. The repository also hosts its packages through Cloudsmith, so the repository has to be configured in your build.

### Does GeckoLib publish releases?

The repository has no GitHub releases, so you track the main branch. The last push to the repository was on 2026-09-27, and the changelog at the repository root is the place to look for what changed.

## Sources

- [bernie-g/geckolib on GitHub](https://github.com/bernie-g/geckolib)
- [Issues](https://github.com/bernie-g/geckolib/issues)
- [License: MIT](https://github.com/bernie-g/geckolib/blob/main/LICENSE)
- [Project website](https://geckolib.com)
- [README](https://github.com/bernie-g/geckolib/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bernie-g-geckolib