Geckolib Entities (Geckolib4)

Steps

Creating a GeckoLib entity requires the following steps:

1. Creating your Blockbench Model
2. Creating your Geo Model
3. Creating your entity class
4. 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 and #4

Full Video Guides

Forge

Fabric

The Entity Class

Quick Summary

1. implement GeoEntity
2. Override getAnimatableInstanceCache and registerControllers
3. Instantiate a new AnimatableInstanceCache via GeckoLibUtil.createInstanceCache(this) at the top of your entity class and return it in getAnimatableInstanceCache
4. Add any controllers you want for animations in registerControllers

There are only a few things needed to set up a GeckoLib entity's class.

The first is to implement GeoEntity on your entity class, and override the two methods your IDE will tell you to override. This interface is the base of all animatable entities in GeckoLib, and lets the various other features of the mod pick up your entity as an animatable entity.

Next, we'll create an instance of an AnimatableInstanceCache for our entity. 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 factory via GeckoLibUtil.createInstanceCache(this) at the top of your entity class, caching it in a final variable.

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

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

Your class is all set up! The only thing left to do is define your animations in registerControllers

Example Entity Class

public class ExampleEntity extends PathfinderMob implements GeoEntity {
        protected static final RawAnimation FLY_ANIM = RawAnimation.begin().thenLoop("move.fly");

        private final AnimatableInstanceCache geoCache = GeckoLibUtil.createInstanceCache(this);

        public ExampleEntity(EntityType<? extends ExampleEntity> type, Level level) {
            super(type, level);
        }
    
        @Override
        public void registerControllers(final AnimatableManager.ControllerRegistrar controllers) {
            controllers.add(new AnimationController<>(this, "Flying", 5, this::flyAnimController));
        }
        
        protected <E extends ExampleEntity> PlayState flyAnimController(final AnimationState<E> event) {
            if (event.isMoving()
                return event.setAndContinue(FLY_ANIM);

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

The Renderer

To have your entity show up in the world, you'll need to register your entity's renderer - like you would for any other entity.

The difference with GeckoLib is that you must register an instance of GeoEntityRenderer, instead of any vanilla renderers.

One bonus to this is that you don't need to register any model layers or mesh definitions like you do with non-GeckoLib models, and instead can skip straight to registering the renderer itself. The renderer will take the render context and your Geo Model instance.

Example Entity Renderer

    public class ExampleEntityRenderer extends GeoEntityRenderer<ExampleEntity> {
        public ExampleEntityRenderer(EntityRendererProvider.Context context) {
            super(context, new ExampleEntityModel());
        }
    }

Common Issues

I get a crash when spawning my entity

If you're getting a crash that says something like this:

java.lang.NullPointerException: Cannot invoke "net.minecraft.client.renderer.entity.EntityRenderer.shouldRender(net.minecraft.world.entity.Entity, net.minecraft.client.renderer.culling.Frustum, double, double, double)" because "entityrenderer" is null

You forgot to register your renderer

I'm using the DefaultAnimations#genericAttackAnimation controller, but it's not swinging!

You need to ensure you're either calling swing, or using a goal/behaviour that calls swing (such as MeleeAttackGoal) to tell your entity to swing its arm Additionally, if you're not extending Monster, you will need to override aiStep in your entity and call updateSwingTime() to ensure it's ticking its swing time

I'm using the DefaultAnimations#genericAttackAnimation controller, but it's only doing part of the animation before stopping!

If your animation is longer than the default swing time (6 ticks, including transition time), then your attack animation won't play fully before the entity stops swinging. To fix this, you need to override getCurrentSwingDuration() in your entity and return a more appropriate swing duration in ticks