Geckolib Items (Geckolib5)

Pre-word

Because Minecraft only ever keeps one instance of any given Item, GeckoLib animations for items need to be handled slightly differently. Where objects like Entities and BlockEntities can have their animations handled directly, Items need to make sure it's matching up with its respective synced equivalent.

Ensure you're thoroughly reading the examples and descriptions on this page to determine the required differences.

Table of Contents

• Steps
• The Item Class
  • Triggerable Animations
  • Perspective-Aware Animation Handling
• The Item Json
• The Item Display Json
  • Example Item Display Json
• The Renderer
  • Creating the Class
    • Example Renderer Class
  • Registering the Renderer
• Example Item Class
• Common Issues
  • My item is just a black & purple square
  • I can't replay an animation after it has played

Steps

Creating a GeckoLib item requires the following steps:

1. Creating your Blockbench Model
2. Creating your Geo Model
3. Creating your item json
4. Creating your item display json
5. Creating your item class
6. Creating and registering your renderer

Steps #1 and #2 will not be covered on this page, instead visit their respective links for info. This page will focus on steps #3 through #6

The Item Class

Quick Summary

1. Implement GeoItem
2. Register as a synced animatable
3. Override getAnimatableInstanceCache and registerControllers
4. Instantiate a new AnimatableInstanceCache via GeckoLibUtil.createInstanceCache(this) at the top of your item class and return it in getAnimatableInstanceCache
5. Add any controllers you want for animations in registerControllers
6. Reference your renderer

There are a few things needed to set up a GeckoLib item class.

The first is to implement GeoItem on your item class, and override the two methods your IDE will tell you to override. This interface is the base for animatable items in GeckoLib, and lets the various other features of the mod pick up your item as an animatable one.

Next, we'll create an instance of an AnimatableInstanceCache for our item. This stores our animatable instance so that it can be retrieved by the renderer and other outside areas.

To do this, we'll instantiate a new cache via GeckoLibUtil.createInstanceCache(this) at the top of your item class, caching it in a final variable.

Next, we'll override getAnimatableInstanceCache in our item class if it hasn't been done already, and return the factory instance we just created.

And finally, override registerControllers in your item class. This method is called when your item is first being used for animations, and is where you define your actual animation handling.

This finalises the base setup for an animatable Item. However because of the nature of items, with these steps alone you'll only be able to do animations based on the client-side state of the itemstack, which often isn't very useful.

To rectify this, we need to do a couple extra things.

Triggerable animations

GeckoLib4 adds the ability to trigger animations remotely, from the server side. This greatly simplifies the process of handling animations from the server side.

See: Triggerable Animations for more information

Perspective-Aware Animation Handling

You may want your item's animations to only show in first-person, or only in third-person, or some other setup. To do this, we need to override GeoItem#isPerspectiveAware in our item class, returning true.

Then, in your controller predicate, you can get the current render perspective via state.getData(DataTickets.ITEM_RENDER_PERSPECTIVE).

From there, you can handle your predicate based on the render perspective. This will cause your predicate to be called for each render perspective currently being rendered each render pass, allowing you to treat your predicate as a separate, non-colliding context for each render perspective.

The Item Json

New to 1.21.4+ Minecraft, all items require an item json. This is not the same thing as the item model json.

The item json goes in assets/<modid>/items, and must be named as the id of your item.
E.G. my_item.json

The contents of this file should be as below:

{
  "model": {
    "type": "minecraft:special",
    "base": "<modid>:item/<item_id>",
    "model": {
      "type": "geckolib:geckolib"
    }
  }
}

Important

"base" should be targeted at your item's model json (the one in /models/item/)

The item display json

As with all items in Minecraft (both GeckoLib and non), an item display json is required.

This is the .json file that sits in your assets/<modid>/models/item folder that determines the item's rotation, scaling, and positioning when rendering. In GeckoLib's case, it is the entrypoint that tells the game to get GeckoLib to render your item instead of treating it like a vanilla item.

This is done by including "parent": "builtin/entity" in the json file.

Example item display json

{
  "parent": "builtin/entity"
}

The Renderer

To then get the item rendering, we'll need to make a renderer then register it. Due to the nature of items, this requires a little more work than is usual to register.

Creating the class

To make the renderer itself, just make a class that extends GeoItemRenderer, passing in the GeoModel instance to the constructor

Example Renderer Class

    public class ExampleItemRenderer extends GeoItemRenderer<ExampleItem> {
    	public ExampleItemRenderer() {
    		super(new ExampleItemModel());
    	}
    }

Registering the Renderer

Item renderers get registered a little differently to other renderers, and GeckoLib utilises the same system, so we need to be aware of the correct method of registration.

GeckoLib implements a dynamic render retrieving system for animatable items, to allow for flexible render handling. We will use this to implement our GeoItem's renderer

To do this, we need to override createGeoRenderer in the item class, and provide the consumer a new instance of GeoRenderProvider. Then, we override getGeoItemRenderer in that, and cache-return our renderer instance

@Override
public void createGeoRenderer(Consumer<GeoRenderProvider> consumer) {
	consumer.accept(new GeoRenderProvider() {
		private ExampleItemRenderer renderer;

		@Override
		public BlockEntityWithoutLevelRenderer getGeoItemRenderer() {
			if (this.renderer == null)
				this.renderer = new ExampleItemRenderer();

			return this.renderer;
		}
	});
}

You can alternatively use Forge/NeoForge/Fabric's built-in item renderer registration methods - though no guarantee is made for 100% compatibility with this option in the future if further functionality is required.

Example Item Class

public final class ExampleItem extends Item implements GeoItem {
	private static final RawAnimation ACTIVATE_ANIM = RawAnimation.begin().thenPlay("use.activate");
	private final AnimatableInstanceCache cache = GeckoLibUtil.createInstanceCache(this);

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

		// Register our item as server-side handled.
		// This enables both animation data syncing and server-side animation triggering
		GeoItem.registerSyncedAnimatable(this);
	}

	// Utilise our own render hook to define our custom renderer
	@Override
	public void createGeoRenderer(Consumer<GeoRenderProvider> consumer) {
		consumer.accept(new GeoRenderProvider() {
			private ExampleItemRenderer renderer;

			@Override
			public BlockEntityWithoutLevelRenderer getGeoItemRenderer() {
				if (this.renderer == null)
					this.renderer = new ExampleItemRenderer();

				return this.renderer;
			}
		});
	}

	@Override
	public void registerControllers(AnimatableManager.ControllerRegistrar controllers) {
		controllers.add(new AnimationController<>("Activation", 0, animTest -> PlayState.STOP)
				.triggerableAnim("activate", ACTIVATE_ANIM));
				// We've marked the "activate" animation as being triggerable from the server
	}

	// Let's handle our use method so that we activate the animation when right-clicking while holding the box
	@Override
	public InteractionResultHolder<ItemStack> use(Level level, Player player, InteractionHand hand) {
		if (level instanceof ServerLevel serverLevel)
			triggerAnim(player, GeoItem.getOrAssignId(player.getItemInHand(hand), serverLevel), "Activation", "activate");

		return super.use(level, player, hand);
	}

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

Common Issues

My item is just a black & purple square

You haven't put in an item json (the one in the assets/<modid>/items folder). All items need an item json.

I can't replay an animation after it has played

You have either forgotten to reset the animation after should have completed (see: DefaultAnimations#genericAttackController), or you have accidentally set your animation's loop type as hold_on_last_frame in your animation JSON.