geckolib

Imported from hairyf/skills (skills/geckolib/SKILL.md). Install upstream with npx skills add hairyf/skills --skill geckolib. Copyright stays with the author.

name: geckolib description: GeckoLib Minecraft mod animation — GeckoLib 5 (1.21+) render-state pipeline plus GeckoLib 4.4.9 (1.20.1) API for Fabric/Forge/NeoForge: setup, entities, blocks, items, armor, replaced entities, animation controllers, Molang, render layers, textures, and data syncing. Use when working with GeckoLib animatables, .geo.json/.animation.json assets, or adding keyframe animations to a Minecraft mod. metadata: author: Hairy version: "2026.8.8" source: Generated from https://github.com/bernie-g/geckolib, scripts at https://github.com/hairyf/skills

GeckoLib

Based on GeckoLib v5.5.3 (2026-06-27) and GeckoLib v4.4.9 (2024-08-30, MC 1.20.1), generated 2026-08-07, v4 content added 2026-08-08. Docs: https://wiki.geckolib.com (v5) + the GeckoLib 4 wiki (v4).

GeckoLib is an animation and rendering engine for Minecraft mods, available for Fabric, Forge, and NeoForge. It plays Blockbench/GeckoLib keyframe animations on entities, blocks, items, and armor, with 30+ easings, Molang math expressions, sound/particle/event keyframes, glowmasks, animated textures, and replaced-entity support. Since v5 it renders from immutable RenderState snapshots (Minecraft 1.21+ render pipeline); v4 (up to 4.4.9 for MC 1.20.1) renders directly from the animatable under the software.bernie.geckolib package with geo/ + animations/ asset folders.

Preferences

• Prefer automatic/defaulted GeoModels over hand-written GeoModel classes; only use basic models for dynamic paths
• Prefer DefaultAnimations built-in controllers and RawAnimation instances over hand-rolled controllers
• Prefer controller-based animations over stateless animations (stateless is less efficient)
• Never mutate GeoBones directly in v5 — use BoneSnapshots/BoneUpdaters via RenderPassInfo
• Cache Identifiers in GeoModels and memoize renderer suppliers in items/armor
• Pass render-time data through DataTickets in GeoRenderState, never hold the live animatable at render time
• Keep client-only classes (renderers, layers) in client sources when using split sources

Core

Creating Animatables

Features

Migration & Examples

GeckoLib 4 (MC 1.20.1)

For projects pinned to GeckoLib 4.4.9 / Minecraft 1.20.1, use these references — they document the software.bernie.geckolib API (not the v5 com.geckolib API) and the v4 asset layout (geo/, animations/). The official GeckoLib 5 wiki is misleading for 1.20.1 projects.

Note: stateless animations and the split-source GeoRenderProvider system did not exist in 4.4.9 — they arrived in 4.5/1.20.6+. Renderers must live in client source sets instead.

Quick Reference

Minimal animated entity

public class ExampleEntity extends PathfinderMob implements GeoEntity {
    private final AnimatableInstanceCache geoCache = GeckoLibUtil.createInstanceCache(this);

    @Override
    public void registerControllers(final AnimatableManager.ControllerRegistrar controllers) {
        controllers.add(DefaultAnimations.genericWalkIdleController());
    }

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

// Renderer registration
context -> new GeoEntityRenderer<>(context, EntityRegistry.EXAMPLE_ENTITY.get());

Assets for examplemod:example_entity

assets/examplemod/geckolib/models/entity/example_entity.geo.json
assets/examplemod/geckolib/animations/entity/example_entity.animation.json
assets/examplemod/textures/entity/example_entity.png

Dependency (Fabric)

repositories {
    exclusiveContent {
        forRepository { maven { name = 'GeckoLib'; url = 'https://dl.cloudsmith.io/public/geckolib3/geckolib/maven/' } }
        filter { includeGroupAndSubgroups('com.geckolib') }
    }
}
dependencies {
    modImplementation "com.geckolib:geckolib-fabric-${minecraftVersion}:${geckolibVersion}"
}

Forge uses implementation minecraft.dependency("com.geckolib:geckolib-forge-..."); NeoForge uses implementation "com.geckolib:geckolib-neoforge-..." (optionally plus interfaceInjectionData).

Key naming conventions

• Controller one animation at a time; multiple controllers for concurrent animation groups
• DefaultAnimations expects animation names like misc.idle, move.walk, attack.swing
• Glowmask textures: <name>_glowmask.png; animated textures: <name>.png.mcmeta