🏃‍♂️ AnimationAction

If you want to perform an action after the animation is done player, you would want to look into using AnimationAction.

It is separated into action types and instances. Type is responsible for creating and executing action instance, while the instance itself is tasked with holding and serializing context information applicable to your action.

If you don't need to store much information, you can just use an empty default AnimationActionInstance. It still offers storage of data through NBT, using AnimationActionInstance.getExtra() method (you can create instance with extra data and execute it that way).

If you want to create custom action instance for storing data, you will need to override AnimationAction.createInstance method to return a new unconfigured instance of your action.

↩️ Built-in actions

HammerAnimations comes with a single animation action out-of-box: MethodAnimAction.

This function allows performing data-driven, serialized method calls on animation completion, allowing invocation of methods through reflection.

Important!

You must annotate the target method that should be called with @ExposedToAnimAction, otherwise it will not receive the invocation.

To create the instance of this action, call MethodAnimAction.create(@NotNull Class<?> owner, @NotNull String methodName, @Nullable Object instance, Object... args).

Now, for static methods, the instance object should be null. For instance methods, you should only use the animated object instance only.

You can pass arguments that would comply with NBTSerializationHelper serialization mechanism plus these types from the animated object (which should be passed as null):

AnimationLayer - the layer on which the action has been called from;
AnimationSystem - the animation system which the action has been called from;
IAnimatedObject (you can specify your overriden class, as long as it matches the caller) - the owner of the animation system, on which the action has been invoked;
World (1.12.2) / Level (1.20.1+) - the world where the action has been called; All other objects must be serializable one way or another through NBTSerializationHelper. You may pass several default types, check the 📦 Out-of-box serializers for what may be passed by default.

Here is a complete example for a BlockEntity:

@ExposedToAnimAction
public void testCall(BlockPos newPos)
{
	HammerAnimations.LOG.info("[{}] testCall() called @ {}", level.isClientSide ? "CLIENT" : "SERVER", newPos);
}

@Override
public void update()
{
	super.update();
	animations.tick();
	setChanged();
	
	if(level.getBestNeighborSignal(worldPosition) > 0)
	{
		animations.startAnimationAt(CommonLayerNames.LEGS, MyAnimations.EXAMPLE_ANIMATION
			.configure()
			.loopMode(LoopMode.ONCE) // Force the animation to finish regardless of its initial options.
			.onFinish(MethodAnimAction.create(getClass(), "testCall", this, new BlockPos(1, 2, 3)))
		);
	}
}

☕ Registration (Java)

⌨️ ModAnimations Class

To bind actions, create an interface ModAnimationActions inside your init package.

The result should look something like this:

package com.yourname.yourmod.init;

import org.zeith.hammerlib.annotations.*;

@SimplyRegister
public interface ModAnimationActions
{
}

📦 Adding action types

To add a new animation container into the mod, simply create a new field inside ModAnimationActions of type AnimationAction, assign it a new AnimationAction type instance, and annotating the field with @RegistryName("name"). The "name" must be unique.

package com.yourname.yourmod.init;

import org.zeith.hammeranims.api.animation.*;
import org.zeith.hammerlib.annotations.*;

@SimplyRegister
public interface ModAnimationActions
{
    @RegistryName("my_action")
    AnimationAction MY_ACTION = new MyAnimationAction();
}

🆕 Creating action type

To start off, let's create a new action type: MyAnimationAction, it will damage information to indicate how much damage to deal to nearby entities, and radius of action.