Playing Animations - BetterModel

Overview

BetterModel provides a powerful animation system that supports looping, single-play animations, speed control, blending, and per-player animation states.

Basic Animation Playback

Playing an Animation

Play an animation by name:

import kr.toxicity.model.api.tracker.Tracker;

Tracker tracker = // your tracker

// Play with default settings (loop)
boolean success = tracker.animate("walk");

if (success) {
    System.out.println("Animation started");
} else {
    System.out.println("Animation not found");
}

Play Once

Play an animation a single time:

import kr.toxicity.model.api.animation.AnimationModifier;

tracker.animate("attack", AnimationModifier.DEFAULT_WITH_PLAY_ONCE);

Animation with Callback

Execute code when an animation finishes:

tracker.animate("death", AnimationModifier.DEFAULT_WITH_PLAY_ONCE, () -> {
    System.out.println("Death animation finished");
    tracker.close(); // Remove the tracker
});

Animation Modifiers

Creating Custom Modifiers

AnimationModifier controls how animations play:

import kr.toxicity.model.api.animation.AnimationIterator;

AnimationModifier modifier = AnimationModifier.builder()
    .start(10)              // Lerp-in time (ticks)
    .end(5)                 // Lerp-out time (ticks)
    .speed(1.5F)            // 1.5x speed
    .type(AnimationIterator.Type.PLAY_ONCE) // Play once
    .override(true)         // Override other animations
    .build();

tracker.animate("run", modifier);

Animation Types

public enum Type {
    LOOP,       // Loop indefinitely
    PLAY_ONCE,  // Play once and stop
    HOLD        // Play once and hold the last frame
}

Example usage:

// Loop continuously
AnimationModifier looping = AnimationModifier.builder()
    .type(AnimationIterator.Type.LOOP)
    .build();

// Play once
AnimationModifier once = AnimationModifier.builder()
    .type(AnimationIterator.Type.PLAY_ONCE)
    .build();

// Hold last frame
AnimationModifier hold = AnimationModifier.builder()
    .type(AnimationIterator.Type.HOLD)
    .build();

Speed Control

Adjust animation speed:

// Static speed
AnimationModifier fast = AnimationModifier.builder()
    .speed(2.0F)  // 2x speed
    .build();

AnimationModifier slow = AnimationModifier.builder()
    .speed(0.5F)  // Half speed
    .build();

// Dynamic speed
AnimationModifier dynamic = AnimationModifier.builder()
    .speed(() -> entity.isSprinting() ? 1.5F : 1.0F)
    .build();

Lerp (Blend) Transitions

Smooth transitions between animations:

AnimationModifier smooth = AnimationModifier.builder()
    .start(20)  // 20 ticks (1 second) blend in
    .end(10)    // 10 ticks (0.5 seconds) blend out
    .build();

tracker.animate("walk", smooth);

Use longer lerp times for smoother transitions between animations. A value of 10-20 ticks works well for most cases.

Conditional Animations

Play animations based on conditions:

AnimationModifier conditional = AnimationModifier.builder()
    .predicate(() -> entity.isOnGround()) // Only play when on ground
    .build();

tracker.animate("walk", conditional);

Stopping Animations

Stop by Name

Stop a specific animation:

// Stop on all bones
boolean stopped = tracker.stopAnimation("walk");

// Stop on specific bones
tracker.stopAnimation(
    bone -> bone.name().toString().contains("arm"),
    "attack"
);

Stop for Specific Player

Stop a per-player animation:

import kr.toxicity.model.api.platform.PlatformPlayer;

PlatformPlayer player = BukkitAdapter.adapt(bukkitPlayer);

tracker.stopAnimation(
    bone -> true,
    "custom_animation",
    player
);

Animation Replacement

Replace Running Animation

Seamlessly transition from one animation to another:

// Replace "walk" with "run"
tracker.replace("walk", "run", AnimationModifier.DEFAULT);

// With custom modifier
AnimationModifier fast = AnimationModifier.builder()
    .speed(1.5F)
    .start(5)
    .build();

tracker.replace("idle", "attack", fast);

Using Blueprint Animations

Replace with a blueprint animation object:

import kr.toxicity.model.api.data.blueprint.BlueprintAnimation;

tracker.renderer().animation("special_attack").ifPresent(animation -> {
    tracker.replace("attack", animation, AnimationModifier.DEFAULT);
});

Per-Player Animations

What are Per-Player Animations?

Per-player animations show different animations to different players for the same model. This is essential for:

Custom player emotes visible only to nearby players
Player-specific effects
Individualized NPC interactions

Playing Per-Player Animations

Use the player() modifier to target specific players:

import org.bukkit.entity.Player;

Player targetPlayer = // the player who should see this animation

AnimationModifier perPlayer = AnimationModifier.builder()
    .player(BukkitAdapter.adapt(targetPlayer))
    .type(AnimationIterator.Type.PLAY_ONCE)
    .build();

tracker.animate("wave", perPlayer);

Per-Player Events

Listen for per-player animation events:

import kr.toxicity.model.api.event.PlayerPerAnimationStartEvent;
import kr.toxicity.model.api.event.PlayerPerAnimationEndEvent;
import org.bukkit.event.EventHandler;

@EventHandler
public void onPerPlayerAnimStart(PlayerPerAnimationStartEvent event) {
    Tracker tracker = event.tracker();
    PlatformPlayer player = event.player();
    
    System.out.println("Per-player animation started for: " + player.name());
}

@EventHandler
public void onPerPlayerAnimEnd(PlayerPerAnimationEndEvent event) {
    System.out.println("Per-player animation ended");
}

Per-player animations increase packet overhead. Use them sparingly and only when necessary.

Built-in Animations

Spawn Animation

Automatic animations on tracker creation:

// The "spawn" animation plays automatically if defined
DummyTracker tracker = BetterModel.model("npc")
    .map(r -> r.create(BukkitAdapter.adapt(location)))
    .orElse(null);

// Built-in animations are played via TrackerBuiltInAnimation
import kr.toxicity.model.api.tracker.TrackerBuiltInAnimation;

// You can also manually trigger built-in animations
TrackerBuiltInAnimation.play(tracker);

Damage Animation

Automatic damage animation on entity hit (if enabled in TrackerModifier):

EntityTracker tracker = // your tracker

// Trigger damage tint manually
tracker.damageTint();

// Cancel damage tint
tracker.cancelDamageTint();

// Set custom damage tint color
tracker.damageTintValue(0xFF0000); // Red
tracker.damageTint();

Animation Layering

Override vs. Blend

// Blend with existing animations (default)
AnimationModifier blend = AnimationModifier.builder()
    .override(false)
    .build();

tracker.animate("attack", blend);

// Override all animations on affected bones
AnimationModifier override = AnimationModifier.builder()
    .override(true)
    .build();

tracker.animate("attack", override);

Bone-Specific Animations

Play animations on specific bones:

import kr.toxicity.model.api.data.blueprint.BlueprintAnimation;

tracker.renderer().animation("wave_arm").ifPresent(animation -> {
    // This animation will only affect bones it's designed for
    tracker.animate(animation, AnimationModifier.DEFAULT);
});

Advanced Patterns

Animation State Machine

Implement a simple state machine:

public class EntityAnimationController {
    private final Tracker tracker;
    private String currentState = "idle";
    
    public void setState(String newState) {
        if (currentState.equals(newState)) return;
        
        // Replace current animation with new one
        tracker.replace(currentState, newState, AnimationModifier.builder()
            .start(5)
            .end(5)
            .build()
        );
        
        currentState = newState;
    }
    
    public void tick(Entity entity) {
        if (entity.isOnGround() && entity.getVelocity().lengthSquared() > 0.01) {
            setState("walk");
        } else if (entity.isOnGround()) {
            setState("idle");
        } else {
            setState("jump");
        }
    }
}

Combo Attacks

Chain animations together:

public void performCombo(Tracker tracker) {
    tracker.animate("attack_1", AnimationModifier.DEFAULT_WITH_PLAY_ONCE, () -> {
        tracker.animate("attack_2", AnimationModifier.DEFAULT_WITH_PLAY_ONCE, () -> {
            tracker.animate("attack_3", AnimationModifier.DEFAULT_WITH_PLAY_ONCE, () -> {
                tracker.animate("idle");
            });
        });
    });
}

Synchronized Group Animations

Animate multiple trackers together:

public void synchronizedAnimation(List<Tracker> trackers, String animation) {
    AnimationModifier sync = AnimationModifier.DEFAULT;
    
    trackers.forEach(tracker -> tracker.animate(animation, sync));
}

Animation Debugging

Checking Running Animations

// Access bones to check animations
tracker.bones().forEach(bone -> {
    System.out.println("Bone: " + bone.name());
    // Check animation state via bone methods
});

Listing Available Animations

import kr.toxicity.model.api.data.renderer.ModelRenderer;

ModelRenderer renderer = tracker.renderer();
renderer.animations().forEach((name, animation) -> {
    System.out.println("Animation: " + name);
});

Performance Considerations

Use LOOP for continuous animations (idle, walk)
Use PLAY_ONCE for actions (attack, jump)
Avoid starting/stopping animations every tick
Cache AnimationModifier instances when possible
Limit per-player animations to visible range

Getting Started

Core Concepts

Guides

Platform Support

​Overview

​Basic Animation Playback

​Playing an Animation

​Play Once

​Animation with Callback

​Animation Modifiers

​Creating Custom Modifiers

​Animation Types

​Speed Control

​Lerp (Blend) Transitions

​Conditional Animations

​Stopping Animations

​Stop by Name

​Stop for Specific Player

​Animation Replacement

​Replace Running Animation

​Using Blueprint Animations

​Per-Player Animations

​What are Per-Player Animations?

​Playing Per-Player Animations

​Per-Player Events

​Built-in Animations

​Spawn Animation

​Damage Animation

​Animation Layering

​Override vs. Blend

​Bone-Specific Animations

​Advanced Patterns

​Animation State Machine

​Combo Attacks

​Synchronized Group Animations

​Animation Debugging

​Checking Running Animations

​Listing Available Animations

​Performance Considerations

​Next Steps

Custom Hitboxes

Per-Player Animation

Build docs developers (and LLMs) love

Overview

Basic Animation Playback

Playing an Animation

Play Once

Animation with Callback

Animation Modifiers

Creating Custom Modifiers

Animation Types

Speed Control

Lerp (Blend) Transitions

Conditional Animations

Stopping Animations

Stop by Name

Stop for Specific Player

Animation Replacement

Replace Running Animation

Using Blueprint Animations

Per-Player Animations

What are Per-Player Animations?

Playing Per-Player Animations

Per-Player Events

Built-in Animations

Spawn Animation

Damage Animation

Animation Layering

Override vs. Blend

Bone-Specific Animations

Advanced Patterns

Animation State Machine

Combo Attacks

Synchronized Group Animations

Animation Debugging

Checking Running Animations

Listing Available Animations

Performance Considerations

Next Steps