GeckoLib Documentation

GeckoLib is an animation and rendering engine designed for Minecraft Mods. It enables developers to implement complex 3D keyframe-based animations.

Key features include:

• Support for 30+ easing functions.
• Concurrent animation support (playing multiple animations at once).
• Sound and particle keyframe integration.
• Event keyframes for triggering logic during animations.

GeckoLib is compatible with the following Minecraft modding loaders:

• Forge
• Fabric
• NeoForge

GeckoLib maintains an extensive wiki for detailed technical documentation and a Discord server for community support and troubleshooting.

• Documentation: Detailed guides and API information are available at the GeckoLib Wiki.
• Support: If you have questions or need help getting started, join the GeckoLib Discord.

For detailed installation instructions specifically for modders, please refer to the official GeckoLib Quick Reference wiki page. The README points to the following resource for setup guidance:

https://wiki.geckolib.com/docs/geckolib5/quick-reference

By default, GeoItem animations are not perspective-aware. If you want animations to change based on the ItemDisplayContext (e.g., how the item looks in a third-person view vs. first-person), you must:

1. Override isPerspectiveAware() to return true.
2. GeckoLib will then automatically use ContextBasedAnimatableInstanceCache, which manages separate AnimatableManager instances for each ItemDisplayContext.

This allows you to use DataTickets.ITEM_RENDER_PERSPECTIVE to determine the current rendering context.

To make a Minecraft Item (including armor) animatable using GeckoLib, implement the GeoItem interface. This interface extends SingletonGeoAnimatable, meaning animations are managed via a singleton pattern tied to the item type, but can be differentiated by unique IDs assigned to specific ItemStack instances.

Key Concepts

• ID Assignment: GeckoLib uses unique IDs stored in the ItemStack components to differentiate between different instances of the same item (e.g., two different swords having different animation states). Use GeoItem.getOrAssignId(stack, level) to ensure an ID is present.
• Perspective Awareness: If your item needs to play different animations depending on how it is being viewed (e.g., in a GUI vs. held in hand), override isPerspectiveAware() to return true.

To ensure your GeoItem animations are synchronized across the network, call GeoItem.registerSyncedAnimatable(this) inside the constructor of your item class.

public class MyAnimatableItem extends Item implements GeoItem {
    public MyAnimatableItem(Properties properties) {
        super(properties);
        GeoItem.registerSyncedAnimatable(this);
    }

    // Implement required GeoItem/SingletonGeoAnimatable methods...
}

GeckoLib tracks individual item instances using unique IDs stored in the ItemStack's data components. Use these static methods to handle ID retrieval and assignment:

• getId(ItemStack stack): Retrieves the unique ID from the stack's components. Returns Long.MAX_VALUE if no ID is assigned.
• getOrAssignId(ItemStack stack, ServerLevel level): Retrieves the ID, or if none exists, reserves a new ID from the AnimatableIdCache and assigns it to the stack's components.