From f40d4c4a11f5f5ae0c8ea1c34d57b0c1283a55de Mon Sep 17 00:00:00 2001
From: Kam
Date: Thu, 12 Mar 2026 18:44:27 -0400
Subject: [PATCH] CUSTOM MODEL HANDLING ON GECKO MODELS!
---
.../npcgecko/api/AbstractGeckoAPI.java | 270 +++++++++---------
.../com/goodbird/npcgecko/api/GeckoAPI.java | 87 +-----
.../npcgecko/api/IGeckoAnimatable.java | 74 +++--
.../npcgecko/api/IGeckoAnimation.java | 31 +-
.../npcgecko/api/IGeckoAnimationBuilder.java | 51 ++--
.../com/goodbird/npcgecko/api/IGeckoBone.java | 110 ++++---
.../goodbird/npcgecko/api/IGeckoColor.java | 38 ++-
.../npcgecko/api/IGeckoItemModel.java | 164 +++++++++++
.../goodbird/npcgecko/api/IGeckoModel.java | 19 +-
.../npcgecko/client/ModelItemRenderUtil.java | 43 +--
.../mixin/impl/MixinScriptCustomItem.java | 42 ++-
.../mixin/impl/MixinScriptLinkedItem.java | 42 ++-
.../wrapper/GeckoItemModelWrapper.java | 157 ++++++++++
13 files changed, 762 insertions(+), 366 deletions(-)
create mode 100644 src/main/java/com/goodbird/npcgecko/api/IGeckoItemModel.java
create mode 100644 src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
diff --git a/src/main/java/com/goodbird/npcgecko/api/AbstractGeckoAPI.java b/src/main/java/com/goodbird/npcgecko/api/AbstractGeckoAPI.java
index 6800c4a..51e506d 100644
--- a/src/main/java/com/goodbird/npcgecko/api/AbstractGeckoAPI.java
+++ b/src/main/java/com/goodbird/npcgecko/api/AbstractGeckoAPI.java
@@ -8,13 +8,45 @@ import noppes.npcs.api.entity.IPlayer;
import noppes.npcs.api.item.IItemCustomizable;
import noppes.npcs.entity.EntityNPCInterface;
+/**
+ * Main entry point for the GeckoLib Addon API.
+ * Provides methods for controlling GeckoLib 3D models, animations, textures,
+ * and display settings on CustomNPC+ entities, scripted blocks, and items.
+ *
+ * Access the API singleton via {@code AbstractGeckoAPI.Instance()}.
+ * Check availability first with {@code AbstractGeckoAPI.IsAvailable()}.
+ *
+ * Script usage example:
+ *
+ * var gecko = Java.type("com.goodbird.npcgecko.api.AbstractGeckoAPI").Instance();
+ * if (gecko != null) {
+ * gecko.setModel(npc, "geckolib3:geo/custom_npc.geo.json");
+ * gecko.setTexture(npc, "geckolib3:textures/model/custom_npc.png");
+ * }
+ *
+ *
+ * @see IGeckoAnimatable
+ * @see IGeckoItemModel
+ * @see IGeckoAnimationBuilder
+ */
public abstract class AbstractGeckoAPI {
private static AbstractGeckoAPI instance = null;
+ /**
+ * Check whether the GeckoLib mod is loaded and the API is available.
+ *
+ * @return true if GeckoLib is loaded
+ */
public static boolean IsAvailable() {
return Loader.isModLoaded("geckolib3");
}
+ /**
+ * Get the API singleton instance.
+ * Returns null if GeckoLib is not loaded.
+ *
+ * @return the API instance, or null if GeckoLib is unavailable
+ */
public static AbstractGeckoAPI Instance() {
if (instance != null) {
return instance;
@@ -37,15 +69,23 @@ public abstract class AbstractGeckoAPI {
/**
* Create a new animation builder for constructing animation sequences.
+ * Alias for {@link #createAnimationBuilder()}.
*
- * @return A new animation builder
+ * @return a new animation builder instance
*/
public abstract IGeckoAnimationBuilder createAnimBuilder();
/**
* Create a new animation builder for constructing animation sequences.
*
- * @return A new animation builder
+ * Usage example:
+ *
+ * var builder = gecko.createAnimationBuilder();
+ * builder.playOnce("animation.model.attack").loop("animation.model.idle");
+ * gecko.syncAnimForAll(npc, builder);
+ *
+ *
+ * @return a new animation builder instance
*/
public abstract IGeckoAnimationBuilder createAnimationBuilder();
@@ -54,18 +94,24 @@ public abstract class AbstractGeckoAPI {
// ========================================================================
/**
- * Get the animation configuration interface for an NPC.
+ * Get the gecko model configuration interface for an NPC.
+ * The returned object allows reading and writing model, texture,
+ * animation file, and animation state settings.
*
- * @param npc The NPC to get animation config for
- * @return The animatable interface for this NPC
+ * @param npc the NPC to configure
+ * @return the animatable interface for this NPC
+ * @see IGeckoAnimatable
*/
public abstract IGeckoAnimatable getAnimatable(ICustomNpc npc);
/**
- * Get the animation configuration interface for a scripted block.
+ * Get the gecko model configuration interface for a scripted block.
+ * The returned object allows reading and writing model, texture,
+ * animation file, and animation state settings.
*
- * @param scriptedBlock The block to get animation config for
- * @return The animatable interface for this block
+ * @param scriptedBlock the scripted block to configure
+ * @return the animatable interface for this block
+ * @see IGeckoAnimatable
*/
public abstract IGeckoAnimatable getAnimatable(IBlockScripted scriptedBlock);
@@ -74,26 +120,28 @@ public abstract class AbstractGeckoAPI {
// ========================================================================
/**
- * Get a list of all animation names in an animation file.
+ * Get a list of all animation names defined in an animation file.
*
- * @param animationFile The animation file resource location (e.g. "npcgecko:animations/geo_npc.animation.json")
- * @return Array of animation names, or empty array if file not found
+ * @param animationFile the animation file resource location
+ * (e.g. "geckolib3:animations/model.animation.json")
+ * @return array of animation names, or an empty array if the file was not found
*/
public abstract String[] getAnimationList(String animationFile);
/**
* Get a list of all loaded animation file resource locations.
*
- * @return Array of animation file paths
+ * @return array of animation file resource location strings
*/
public abstract String[] getAnimationFileList();
/**
* Get animation metadata from a loaded animation file.
*
- * @param animationFile The animation file resource location
- * @param animationName The animation name within the file
- * @return The animation metadata, or null if not found
+ * @param animationFile the animation file resource location
+ * @param animationName the animation name within the file
+ * @return the animation metadata, or null if not found
+ * @see IGeckoAnimation
*/
public abstract IGeckoAnimation getAnimation(String animationFile, String animationName);
@@ -104,21 +152,23 @@ public abstract class AbstractGeckoAPI {
/**
* Create a color from RGB components.
*
- * @param r Red component (0-255)
- * @param g Green component (0-255)
- * @param b Blue component (0-255)
- * @return A new color
+ * @param r red component (0-255)
+ * @param g green component (0-255)
+ * @param b blue component (0-255)
+ * @return a new color instance
+ * @see IGeckoColor
*/
public abstract IGeckoColor colorOfRGB(int r, int g, int b);
/**
* Create a color from RGBA components.
*
- * @param r Red component (0-255)
- * @param g Green component (0-255)
- * @param b Blue component (0-255)
- * @param a Alpha component (0-255)
- * @return A new color
+ * @param r red component (0-255)
+ * @param g green component (0-255)
+ * @param b blue component (0-255)
+ * @param a alpha component (0-255, where 255 is fully opaque)
+ * @return a new color instance
+ * @see IGeckoColor
*/
public abstract IGeckoColor colorOfRGBA(int r, int g, int b, int a);
@@ -127,51 +177,54 @@ public abstract class AbstractGeckoAPI {
// ========================================================================
/**
- * Set the geo model resource location for an NPC.
+ * Set the GeckoLib geo model resource location for an NPC.
*
- * @param npc The target NPC
- * @param model The model path (e.g. "geckolib3:geo/npc.geo.json")
+ * @param npc the target NPC
+ * @param model the model resource location (e.g. "geckolib3:geo/npc.geo.json")
*/
public abstract void setModel(ICustomNpc npc, String model);
/**
* Set the texture resource location for an NPC.
*
- * @param npc The target NPC
- * @param texture The texture path
+ * @param npc the target NPC
+ * @param texture the texture resource location (e.g. "geckolib3:textures/model/npc.png")
*/
public abstract void setTexture(ICustomNpc npc, String texture);
/**
* Set the animation file resource location for an NPC.
*
- * @param npc The target NPC
- * @param animation The animation file path
+ * @param npc the target NPC
+ * @param animation the animation file resource location
+ * (e.g. "geckolib3:animations/npc.animation.json")
*/
public abstract void setAnimationFile(ICustomNpc npc, String animation);
/**
* Set the idle animation name for an NPC.
+ * The animation must exist in the currently assigned animation file.
*
- * @param npc The target NPC
- * @param animation The animation name from the animation file
+ * @param npc the target NPC
+ * @param animation the animation name (e.g. "animation.npc.idle")
*/
public abstract void setIdleAnimation(ICustomNpc npc, String animation);
/**
- * Sync an animation to a specific player for an NPC.
+ * Sync a queued animation sequence to a specific player for an NPC.
+ * Only the specified player will see the animation.
*
- * @param npc The NPC to play the animation on
- * @param builder The animation builder with queued animations
- * @param player The player to send the animation to
+ * @param npc the NPC to play the animation on
+ * @param builder the animation builder containing the queued animation sequence
+ * @param player the player to send the animation to
*/
public abstract void syncAnimForPlayer(ICustomNpc npc, IGeckoAnimationBuilder builder, IPlayer player);
/**
- * Sync an animation to all players for an NPC.
+ * Sync a queued animation sequence to all connected players for an NPC.
*
- * @param npc The NPC to play the animation on
- * @param builder The animation builder with queued animations
+ * @param npc the NPC to play the animation on
+ * @param builder the animation builder containing the queued animation sequence
*/
public abstract void syncAnimForAll(ICustomNpc npc, IGeckoAnimationBuilder builder);
@@ -180,51 +233,54 @@ public abstract class AbstractGeckoAPI {
// ========================================================================
/**
- * Set the geo model resource location for a scripted block.
+ * Set the GeckoLib geo model resource location for a scripted block.
*
- * @param scriptedBlock The target block
- * @param model The model path
+ * @param scriptedBlock the target scripted block
+ * @param model the model resource location (e.g. "geckolib3:geo/block.geo.json")
*/
public abstract void setModel(IBlockScripted scriptedBlock, String model);
/**
* Set the texture resource location for a scripted block.
*
- * @param scriptedBlock The target block
- * @param texture The texture path
+ * @param scriptedBlock the target scripted block
+ * @param texture the texture resource location (e.g. "geckolib3:textures/model/block.png")
*/
public abstract void setTexture(IBlockScripted scriptedBlock, String texture);
/**
* Set the animation file resource location for a scripted block.
*
- * @param scriptedBlock The target block
- * @param animation The animation file path
+ * @param scriptedBlock the target scripted block
+ * @param animation the animation file resource location
+ * (e.g. "geckolib3:animations/block.animation.json")
*/
public abstract void setAnimationFile(IBlockScripted scriptedBlock, String animation);
/**
* Set the idle animation name for a scripted block.
+ * The animation must exist in the currently assigned animation file.
*
- * @param scriptedBlock The target block
- * @param animation The animation name from the animation file
+ * @param scriptedBlock the target scripted block
+ * @param animation the animation name (e.g. "animation.block.idle")
*/
public abstract void setIdleAnimation(IBlockScripted scriptedBlock, String animation);
/**
- * Sync an animation to a specific player for a scripted block.
+ * Sync a queued animation sequence to a specific player for a scripted block.
+ * Only the specified player will see the animation.
*
- * @param scriptedBlock The block to play the animation on
- * @param builder The animation builder with queued animations
- * @param player The player to send the animation to
+ * @param scriptedBlock the scripted block to play the animation on
+ * @param builder the animation builder containing the queued animation sequence
+ * @param player the player to send the animation to
*/
public abstract void syncAnimForPlayer(IBlockScripted scriptedBlock, IGeckoAnimationBuilder builder, IPlayer player);
/**
- * Sync an animation to all players for a scripted block.
+ * Sync a queued animation sequence to all connected players for a scripted block.
*
- * @param scriptedBlock The block to play the animation on
- * @param builder The animation builder with queued animations
+ * @param scriptedBlock the scripted block to play the animation on
+ * @param builder the animation builder containing the queued animation sequence
*/
public abstract void syncAnimForAll(IBlockScripted scriptedBlock, IGeckoAnimationBuilder builder);
@@ -233,95 +289,33 @@ public abstract class AbstractGeckoAPI {
// ========================================================================
/**
- * Set the geo model resource location for a customizable item.
+ * Get the gecko model interface for a customizable item.
* Works with both Scripted Items and Linked Items.
+ * The returned object allows reading and writing model, texture,
+ * animation, and display transform settings.
*
- * @param item The item (IItemCustom or IItemLinked from event.item or API)
- * @param model The model path (e.g. "geckolib3:geo/mymodel.geo.json")
+ * Usage example:
+ *
+ * var itemGecko = gecko.getItemGecko(event.item);
+ * itemGecko.setModel("geckolib3:geo/sword.geo.json");
+ * itemGecko.setTexture("geckolib3:textures/model/sword.png");
+ * itemGecko.setAnimationFile("geckolib3:animations/sword.animation.json");
+ * itemGecko.setIdleAnimation("animation.sword.idle");
+ *
+ *
+ * @param item the customizable item (IItemCustom or IItemLinked)
+ * @return the gecko model interface for this item
+ * @throws IllegalArgumentException if the item is not a Scripted or Linked item
+ * @see IGeckoItemModel
*/
- public abstract void setItemModel(IItemCustomizable item, String model);
+ public abstract IGeckoItemModel getItemGecko(IItemCustomizable item);
/**
- * Set the texture resource location for a customizable item.
- *
- * @param item The item
- * @param texture The texture path (e.g. "geckolib3:textures/item/mytexture.png")
- */
- public abstract void setItemTexture(IItemCustomizable item, String texture);
-
- /**
- * Set the animation file resource location for a customizable item.
- *
- * @param item The item
- * @param animation The animation file path (e.g. "geckolib3:animations/mymodel.animation.json")
- */
- public abstract void setItemAnimationFile(IItemCustomizable item, String animation);
-
- /**
- * Set the idle animation name for a customizable item.
- *
- * @param item The item
- * @param animation The animation name from the animation file
- */
- public abstract void setItemIdleAnimation(IItemCustomizable item, String animation);
-
- /**
- * Check if a customizable item has a gecko model assigned.
- *
- * @param item The item to check
- * @return true if the item has a custom gecko model
- */
- public abstract boolean hasItemModel(IItemCustomizable item);
-
- /**
- * Remove the gecko model from a customizable item, reverting to normal 2D rendering.
- *
- * @param item The item to clear the model from
- */
- public abstract void clearItemModel(IItemCustomizable item);
-
- /**
- * Set the display JSON file for a gecko item.
- * The file is loaded from assets/{domain}/item_displays/ folders.
- * This controls how the 3D model is positioned, rotated, and scaled
+ * Get a list of all loaded display file names from item_displays/ resource folders.
+ * Display files control how 3D item models are positioned, rotated, and scaled
* in each render context (first person, third person, inventory, ground).
*
- * Example: {@code GeckoAPI.setDisplayJSON(item, "sword.json")}
- *
- * @param item The item to set the display JSON on
- * @param displayFile The display JSON filename (e.g. "sword.json")
- */
- public abstract void setDisplayJSON(IItemCustomizable item, String displayFile);
-
- /**
- * Get a list of all loaded display file names from item_displays/ folders.
- *
- * @return Array of display file names
+ * @return array of display file names (e.g. "sword.json", "tool.json")
*/
public abstract String[] getDisplayFileList();
-
- /**
- * Set the display transform for a specific render context on a gecko item.
- * This controls how the 3D model is positioned, rotated, and scaled
- * when rendered in that context.
- *
- * If no per-context transform is set, the item's existing rotation/scale/translate
- * properties are used as fallback.
- *
- * @param item The item to set the display transform on
- * @param context The render context: "first_person", "third_person", "inventory", or "ground"
- * @param tx Translation X
- * @param ty Translation Y
- * @param tz Translation Z
- * @param rx Rotation X (degrees)
- * @param ry Rotation Y (degrees)
- * @param rz Rotation Z (degrees)
- * @param sx Scale X
- * @param sy Scale Y
- * @param sz Scale Z
- */
- public abstract void setItemDisplay(IItemCustomizable item, String context,
- float tx, float ty, float tz,
- float rx, float ry, float rz,
- float sx, float sy, float sz);
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/GeckoAPI.java b/src/main/java/com/goodbird/npcgecko/api/GeckoAPI.java
index 10f6120..dd44dc3 100644
--- a/src/main/java/com/goodbird/npcgecko/api/GeckoAPI.java
+++ b/src/main/java/com/goodbird/npcgecko/api/GeckoAPI.java
@@ -1,7 +1,5 @@
package com.goodbird.npcgecko.api;
-import com.goodbird.npcgecko.data.CustomItemModelData;
-import com.goodbird.npcgecko.data.ItemDisplayTransform;
import software.bernie.geckolib3.resource.ItemDisplayLibrary;
import com.goodbird.npcgecko.wrapper.*;
import com.goodbird.npcgecko.mixin.IDataDisplay;
@@ -18,13 +16,17 @@ import noppes.npcs.api.entity.IPlayer;
import noppes.npcs.api.item.IItemCustomizable;
import noppes.npcs.blocks.tiles.TileScripted;
import noppes.npcs.entity.EntityNPCInterface;
-import noppes.npcs.scripted.item.ScriptCustomizableItem;
import software.bernie.geckolib3.core.builder.Animation;
import software.bernie.geckolib3.core.builder.AnimationBuilder;
import software.bernie.geckolib3.core.util.Color;
import software.bernie.geckolib3.file.AnimationFile;
import software.bernie.geckolib3.resource.GeckoLibCache;
+/**
+ * Implementation of {@link AbstractGeckoAPI} that provides the concrete GeckoLib integration.
+ * This class is loaded reflectively when GeckoLib is present and should not be
+ * referenced directly. Use {@link AbstractGeckoAPI#Instance()} to obtain the API.
+ */
public class GeckoAPI extends AbstractGeckoAPI {
private static AbstractGeckoAPI Instance;
@@ -225,89 +227,16 @@ public class GeckoAPI extends AbstractGeckoAPI {
// Item Methods
// ========================================================================
- private CustomItemModelData getOrCreateItemModelData(IItemCustomizable item) {
+ @Override
+ public IGeckoItemModel getItemGecko(IItemCustomizable item) {
if (!(item instanceof IScriptCustomItem)) {
throw new IllegalArgumentException("Item does not support gecko models. Must be a Scripted or Linked item.");
}
- IScriptCustomItem scriptItem = (IScriptCustomItem) item;
- if (!scriptItem.hasCustomModel()) {
- scriptItem.setCustomModelData(new CustomItemModelData());
- }
- return scriptItem.getCustomModelData();
- }
-
- @Override
- public void setItemModel(IItemCustomizable item, String model) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- data.setModel(model);
- ((ScriptCustomizableItem) item).saveItemData();
- }
-
- @Override
- public void setItemTexture(IItemCustomizable item, String texture) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- data.setTexture(texture);
- ((ScriptCustomizableItem) item).saveItemData();
- }
-
- @Override
- public void setItemAnimationFile(IItemCustomizable item, String animation) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- data.setAnimFile(animation);
- ((ScriptCustomizableItem) item).saveItemData();
- }
-
- @Override
- public void setItemIdleAnimation(IItemCustomizable item, String animation) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- data.setIdleAnim(animation);
- ((ScriptCustomizableItem) item).saveItemData();
- }
-
- @Override
- public boolean hasItemModel(IItemCustomizable item) {
- if (!(item instanceof IScriptCustomItem)) {
- return false;
- }
- return ((IScriptCustomItem) item).hasCustomModel();
- }
-
- @Override
- public void clearItemModel(IItemCustomizable item) {
- if (item instanceof IScriptCustomItem) {
- ((IScriptCustomItem) item).setCustomModelData(null);
- ((ScriptCustomizableItem) item).saveItemData();
- }
- }
-
- @Override
- public void setDisplayJSON(IItemCustomizable item, String displayFile) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- data.setDisplayFile(displayFile);
- ((ScriptCustomizableItem) item).saveItemData();
+ return new GeckoItemModelWrapper(item);
}
@Override
public String[] getDisplayFileList() {
return ItemDisplayLibrary.instance.getFileNames();
}
-
- @Override
- public void setItemDisplay(IItemCustomizable item, String context,
- float tx, float ty, float tz,
- float rx, float ry, float rz,
- float sx, float sy, float sz) {
- CustomItemModelData data = getOrCreateItemModelData(item);
- ItemDisplayTransform transform = new ItemDisplayTransform(tx, ty, tz, rx, ry, rz, sx, sy, sz);
- switch (context.toLowerCase()) {
- case "first_person": data.setFirstPerson(transform); break;
- case "third_person": data.setThirdPerson(transform); break;
- case "inventory": data.setInventory(transform); break;
- case "ground": data.setGround(transform); break;
- default:
- throw new IllegalArgumentException("Unknown display context: " + context
- + ". Use: first_person, third_person, inventory, ground");
- }
- ((ScriptCustomizableItem) item).saveItemData();
- }
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimatable.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimatable.java
index 5d6239f..25cc069 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimatable.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimatable.java
@@ -1,151 +1,171 @@
package com.goodbird.npcgecko.api;
/**
- * Interface for accessing and modifying Gecko model configuration on NPCs and scripted blocks.
- * Provides control over model, texture, animation files, and animation names for each state.
+ * Interface for accessing and modifying GeckoLib model configuration on NPCs and scripted blocks.
+ * Provides control over model, texture, animation file, and named animation states.
*
- * Obtain via {@link AbstractGeckoAPI#getAnimatable(noppes.npcs.api.entity.ICustomNpc)}
- * or {@link AbstractGeckoAPI#getAnimatable(noppes.npcs.api.block.IBlockScripted)}.
+ * Changes made through this interface are automatically synced to clients.
+ *
+ * Obtain an instance via {@link AbstractGeckoAPI#getAnimatable}.
+ *
+ * Usage example:
+ *
+ * var animatable = gecko.getAnimatable(npc);
+ * animatable.setModel("geckolib3:geo/custom_npc.geo.json");
+ * animatable.setTexture("geckolib3:textures/model/custom_npc.png");
+ * animatable.setAnimationFile("geckolib3:animations/custom_npc.animation.json");
+ * animatable.setIdleAnimation("animation.custom_npc.idle");
+ *
+ *
+ * @see AbstractGeckoAPI#getAnimatable
*/
public interface IGeckoAnimatable {
/**
* Get the geo model resource location.
*
- * @return The model path (e.g. "geckolib3:geo/npc.geo.json")
+ * @return the model resource location string
*/
String getModel();
/**
- * Set the geo model resource location.
+ * Set the GeckoLib geo model resource location.
*
- * @param model The model path (e.g. "geckolib3:geo/npc.geo.json")
+ * @param model the model resource location (e.g. "geckolib3:geo/npc.geo.json")
*/
void setModel(String model);
/**
* Get the texture resource location.
*
- * @return The texture path
+ * @return the texture resource location string
*/
String getTexture();
/**
* Set the texture resource location.
*
- * @param texture The texture path
+ * @param texture the texture resource location (e.g. "geckolib3:textures/model/npc.png")
*/
void setTexture(String texture);
/**
* Get the animation file resource location.
*
- * @return The animation file path (e.g. "npcgecko:animations/geo_npc.animation.json")
+ * @return the animation file resource location string
*/
String getAnimationFile();
/**
* Set the animation file resource location.
*
- * @param animationFile The animation file path
+ * @param animationFile the animation file resource location
+ * (e.g. "geckolib3:animations/npc.animation.json")
*/
void setAnimationFile(String animationFile);
/**
* Get the idle animation name.
*
- * @return The idle animation name, or empty string if none
+ * @return the idle animation name, or an empty string if none is set
*/
String getIdleAnimation();
/**
* Set the idle animation name.
+ * This animation plays continuously while the entity is standing still.
*
- * @param animation The animation name from the animation file
+ * @param animation the animation name (e.g. "animation.npc.idle")
*/
void setIdleAnimation(String animation);
/**
* Get the walk animation name.
*
- * @return The walk animation name, or empty string if none
+ * @return the walk animation name, or an empty string if none is set
*/
String getWalkAnimation();
/**
* Set the walk animation name.
+ * This animation plays while the entity is moving.
*
- * @param animation The animation name from the animation file
+ * @param animation the animation name (e.g. "animation.npc.walk")
*/
void setWalkAnimation(String animation);
/**
* Get the hurt animation name.
*
- * @return The hurt animation name, or empty string if none
+ * @return the hurt animation name, or an empty string if none is set
*/
String getHurtAnimation();
/**
* Set the hurt animation name.
+ * This animation plays when the entity takes damage.
*
- * @param animation The animation name from the animation file
+ * @param animation the animation name (e.g. "animation.npc.hurt")
*/
void setHurtAnimation(String animation);
/**
* Get the melee attack animation name.
*
- * @return The melee attack animation name, or empty string if none
+ * @return the melee attack animation name, or an empty string if none is set
*/
String getMeleeAttackAnimation();
/**
* Set the melee attack animation name.
+ * This animation plays when the entity performs a melee attack.
*
- * @param animation The animation name from the animation file
+ * @param animation the animation name (e.g. "animation.npc.melee")
*/
void setMeleeAttackAnimation(String animation);
/**
* Get the ranged attack animation name.
*
- * @return The ranged attack animation name, or empty string if none
+ * @return the ranged attack animation name, or an empty string if none is set
*/
String getRangedAttackAnimation();
/**
* Set the ranged attack animation name.
+ * This animation plays when the entity performs a ranged attack.
*
- * @param animation The animation name from the animation file
+ * @param animation the animation name (e.g. "animation.npc.ranged")
*/
void setRangedAttackAnimation(String animation);
/**
- * Get the bone name used for head tracking/rotation.
+ * Get the bone name used for head tracking and rotation.
*
- * @return The head bone name (default: "head")
+ * @return the head bone name (default: "head")
*/
String getHeadBoneName();
/**
- * Set the bone name used for head tracking/rotation.
+ * Set the bone name used for head tracking and rotation.
+ * The bone must exist in the assigned model file.
*
- * @param boneName The bone name in the model
+ * @param boneName the bone name as defined in the model
*/
void setHeadBoneName(String boneName);
/**
* Get the transition duration between animations in ticks.
*
- * @return Transition length in ticks (default: 10)
+ * @return the transition length in ticks (default: 10)
*/
int getTransitionLengthTicks();
/**
* Set the transition duration between animations in ticks.
+ * Controls how smoothly one animation blends into the next.
*
- * @param ticks Transition length in ticks
+ * @param ticks the transition length in ticks (20 ticks = 1 second)
*/
void setTransitionLengthTicks(int ticks);
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimation.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimation.java
index fa1fb67..dd9ce64 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimation.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimation.java
@@ -1,59 +1,62 @@
package com.goodbird.npcgecko.api;
/**
- * Interface for querying animation metadata from a loaded animation file.
- * Provides read-only access to animation properties defined in Blockbench.
+ * Read-only interface for querying animation metadata from a loaded animation file.
+ * Provides access to animation properties as defined in Blockbench.
*
- * Obtain via {@link AbstractGeckoAPI#getAnimation(String, String)}.
+ * Obtain an instance via {@link AbstractGeckoAPI#getAnimation}.
+ *
+ * @see AbstractGeckoAPI#getAnimation
+ * @see AbstractGeckoAPI#getAnimationList
*/
public interface IGeckoAnimation {
/**
* Get the animation name as defined in the animation file.
*
- * @return The animation name
+ * @return the animation name
*/
String getName();
/**
- * Get the duration of this animation in seconds.
+ * Get the total duration of this animation in seconds.
*
- * @return The animation length in seconds
+ * @return the animation length in seconds
*/
double getLength();
/**
- * Whether this animation loops by default.
+ * Check whether this animation loops by default as defined in the animation file.
*
- * @return True if the animation loops
+ * @return true if the animation is set to loop
*/
boolean isLooping();
/**
* Get the names of all bones that have keyframes in this animation.
*
- * @return Array of bone names with animation data
+ * @return array of bone names that are animated
*/
String[] getAnimatedBoneNames();
/**
- * Get the number of sound keyframes in this animation.
+ * Get the number of sound effect keyframes in this animation.
*
- * @return The sound keyframe count
+ * @return the sound keyframe count
*/
int getSoundKeyframeCount();
/**
- * Get the number of particle keyframes in this animation.
+ * Get the number of particle effect keyframes in this animation.
*
- * @return The particle keyframe count
+ * @return the particle keyframe count
*/
int getParticleKeyframeCount();
/**
* Get the number of custom instruction keyframes in this animation.
*
- * @return The custom instruction keyframe count
+ * @return the custom instruction keyframe count
*/
int getCustomInstructionKeyframeCount();
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimationBuilder.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimationBuilder.java
index 69da84d..dd86742 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimationBuilder.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoAnimationBuilder.java
@@ -2,62 +2,69 @@ package com.goodbird.npcgecko.api;
/**
* Builder interface for constructing animation sequences.
- * Follows the builder pattern - all methods return the builder for chaining.
+ * Follows the builder pattern where all methods return this builder for chaining.
*
- * Example usage in scripts:
+ * Create an instance via {@link AbstractGeckoAPI#createAnimationBuilder()}.
+ *
+ * Usage example:
*
- * var builder = GeckoAPI.Instance().createAnimationBuilder();
- * builder.playOnce("attack").loop("idle");
- * GeckoAPI.Instance().syncAnimForAll(npc, builder);
+ * var builder = gecko.createAnimationBuilder();
+ * builder.playOnce("animation.npc.attack").loop("animation.npc.idle");
+ * gecko.syncAnimForAll(npc, builder);
*
+ *
+ * @see AbstractGeckoAPI#createAnimationBuilder()
+ * @see AbstractGeckoAPI#syncAnimForAll
+ * @see AbstractGeckoAPI#syncAnimForPlayer
*/
public interface IGeckoAnimationBuilder {
/**
- * Add an animation that plays once then moves to the next in queue.
+ * Add an animation that plays once, then advances to the next in the queue.
*
- * @param animationName The animation name matching the Blockbench file
- * @return This builder for chaining
+ * @param animationName the animation name as defined in the Blockbench animation file
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder playOnce(String animationName);
/**
- * Add an animation that loops indefinitely until replaced.
+ * Add an animation that loops indefinitely until replaced by another animation.
*
- * @param animationName The animation name matching the Blockbench file
- * @return This builder for chaining
+ * @param animationName the animation name as defined in the Blockbench animation file
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder loop(String animationName);
/**
* Add an animation that plays once and holds on the last frame.
*
- * @param animationName The animation name matching the Blockbench file
- * @return This builder for chaining
+ * @param animationName the animation name as defined in the Blockbench animation file
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder playAndHold(String animationName);
/**
- * Add an animation to the queue with default loop behavior from the animation file.
+ * Add an animation to the queue using the default loop behavior
+ * defined in the animation file.
*
- * @param animationName The animation name matching the Blockbench file
- * @return This builder for chaining
+ * @param animationName the animation name as defined in the Blockbench animation file
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder addAnimation(String animationName);
/**
- * Add an animation to the queue repeated multiple times.
+ * Add an animation to the queue that repeats a specified number of times.
*
- * @param animationName The animation name matching the Blockbench file
- * @param timesToRepeat How many times to repeat the animation
- * @return This builder for chaining
+ * @param animationName the animation name as defined in the Blockbench animation file
+ * @param timesToRepeat how many times to repeat the animation
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder addRepeatingAnimation(String animationName, int timesToRepeat);
/**
- * Clear all animations currently in the builder.
+ * Clear all animations currently queued in this builder.
*
- * @return This builder for chaining
+ * @return this builder for chaining
*/
IGeckoAnimationBuilder clearAnimations();
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoBone.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoBone.java
index b88102f..bb6b2b1 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoBone.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoBone.java
@@ -1,188 +1,218 @@
package com.goodbird.npcgecko.api;
/**
- * Interface for querying and modifying bone transforms on a Gecko model at runtime.
- * Bones represent individual parts of a model (e.g. "head", "left_arm", "held_item").
+ * Interface for querying and modifying bone transforms on a GeckoLib model at runtime.
+ * Bones represent individual parts of a model (e.g. "head", "left_arm", "body").
*
* Position values are relative offsets from the bone's rest position.
- * Rotation values are in radians. Scale values are multipliers (1.0 = default).
+ * Rotation values are in radians.
+ * Scale values are multipliers where 1.0 is the default size.
+ *
+ * @see IGeckoModel#getBone
*/
public interface IGeckoBone {
/**
* Get the name of this bone as defined in the model file.
*
- * @return The bone name
+ * @return the bone name
*/
String getName();
/**
- * @return The X position offset
+ * Get the X position offset from the bone's rest position.
+ *
+ * @return the X position offset
*/
float getPositionX();
/**
- * @return The Y position offset
+ * Get the Y position offset from the bone's rest position.
+ *
+ * @return the Y position offset
*/
float getPositionY();
/**
- * @return The Z position offset
+ * Get the Z position offset from the bone's rest position.
+ *
+ * @return the Z position offset
*/
float getPositionZ();
/**
- * Set the X position offset.
+ * Set the X position offset from the bone's rest position.
*
- * @param value The X position offset
+ * @param value the X position offset
*/
void setPositionX(float value);
/**
- * Set the Y position offset.
+ * Set the Y position offset from the bone's rest position.
*
- * @param value The Y position offset
+ * @param value the Y position offset
*/
void setPositionY(float value);
/**
- * Set the Z position offset.
+ * Set the Z position offset from the bone's rest position.
*
- * @param value The Z position offset
+ * @param value the Z position offset
*/
void setPositionZ(float value);
/**
- * @return The X rotation in radians
+ * Get the X rotation in radians.
+ *
+ * @return the X rotation in radians
*/
float getRotationX();
/**
- * @return The Y rotation in radians
+ * Get the Y rotation in radians.
+ *
+ * @return the Y rotation in radians
*/
float getRotationY();
/**
- * @return The Z rotation in radians
+ * Get the Z rotation in radians.
+ *
+ * @return the Z rotation in radians
*/
float getRotationZ();
/**
* Set the X rotation in radians.
*
- * @param value The X rotation in radians
+ * @param value the X rotation in radians
*/
void setRotationX(float value);
/**
* Set the Y rotation in radians.
*
- * @param value The Y rotation in radians
+ * @param value the Y rotation in radians
*/
void setRotationY(float value);
/**
* Set the Z rotation in radians.
*
- * @param value The Z rotation in radians
+ * @param value the Z rotation in radians
*/
void setRotationZ(float value);
/**
- * @return The X scale multiplier
+ * Get the X scale multiplier.
+ *
+ * @return the X scale multiplier (1.0 = default size)
*/
float getScaleX();
/**
- * @return The Y scale multiplier
+ * Get the Y scale multiplier.
+ *
+ * @return the Y scale multiplier (1.0 = default size)
*/
float getScaleY();
/**
- * @return The Z scale multiplier
+ * Get the Z scale multiplier.
+ *
+ * @return the Z scale multiplier (1.0 = default size)
*/
float getScaleZ();
/**
* Set the X scale multiplier.
*
- * @param value The X scale multiplier (1.0 = default)
+ * @param value the X scale multiplier (1.0 = default size)
*/
void setScaleX(float value);
/**
* Set the Y scale multiplier.
*
- * @param value The Y scale multiplier (1.0 = default)
+ * @param value the Y scale multiplier (1.0 = default size)
*/
void setScaleY(float value);
/**
* Set the Z scale multiplier.
*
- * @param value The Z scale multiplier (1.0 = default)
+ * @param value the Z scale multiplier (1.0 = default size)
*/
void setScaleZ(float value);
/**
- * @return The X pivot point
+ * Get the X pivot point of this bone.
+ *
+ * @return the X pivot point
*/
float getPivotX();
/**
- * @return The Y pivot point
+ * Get the Y pivot point of this bone.
+ *
+ * @return the Y pivot point
*/
float getPivotY();
/**
- * @return The Z pivot point
+ * Get the Z pivot point of this bone.
+ *
+ * @return the Z pivot point
*/
float getPivotZ();
/**
- * Set the X pivot point.
+ * Set the X pivot point of this bone.
*
- * @param value The X pivot point
+ * @param value the X pivot point
*/
void setPivotX(float value);
/**
- * Set the Y pivot point.
+ * Set the Y pivot point of this bone.
*
- * @param value The Y pivot point
+ * @param value the Y pivot point
*/
void setPivotY(float value);
/**
- * Set the Z pivot point.
+ * Set the Z pivot point of this bone.
*
- * @param value The Z pivot point
+ * @param value the Z pivot point
*/
void setPivotZ(float value);
/**
- * @return Whether this bone is hidden from rendering
+ * Check whether this bone is hidden from rendering.
+ *
+ * @return true if this bone is currently hidden
*/
boolean isHidden();
/**
* Set whether this bone is hidden from rendering.
+ * Hidden bones and their children are not drawn.
*
- * @param hidden True to hide this bone
+ * @param hidden true to hide this bone, false to show it
*/
void setHidden(boolean hidden);
/**
- * Get the parent bone, or null if this is a root bone.
+ * Get the parent bone in the bone hierarchy.
*
- * @return The parent bone, or null
+ * @return the parent bone, or null if this is a root bone
*/
IGeckoBone getParent();
/**
- * Get the child bones of this bone.
+ * Get the direct child bones of this bone.
*
- * @return Array of child bones
+ * @return array of child bones, or an empty array if this bone has no children
*/
IGeckoBone[] getChildBones();
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoColor.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoColor.java
index 63b52fc..e9f4dbc 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoColor.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoColor.java
@@ -1,57 +1,67 @@
package com.goodbird.npcgecko.api;
/**
- * Interface for color manipulation. Provides access to RGBA color components
- * and common color operations.
+ * Interface for color manipulation with RGBA components.
*
* Create colors using the factory methods on {@link AbstractGeckoAPI}:
*
- * var color = GeckoAPI.Instance().colorOfRGB(255, 0, 0); // Red
- * var alpha = GeckoAPI.Instance().colorOfRGBA(255, 0, 0, 128); // Semi-transparent red
+ * var red = gecko.colorOfRGB(255, 0, 0);
+ * var semiTransparent = gecko.colorOfRGBA(255, 0, 0, 128);
*
+ *
+ * @see AbstractGeckoAPI#colorOfRGB
+ * @see AbstractGeckoAPI#colorOfRGBA
*/
public interface IGeckoColor {
/**
- * Get the packed ARGB color value.
+ * Get the packed ARGB color value as a single integer.
*
- * @return The packed color as an integer
+ * @return the packed ARGB color integer
*/
int getColor();
/**
- * @return The red component (0-255)
+ * Get the red component.
+ *
+ * @return the red component (0-255)
*/
int getRed();
/**
- * @return The green component (0-255)
+ * Get the green component.
+ *
+ * @return the green component (0-255)
*/
int getGreen();
/**
- * @return The blue component (0-255)
+ * Get the blue component.
+ *
+ * @return the blue component (0-255)
*/
int getBlue();
/**
- * @return The alpha component (0-255)
+ * Get the alpha (transparency) component.
+ *
+ * @return the alpha component (0-255, where 255 is fully opaque)
*/
int getAlpha();
/**
* Create a brighter version of this color.
*
- * @param factor How much brighter (0.0 = no change, 1.0 = white)
- * @return A new brighter color
+ * @param factor brightness factor (0.0 = no change, 1.0 = white)
+ * @return a new brighter color
*/
IGeckoColor brighter(double factor);
/**
* Create a darker version of this color.
*
- * @param factor How much darker (0.0 = no change, 1.0 = black)
- * @return A new darker color
+ * @param factor darkness factor (0.0 = no change, 1.0 = black)
+ * @return a new darker color
*/
IGeckoColor darker(double factor);
}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoItemModel.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoItemModel.java
new file mode 100644
index 0000000..90813bb
--- /dev/null
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoItemModel.java
@@ -0,0 +1,164 @@
+package com.goodbird.npcgecko.api;
+
+/**
+ * Interface for accessing and modifying GeckoLib 3D model configuration on items.
+ * Provides control over model, texture, animation files, display transforms,
+ * and display JSON settings for Scripted and Linked items.
+ *
+ * Changes made through this interface are automatically persisted to the
+ * ItemStack's NBT and synced to clients via container mechanics.
+ *
+ * Obtain an instance via {@link AbstractGeckoAPI#getItemGecko}.
+ *
+ * Usage example:
+ *
+ * var itemGecko = gecko.getItemGecko(event.item);
+ * itemGecko.setModel("geckolib3:geo/sword.geo.json");
+ * itemGecko.setTexture("geckolib3:textures/model/sword.png");
+ * itemGecko.setAnimationFile("geckolib3:animations/sword.animation.json");
+ * itemGecko.setIdleAnimation("animation.sword.idle");
+ *
+ *
+ * @see AbstractGeckoAPI#getItemGecko
+ */
+public interface IGeckoItemModel {
+
+ /**
+ * Check if this item currently has a gecko model assigned.
+ *
+ * @return true if the item has a GeckoLib 3D model
+ */
+ boolean hasModel();
+
+ /**
+ * Get the geo model resource location.
+ *
+ * @return the model resource location string, or an empty string if no model is set
+ */
+ String getModel();
+
+ /**
+ * Set the GeckoLib geo model resource location.
+ * The model file should be a Blockbench geo JSON exported for GeckoLib.
+ *
+ * @param model the model resource location (e.g. "geckolib3:geo/sword.geo.json")
+ */
+ void setModel(String model);
+
+ /**
+ * Get the texture resource location.
+ *
+ * @return the texture resource location string, or an empty string if no texture is set
+ */
+ String getTexture();
+
+ /**
+ * Set the texture resource location used when rendering this item's 3D model.
+ *
+ * @param texture the texture resource location (e.g. "geckolib3:textures/model/sword.png")
+ */
+ void setTexture(String texture);
+
+ /**
+ * Get the animation file resource location.
+ *
+ * @return the animation file resource location string, or an empty string if none is set
+ */
+ String getAnimationFile();
+
+ /**
+ * Set the animation file resource location.
+ * The file should be a Blockbench animation JSON exported for GeckoLib.
+ *
+ * @param animationFile the animation file resource location
+ * (e.g. "geckolib3:animations/sword.animation.json")
+ */
+ void setAnimationFile(String animationFile);
+
+ /**
+ * Get the idle animation name.
+ *
+ * @return the idle animation name, or an empty string if none is set
+ */
+ String getIdleAnimation();
+
+ /**
+ * Set the idle animation name.
+ * This animation plays continuously while the item is not performing other actions.
+ * The animation must be defined in the currently assigned animation file.
+ *
+ * @param animation the animation name (e.g. "animation.sword.idle")
+ */
+ void setIdleAnimation(String animation);
+
+ /**
+ * Get the transition duration between animations in ticks.
+ *
+ * @return the transition length in ticks (default: 10)
+ */
+ int getTransitionLengthTicks();
+
+ /**
+ * Set the transition duration between animations in ticks.
+ * Controls how smoothly one animation blends into the next.
+ *
+ * @param ticks the transition length in ticks (20 ticks = 1 second)
+ */
+ void setTransitionLengthTicks(int ticks);
+
+ /**
+ * Get the display JSON filename currently assigned to this item.
+ *
+ * @return the display JSON filename (e.g. "sword.json"), or an empty string if none is set
+ */
+ String getDisplayJSON();
+
+ /**
+ * Set the display JSON file for controlling how the 3D model is positioned,
+ * rotated, and scaled in each render context (first person, third person,
+ * inventory, and ground).
+ *
+ * Display files are loaded from {@code assets/{domain}/item_displays/} resource folders.
+ * Use {@link AbstractGeckoAPI#getDisplayFileList()} to list available files.
+ *
+ * @param displayFile the display JSON filename (e.g. "sword.json")
+ * @see AbstractGeckoAPI#getDisplayFileList()
+ */
+ void setDisplayJSON(String displayFile);
+
+ /**
+ * Set the display transform for a specific render context.
+ * This overrides any display JSON settings for the specified context and
+ * controls how the 3D model is positioned, rotated, and scaled.
+ *
+ * Valid context values:
+ *
+ * - {@code "first_person"} - held item in first-person view
+ * - {@code "third_person"} - held item in third-person view
+ * - {@code "inventory"} - item icon in inventory GUI
+ * - {@code "ground"} - dropped item entity on the ground
+ *
+ *
+ * @param context the render context name
+ * @param tx translation X offset
+ * @param ty translation Y offset
+ * @param tz translation Z offset
+ * @param rx rotation X in degrees
+ * @param ry rotation Y in degrees
+ * @param rz rotation Z in degrees
+ * @param sx scale X multiplier
+ * @param sy scale Y multiplier
+ * @param sz scale Z multiplier
+ * @throws IllegalArgumentException if the context name is not recognized
+ */
+ void setDisplay(String context,
+ float tx, float ty, float tz,
+ float rx, float ry, float rz,
+ float sx, float sy, float sz);
+
+ /**
+ * Remove the gecko model from this item, reverting it to normal 2D rendering.
+ * Clears all model, texture, animation, and display settings.
+ */
+ void clear();
+}
diff --git a/src/main/java/com/goodbird/npcgecko/api/IGeckoModel.java b/src/main/java/com/goodbird/npcgecko/api/IGeckoModel.java
index 5640dfb..bd68994 100644
--- a/src/main/java/com/goodbird/npcgecko/api/IGeckoModel.java
+++ b/src/main/java/com/goodbird/npcgecko/api/IGeckoModel.java
@@ -1,27 +1,28 @@
package com.goodbird.npcgecko.api;
/**
- * Read-only interface for querying the runtime state of a Gecko model.
- * Allows scripts to inspect model bones and their current transforms.
+ * Read-only interface for querying the runtime state of a GeckoLib model.
+ * Provides access to the model's bone hierarchy after animations have been applied.
*
- * This interface provides access to the model's bone hierarchy after
- * animations have been applied, useful for attaching effects or
- * querying positions of specific model parts.
+ * Useful for inspecting bone transforms, attaching effects to specific
+ * model parts, or querying positions of bones at runtime.
+ *
+ * @see IGeckoBone
*/
public interface IGeckoModel {
/**
- * Get a bone by name.
+ * Get a bone by its name as defined in the model file.
*
- * @param name The bone name as defined in the model file
- * @return The bone, or null if not found
+ * @param name the bone name
+ * @return the bone interface, or null if no bone with that name exists
*/
IGeckoBone getBone(String name);
/**
* Get the names of all bones in this model.
*
- * @return Array of bone names
+ * @return array of all bone names
*/
String[] getBoneNames();
}
diff --git a/src/main/java/com/goodbird/npcgecko/client/ModelItemRenderUtil.java b/src/main/java/com/goodbird/npcgecko/client/ModelItemRenderUtil.java
index 4e94bb5..734ff79 100644
--- a/src/main/java/com/goodbird/npcgecko/client/ModelItemRenderUtil.java
+++ b/src/main/java/com/goodbird/npcgecko/client/ModelItemRenderUtil.java
@@ -4,31 +4,28 @@ import com.goodbird.npcgecko.client.model.ItemModelCustom;
import com.goodbird.npcgecko.data.CustomItemModelData;
import com.goodbird.npcgecko.data.ItemDisplayData;
import com.goodbird.npcgecko.data.ItemDisplayTransform;
-import com.goodbird.npcgecko.mixin.IScriptCustomItem;
import net.minecraft.client.renderer.RenderHelper;
import net.minecraft.item.ItemStack;
+import net.minecraft.nbt.NBTTagCompound;
import net.minecraftforge.client.IItemRenderer.ItemRenderType;
-import noppes.npcs.api.item.IItemCustomizable;
-import noppes.npcs.api.item.IItemStack;
-import noppes.npcs.scripted.NpcAPI;
import org.lwjgl.opengl.GL11;
-import scala.tools.nsc.doc.base.comment.Inline;
import software.bernie.geckolib3.item.AnimatableStackWrapper;
import software.bernie.geckolib3.renderers.geo.GeoItemStackRenderer;
+import java.util.WeakHashMap;
+
public class ModelItemRenderUtil {
private static final GeoItemStackRenderer RENDERER = new GeoItemStackRenderer(new ItemModelCustom());
+ private static final WeakHashMap modelDataCache = new WeakHashMap<>();
/**
* Quick check if an ItemStack has a gecko model attached.
- * Used by the shouldUseRenderHelper mixin to route gecko items
- * through the EQUIPPED_BLOCK path in ForgeHooksClient.
+ * Reads directly from the ItemStack's root NBT tag (top-level "GeckoModelData")
+ * to avoid NpcAPI cache dependencies that cause flickering when items are moved.
*/
public static boolean hasGeckoModel(ItemStack itemStack) {
- IItemStack iItemStack = NpcAPI.Instance().getIItemStack(itemStack);
- if (!(iItemStack instanceof IItemCustomizable)) return false;
- if (!(iItemStack instanceof IScriptCustomItem)) return false;
- return ((IScriptCustomItem) iItemStack).hasCustomModel();
+ if (itemStack == null || !itemStack.hasTagCompound()) return false;
+ return itemStack.getTagCompound().hasKey("GeckoModelData");
}
/**
@@ -52,19 +49,23 @@ public class ModelItemRenderUtil {
/**
* Attempts to render a gecko model for the given item.
- * Returns true if rendering was handled, false if the item has no gecko model.
+ * Reads model data directly from the ItemStack's NBT to avoid NpcAPI cache
+ * dependencies that cause flickering when items are moved in inventory.
*/
public static boolean tryRender(ItemRenderType type, ItemStack itemStack) {
- IItemStack iItemStack = NpcAPI.Instance().getIItemStack(itemStack);
- if (!(iItemStack instanceof IItemCustomizable)) return false;
- IItemCustomizable scriptCustomItem = (IItemCustomizable) iItemStack;
- if (!(scriptCustomItem instanceof IScriptCustomItem)) return false;
- IScriptCustomItem geckoItem = (IScriptCustomItem) scriptCustomItem;
- if (!geckoItem.hasCustomModel()) return false;
+ if (itemStack == null || !itemStack.hasTagCompound()) return false;
+ NBTTagCompound root = itemStack.getTagCompound();
+ if (!root.hasKey("GeckoModelData")) return false;
+
+ CustomItemModelData modelData = modelDataCache.get(itemStack);
+ if (modelData == null) {
+ modelData = new CustomItemModelData();
+ modelData.readFromNBT(root.getCompoundTag("GeckoModelData"));
+ modelDataCache.put(itemStack, modelData);
+ }
- CustomItemModelData modelData = geckoItem.getCustomModelData();
AnimatableStackWrapper wrapper = AnimatableStackWrapper.of(itemStack).withUserData(modelData);
- ItemDisplayTransform transform = resolveTransform(modelData, scriptCustomItem, type);
+ ItemDisplayTransform transform = resolveTransform(modelData, type);
GL11.glPushMatrix();
@@ -183,7 +184,7 @@ public class ModelItemRenderUtil {
* 3) null — let the apply methods use their inline defaults
*/
public static ItemDisplayTransform resolveTransform(
- CustomItemModelData modelData, IItemCustomizable item, ItemRenderType type) {
+ CustomItemModelData modelData, ItemRenderType type) {
// 1) Per-item NBT override
ItemDisplayTransform nbtTransform = null;
diff --git a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptCustomItem.java b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptCustomItem.java
index e9e8765..9a2e513 100644
--- a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptCustomItem.java
+++ b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptCustomItem.java
@@ -2,8 +2,10 @@ package com.goodbird.npcgecko.mixin.impl;
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.scripted.item.ScriptCustomItem;
+import noppes.npcs.scripted.item.ScriptItemStack;
import org.spongepowered.asm.mixin.Mixin;
import org.spongepowered.asm.mixin.Unique;
import org.spongepowered.asm.mixin.injection.At;
@@ -22,19 +24,42 @@ public class MixinScriptCustomItem implements IScriptCustomItem {
NBTTagCompound modelDataTag = new NBTTagCompound();
customNPC_Gecko_Addon$customModelData.writeToNBT(modelDataTag);
compound.setTag("GeckoModelData", modelDataTag);
+ // Also persist to top-level key on the ItemStack for direct NBT reads
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null) {
+ NBTTagCompound root = stack.getTagCompound();
+ if (root == null) {
+ root = new NBTTagCompound();
+ stack.setTagCompound(root);
+ }
+ NBTTagCompound topLevelTag = new NBTTagCompound();
+ customNPC_Gecko_Addon$customModelData.writeToNBT(topLevelTag);
+ root.setTag("GeckoModelData", topLevelTag);
+ }
}
}
@Inject(method = "setItemNBT", at = @At("RETURN"), remap = false)
public void readGeckoData(NBTTagCompound compound, CallbackInfo ci) {
+ // Try reading from the ItemData sub-compound (legacy path)
if (compound.hasKey("GeckoModelData")) {
customNPC_Gecko_Addon$customModelData = new CustomItemModelData();
customNPC_Gecko_Addon$customModelData.readFromNBT(compound.getCompoundTag("GeckoModelData"));
+ return;
+ }
+ // Also try the top-level key on the ItemStack (primary path)
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null && stack.hasTagCompound() && stack.getTagCompound().hasKey("GeckoModelData")) {
+ customNPC_Gecko_Addon$customModelData = new CustomItemModelData();
+ customNPC_Gecko_Addon$customModelData.readFromNBT(stack.getTagCompound().getCompoundTag("GeckoModelData"));
}
}
@Unique
public CustomItemModelData getCustomModelData() {
+ if (customNPC_Gecko_Addon$customModelData != null) return customNPC_Gecko_Addon$customModelData;
+ // Fallback: load from ItemStack NBT when wrapper was recreated by cache miss
+ customNPC_Gecko_Addon$customModelData = customNPC_Gecko_Addon$loadFromNBT();
return customNPC_Gecko_Addon$customModelData;
}
@@ -45,6 +70,21 @@ public class MixinScriptCustomItem implements IScriptCustomItem {
@Unique
public boolean hasCustomModel() {
- return customNPC_Gecko_Addon$customModelData != null;
+ return getCustomModelData() != null;
+ }
+
+ @Unique
+ private CustomItemModelData customNPC_Gecko_Addon$loadFromNBT() {
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null && stack.hasTagCompound()) {
+ NBTTagCompound root = stack.getTagCompound();
+ // Primary: top-level key (written by GeckoAPI.persistGeckoData)
+ if (root.hasKey("GeckoModelData")) {
+ CustomItemModelData data = new CustomItemModelData();
+ data.readFromNBT(root.getCompoundTag("GeckoModelData"));
+ return data;
+ }
+ }
+ return null;
}
}
diff --git a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptLinkedItem.java b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptLinkedItem.java
index 5aa3b68..9402a50 100644
--- a/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptLinkedItem.java
+++ b/src/main/java/com/goodbird/npcgecko/mixin/impl/MixinScriptLinkedItem.java
@@ -2,7 +2,9 @@ package com.goodbird.npcgecko.mixin.impl;
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.scripted.item.ScriptItemStack;
import noppes.npcs.scripted.item.ScriptLinkedItem;
import org.spongepowered.asm.mixin.Mixin;
import org.spongepowered.asm.mixin.Unique;
@@ -22,19 +24,42 @@ public class MixinScriptLinkedItem implements IScriptCustomItem {
NBTTagCompound modelDataTag = new NBTTagCompound();
customNPC_Gecko_Addon$customModelData.writeToNBT(modelDataTag);
compound.setTag("GeckoModelData", modelDataTag);
+ // Also persist to top-level key on the ItemStack for direct NBT reads
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null) {
+ NBTTagCompound root = stack.getTagCompound();
+ if (root == null) {
+ root = new NBTTagCompound();
+ stack.setTagCompound(root);
+ }
+ NBTTagCompound topLevelTag = new NBTTagCompound();
+ customNPC_Gecko_Addon$customModelData.writeToNBT(topLevelTag);
+ root.setTag("GeckoModelData", topLevelTag);
+ }
}
}
@Inject(method = "setItemNBT", at = @At("RETURN"), remap = false)
public void readGeckoData(NBTTagCompound compound, CallbackInfo ci) {
+ // Try reading from the ItemData sub-compound (legacy path)
if (compound.hasKey("GeckoModelData")) {
customNPC_Gecko_Addon$customModelData = new CustomItemModelData();
customNPC_Gecko_Addon$customModelData.readFromNBT(compound.getCompoundTag("GeckoModelData"));
+ return;
+ }
+ // Also try the top-level key on the ItemStack (primary path)
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null && stack.hasTagCompound() && stack.getTagCompound().hasKey("GeckoModelData")) {
+ customNPC_Gecko_Addon$customModelData = new CustomItemModelData();
+ customNPC_Gecko_Addon$customModelData.readFromNBT(stack.getTagCompound().getCompoundTag("GeckoModelData"));
}
}
@Unique
public CustomItemModelData getCustomModelData() {
+ if (customNPC_Gecko_Addon$customModelData != null) return customNPC_Gecko_Addon$customModelData;
+ // Fallback: load from ItemStack NBT when wrapper was recreated by cache miss
+ customNPC_Gecko_Addon$customModelData = customNPC_Gecko_Addon$loadFromNBT();
return customNPC_Gecko_Addon$customModelData;
}
@@ -45,6 +70,21 @@ public class MixinScriptLinkedItem implements IScriptCustomItem {
@Unique
public boolean hasCustomModel() {
- return customNPC_Gecko_Addon$customModelData != null;
+ return getCustomModelData() != null;
+ }
+
+ @Unique
+ private CustomItemModelData customNPC_Gecko_Addon$loadFromNBT() {
+ ItemStack stack = ((ScriptItemStack) (Object) this).getMCItemStack();
+ if (stack != null && stack.hasTagCompound()) {
+ NBTTagCompound root = stack.getTagCompound();
+ // Primary: top-level key (written by GeckoAPI.persistGeckoData)
+ if (root.hasKey("GeckoModelData")) {
+ CustomItemModelData data = new CustomItemModelData();
+ data.readFromNBT(root.getCompoundTag("GeckoModelData"));
+ return data;
+ }
+ }
+ return null;
}
}
diff --git a/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java b/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
new file mode 100644
index 0000000..65712b7
--- /dev/null
+++ b/src/main/java/com/goodbird/npcgecko/wrapper/GeckoItemModelWrapper.java
@@ -0,0 +1,157 @@
+package com.goodbird.npcgecko.wrapper;
+
+import com.goodbird.npcgecko.api.IGeckoItemModel;
+import com.goodbird.npcgecko.data.CustomItemModelData;
+import com.goodbird.npcgecko.data.ItemDisplayTransform;
+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;
+
+/**
+ * Implementation of {@link IGeckoItemModel} that wraps a customizable item's gecko model data.
+ * Handles persistence to both the in-memory wrapper field and the ItemStack's top-level NBT.
+ */
+public class GeckoItemModelWrapper implements IGeckoItemModel {
+ private final IItemCustomizable item;
+ private final IScriptCustomItem scriptItem;
+
+ public GeckoItemModelWrapper(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();
+ persistToNBT();
+ }
+
+ private void persistToNBT() {
+ 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);
+ }
+ }
+
+ @Override
+ public boolean hasModel() {
+ return scriptItem.hasCustomModel();
+ }
+
+ @Override
+ public String getModel() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getModel() : "";
+ }
+
+ @Override
+ public void setModel(String model) {
+ getOrCreateData().setModel(model);
+ persist();
+ }
+
+ @Override
+ public String getTexture() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getTexture() : "";
+ }
+
+ @Override
+ public void setTexture(String texture) {
+ getOrCreateData().setTexture(texture);
+ persist();
+ }
+
+ @Override
+ public String getAnimationFile() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getAnimFile() : "";
+ }
+
+ @Override
+ public void setAnimationFile(String animationFile) {
+ getOrCreateData().setAnimFile(animationFile);
+ persist();
+ }
+
+ @Override
+ public String getIdleAnimation() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getIdleAnim() : "";
+ }
+
+ @Override
+ public void setIdleAnimation(String animation) {
+ getOrCreateData().setIdleAnim(animation);
+ persist();
+ }
+
+ @Override
+ public int getTransitionLengthTicks() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getTransitionLengthTicks() : 10;
+ }
+
+ @Override
+ public void setTransitionLengthTicks(int ticks) {
+ getOrCreateData().setTransitionLengthTicks(ticks);
+ persist();
+ }
+
+ @Override
+ public String getDisplayJSON() {
+ CustomItemModelData data = scriptItem.getCustomModelData();
+ return data != null ? data.getDisplayFile() : "";
+ }
+
+ @Override
+ public void setDisplayJSON(String displayFile) {
+ getOrCreateData().setDisplayFile(displayFile);
+ persist();
+ }
+
+ @Override
+ public void setDisplay(String context,
+ float tx, float ty, float tz,
+ float rx, float ry, float rz,
+ float sx, float sy, float sz) {
+ CustomItemModelData data = getOrCreateData();
+ ItemDisplayTransform transform = new ItemDisplayTransform(tx, ty, tz, rx, ry, rz, sx, sy, sz);
+ switch (context.toLowerCase()) {
+ case "first_person": data.setFirstPerson(transform); break;
+ case "third_person": data.setThirdPerson(transform); break;
+ case "inventory": data.setInventory(transform); break;
+ case "ground": data.setGround(transform); break;
+ default:
+ throw new IllegalArgumentException("Unknown display context: " + context
+ + ". Use: first_person, third_person, inventory, ground");
+ }
+ persist();
+ }
+
+ @Override
+ public void clear() {
+ scriptItem.setCustomModelData(null);
+ ItemStack stack = ((ScriptCustomizableItem) item).getMCItemStack();
+ if (stack != null && stack.hasTagCompound()) {
+ stack.getTagCompound().removeTag("GeckoModelData");
+ }
+ ((ScriptCustomizableItem) item).saveItemData();
+ }
+}