First-person animations play for the local player's held item view. + * Third-person animations play when other players see the item being held.
+ * + *Animations are played based on a priority system:
+ *Obtain an instance via {@link IGeckoItemModel#getItemAnimation()}.
+ * + *Usage example:
+ *
+ * var anim = itemGecko.getItemAnimation();
+ * // Set for both perspectives
+ * anim.setIdleAnimation("animation.sword.idle");
+ * anim.setSwingAnimation("animation.sword.swing");
+ * // Set per-perspective (0 = first person, 1 = third person)
+ * anim.setSwingAnimation("animation.sword.swing_fp", 0);
+ * anim.setSwingAnimation("animation.sword.swing_tp", 1);
+ *
+ *
+ * @see IGeckoItemModel#getItemAnimation()
+ */
+public interface IItemAnimation {
+
+ /**
+ * Get the idle animation name for first person.
+ *
+ * @return the idle animation name, or an empty string if none is set
+ */
+ String getIdleAnimation();
+
+ /**
+ * Get the idle animation name for a specific perspective.
+ *
+ * @param perspective 0 for first person, 1 for third person
+ * @return the idle animation name, or an empty string if none is set
+ */
+ String getIdleAnimation(int perspective);
+
+ /**
+ * Set the idle animation name for both perspectives.
+ *
+ * @param animation the animation name, or an empty string to clear
+ */
+ void setIdleAnimation(String animation);
+
+ /**
+ * Set the idle animation name for a specific perspective.
+ *
+ * @param animation the animation name, or an empty string to clear
+ * @param perspective 0 for first person, 1 for third person
+ */
+ void setIdleAnimation(String animation, int perspective);
+
+ /**
+ * Get the swing animation name for first person.
+ *
+ * @return the swing animation name, or an empty string if none is set
+ */
+ String getSwingAnimation();
+
+ /**
+ * Get the swing animation name for a specific perspective.
+ *
+ * @param perspective 0 for first person, 1 for third person
+ * @return the swing animation name, or an empty string if none is set
+ */
+ String getSwingAnimation(int perspective);
+
+ /**
+ * Set the swing animation name for both perspectives.
+ * This animation plays once when the player swings or attacks with the item.
+ *
+ * @param animation the animation name, or an empty string to clear
+ */
+ void setSwingAnimation(String animation);
+
+ /**
+ * Set the swing animation name for a specific perspective.
+ *
+ * @param animation the animation name, or an empty string to clear
+ * @param perspective 0 for first person, 1 for third person
+ */
+ void setSwingAnimation(String animation, int perspective);
+
+ /**
+ * Get the use animation name for first person.
+ *
+ * @return the use animation name, or an empty string if none is set
+ */
+ String getUseAnimation();
+
+ /**
+ * Get the use animation name for a specific perspective.
+ *
+ * @param perspective 0 for first person, 1 for third person
+ * @return the use animation name, or an empty string if none is set
+ */
+ String getUseAnimation(int perspective);
+
+ /**
+ * Set the use animation name for both perspectives.
+ * This animation plays while the player is actively using the item.
+ *
+ * @param animation the animation name, or an empty string to clear
+ */
+ void setUseAnimation(String animation);
+
+ /**
+ * Set the use animation name for a specific perspective.
+ *
+ * @param animation the animation name, or an empty string to clear
+ * @param perspective 0 for first person, 1 for third person
+ */
+ void setUseAnimation(String animation, int perspective);
+}
diff --git a/src/main/java/com/goodbird/npcgecko/client/ItemAnimationStateTracker.java b/src/main/java/com/goodbird/npcgecko/client/ItemAnimationStateTracker.java
new file mode 100644
index 0000000..644bece
--- /dev/null
+++ b/src/main/java/com/goodbird/npcgecko/client/ItemAnimationStateTracker.java
@@ -0,0 +1,42 @@
+package com.goodbird.npcgecko.client;
+
+import com.goodbird.npcgecko.constants.EnumItemAnimType;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Client-side tracker for item animation states.
+ * Keyed by GeckoLibID (the stable unique ID assigned to each ItemStack).
+ * Tracks both the animation type and a sequence counter for swing re-triggering.
+ */
+public class ItemAnimationStateTracker {
+
+ public static class AnimState {
+ public final EnumItemAnimType type;
+ public final int sequence;
+
+ public AnimState(EnumItemAnimType type, int sequence) {
+ this.type = type;
+ this.sequence = sequence;
+ }
+ }
+
+ private static final MapPlayState predicate(AnimationEvent
event) {
- ItemStack stack = (ItemStack) event.getExtraData().get(0);
- IItemStack istack = NpcAPI.Instance().getIItemStack(stack);
- if (!(istack instanceof IItemCustomizable)) return PlayState.STOP;
- if (!(istack instanceof IScriptCustomItem)) return PlayState.STOP;
- IScriptCustomItem item = (IScriptCustomItem) istack;
- CustomItemModelData data = item.getCustomModelData();
+
+ private static final Map PlayState predicate(AnimationEvent event) {
+ P animatable = event.getAnimatable();
+ if (!(animatable instanceof AnimatableStackWrapper)) return PlayState.STOP;
+ AnimatableStackWrapper wrapper = (AnimatableStackWrapper) animatable;
+
+ Object userData = wrapper.getUserData();
+ if (!(userData instanceof ItemRenderContext)) return PlayState.STOP;
+ ItemRenderContext ctx = (ItemRenderContext) userData;
+ CustomItemModelData data = ctx.modelData;
if (data == null) return PlayState.STOP;
- String idleAnim = data.getIdleAnim();
- if (idleAnim == null || idleAnim.isEmpty()) return PlayState.STOP;
- event.getController().setAnimation(new AnimationBuilder().loop(idleAnim));
- return PlayState.CONTINUE;
+
+ AnimationController controller = event.getController();
+ ItemRenderType renderType = ctx.renderType;
+ int animId = (ctx.entityId << 4) | (ctx.slotIndex & 0xF);
+
+ boolean isFirstPerson = (renderType == ItemRenderType.EQUIPPED_FIRST_PERSON);
+
+ // Keep transition length in sync with model data (script may change it at runtime)
+ controller.transitionLengthTicks = data.getTransitionLengthTicks();
+
+ // Select perspective-specific animations
+ String swingAnim = isFirstPerson ? data.getSwingAnimFP() : data.getSwingAnimTP();
+ String useAnim = isFirstPerson ? data.getUseAnimFP() : data.getUseAnimTP();
+ String idleAnim = isFirstPerson ? data.getIdleAnimFP() : data.getIdleAnimTP();
+
+ if (isFirstPerson) {
+ // ================================================================
+ // FIRST PERSON: local player, read state directly from client
+ // ================================================================
+ EntityPlayer localPlayer = Minecraft.getMinecraft().thePlayer;
+ if (localPlayer == null) return PlayState.STOP;
+
+ Boolean fpActive = fpSwingActive.get(animId);
+ boolean swingActive = fpActive != null && fpActive;
+
+ // --- Swing (allows interruption: new clicks restart the animation) ---
+ boolean isSwinging = localPlayer.isSwingInProgress;
+ if (isSwinging && swingAnim != null && !swingAnim.isEmpty()) {
+ // Start OR restart the swing animation on every new click
+ fpSwingActive.put(animId, true);
+ localPlayer.isSwingInProgress = false;
+ localPlayer.swingProgressInt = 0;
+ controller.markNeedsReload();
+ controller.setAnimation(new AnimationBuilder().playOnce(swingAnim));
+ return PlayState.CONTINUE;
+ }
+
+ if (swingActive) {
+ if (controller.getAnimationState() == AnimationState.Stopped) {
+ fpSwingActive.put(animId, false);
+ // Fall through to use/idle
+ } else {
+ // Swing still playing, no new click — suppress vanilla swing
+ localPlayer.isSwingInProgress = false;
+ localPlayer.swingProgressInt = 0;
+ return PlayState.CONTINUE;
+ }
+ }
+
+ // --- Use ---
+ if (localPlayer.isUsingItem() && useAnim != null && !useAnim.isEmpty()) {
+ controller.setAnimation(new AnimationBuilder().loop(useAnim));
+ return PlayState.CONTINUE;
+ }
+
+ } else {
+ // ================================================================
+ // THIRD PERSON: read from ItemAnimationStateTracker (keyed by animId)
+ // ================================================================
+
+ // Clear any stale FP swing flag — prevents getting stuck when
+ // toggling F5 (FP→TP→FP) while a swing was active
+ fpSwingActive.remove(animId);
+
+ ItemAnimationStateTracker.AnimState trackerState = ItemAnimationStateTracker.getAnimation(animId);
+
+ // --- Swing (sequence-based detection) ---
+ if (trackerState != null && trackerState.type == EnumItemAnimType.SWING
+ && swingAnim != null && !swingAnim.isEmpty()) {
+ Integer lastSeq = lastProcessedSwingSeq.get(animId);
+ if (lastSeq == null || lastSeq != trackerState.sequence) {
+ // New swing detected
+ lastProcessedSwingSeq.put(animId, trackerState.sequence);
+ controller.markNeedsReload();
+ controller.setAnimation(new AnimationBuilder().playOnce(swingAnim));
+ return PlayState.CONTINUE;
+ }
+ // Same swing, still playing
+ if (controller.getAnimationState() != AnimationState.Stopped) {
+ return PlayState.CONTINUE;
+ }
+ // Swing finished, fall through to idle
+ }
+
+ // --- Use ---
+ if (trackerState != null && trackerState.type == EnumItemAnimType.USE_START
+ && useAnim != null && !useAnim.isEmpty()) {
+ controller.setAnimation(new AnimationBuilder().loop(useAnim));
+ return PlayState.CONTINUE;
+ }
+ }
+
+ // --- Idle (lowest priority, both perspectives) ---
+ if (idleAnim != null && !idleAnim.isEmpty()) {
+ controller.setAnimation(new AnimationBuilder().loop(idleAnim));
+ return PlayState.CONTINUE;
+ }
+
+ return PlayState.STOP;
}
}
diff --git a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinCustomItemRenderer.java b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinCustomItemRenderer.java
index 9110088..73e3fc4 100644
--- a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinCustomItemRenderer.java
+++ b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinCustomItemRenderer.java
@@ -38,7 +38,7 @@ public class MixinCustomItemRenderer {
remap = false
)
public void renderItem(ItemRenderType type, ItemStack itemStack, Object[] data, CallbackInfo ci) {
- if (ModelItemRenderUtil.tryRender(type, itemStack)) {
+ if (ModelItemRenderUtil.tryRender(type, itemStack, data)) {
ci.cancel();
}
}
diff --git a/src/main/java/com/goodbird/npcgecko/network/ItemAnimSyncable.java b/src/main/java/com/goodbird/npcgecko/network/ItemAnimSyncable.java
new file mode 100644
index 0000000..95d432b
--- /dev/null
+++ b/src/main/java/com/goodbird/npcgecko/network/ItemAnimSyncable.java
@@ -0,0 +1,79 @@
+package com.goodbird.npcgecko.network;
+
+import com.goodbird.npcgecko.client.ItemAnimationStateTracker;
+import com.goodbird.npcgecko.constants.EnumItemAnimType;
+import software.bernie.geckolib3.core.IAnimatable;
+import software.bernie.geckolib3.core.PlayState;
+import software.bernie.geckolib3.core.controller.AnimationController;
+import software.bernie.geckolib3.core.manager.AnimationData;
+import software.bernie.geckolib3.core.manager.AnimationFactory;
+import software.bernie.geckolib3.core.manager.SingletonAnimationFactory;
+import software.bernie.geckolib3.network.GeckoLibNetwork;
+import software.bernie.geckolib3.network.ISyncable;
+
+/**
+ * Singleton ISyncable that handles animation sync for ALL dynamic/scripted items.
+ * Owns the shared SingletonAnimationFactory used by all AnimatableStackWrappers.
+ *
+ * State encoding: (sequence << 8) | (type.ordinal() & 0xFF)
+ * This allows the client to detect new swings by comparing sequence numbers.
+ */
+public class ItemAnimSyncable implements ISyncable {
+ public static final ItemAnimSyncable INSTANCE = new ItemAnimSyncable();
+ private static final String SYNC_KEY = "npcgecko:item_anim";
+
+ private final SingletonAnimationFactory factory;
+
+ private ItemAnimSyncable() {
+ // Dummy animatable for the factory constructor — actual controllers
+ // are registered per-ID by the AnimatableStackWrapper via the
+ // two-argument getOrCreateAnimationData(id, wrapper) at render time.
+ IAnimatable dummy = new IAnimatable() {
+ @Override
+ public void registerControllers(AnimationData data) {
+ data.addAnimationController(
+ new AnimationController<>(this, "item_controller", 0, e -> PlayState.STOP));
+ }
+ @Override
+ public AnimationFactory getFactory() { return factory; }
+ };
+ this.factory = new SingletonAnimationFactory(dummy);
+ }
+
+ public void register() {
+ GeckoLibNetwork.registerSyncable(this);
+ }
+
+ @Override
+ public String getSyncKey() {
+ return SYNC_KEY;
+ }
+
+ @Override
+ public void onAnimationSync(int id, int state) {
+ int animTypeOrdinal = state & 0xFF;
+ int sequence = state >>> 8;
+
+ EnumItemAnimType[] values = EnumItemAnimType.values();
+ if (animTypeOrdinal < 0 || animTypeOrdinal >= values.length) return;
+ EnumItemAnimType type = values[animTypeOrdinal];
+
+ if (type == EnumItemAnimType.USE_STOP) {
+ ItemAnimationStateTracker.clearAnimation(id);
+ } else {
+ ItemAnimationStateTracker.setAnimation(id, type, sequence);
+ }
+ }
+
+ public AnimationFactory getSharedFactory() {
+ return factory;
+ }
+
+ /**
+ * Encodes an EnumItemAnimType and sequence counter into a single int
+ * for the ISyncable state parameter.
+ */
+ public static int encodeState(EnumItemAnimType type, int sequence) {
+ return (sequence << 8) | (type.ordinal() & 0xFF);
+ }
+}
diff --git a/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java b/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
index 65712b7..1d37839 100644
--- a/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
+++ b/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
@@ -1,5 +1,6 @@
package com.goodbird.npcgecko.wrapper;
+import com.goodbird.npcgecko.api.IItemAnimation;
import com.goodbird.npcgecko.api.IGeckoItemModel;
import com.goodbird.npcgecko.data.CustomItemModelData;
import com.goodbird.npcgecko.data.ItemDisplayTransform;
@@ -91,15 +92,8 @@ public class GeckoItemModelWrapper implements IGeckoItemModel {
}
@Override
- public String getIdleAnimation() {
- CustomItemModelData data = scriptItem.getCustomModelData();
- return data != null ? data.getIdleAnim() : "";
- }
-
- @Override
- public void setIdleAnimation(String animation) {
- getOrCreateData().setIdleAnim(animation);
- persist();
+ public IItemAnimation getItemAnimation() {
+ return new ItemAnimationWrapper(item);
}
@Override
diff --git a/src/main/java/com/goodbird/npcgecko/wrapper/ItemAnimationWrapper.java b/src/main/java/com/goodbird/npcgecko/wrapper/ItemAnimationWrapper.java
new file mode 100644
index 0000000..fb8e6ec
--- /dev/null
+++ b/src/main/java/com/goodbird/npcgecko/wrapper/ItemAnimationWrapper.java
@@ -0,0 +1,129 @@
+package com.goodbird.npcgecko.wrapper;
+
+import com.goodbird.npcgecko.api.IItemAnimation;
+import com.goodbird.npcgecko.data.CustomItemModelData;
+import com.goodbird.npcgecko.mixin.IScriptCustomItem;
+import net.minecraft.item.ItemStack;
+import net.minecraft.nbt.NBTTagCompound;
+import noppes.npcs.api.item.IItemCustomizable;
+import noppes.npcs.scripted.item.ScriptCustomizableItem;
+
+public class ItemAnimationWrapper implements IItemAnimation {
+ private final IItemCustomizable item;
+ private final IScriptCustomItem scriptItem;
+
+ public ItemAnimationWrapper(IItemCustomizable item) {
+ this.item = item;
+ this.scriptItem = (IScriptCustomItem) item;
+ }
+
+ private CustomItemModelData getOrCreateData() {
+ if (!scriptItem.hasCustomModel()) {
+ scriptItem.setCustomModelData(new CustomItemModelData());
+ }
+ return scriptItem.getCustomModelData();
+ }
+
+ private void persist() {
+ ((ScriptCustomizableItem) item).saveItemData();
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ ItemStack stack = ((ScriptCustomizableItem) item).getMCItemStack();
+ if (data != null && stack != null) {
+ NBTTagCompound root = stack.getTagCompound();
+ if (root == null) { root = new NBTTagCompound(); stack.setTagCompound(root); }
+ NBTTagCompound tag = new NBTTagCompound();
+ data.writeToNBT(tag);
+ root.setTag("GeckoModelData", tag);
+ }
+ }
+
+ // --- Idle ---
+
+ @Override
+ public String getIdleAnimation() { return getIdleAnimation(0); }
+
+ @Override
+ public String getIdleAnimation(int perspective) {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ if (data == null) return "";
+ return perspective == 0 ? data.getIdleAnimFP() : data.getIdleAnimTP();
+ }
+
+ @Override
+ public void setIdleAnimation(String animation) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ data.setIdleAnimFP(v);
+ data.setIdleAnimTP(v);
+ persist();
+ }
+
+ @Override
+ public void setIdleAnimation(String animation, int perspective) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ if (perspective == 0) data.setIdleAnimFP(v);
+ else data.setIdleAnimTP(v);
+ persist();
+ }
+
+ // --- Swing ---
+
+ @Override
+ public String getSwingAnimation() { return getSwingAnimation(0); }
+
+ @Override
+ public String getSwingAnimation(int perspective) {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ if (data == null) return "";
+ return perspective == 0 ? data.getSwingAnimFP() : data.getSwingAnimTP();
+ }
+
+ @Override
+ public void setSwingAnimation(String animation) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ data.setSwingAnimFP(v);
+ data.setSwingAnimTP(v);
+ persist();
+ }
+
+ @Override
+ public void setSwingAnimation(String animation, int perspective) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ if (perspective == 0) data.setSwingAnimFP(v);
+ else data.setSwingAnimTP(v);
+ persist();
+ }
+
+ // --- Use ---
+
+ @Override
+ public String getUseAnimation() { return getUseAnimation(0); }
+
+ @Override
+ public String getUseAnimation(int perspective) {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ if (data == null) return "";
+ return perspective == 0 ? data.getUseAnimFP() : data.getUseAnimTP();
+ }
+
+ @Override
+ public void setUseAnimation(String animation) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ data.setUseAnimFP(v);
+ data.setUseAnimTP(v);
+ persist();
+ }
+
+ @Override
+ public void setUseAnimation(String animation, int perspective) {
+ CustomItemModelData data = getOrCreateData();
+ String v = animation != null ? animation : "";
+ if (perspective == 0) data.setUseAnimFP(v);
+ else data.setUseAnimTP(v);
+ persist();
+ }
+}