package com.goodbird.npcgecko.api; import cpw.mods.fml.common.Loader; import net.minecraft.entity.player.EntityPlayerMP; import noppes.npcs.api.block.IBlockScripted; import noppes.npcs.api.entity.ICustomNpc; 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; } else if (!IsAvailable()) { return null; } else { try { Class c = Class.forName("com.goodbird.npcgecko.api.GeckoAPI"); instance = (AbstractGeckoAPI) c.getMethod("Instance").invoke(null); } catch (Exception ignored) { } return instance; } } // ======================================================================== // Animation Builder // ======================================================================== /** * Create a new animation builder for constructing animation sequences. * Alias for {@link #createAnimationBuilder()}. * * @return a new animation builder instance */ public abstract IGeckoAnimationBuilder createAnimBuilder(); /** * Create a new animation builder for constructing animation sequences. * *

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(); // ======================================================================== // Animatable Access // ======================================================================== /** * 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 configure * @return the animatable interface for this NPC * @see IGeckoAnimatable */ public abstract IGeckoAnimatable getAnimatable(ICustomNpc npc); /** * 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 scripted block to configure * @return the animatable interface for this block * @see IGeckoAnimatable */ public abstract IGeckoAnimatable getAnimatable(IBlockScripted scriptedBlock); // ======================================================================== // Animation Queries // ======================================================================== /** * Get a list of all animation names defined in an animation file. * * @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 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 * @see IGeckoAnimation */ public abstract IGeckoAnimation getAnimation(String animationFile, String animationName); // ======================================================================== // Color Utilities // ======================================================================== /** * 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 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, where 255 is fully opaque) * @return a new color instance * @see IGeckoColor */ public abstract IGeckoColor colorOfRGBA(int r, int g, int b, int a); // ======================================================================== // NPC Methods // ======================================================================== /** * Set the GeckoLib geo model resource location for an NPC. * * @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 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 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 (e.g. "animation.npc.idle") */ public abstract void setIdleAnimation(ICustomNpc npc, String animation); /** * 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 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 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 containing the queued animation sequence */ public abstract void syncAnimForAll(ICustomNpc npc, IGeckoAnimationBuilder builder); // ======================================================================== // Block Methods // ======================================================================== /** * Set the GeckoLib geo model resource location for a scripted block. * * @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 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 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 scripted block * @param animation the animation name (e.g. "animation.block.idle") */ public abstract void setIdleAnimation(IBlockScripted scriptedBlock, String animation); /** * Sync a queued animation sequence to a specific player for a scripted block. * Only the specified player will see the animation. * * @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 a queued animation sequence to all connected players for a scripted block. * * @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); // ======================================================================== // Item Methods // ======================================================================== /** * 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. * *

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 IGeckoItemModel getItemGecko(IItemCustomizable item); /** * 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). * * @return array of display file names (e.g. "sword.json", "tool.json") */ public abstract String[] getDisplayFileList(); }