Craft-Animation

# **Craft Animation**
Craft Animation is a reusable animation library for Forge mod development.

This is not a content mod that directly adds weapons, mobs, or gameplay systems on its own. Instead, it provides a shared animation foundation that other mods can use to load, play, sample, and apply animations in a consistent way. The goal is to support players, mobs, generic entities, blocks, block entities, items, and display-based render objects through one common runtime structure.

**Supported targets**
- Players
- Mobs
- Generic entities
- Blocks
- Block entities
- Items
- Display-based render objects

**Included systems**
- Shared animation target types
- Keyframe-based clip structures
- Easing support
- Controllers for play, stop, loop, and playback speed
- Runtime tracking for active animation subjects
- JSON-based animation loading
- Example animation resources

**Supported formats**
Craft Animation is designed around two main input paths:

- A generic built-in JSON clip format
- Emotecraft-style emote JSON loading

That means you can either author your own clip format directly or reuse existing player animation data structures as part of your pipeline.

**How to connect and use it in your mod**
This library is meant to be connected to your own renderer, model, or gameplay code. It does not automatically inject finished animations into every vanilla render path by itself. The normal workflow looks like this:

**1. Create an animation JSON file**
Example location:

```
assets/yourmod/animations/guardian_idle.json
```

You can use the built-in example file as a reference:

```
assets/craftanimation/animations/example_idle.json
```

**2. Load and register the clip**
Use AnimationLibrary through CraftAnimationApi.library().

```
AnimationClip clip = CraftAnimationApi.library().loadBuiltin(
    "assets/yourmod/animations/guardian_idle.json",
    getClass().getClassLoader()
);
```

If the clip is already registered, you can fetch it later with:

```
AnimationClip clip = CraftAnimationApi.library().require("yourmod:guardian_idle");
```

**3. Create an animation subject key**
The runtime keeps separate animation state for each subject through AnimationSubjectKey.

Player example:

```
AnimationSubjectKey key = AnimationSubjectKey.player(
    level.dimension().location().toString(),
    player.getUUID()
);
```

Mob example:

```
AnimationSubjectKey key = AnimationSubjectKey.mob(
    level.dimension().location().toString(),
    mob.getUUID()
);
```

Block entity example:

```
AnimationSubjectKey key = AnimationSubjectKey.blockEntity(
    level.dimension().location().toString(),
    pos.getX(), pos.getY(), pos.getZ()
);
```

**4. Start playback**

```
CraftAnimationApi.runtime().play(key, clip);
```

You can also access the controller directly and change playback speed:

```
CraftAnimationApi.runtime().controller(key).setSpeed(1.25F);
```

**5. Advance the animation every tick**

```
CraftAnimationApi.runtime().tick(key, deltaTicks);
```

Or update every active controller at once:

```
CraftAnimationApi.runtime().tickAll(deltaTicks);
```

**6. Sample the current pose**

```
AnimationPose pose = CraftAnimationApi.runtime().sample(key);
```

The sampled AnimationPose is what you apply inside your own player renderer, entity model, block entity renderer, custom item renderer, or display rendering logic.

In short, the normal usage flow is:

- Load a clip
- Create a subject key
- Play the clip
- Tick the runtime
- Sample the pose
- Apply the pose in your render/model code

**Typical use cases**
- Player idle stances while holding custom weapons
- Mob idle, walk, or attack poses
- Boss or scripted entity animation playback
- Block entity machine or structure motion
- Display-based cinematic timelines and visual effects

**Notes**
- This mod is primarily a developer-facing library.
- Installing it by itself will not add major gameplay content.
- Final visual animation results still depend on how the consuming mod applies sampled poses to its renderer or model layer.
- The runtime is shared, but the final implementation path is different for players, entities, blocks, and custom render systems.

**Intended users**
- Forge mod developers
- Projects that need a reusable data-driven animation system
- Multi-version mod environments that want to keep one common animation architecture