Geckolib is an entity animation loader for Minecraft Java Edition, which lets you export Minecraft Bedrock animations and play them in your mod. Geckolib also supports sound keyframes, particle keyframes, event keyframes, 30+ easing types, and much more. The library is currently available on Forge 1.12, 1.15, 1.16, Fabric 1.15, and Fabric 1.16. We are currently supporting all of those versions (which is a pain, so please star the github to show support :)
Table of Contents
- Getting Started
To install the library, read here.
Installing the Plugin
In order to use blockbench (bedrock) animations in forge, you'll need to install the Geckolib blockbench plugin. You can find it by going to File -> Plugins -> Available -> Search for "GeckoLib Animation Utils". Keep in mind the plugin is only available for BlockBench 3.6+, so make sure to fix it.
If you prefer videos to written documentation, TurtyWurty made a great Geckolib 2.0 Tutorial to walk you through how to rig, animate, and code:
Creating a Model
In order to create a model compatible with Geckolib, you should create a new Animated Entity Model in blockbench, by going to File -> New Animated Java Entity.
Converting an Existing Model
If you have already created a bedrock or normal java entity, you can convert it to an Animated Entity Model compatible with Geckolib by going to File -> Convert Project -> Select "Animated Java Entity". Keep in mind that if you're converting from a bedrock model to a java model, there are occasionally hiccups in the model conversion process since the models are stored in different file formats. You'll have to either fix these issues manually or consult the blockbench discord.
The process of preparing a model for animation is known as "rigging". You can think of it as the process of creating a skeleton for your model. Spending a little time rigging makes the animation process much easier.
In entity models, you cannot rotate cubes, only groups. So, click the "add group" button and make sure all your cubes are inside group "folders":
Parenting and Pivots
The rig for a model is like a skeleton. Groups are the bones, pivots are the joints, and cubes are the flesh.
Unless your model has multiple object parts that can move independently (like if your entity was a school of fish), you probably want a single root group with many nested child groups. When each group moves, it also moves it's children.
Pivot points can be set using the pivot tool and affect what point a group pivots from when it rotates.
This is easier to explain visually so you can watch this video showing how to set up parenting and pivots for a simple skeleton:
These images are from the article Minecraft Modeling & Texturing Tips by MasterianoX. You can read it for more detail and lots more helpful modeling tips.
You can animate your model in the Animation tab on the right. Geckolib currently supports position, scale, and rotation keyframes. Support for sound, particle, and custom event keyframes is in development. It's also important that you set the loop setting to the appropriate value for each animation in the editor. This will determine if the animation will loop in game. You can set this value by right-clicking the animation in the Animation Pane and selecting loop.
Animating in GeckoLib is almost exactly the same as how you would animate for a bedrock entity, so most bedrock animation tutorials also apply to GeckoLib.
Ideally, animations should be split up as much as possible. Geckolib allows you to run multiple animations simultaneously, so in order to make the smoothest transitions, you should split up each logical animation. For example, if you're making a flying creature with several flying types, several running types, and several head movements, you should split each one into it's own animation and combine them in code.
In this example, you should make these animations in blockbench (examples):
- Default Head Movement Animation
- Spitting Head Animation
- Wing Flapping Animation (only involving wings)
- Faster Wing Flapping Animation (only involving wings)
- Running Animation (only involving legs)
- Walking Animation (only involving legs)
This is different to the normal way most people animate. Usually, you would animate the entire body at once and duplicate it + adjust keyframes. This can certainly work, but it will provide for a less seamless transition period in between animations. Additionally, the modular system Geckolib encourages allows for more possible animation combinations and a greater control for the developer.
(2.0) Working with easing curves
GeckoLib 2.0 added a powerful new feature called easing curves. These allow you to create smooth, natural-looking animations with less effort than previously.
In Bedrock and GeckoLib 1.0, the only type of "tweening" or interpolation that could be used between keyframes was linear interpolation, or "lerp". This means that as time progresses forwards, the value would change from the starting keyframe to the next keyframe at a constant speed. Real objects don't usually move in this way, they tend to need to accelerate a bit when starting and decelerate when stopping.
An easing curve is a mathematical function that can allow for animations to be interpolated in a more gradual fashion. The value of the "tween" at any given point in time is taken from the given easing curve rather than a straight line. This allows you to easily achieve effects like a smooth start and stop, an object overshooting its destination and sliding back into place (back curve), or an object bouncing (bounce curve).
Source: 1ucasvb. Note some curve names differ from ours but the principles are the same.
In addition, there are three directions a curve can be applied. "In" usually means the curve is applied focusing on the beginning of the interpolation, focusing on a smooth-looking start. "Out" usually means the curve is applied focusing on the end of the interpolation (the reverse of "In"), focusing on a smooth-looking end. "InOut" means the curve is symmetrically applied to both the start and end. In the animation above, when the animation plays from left to right it corresponds to "In", and when it plays backwards/right to left it corresponds to "Out". See below for a comparison:
We implemented all of the easing curves from easings.net and recommend you check out that website for an interactive, animated explanation of all the different curves and directions.
We also added a default "linear" curve to emulate bedrock behavior, and a "step" curve which snaps the value to a specified number of steps instead of moving smoothly. This can be used to animate things like clock hands or simulate a reduced framerate.
In addition, we created arguments for the "back", "elastic", and "bounce" curves to give you additional control over their shapes.
In GeckoLib, we use the right-hand or "to" keyframe to specify the easing for each tween. Therefore, there is no easing curve on the first keyframe in any timeline. You need to make a second keyframe in order to assign an easing curve.
Eliot also made a code sandbox to explore the different curves and see the effect of the adjustment parameters for ones that have them. Feel free to play around with it if you find it helpful.
Here's a short demo of how to use the easing curves editor:
Exporting Your Model
After you finish making your model in Blockbench, you need to export both the .java entity model and the .json animation file. You can export the model by going to File -> Export -> Export Animated Java Entity. You can export the animation json file by going to Animation -> Export Animations
(2.0) Animated Entity Settings Window
GeckoLib 2.0 added an
Animated Entity Settings Window which can be accessed from the
File menu for Animated Java Entity projects:
This can be used to customize the Java code template so that you can export many times if needed without having to manually edit the code afterwards. These settings are completely optional, you can just edit the code by hand still if you prefer.
|Modding SDK||Choose which Modding SDK and version you are using so code will be generated in the correct format.|
|Entity Type||The fully qualified type name of your Entity which will be supplied as the type parameter to the model's superclass,
|Java Package||The Java package you want your model to be in, ex.
|Animation File Namespace||The namespace where your animation file resource is in. This should probably be your mod ID, ex.
|Animation File Path||The path to the animation file inside the namespace, ex.
To add your model and animation in game, read how to do so here.