Skip to main content
Version: GeckoLib5

The Item Class

To have a GeckoLib item, you first need to have an item class.

note

This tutorial is specifically for GeckoLib implementation. For information on general-modding item features, seek a tutorial or community support.

Creating the class​

💻Additive Code Section
All code snippets in this section add onto the previous code snippets, using a step-by-step approach to build the complete code.
Green highlights show added or modified lines of code for each step.

First, we create the base item class and implement the base constructor:

public class ExampleItem extends Item {
    public ExampleItem(Properties properties) {
        super(properties);
    }
}

Then, we will implement the GeoItem interface and override the getAnimatableInstanceCache and registerControllers methods:

public class ExampleItem extends Item implements GeoItem {
    public ExampleItem(Properties properties) {
        super(properties);
    }

    @Override
    public void registerControllers(final AnimatableManager.ControllerRegistrar controllers) {
        // We can fill this in later
    }

    @Override
    public AnimatableInstanceCache getAnimatableInstanceCache() {
        return null;
    }
}

Next, let's instantiate an AnimatableInstanceCache in a final field at the top of our class, and return it in getAnimatableInstanceCache:

public class ExampleItem extends Item implements GeoItem {
    private final AnimatableInstanceCache geoCache = GeckoLibUtil.createInstanceCache(this);

    public ExampleItem(Properties properties) {
        super(properties);
    }

    @Override
    public void registerControllers(final AnimatableManager.ControllerRegistrar controllers) {
        // We can fill this in later
    }

    @Override
    public AnimatableInstanceCache getAnimatableInstanceCache() {
        return this.geoCache;
    }
}

And you're done!

For information on adding animation controllers, see the Animation Controllers page.

Extra Bits​

I want to use triggered animations on this item​

Click to Expand

To prepare your item class for using triggered animations, you'll need to register the item as a synced animatable.
This is done in the constructor, like so:

public class ExampleItem extends Item implements GeoItem {
    private final AnimatableInstanceCache geoCache = GeckoLibUtil.createInstanceCache(this);

    public ExampleItem(Properties properties) {
        super(properties);

        GeoItem.registerSyncedAnimatable(this);
    }

    // ...
}

See the Triggered Animations section for more information on triggered animations and how to use them

I want to have my animations only play in my hand, but not in GUI (or vice versa)​

Click to Expand

If you want to handle animations differently depending on the render perspective, you'll need to mark the item as perspective-aware.
This is done by adding a method to your item's class, like so:

public class ExampleItem extends Item implements GeoItem {
    private final AnimatableInstanceCache geoCache = GeckoLibUtil.createInstanceCache(this);

    public ExampleItem(Properties properties) {
        super(properties);
    }

    // ...

    @Override
    public boolean isPerspectiveAware() {
        return true;
    }
}

See the Perspective-Aware Animations section for more information on this feature and how to use it.

Registering the item​

Once you have created your item class, you then need to register it. This differs depending on the modloader you are using.

Select your loader below for a link to that loader's documentation for registering entities.

https://docs.neoforged.net/docs/items/#deferredregisteritems