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(ICustomNpcUsage 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:
+ *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