From 319e77451862a113b156c988a1234b2acbadfb2b Mon Sep 17 00:00:00 2001 From: Kam Date: Mon, 9 Mar 2026 16:20:07 -0400 Subject: [PATCH] A lot of GOOD API DOCUMENTATION --- java/net/minecraft/util/Vec3i.java | 8 + java/net/minecraft/util/math/BlockPos.java | 74 +++++- java/net/minecraft/util/math/IntHashMap.java | 35 ++- java/noppes/npcs/api/AbstractNpcAPI.java | 13 + java/noppes/npcs/api/ICommand.java | 44 +++ java/noppes/npcs/api/IEnergyController.java | 63 ++++- java/noppes/npcs/api/INbt.java | 7 + java/noppes/npcs/api/IPixelmonPlayerData.java | 12 + java/noppes/npcs/api/IPos.java | 11 + java/noppes/npcs/api/IScreenSize.java | 21 ++ java/noppes/npcs/api/ISkinOverlay.java | 12 + java/noppes/npcs/api/ITelegraph.java | 50 +++- java/noppes/npcs/api/ITelegraphInstance.java | 30 ++- java/noppes/npcs/api/ITileEntity.java | 5 + java/noppes/npcs/api/ITimers.java | 11 + java/noppes/npcs/api/IWorld.java | 54 +++- java/noppes/npcs/api/ability/IAbility.java | 20 ++ .../npcs/api/ability/IAbilityHandler.java | 8 + .../npcs/api/ability/ICustomAbility.java | 16 ++ .../npcs/api/ability/IDataAbilities.java | 32 +++ .../npcs/api/ability/IPlayerAbilityData.java | 37 ++- .../api/ability/data/IEnergyAnchorData.java | 7 +- .../noppes/npcs/api/block/IBlockScripted.java | 2 + java/noppes/npcs/api/block/ITextPlane.java | 65 ++++- java/noppes/npcs/api/entity/IArrow.java | 11 + .../npcs/api/entity/IEnergyBarrier.java | 1 + java/noppes/npcs/api/entity/IEnergyBeam.java | 5 +- java/noppes/npcs/api/entity/IEnergyDisc.java | 5 +- java/noppes/npcs/api/entity/IEnergyDome.java | 2 + .../npcs/api/entity/IEnergyExplosion.java | 6 +- java/noppes/npcs/api/entity/IEnergyLaser.java | 5 +- java/noppes/npcs/api/entity/IEnergyPanel.java | 1 + .../npcs/api/entity/IEnergyProjectile.java | 15 +- .../noppes/npcs/api/entity/IEnergySlicer.java | 5 +- .../npcs/api/entity/IEnergySweeper.java | 18 ++ java/noppes/npcs/api/entity/IEnergyZone.java | 10 +- .../npcs/api/entity/IEntityLivingBase.java | 5 + java/noppes/npcs/api/entity/IFishHook.java | 8 + java/noppes/npcs/api/entity/IPlayer.java | 5 + java/noppes/npcs/api/entity/IThrowable.java | 8 + java/noppes/npcs/api/event/IAbilityEvent.java | 16 ++ .../npcs/api/event/IAnimationEvent.java | 11 + java/noppes/npcs/api/event/IBlockEvent.java | 4 + java/noppes/npcs/api/event/IChainEvent.java | 9 + .../npcs/api/event/ICustomGuiEvent.java | 5 + .../npcs/api/event/ICustomNPCsEvent.java | 4 + java/noppes/npcs/api/event/IDialogEvent.java | 15 ++ .../npcs/api/event/IEnergyBarrierEvent.java | 12 + .../api/event/IEnergyProjectileEvent.java | 14 + java/noppes/npcs/api/event/IFactionEvent.java | 10 + java/noppes/npcs/api/event/IForgeEvent.java | 9 + java/noppes/npcs/api/event/IItemEvent.java | 92 ++++++- .../npcs/api/event/ILinkedItemEvent.java | 8 +- java/noppes/npcs/api/event/INpcEvent.java | 107 +++++++- java/noppes/npcs/api/event/IPartyEvent.java | 41 ++- java/noppes/npcs/api/event/IPlayerEvent.java | 251 +++++++++++++++++- .../npcs/api/event/IProjectileEvent.java | 10 + java/noppes/npcs/api/event/IQuestEvent.java | 17 ++ java/noppes/npcs/api/event/IRecipeEvent.java | 17 ++ java/noppes/npcs/api/gui/ICustomGui.java | 7 + .../npcs/api/handler/IAbilityHandler.java | 24 ++ .../npcs/api/handler/IActionManager.java | 24 +- .../npcs/api/handler/IAnimationHandler.java | 6 + .../npcs/api/handler/IAuctionHandler.java | 12 + .../npcs/api/handler/ICloneHandler.java | 169 ++++++++++++ .../npcs/api/handler/IDialogHandler.java | 17 +- .../npcs/api/handler/IFactionHandler.java | 34 ++- .../npcs/api/handler/ILinkedItemHandler.java | 46 ++++ .../api/handler/INaturalSpawnsHandler.java | 32 +++ .../npcs/api/handler/IOverlayHandler.java | 36 +++ .../npcs/api/handler/IPlayerBankData.java | 4 + java/noppes/npcs/api/handler/IPlayerData.java | 32 +++ .../npcs/api/handler/IPlayerDialogData.java | 19 ++ .../npcs/api/handler/IPlayerFactionData.java | 22 ++ .../api/handler/IPlayerItemGiverData.java | 22 ++ .../npcs/api/handler/IPlayerMailData.java | 29 ++ .../npcs/api/handler/IPlayerQuestData.java | 48 +++- .../npcs/api/handler/IPlayerTradeData.java | 14 + .../api/handler/IPlayerTransportData.java | 33 +++ .../npcs/api/handler/IProfileHandler.java | 43 +++ .../npcs/api/handler/IQuestHandler.java | 17 +- .../npcs/api/handler/IRecipeHandler.java | 55 +++- java/noppes/npcs/api/handler/ITagHandler.java | 35 ++- .../npcs/api/handler/ITelegraphHandler.java | 16 +- .../npcs/api/handler/ITransportHandler.java | 24 ++ .../noppes/npcs/api/handler/data/IAction.java | 38 ++- .../npcs/api/handler/data/IActionChain.java | 6 +- .../api/handler/data/IActionListener.java | 4 + .../npcs/api/handler/data/IActionQueue.java | 8 +- .../npcs/api/handler/data/IAnimation.java | 2 + .../npcs/api/handler/data/IAnvilRecipe.java | 6 + .../npcs/api/handler/data/IAuctionClaim.java | 15 ++ .../api/handler/data/IAuctionListing.java | 23 ++ .../npcs/api/handler/data/ICustomEffect.java | 140 ++++++++++ .../noppes/npcs/api/handler/data/IDialog.java | 241 +++++++++++++++++ .../api/handler/data/IDialogCategory.java | 13 + .../npcs/api/handler/data/IDialogImage.java | 92 +++++++ .../npcs/api/handler/data/IDialogOption.java | 9 + .../npcs/api/handler/data/IFaction.java | 88 ++++++ java/noppes/npcs/api/handler/data/IFrame.java | 54 ++++ .../npcs/api/handler/data/IFramePart.java | 56 ++++ java/noppes/npcs/api/handler/data/ILine.java | 27 ++ java/noppes/npcs/api/handler/data/ILines.java | 37 +++ .../npcs/api/handler/data/ILinkedItem.java | 50 +++- .../npcs/api/handler/data/INaturalSpawn.java | 55 ++++ java/noppes/npcs/api/handler/data/IParty.java | 2 + .../npcs/api/handler/data/IPartyOptions.java | 30 ++- .../api/handler/data/IPlayerAttributes.java | 2 + .../npcs/api/handler/data/IPlayerEffect.java | 17 ++ .../npcs/api/handler/data/IPlayerMail.java | 21 ++ java/noppes/npcs/api/handler/data/IQuest.java | 58 +++- .../npcs/api/handler/data/IQuestCategory.java | 12 + .../npcs/api/handler/data/IQuestDialog.java | 4 + .../api/handler/data/IQuestInterface.java | 3 + .../npcs/api/handler/data/IQuestItem.java | 11 + .../npcs/api/handler/data/IQuestKill.java | 13 + .../npcs/api/handler/data/IQuestLocation.java | 11 + .../api/handler/data/IQuestObjective.java | 4 + .../noppes/npcs/api/handler/data/IRecipe.java | 23 +- java/noppes/npcs/api/handler/data/ISlot.java | 6 + java/noppes/npcs/api/handler/data/ISound.java | 33 +++ java/noppes/npcs/api/handler/data/ITag.java | 13 + .../api/handler/data/ITransportCategory.java | 22 ++ .../api/handler/data/ITransportLocation.java | 30 +++ .../data/actions/IConditionalAction.java | 2 +- java/noppes/npcs/api/roles/IRole.java | 8 + java/noppes/npcs/api/roles/IRoleBank.java | 3 + java/noppes/npcs/api/roles/IRoleFollower.java | 2 + java/noppes/npcs/api/roles/IRoleMailman.java | 3 + java/noppes/npcs/api/roles/IRoleTrader.java | 2 +- .../npcs/api/roles/IRoleTransporter.java | 20 ++ 131 files changed, 3363 insertions(+), 175 deletions(-) diff --git a/java/net/minecraft/util/Vec3i.java b/java/net/minecraft/util/Vec3i.java index 9c7bdef..9000e6a 100644 --- a/java/net/minecraft/util/Vec3i.java +++ b/java/net/minecraft/util/Vec3i.java @@ -67,6 +67,7 @@ public class Vec3i implements Comparable { /** * Get the X coordinate + * @return the X component */ public int getX() { return this.x; @@ -74,6 +75,7 @@ public class Vec3i implements Comparable { /** * Get the Y coordinate + * @return the Y component */ public int getY() { return this.y; @@ -81,6 +83,7 @@ public class Vec3i implements Comparable { /** * Get the Z coordinate + * @return the Z component */ public int getZ() { return this.z; @@ -89,6 +92,7 @@ public class Vec3i implements Comparable { /** * Get the X coordinate as a double + * @return the X component as a double */ public double getXD() { return this.xd; @@ -96,6 +100,7 @@ public class Vec3i implements Comparable { /** * Get the Y coordinate as a double + * @return the Y component as a double */ public double getYD() { return this.yd; @@ -103,6 +108,7 @@ public class Vec3i implements Comparable { /** * Get the Z coordinate as a double + * @return the Z component as a double */ public double getZD() { return this.zd; @@ -110,6 +116,8 @@ public class Vec3i implements Comparable { /** * Calculate the cross product of this and the given Vector + * @param vec the other vector + * @return the cross product of this vector and the given vector */ public Vec3i crossProduct(Vec3i vec) { return new Vec3i(this.getYD() * vec.getZD() - this.getZD() * vec.getYD(), this.getZD() * vec.getXD() - this.getXD() * vec.getZD(), this.getXD() * vec.getYD() - this.getYD() * vec.getXD()); diff --git a/java/net/minecraft/util/math/BlockPos.java b/java/net/minecraft/util/math/BlockPos.java index 131e037..963c775 100644 --- a/java/net/minecraft/util/math/BlockPos.java +++ b/java/net/minecraft/util/math/BlockPos.java @@ -50,6 +50,11 @@ public class BlockPos extends Vec3i { /** * Add the given coordinates to the coordinates of this BlockPos + * + * @param x X offset + * @param y Y offset + * @param z Z offset + * @return a new BlockPos offset by the given values */ public BlockPos add(double x, double y, double z) { return x == 0.0D && y == 0.0D && z == 0.0D ? this : new BlockPos(this.getXD() + x, this.getYD() + y, this.getZD() + z); @@ -57,6 +62,11 @@ public class BlockPos extends Vec3i { /** * Add the given coordinates to the coordinates of this BlockPos + * + * @param x X offset + * @param y Y offset + * @param z Z offset + * @return a new BlockPos offset by the given values */ public BlockPos add(int x, int y, int z) { return x == 0 && y == 0 && z == 0 ? this : new BlockPos(this.getXD() + x, this.getYD() + y, this.getZD() + z); @@ -64,6 +74,9 @@ public class BlockPos extends Vec3i { /** * Add the given Vector to this BlockPos + * + * @param vec the vector to add + * @return a new BlockPos offset by the vector */ public BlockPos add(Vec3i vec) { return vec.getXD() == 0 && vec.getYD() == 0 && vec.getZD() == 0 ? this : new BlockPos(this.getXD() + vec.getXD(), this.getYD() + vec.getYD(), this.getZD() + vec.getZD()); @@ -71,6 +84,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block up + * + * @return the BlockPos one block above */ public BlockPos up() { return this.up(1); @@ -78,6 +93,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks up + * + * @param n the distance upward + * @return the BlockPos n blocks above */ public BlockPos up(double n) { return this.offset(EnumFacing.UP, n); @@ -85,6 +103,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block down + * + * @return the BlockPos one block below */ public BlockPos down() { return this.down(1); @@ -92,6 +112,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks down + * + * @param n the distance downward + * @return the BlockPos n blocks below */ public BlockPos down(double n) { return this.offset(EnumFacing.DOWN, n); @@ -99,6 +122,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block in northern direction + * + * @return the BlockPos one block to the north */ public BlockPos north() { return this.north(1); @@ -106,6 +131,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks in northern direction + * + * @param n the distance northward + * @return the BlockPos n blocks to the north */ public BlockPos north(double n) { return this.offset(EnumFacing.NORTH, n); @@ -113,6 +141,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block in southern direction + * + * @return the BlockPos one block to the south */ public BlockPos south() { return this.south(1); @@ -120,6 +150,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks in southern direction + * + * @param n the distance southward + * @return the BlockPos n blocks to the south */ public BlockPos south(double n) { return this.offset(EnumFacing.SOUTH, n); @@ -127,6 +160,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block in western direction + * + * @return the BlockPos one block to the west */ public BlockPos west() { return this.west(1); @@ -134,6 +169,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks in western direction + * + * @param n the distance westward + * @return the BlockPos n blocks to the west */ public BlockPos west(double n) { return this.offset(EnumFacing.WEST, n); @@ -141,6 +179,8 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block in eastern direction + * + * @return the BlockPos one block to the east */ public BlockPos east() { return this.east(1); @@ -148,6 +188,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos n blocks in eastern direction + * + * @param n the distance eastward + * @return the BlockPos n blocks to the east */ public BlockPos east(double n) { return this.offset(EnumFacing.EAST, n); @@ -155,6 +198,9 @@ public class BlockPos extends Vec3i { /** * Offset this BlockPos 1 block in the given direction + * + * @param facing the direction to offset + * @return the BlockPos one block in the given direction */ public BlockPos offset(EnumFacing facing) { return this.offset(facing, 1); @@ -162,6 +208,10 @@ public class BlockPos extends Vec3i { /** * Offsets this BlockPos n blocks in the given direction + * + * @param facing the direction to offset + * @param n the distance + * @return the BlockPos n blocks in the given direction */ public BlockPos offset(EnumFacing facing, double n) { return n == 0 ? this : new BlockPos(this.getXD() + facing.getFrontOffsetX() * n, this.getYD() + facing.getFrontOffsetY() * n, this.getZD() + facing.getFrontOffsetZ() * n); @@ -176,6 +226,8 @@ public class BlockPos extends Vec3i { /** * Serialize this BlockPos into a long value + * + * @return this position serialized as a long */ public long toLong() { return ((long) this.getX() & X_MASK) << X_SHIFT | ((long) this.getY() & Y_MASK) << Y_SHIFT | ((long) this.getZ() & Z_MASK) << 0; @@ -183,6 +235,9 @@ public class BlockPos extends Vec3i { /** * Create a BlockPos from a serialized long value (created by toLong) + * + * @param serialized the serialized position + * @return a BlockPos decoded from the long */ public static BlockPos fromLong(long serialized) { int i = (int) (serialized << 64 - X_SHIFT - NUM_X_BITS >> 64 - NUM_X_BITS); @@ -193,6 +248,10 @@ public class BlockPos extends Vec3i { /** * Create an Iterable that returns all positions in the box specified by the given corners + * + * @param from the starting corner + * @param to the ending corner + * @return an iterable of all BlockPos within the bounding box */ public static Iterable getAllInBox(BlockPos from, BlockPos to) { final BlockPos blockpos = new BlockPos(Math.min(from.getX(), to.getX()), Math.min(from.getY(), to.getY()), Math.min(from.getZ(), to.getZ())); @@ -285,11 +344,16 @@ public class BlockPos extends Vec3i { /** * Sets the position, MUST not be name 'set' as that causes obfusication conflicts with func_185343_d + * + * @param x the X coordinate + * @param y the Y coordinate + * @param z the Z coordinate + * @return this mutable position */ - public BlockPos.MutableBlockPos setPos(int xIn, int yIn, int zIn) { - this.x = xIn; - this.y = yIn; - this.z = zIn; + public BlockPos.MutableBlockPos setPos(int x, int y, int z) { + this.x = x; + this.y = y; + this.z = z; return this; } @@ -318,6 +382,8 @@ public class BlockPos extends Vec3i { * *

When storing a BlockPos given to you for an extended period of time, make sure you * use this in case the value is changed internally.

+ * + * @return an immutable copy of this position */ public BlockPos toImmutable() { return new BlockPos(this); diff --git a/java/net/minecraft/util/math/IntHashMap.java b/java/net/minecraft/util/math/IntHashMap.java index 797013d..783c17f 100644 --- a/java/net/minecraft/util/math/IntHashMap.java +++ b/java/net/minecraft/util/math/IntHashMap.java @@ -32,12 +32,15 @@ public class IntHashMap { /** * Returns the object associated to a key + * + * @param key the integer key to look up + * @return the value associated with the key, or null if not found */ - public V lookup(int p_76041_1_) { - int i = computeHash(p_76041_1_); + public V lookup(int key) { + int i = computeHash(key); for (IntHashMap.Entry entry = this.slots[getSlotIndex(i, this.slots.length)]; entry != null; entry = entry.nextEntry) { - if (entry.hashEntry == p_76041_1_) { + if (entry.hashEntry == key) { return entry.valueEntry; } } @@ -47,9 +50,12 @@ public class IntHashMap { /** * Returns true if this hash table contains the specified item. + * + * @param key the integer key to check + * @return true if the map contains this key */ - public boolean containsItem(int p_76037_1_) { - return this.lookupEntry(p_76037_1_) != null; + public boolean containsItem(int key) { + return this.lookupEntry(key) != null; } final IntHashMap.Entry lookupEntry(int p_76045_1_) { @@ -66,19 +72,22 @@ public class IntHashMap { /** * Adds a key and associated value to this map + * + * @param key the integer key + * @param value the value to associate with the key */ - public void addKey(int p_76038_1_, V p_76038_2_) { - int i = computeHash(p_76038_1_); + public void addKey(int key, V value) { + int i = computeHash(key); int j = getSlotIndex(i, this.slots.length); for (IntHashMap.Entry entry = this.slots[j]; entry != null; entry = entry.nextEntry) { - if (entry.hashEntry == p_76038_1_) { - entry.valueEntry = p_76038_2_; + if (entry.hashEntry == key) { + entry.valueEntry = value; return; } } - this.insert(i, p_76038_1_, p_76038_2_, j); + this.insert(i, key, value, j); } /** @@ -128,9 +137,11 @@ public class IntHashMap { /** * Removes the specified object from the map and returns it + * + * @param key the integer key to remove */ - public V removeObject(int p_76049_1_) { - IntHashMap.Entry entry = this.removeEntry(p_76049_1_); + public V removeObject(int key) { + IntHashMap.Entry entry = this.removeEntry(key); return (V) (entry == null ? null : entry.valueEntry); } diff --git a/java/noppes/npcs/api/AbstractNpcAPI.java b/java/noppes/npcs/api/AbstractNpcAPI.java index e5b377f..75fcfba 100644 --- a/java/noppes/npcs/api/AbstractNpcAPI.java +++ b/java/noppes/npcs/api/AbstractNpcAPI.java @@ -190,6 +190,12 @@ public abstract class AbstractNpcAPI { /** * * Spawns a new NPC in the world at the given coordinates and returns an ICustomNpc object of it. + * + * @param var1 the world + * @param var2 X position + * @param var3 Y position + * @param var4 Z position + * @return the spawned NPC */ public abstract ICustomNpc spawnNPC(IWorld var1, int var2, int var3, int var4); @@ -243,11 +249,13 @@ public abstract class AbstractNpcAPI { public abstract IItemStack getIItemStack(ItemStack var1); /** + * @param var1 the Minecraft world * @return A single IWorld from Loaded IWorlds */ public abstract IWorld getIWorld(World var1); /** + * @param var1 the dimension ID * @return A single IWorld from Loaded IWorlds */ public abstract IWorld getIWorld(int var1); @@ -257,6 +265,7 @@ public abstract class AbstractNpcAPI { * Forge sometimes automatically, unloads the End when all players * are no longer present. * + * @param var1 the dimension ID * @return A single IWorld from Loaded/Unloaded IWorlds */ public abstract IWorld getIWorldLoad(int var1); @@ -325,6 +334,7 @@ public abstract class AbstractNpcAPI { * 0: Random * 1: Male * 2: Female + * @return a random name */ public abstract String getRandomName(int dictionary, int gender); @@ -357,6 +367,7 @@ public abstract class AbstractNpcAPI { /** * + * @param directory the particle texture directory * @return A new IParticle object initialized with the given texture. */ public abstract IParticle createParticle(String directory); @@ -408,12 +419,14 @@ public abstract class AbstractNpcAPI { /** * + * @param id the overlay ID * @return A new ICustomOverlay overlay object with the given ID. */ public abstract ICustomOverlay createCustomOverlay(int id); /** * + * @param texture the texture path * @return A new ISkinOverlay object initialized with the given texture. */ public abstract ISkinOverlay createSkinOverlay(String texture); diff --git a/java/noppes/npcs/api/ICommand.java b/java/noppes/npcs/api/ICommand.java index 444c909..b59833a 100644 --- a/java/noppes/npcs/api/ICommand.java +++ b/java/noppes/npcs/api/ICommand.java @@ -1,23 +1,67 @@ package noppes.npcs.api; +/** + * Represents a custom command that can be registered and executed. + */ public interface ICommand { + /** + * Gets the name of this command. + * @return the command name + */ String getCommandName(); + /** + * Gets the usage string for this command. + * @return the command usage description + */ String getCommandUsage(); + /** + * Gets the permission level required to execute this command. + * @return the permission level (0 = all, 1 = moderator, 2 = gamemaster, 3 = admin, 4 = owner) + */ int getPermissionLevel(); + /** + * Sets the name of this command. + * @param commandName the command name to set + */ void setCommandName(String commandName); + /** + * Sets the usage string for this command. + * @param commandUsage the command usage description to set + */ void setCommandUsage(String commandUsage); + /** + * Sets the permission level required to execute this command. + * @param permissionLevel the permission level (0 = all, 1 = moderator, 2 = gamemaster, 3 = admin, 4 = owner) + */ void setPermissionLevel(int permissionLevel); + /** + * Gets all aliases for this command. + * @return an array of alias strings + */ String[] getAliases(); + /** + * Adds one or more aliases for this command. + * @param aliases the alias(es) to add + */ void addAliases(String... aliases); + /** + * Checks whether this command has a specific alias. + * @param alias the alias to check for + * @return true if the alias exists + */ boolean hasAlias(String alias); + /** + * Removes an alias from this command. + * @param alias the alias to remove + */ void removeAlias(String alias); } diff --git a/java/noppes/npcs/api/IEnergyController.java b/java/noppes/npcs/api/IEnergyController.java index 5c3156f..a3cd8f7 100644 --- a/java/noppes/npcs/api/IEnergyController.java +++ b/java/noppes/npcs/api/IEnergyController.java @@ -17,21 +17,51 @@ public interface IEnergyController { /** * Create an energy orb projectile. Not spawned until fire() is called. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @param size the orb size + * @return the energy orb entity */ IEnergyOrb createOrb(IWorld world, IEntity owner, double x, double y, double z, float size); /** * Create an energy beam projectile. Not spawned until fire() is called. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @param beamWidth the beam width + * @param headSize the head size + * @return the energy beam entity */ IEnergyBeam createBeam(IWorld world, IEntity owner, double x, double y, double z, float beamWidth, float headSize); /** * Create an energy disc projectile. Not spawned until fire() is called. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @param radius the disc radius + * @param thickness the disc thickness + * @return the energy disc entity */ IEnergyDisc createDisc(IWorld world, IEntity owner, double x, double y, double z, float radius, float thickness); /** * Create an energy laser projectile. Not spawned until fire() is called. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @param laserWidth the laser width + * @return the energy laser entity */ IEnergyLaser createLaser(IWorld world, IEntity owner, double x, double y, double z, float laserWidth); @@ -40,12 +70,24 @@ public interface IEnergyController { /** * Create a hazard zone entity with defaults. Not spawned until spawn() is called. * Hazards deal continuous damage to entities within the zone. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @return the energy zone entity */ IEnergyZone createHazard(IWorld world, IEntity owner, double x, double y, double z); /** * Create a trap zone entity with defaults. Not spawned until spawn() is called. * Traps trigger when entities enter and deal burst damage. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @return the energy zone entity */ IEnergyZone createTrap(IWorld world, IEntity owner, double x, double y, double z); @@ -54,6 +96,12 @@ public interface IEnergyController { /** * Create a sweeper entity with defaults. Not spawned until spawn() is called. * Sweepers rotate a beam that damages entities in its path. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @return the energy sweeper entity */ IEnergySweeper createSweeper(IWorld world, IEntity owner, double x, double y, double z); @@ -62,6 +110,12 @@ public interface IEnergyController { /** * Create a panel entity with defaults. Not spawned until spawn() is called. * Panels are flat energy barriers that can deal damage on contact. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @return the energy panel entity */ IEnergyPanel createPanel(IWorld world, IEntity owner, double x, double y, double z); @@ -69,7 +123,14 @@ public interface IEnergyController { /** * Create an energy explosion entity. Not spawned until spawn() is called. - * Visual-only by default. Set damage > 0 to enable area damage with falloff. + * Visual-only by default. Set damage > 0 to enable area damage with falloff. + * @param world the world + * @param owner the owning entity + * @param x X position + * @param y Y position + * @param z Z position + * @param radius the explosion radius + * @return the energy explosion entity */ IEnergyExplosion createExplosion(IWorld world, IEntity owner, double x, double y, double z, float radius); } diff --git a/java/noppes/npcs/api/INbt.java b/java/noppes/npcs/api/INbt.java index 234befa..485e3f5 100644 --- a/java/noppes/npcs/api/INbt.java +++ b/java/noppes/npcs/api/INbt.java @@ -30,10 +30,12 @@ import net.minecraft.nbt.NBTTagCompound; public interface INbt { /** * Returns the tag with the given key from the compound tag. + * @param key the NBT key */ void remove(String key); /** + * @param key the NBT key * @return True if the compound tag has a tag with the given key. */ boolean has(String key); @@ -82,12 +84,16 @@ public interface INbt { * Returns a tag list of objects with this key in the compound tag. All the objects in the list * will always be of the same type. * + * @param key the NBT key + * @param value the list type * @return The tag list of objects, depending on the tag type. */ Object[] getList(String key, int value); /** * Returns the type of the tag list with this key, as an integer. + * @param key the NBT key + * @return the list element type */ int getListType(String key); @@ -112,6 +118,7 @@ public interface INbt { /** * + * @param key the NBT key * @return The type of the tag with the input key as an integer. */ int getType(String key); diff --git a/java/noppes/npcs/api/IPixelmonPlayerData.java b/java/noppes/npcs/api/IPixelmonPlayerData.java index 63abb2c..0d224ef 100644 --- a/java/noppes/npcs/api/IPixelmonPlayerData.java +++ b/java/noppes/npcs/api/IPixelmonPlayerData.java @@ -2,9 +2,21 @@ package noppes.npcs.api; import noppes.npcs.api.entity.IPixelmon; +/** + * Provides access to a player's Pixelmon data, including party and PC storage. + */ public interface IPixelmonPlayerData { + /** + * Gets the Pixelmon in the specified party slot. + * @param slot the party slot index (0-5) + * @return the Pixelmon in that slot, or null if empty + */ IPixelmon getPartySlot(int slot); + /** + * Gets the total number of Pixelmon stored in the player's PC. + * @return the PC Pixelmon count + */ int countPCPixelmon(); } diff --git a/java/noppes/npcs/api/IPos.java b/java/noppes/npcs/api/IPos.java index 45ba39e..dd69b03 100644 --- a/java/noppes/npcs/api/IPos.java +++ b/java/noppes/npcs/api/IPos.java @@ -19,6 +19,7 @@ public interface IPos { /** * Shifts the IPos up by 1 block and returns the new object. * + * @return the position above */ IPos up(); @@ -32,6 +33,7 @@ public interface IPos { /** * Shifts the IPos down by 1 block and returns the new object. * + * @return the position below */ IPos down(); @@ -45,6 +47,7 @@ public interface IPos { /** * Shifts the IPos north by 1 block and returns the new object. * + * @return the position to the north */ IPos north(); @@ -58,6 +61,7 @@ public interface IPos { /** * Shifts the IPos east by 1 block and returns the new object. * + * @return the position to the east */ IPos east(); @@ -71,6 +75,7 @@ public interface IPos { /** * Shifts the IPos south by 1 block and returns the new object. * + * @return the position to the south */ IPos south(); @@ -84,6 +89,7 @@ public interface IPos { /** * Shifts the IPos west by 1 block and returns the new object. * + * @return the position to the west */ IPos west(); @@ -146,12 +152,17 @@ public interface IPos { /** * Offsets the block by 1 block in the given direction and returns the resulting IPos object * + * @param direction the direction ordinal + * @return the offset position */ IPos offset(int direction); /** * Offsets the block by n blocks in the given direction and returns the resulting IPos object * + * @param direction the direction ordinal + * @param n the distance + * @return the offset position */ IPos offset(int direction, double n); diff --git a/java/noppes/npcs/api/IScreenSize.java b/java/noppes/npcs/api/IScreenSize.java index 07d98af..9f8d281 100644 --- a/java/noppes/npcs/api/IScreenSize.java +++ b/java/noppes/npcs/api/IScreenSize.java @@ -1,12 +1,33 @@ package noppes.npcs.api; +/** + * Represents the scaled screen dimensions of the client display. + */ public interface IScreenSize { + /** + * Gets the scaled screen width in pixels. + * @return the screen width + */ public int getWidth(); + /** + * Gets the scaled screen height in pixels. + * @return the screen height + */ public int getHeight(); + /** + * Gets a pixel value representing the given percentage of the screen width. + * @param percent the percentage of the width (0.0 to 100.0) + * @return the corresponding pixel value + */ public int getWidthPercent(double percent); + /** + * Gets a pixel value representing the given percentage of the screen height. + * @param percent the percentage of the height (0.0 to 100.0) + * @return the corresponding pixel value + */ public int getHeightPercent(double percent); } diff --git a/java/noppes/npcs/api/ISkinOverlay.java b/java/noppes/npcs/api/ISkinOverlay.java index 1f15a85..5d7834d 100644 --- a/java/noppes/npcs/api/ISkinOverlay.java +++ b/java/noppes/npcs/api/ISkinOverlay.java @@ -9,6 +9,7 @@ package noppes.npcs.api; public interface ISkinOverlay { /** * Sets the directory texture of the overlay. Does not support URLs. + * @param texture the texture path */ void setTexture(String texture); @@ -16,6 +17,7 @@ public interface ISkinOverlay { /** * Sets whether this overlay glows in the dark or not. + * @param glow whether to glow */ void setGlow(boolean glow); @@ -23,6 +25,7 @@ public interface ISkinOverlay { /** * Sets whether this overlay blends on top of bottom textures at any alpha value. + * @param blend whether to blend */ void setBlend(boolean blend); @@ -30,6 +33,7 @@ public interface ISkinOverlay { /** * Sets the transparency of the overlay, from 0 to 1. + * @param alpha the alpha value */ void setAlpha(float alpha); @@ -38,6 +42,7 @@ public interface ISkinOverlay { /** * Sets the size of the entire overlay when rendered on the entity. By default, overlays render slightly on top of * the entity's model. + * @param size the overlay size */ void setSize(float size); @@ -49,6 +54,8 @@ public interface ISkinOverlay { /** * Sets the texture scale of the overlay. Higher values will "zoom in" to the texture more. + * @param scaleX horizontal scale + * @param scaleY vertical scale */ void setTextureScale(float scaleX, float scaleY); @@ -59,6 +66,8 @@ public interface ISkinOverlay { /** * Sets the "texture speed" by which the texture shifts on each render tick. Used to create a powered creeper effect! * This does not move the entire overlay, it just moves the position at which the texture begins rendering. + * @param speedX horizontal speed + * @param speedY vertical speed */ void setSpeed(float speedX, float speedY); @@ -68,6 +77,9 @@ public interface ISkinOverlay { /** * Sets the amount in each direction by which the overlay will be offset from the entity. + * @param offsetX horizontal render offset + * @param offsetY vertical render offset + * @param offsetZ depth render offset */ void setOffset(float offsetX, float offsetY, float offsetZ); diff --git a/java/noppes/npcs/api/ITelegraph.java b/java/noppes/npcs/api/ITelegraph.java index 389cddc..63fe339 100644 --- a/java/noppes/npcs/api/ITelegraph.java +++ b/java/noppes/npcs/api/ITelegraph.java @@ -25,9 +25,9 @@ import noppes.npcs.api.entity.IEntity; */ public interface ITelegraph { - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // TYPE - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the telegraph type. @@ -43,143 +43,165 @@ public interface ITelegraph { */ void setType(String type); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // SHAPE PARAMETERS - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the radius (for CIRCLE and RING types). + * @return the circle/ring radius in blocks */ float getRadius(); /** * Set the radius (for CIRCLE and RING types). + * @param radius circle/ring radius in blocks */ void setRadius(float radius); /** * Get the inner radius (for RING type). + * @return the inner radius for RING type in blocks */ float getInnerRadius(); /** * Set the inner radius (for RING type). + * @param innerRadius inner radius for RING type in blocks */ void setInnerRadius(float innerRadius); /** * Get the length (for LINE and CONE types). + * @return the length for LINE/CONE types in blocks */ float getLength(); /** * Set the length (for LINE and CONE types). + * @param length length for LINE/CONE types in blocks */ void setLength(float length); /** * Get the width (for LINE type). + * @return the width for LINE type in blocks */ float getWidth(); /** * Set the width (for LINE type). + * @param width width for LINE type in blocks */ void setWidth(float width); /** * Get the angle in degrees (for CONE type). + * @return the arc angle for CONE type in degrees */ float getAngle(); /** * Set the angle in degrees (for CONE type). + * @param angle arc angle for CONE type in degrees */ void setAngle(float angle); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // TIMING - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the duration in ticks. + * @return duration in ticks (20 ticks = 1 second) */ int getDuration(); /** * Set the duration in ticks (20 ticks = 1 second). + * @param ticks duration in ticks (20 ticks = 1 second) */ void setDuration(int ticks); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // COLORS - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the primary color in ARGB format. + * @return the primary color in ARGB format */ int getColor(); /** * Set the primary color in ARGB format. * Example: 0x80FF0000 for semi-transparent red + * @param argb primary color in ARGB format (e.g. 0x80FF0000) */ void setColor(int argb); /** * Get the warning phase color in ARGB format. + * @return the warning phase color in ARGB format */ int getWarningColor(); /** * Set the warning phase color in ARGB format. * This color is used during the final warning phase. + * @param argb warning phase color in ARGB format */ void setWarningColor(int argb); /** * Get the tick at which warning phase begins. + * @return the tick at which warning phase begins */ int getWarningStartTick(); /** * Set the tick at which warning phase begins. * When remaining ticks falls below this value, the telegraph uses the warning color. + * @param tick tick at which warning phase begins */ void setWarningStartTick(int tick); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // ANIMATION - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Check if pulsing animation is enabled. + * @return true if pulsing animation is enabled */ boolean isAnimated(); /** * Enable or disable pulsing animation. + * @param animated whether pulsing animation is enabled */ void setAnimated(boolean animated); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // POSITIONING - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the height offset from ground level. + * @return the height offset from ground level in blocks */ float getHeightOffset(); /** * Set the height offset from ground level. * Default is 0.1 to prevent z-fighting with ground blocks. + * @param offset height offset from ground level in blocks */ void setHeightOffset(float offset); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // SPAWN METHODS - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Spawn this telegraph at a position. diff --git a/java/noppes/npcs/api/ITelegraphInstance.java b/java/noppes/npcs/api/ITelegraphInstance.java index 2421e1a..a21c93e 100644 --- a/java/noppes/npcs/api/ITelegraphInstance.java +++ b/java/noppes/npcs/api/ITelegraphInstance.java @@ -19,46 +19,55 @@ public interface ITelegraphInstance { /** * Get the unique instance ID. + * @return the unique instance identifier */ String getInstanceId(); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // POSITION - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the current X position. + * @return the current X coordinate */ double getX(); /** * Get the current Y position. + * @return the current Y coordinate */ double getY(); /** * Get the current Z position. + * @return the current Z coordinate */ double getZ(); /** * Get the rotation yaw. + * @return the rotation yaw in degrees */ float getYaw(); /** * Set the position. * Note: Only works for static telegraphs (not following an entity). + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate */ void setPosition(double x, double y, double z); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // ENTITY FOLLOWING - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Make this telegraph follow an entity. * The telegraph position will update each tick to match the entity. + * @param entity the entity to follow */ void followEntity(IEntity entity); @@ -69,36 +78,41 @@ public interface ITelegraphInstance { /** * Check if this telegraph is following an entity. + * @return true if currently following an entity */ boolean isFollowing(); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // TIMING - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get the remaining ticks before the telegraph expires. + * @return remaining ticks before expiration */ int getRemainingTicks(); /** * Get the total duration ticks. + * @return the total duration in ticks */ int getTotalTicks(); /** * Get the progress from 0.0 (just started) to 1.0 (finished). + * @return progress from 0.0 (just started) to 1.0 (finished) */ float getProgress(); /** * Check if the telegraph is in the warning phase. + * @return true if in the warning phase */ boolean isWarning(); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // CONTROL - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Remove this telegraph immediately. diff --git a/java/noppes/npcs/api/ITileEntity.java b/java/noppes/npcs/api/ITileEntity.java index 4443c85..bb2e738 100644 --- a/java/noppes/npcs/api/ITileEntity.java +++ b/java/noppes/npcs/api/ITileEntity.java @@ -29,10 +29,14 @@ public interface ITileEntity { /** * Reads an INbt compound tag, creates a tile entity based on the data, and replaces this entity with the new one. + * @param nbt the NBT data to read from */ void readFromNBT(INbt nbt); /** + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate * @return The distance of this tile entity from the point given by the x, y, and z parameters. */ double getDistanceFrom(double x, double y, double z); @@ -67,6 +71,7 @@ public interface ITileEntity { /** * Writes the tile entity to NBT and returns the compound tag. + * @return the tile entity's NBT data */ INbt getNBT(); } diff --git a/java/noppes/npcs/api/ITimers.java b/java/noppes/npcs/api/ITimers.java index b0da686..2a509ab 100644 --- a/java/noppes/npcs/api/ITimers.java +++ b/java/noppes/npcs/api/ITimers.java @@ -26,6 +26,7 @@ public interface ITimers { /** * + * @param id the timer ID * @return True if the set of timers contains a timer with the given id, false otherwise. */ boolean has(int id); @@ -33,12 +34,14 @@ public interface ITimers { /** * Stops the timer with the given id * + * @param id the timer ID * @return True if there was a timer with the given id. */ boolean stop(int id); /** * Resets the ticks elapsed in the timer with the given id to 0. + * @param id the timer ID */ void reset(int id); @@ -48,6 +51,7 @@ public interface ITimers { void clear(); /** + * @param id the timer ID * @return The amount of ticks elapsed in the timer. */ int ticks(int id); @@ -55,27 +59,34 @@ public interface ITimers { /** * Sets the amount of ticks elapsed in the timer with the given id to a different value. * + * @param id the timer ID * @param ticks The new ticks elapsed by the timer. */ void setTicks(int id, int ticks); /** + * @param id the timer ID * @return The maximum amount of ticks the timer with the given id runs for before it stops. */ int maxTicks(int id); /** * Sets the maximum amount of ticks the timer with the given id can run for before it stops. + * @param id the timer ID + * @param maxTicks the maximum tick count */ void setMaxTicks(int id, int maxTicks); /** + * @param id the timer ID * @return True if the timer with the given id repeats, false otherwise. */ boolean repeats(int id); /** * Sets whether the timer with the given id repeats or not. + * @param id the timer ID + * @param repeat whether the timer repeats */ void setRepeats(int id, boolean repeat); diff --git a/java/noppes/npcs/api/IWorld.java b/java/noppes/npcs/api/IWorld.java index 591b1e6..23a327f 100644 --- a/java/noppes/npcs/api/IWorld.java +++ b/java/noppes/npcs/api/IWorld.java @@ -33,13 +33,14 @@ public interface IWorld { public IBlock getBlock(int x, int y, int z); /** - * @param pos + * @param pos the block position * @return The block at the given position. Returns null if there isn't a block */ public IBlock getBlock(IPos pos); /** - * + * @param x X coordinate + * @param z Z coordinate * @return The top-most block in the world as an IBlock object. */ IBlock getTopBlock(int x, int z); @@ -71,20 +72,27 @@ public interface IWorld { boolean canSnowAtBody(int x, int y, int z, boolean checkLight); /** - * @return The Y-value of the world at this x & z value based on the height map of the world. + * @param x X coordinate + * @param z Z coordinate + * @return The Y-value of the world at this x & z value based on the height map of the world. */ int getHeightValue(int x, int z); int getHeightValue(IPos pos); /** - * @return The minimum Y-value of the world at this x & z value based on the height map of the world. + * @param x X coordinate + * @param z Z coordinate + * @return The minimum Y-value of the world at this x & z value based on the height map of the world. */ int getChunkHeightMapMinimum(int x, int z); int getChunkHeightMapMinimum(IPos pos); /** + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate * @return The metadata of the block at this position. */ int getBlockMetadata(int x, int y, int z); @@ -96,15 +104,15 @@ public interface IWorld { boolean setBlockMetadataWithNotify(IPos pos, int metadata, int flag); /** - * @param x - * @param y - * @param z + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate * @return can the block at this position see the sky or are there no blocks above this one */ boolean canSeeSky(int x, int y, int z); /** - * @param pos + * @param pos the block position * @return can the block at this position see the sky or are there no blocks above this one */ boolean canSeeSky(IPos pos); @@ -162,6 +170,11 @@ public interface IWorld { /** * Sets the block's tile entity at the given position. + * + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate + * @param tileEntity the tile entity to place */ void setTileEntity(int x, int y, int z, ITileEntity tileEntity); @@ -169,13 +182,19 @@ public interface IWorld { /** * Removes the block's tile entity at the given position. + * + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate */ void removeTileEntity(int x, int y, int z); void removeTileEntity(IPos pos); /** - * + * @param x X coordinate + * @param y Y coordinate + * @param z Z coordinate * @return True if the block at this position is of cubic shape. (Not a stair, slab, etc.) */ boolean isBlockFullCube(int x, int y, int z); @@ -212,6 +231,7 @@ public interface IWorld { * @param y World position y * @param z World position z * @param item The block to be set + * @return true if the block was successfully placed */ boolean setBlock(int x, int y, int z, IItemStack item); @@ -222,6 +242,7 @@ public interface IWorld { * @param y World position y * @param z World position z * @param block The block to be set + * @return true if the block was successfully placed */ boolean setBlock(int x, int y, int z, IBlock block); @@ -255,9 +276,12 @@ public interface IWorld { /** * starting at the start position, draw a line in the lookVector direction until a block is detected * - * @param startPos + * @param startPos the ray origin as [x, y, z] * @param lookVector should be a normalized direction vector - * @param maxDistance + * @param maxDistance maximum ray distance in blocks + * @param stopOnBlock whether to stop on solid blocks + * @param stopOnLiquid whether to stop on liquid blocks + * @param stopOnCollision whether to stop on collision boundaries * @return the first detected block but null if maxDistance is reached */ IBlock rayCastBlock(double[] startPos, double[] lookVector, int maxDistance, boolean stopOnBlock, boolean stopOnLiquid, boolean stopOnCollision); @@ -269,8 +293,8 @@ public interface IWorld { IBlock rayCastBlock(IPos startPos, IPos lookVector, int maxDistance); /** - * @param startPos - * @param maxHeight + * @param startPos the start position as [x, y, z] + * @param maxHeight maximum search height * @return the position of the closest block of air to startPos */ public IPos getNearestAir(IPos startPos, int maxHeight); @@ -457,6 +481,7 @@ public interface IWorld { * @param y Spawn Y position * @param z Spawn Z position * @param size Orb size + * @return the energy orb entity */ IEnergyOrb createEnergyOrb(IEntity owner, double x, double y, double z, float size); @@ -469,6 +494,7 @@ public interface IWorld { * @param z Spawn Z position * @param beamWidth Width of the beam * @param headSize Size of the beam head + * @return the energy beam entity */ IEnergyBeam createEnergyBeam(IEntity owner, double x, double y, double z, float beamWidth, float headSize); @@ -481,6 +507,7 @@ public interface IWorld { * @param z Spawn Z position * @param radius Disc radius * @param thickness Disc thickness + * @return the energy disc entity */ IEnergyDisc createEnergyDisc(IEntity owner, double x, double y, double z, float radius, float thickness); @@ -492,6 +519,7 @@ public interface IWorld { * @param y Spawn Y position * @param z Spawn Z position * @param laserWidth Width of the laser + * @return the energy laser entity */ IEnergyLaser createEnergyLaser(IEntity owner, double x, double y, double z, float laserWidth); diff --git a/java/noppes/npcs/api/ability/IAbility.java b/java/noppes/npcs/api/ability/IAbility.java index 6c5dcbb..456db39 100644 --- a/java/noppes/npcs/api/ability/IAbility.java +++ b/java/noppes/npcs/api/ability/IAbility.java @@ -12,6 +12,7 @@ public interface IAbility extends IAbilityAction { /** * Get the unique ID (UUID for custom abilities, registry key for built-in). * This is the stable reference that never changes after creation. + * @return the unique ability ID */ String getId(); @@ -34,6 +35,7 @@ public interface IAbility extends IAbilityAction { /** * Get the display name (cosmetic). Falls back to getName() if not set. + * @return the display name */ String getDisplayName(); @@ -45,6 +47,7 @@ public interface IAbility extends IAbilityAction { /** * Get the type ID of this ability (e.g., "cnpc:slam", "cnpc:beam"). + * @return the type ID */ String getTypeId(); @@ -106,6 +109,7 @@ public interface IAbility extends IAbilityAction { /** * Get the wind-up time in ticks (telegraph phase). + * @return wind-up time in ticks */ int getWindUpTicks(); @@ -117,6 +121,7 @@ public interface IAbility extends IAbilityAction { /** * Get the dazed time in ticks (stun after interrupt during WINDUP). + * @return dazed time in ticks */ int getDazedTicks(); @@ -128,6 +133,7 @@ public interface IAbility extends IAbilityAction { /** * Check if this ability can be interrupted by damage. + * @return true if interruptible */ boolean isInterruptible(); @@ -139,6 +145,7 @@ public interface IAbility extends IAbilityAction { /** * Check if this ability ignores target invulnerability frames (hurt resistance). + * @return true if ignoring invulnerability frames */ boolean isIgnoreIFrames(); @@ -193,6 +200,7 @@ public interface IAbility extends IAbilityAction { /** * Get track speed for TRACK rotation mode (blocks/second). * 0 = instant tracking. Comparable to player sprint speed (~5.6 blocks/sec). + * @return track speed in blocks/second */ float getTrackSpeedValue(); @@ -205,36 +213,43 @@ public interface IAbility extends IAbilityAction { /** * Check if movement (pathfinding/motion) is locked during the WINDUP phase. + * @return true if movement is locked during windup */ boolean isMovementLockedDuringWindup(); /** * Check if movement (pathfinding/motion) is locked during the ACTIVE phase. + * @return true if movement is locked during active phase */ boolean isMovementLockedDuringActive(); /** * Check if rotation (yaw/pitch) is locked during the WINDUP phase. + * @return true if rotation is locked during windup */ boolean isRotationLockedDuringWindup(); /** * Check if rotation (yaw/pitch) is locked during the ACTIVE phase. + * @return true if rotation is locked during active phase */ boolean isRotationLockedDuringActive(); /** * Check if this ability is currently being executed. + * @return true if currently executing */ boolean isExecuting(); /** * Get the current execution phase (0=IDLE, 1=WINDUP, 2=ACTIVE, 3=DAZED, 4=BURST_DELAY). + * @return the current phase ordinal */ int getPhaseInt(); /** * Get the current tick within the current phase. + * @return the current tick within the phase */ int getCurrentTick(); @@ -254,6 +269,7 @@ public interface IAbility extends IAbilityAction { /** * Check if this ability ignores cooldowns. + * @return true if ignoring cooldowns */ boolean isIgnoreCooldown(); @@ -266,6 +282,7 @@ public interface IAbility extends IAbilityAction { /** * Check if this ability uses per-ability cooldown instead of global cooldown. * When true, using this ability only puts THIS ability on cooldown, not all abilities. + * @return true if using per-ability cooldown */ boolean isPerAbilityCooldown(); @@ -277,6 +294,7 @@ public interface IAbility extends IAbilityAction { /** * Get this ability's data as NBT. + * @return the ability's NBT data */ INbt getNbt(); @@ -322,12 +340,14 @@ public interface IAbility extends IAbilityAction { /** * Check if this ability is toggleable (has at least 1 toggle state). + * @return true if toggleable */ boolean isToggleable(); /** * Get the number of toggle states. * 0 = not toggleable, 1 = binary on/off, 2+ = multi-state cycling. + * @return number of toggle states */ int getToggleStates(); diff --git a/java/noppes/npcs/api/ability/IAbilityHandler.java b/java/noppes/npcs/api/ability/IAbilityHandler.java index b3ae328..0ccacf1 100644 --- a/java/noppes/npcs/api/ability/IAbilityHandler.java +++ b/java/noppes/npcs/api/ability/IAbilityHandler.java @@ -17,17 +17,25 @@ public interface IAbilityHandler { /** * Check if an ability type is registered. + * + * @param typeId the type ID to check + * @return true if registered */ boolean hasType(String typeId); /** * Get all registered ability type IDs. + * + * @return array of registered type IDs */ String[] getTypes(); /** * Create a new ability of the given type. * Returns null if the type is not registered. + * + * @param typeId the type ID + * @return the new ability, or null */ IAbility create(String typeId); diff --git a/java/noppes/npcs/api/ability/ICustomAbility.java b/java/noppes/npcs/api/ability/ICustomAbility.java index 631dcf4..616a96f 100644 --- a/java/noppes/npcs/api/ability/ICustomAbility.java +++ b/java/noppes/npcs/api/ability/ICustomAbility.java @@ -8,11 +8,13 @@ public interface ICustomAbility extends IAbility { /** * Get the duration in ticks for instant mode (non-toggle). + * @return duration in ticks */ int getDurationTicks(); /** * Set the duration in ticks for instant mode. + * @param ticks duration in ticks */ void setDurationTicks(int ticks); @@ -43,72 +45,86 @@ public interface ICustomAbility extends IAbility { /** * Get how many ticks the telegraph persists during the active phase. * When syncTelegraphWithDuration is true, this returns the duration ticks. + * @return telegraph active ticks */ int getTelegraphActiveTicks(); /** * Set how many ticks the telegraph persists during the active phase. * Only used when syncTelegraphWithDuration is false. + * @param ticks telegraph active ticks */ void setTelegraphActiveTicks(int ticks); /** * Whether telegraph active ticks are synced to the ability duration. + * @return true if synced */ boolean isSyncTelegraphWithDuration(); /** * Set whether telegraph active ticks should sync to the ability duration. + * @param sync whether to sync */ void setSyncTelegraphWithDuration(boolean sync); /** * Get the telegraph radius (used by CIRCLE, RING, SQUARE shapes). + * @return the telegraph radius */ float getTelegraphRadius(); /** * Set the telegraph radius. + * @param radius the telegraph radius */ void setTelegraphRadius(float radius); /** * Get the telegraph inner radius (used by RING, CONE shapes). + * @return the inner radius */ float getTelegraphInnerRadius(); /** * Set the telegraph inner radius. + * @param innerRadius the inner radius */ void setTelegraphInnerRadius(float innerRadius); /** * Get the telegraph length (used by LINE, CONE shapes). + * @return the telegraph length */ float getTelegraphLength(); /** * Set the telegraph length. + * @param length the telegraph length */ void setTelegraphLength(float length); /** * Get the telegraph width (used by LINE shape). + * @return the telegraph width */ float getTelegraphWidth(); /** * Set the telegraph width. + * @param width the telegraph width */ void setTelegraphWidth(float width); /** * Get the telegraph angle in degrees (used by CONE shape). + * @return the telegraph angle in degrees */ float getTelegraphAngle(); /** * Set the telegraph angle in degrees. + * @param angle the angle in degrees */ void setTelegraphAngle(float angle); } diff --git a/java/noppes/npcs/api/ability/IDataAbilities.java b/java/noppes/npcs/api/ability/IDataAbilities.java index 9a3feb0..4345cd5 100644 --- a/java/noppes/npcs/api/ability/IDataAbilities.java +++ b/java/noppes/npcs/api/ability/IDataAbilities.java @@ -8,54 +8,78 @@ public interface IDataAbilities { /** * Check if the ability system is enabled for this NPC. + * + * @return true if enabled */ boolean isEnabled(); /** * Enable or disable the ability system for this NPC. + * + * @param enabled whether to enable */ void setEnabled(boolean enabled); /** * Get all abilities assigned to this NPC (resolved from slots). * Returns safe deep copies. Use {@link #getSourceAbility(String)} for live references. + * + * @return array of abilities */ IAbility[] getAbilities(); /** * Add an inline ability to this NPC. + * + * @param ability the ability to add */ void addAbility(IAbility ability); /** * Add a reference ability by key (built-in name or custom UUID). + * + * @param key the ability reference key */ void addAbilityReference(String key); /** * Remove an ability by ID. + * + * @param abilityId the ability ID to remove */ void removeAbility(String abilityId); /** * Get an ability by ID. * Returns a safe deep copy. Use {@link #getSourceAbility(String)} for the live reference. + * + * @param abilityId the ability ID + * @return the ability, or null */ IAbility getAbility(String abilityId); /** * Check if the NPC has an ability with the given ID. + * + * @param abilityId the ability ID + * @return true if found */ boolean hasAbility(String abilityId); /** * Check if a slot is a reference (by ability ID). + * + * @param abilityId the ability ID + * @return true if reference */ boolean isAbilityReference(String abilityId); /** * Convert a reference slot to inline (by ability ID). * Returns false if the reference cannot be resolved. + * + * @param abilityId the ability ID + * @return true if converted successfully */ boolean convertToInline(String abilityId); @@ -67,11 +91,15 @@ public interface IDataAbilities { /** * Get the currently executing ability, or null if none. * Returns a safe deep copy. Use {@link #getSourceCurrentAbility()} for the live reference. + * + * @return the current ability, or null */ IAbility getCurrentAbility(); /** * Check if any ability is currently executing. + * + * @return true if executing */ boolean isExecutingAbility(); @@ -87,11 +115,15 @@ public interface IDataAbilities { /** * Get the global cooldown timer in ticks. + * + * @return cooldown in ticks */ int getGlobalCooldown(); /** * Set the global cooldown timer in ticks. + * + * @param ticks cooldown in ticks */ void setGlobalCooldown(int ticks); diff --git a/java/noppes/npcs/api/ability/IPlayerAbilityData.java b/java/noppes/npcs/api/ability/IPlayerAbilityData.java index ece63ee..1dad19e 100644 --- a/java/noppes/npcs/api/ability/IPlayerAbilityData.java +++ b/java/noppes/npcs/api/ability/IPlayerAbilityData.java @@ -10,6 +10,8 @@ public interface IPlayerAbilityData { /** * Get all unlocked ability keys. + * + * @return array of ability keys */ String[] getUnlockedAbilities(); @@ -22,26 +24,37 @@ public interface IPlayerAbilityData { /** * Lock (remove) an ability from this player. + * + * @param key the ability key */ void lockAbility(String key); /** * Check if the player has unlocked a specific ability. + * + * @param key the ability key + * @return true if unlocked */ boolean hasUnlockedAbility(String key); /** * Get the currently selected ability index. + * + * @return the selected index */ int getSelectedIndex(); /** * Set the selected ability index. + * + * @param index the ability index */ void setSelectedIndex(int index); /** * Get the key of the currently selected ability. + * + * @return the selected ability key */ String getSelectedAbilityKey(); @@ -57,11 +70,15 @@ public interface IPlayerAbilityData { /** * Check if the player is currently executing an ability. + * + * @return true if executing */ boolean isExecutingAbility(); /** * Get the currently executing ability. + * + * @return the current ability, or null */ IAbility getCurrentAbility(); @@ -77,6 +94,8 @@ public interface IPlayerAbilityData { /** * Check if the player is on universal cooldown. + * + * @return true if on cooldown */ boolean isOnCooldown(); @@ -107,11 +126,16 @@ public interface IPlayerAbilityData { /** * Activate the currently selected ability. + * + * @return true if activated */ boolean activateAbility(); /** * Activate a specific ability by key. + * + * @param key the ability key + * @return true if activated */ boolean activateAbility(String key); @@ -119,24 +143,33 @@ public interface IPlayerAbilityData { /** * Cycle a toggle ability to its next state. - * Off -> State 1 -> State 2 -> ... -> State N -> Off + * Off -> State 1 -> State 2 -> ... -> State N -> Off + * @param key the ability key * @return The new state (0 = off, 1+ = active state number) */ int toggleAbility(String key); /** * Get the current toggle state for an ability. + * + * @param key the ability key * @return 0 if not active, 1+ for active state */ int getToggleState(String key); /** * Set a toggle to a specific state. 0 = deactivate, 1+ = specific state. + * + * @param key the ability key + * @param state the toggle state */ void setToggleState(String key, int state); /** - * Check if a toggle ability is currently active (any state > 0). + * Check if a toggle ability is currently active (any state > 0). + * + * @param key the ability key + * @return true if toggled on */ boolean isAbilityToggled(String key); } diff --git a/java/noppes/npcs/api/ability/data/IEnergyAnchorData.java b/java/noppes/npcs/api/ability/data/IEnergyAnchorData.java index fb8b1c2..5abdbfc 100644 --- a/java/noppes/npcs/api/ability/data/IEnergyAnchorData.java +++ b/java/noppes/npcs/api/ability/data/IEnergyAnchorData.java @@ -5,10 +5,13 @@ package noppes.npcs.api.ability.data; * Controls where the projectile spawns relative to the caster. */ public interface IEnergyAnchorData { - /** @return Anchor point ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */ + /** @return Anchor point ordinal (0=FRONT, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=ABOVE_HEAD, 5=CHEST, 6=EYE). */ int getAnchor(); - /** Set the anchor point. @param anchor Anchor ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */ + /** + * Set the anchor point. + * @param anchor Anchor ordinal (0=FRONT, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=ABOVE_HEAD, 5=CHEST, 6=EYE) + */ void setAnchor(int anchor); /** @return X offset from the anchor point (positive = right). */ diff --git a/java/noppes/npcs/api/block/IBlockScripted.java b/java/noppes/npcs/api/block/IBlockScripted.java index 213c04d..f97b107 100644 --- a/java/noppes/npcs/api/block/IBlockScripted.java +++ b/java/noppes/npcs/api/block/IBlockScripted.java @@ -79,11 +79,13 @@ public interface IBlockScripted extends IBlock { /** * TYPO VERSION + * @return true if entities can pass through this block */ boolean getIsPassible(); /** * TYPO VERSION + * @param bo whether entities can pass through this block */ void setIsPassible(boolean bo); diff --git a/java/noppes/npcs/api/block/ITextPlane.java b/java/noppes/npcs/api/block/ITextPlane.java index 337bf07..ebed3bf 100644 --- a/java/noppes/npcs/api/block/ITextPlane.java +++ b/java/noppes/npcs/api/block/ITextPlane.java @@ -1,42 +1,103 @@ package noppes.npcs.api.block; +/** + * Represents a text plane that can be positioned, rotated, and scaled on a block. + */ public interface ITextPlane { + /** + * Gets the text displayed on this plane. + * @return the display text + */ public String getText(); + /** + * Sets the text displayed on this plane. + * @param text the display text to set + */ public void setText(String text); + /** + * Gets the X-axis rotation in degrees. + * @return the X rotation + */ public int getRotationX(); + /** + * Gets the Y-axis rotation in degrees. + * @return the Y rotation + */ public int getRotationY(); + /** + * Gets the Z-axis rotation in degrees. + * @return the Z rotation + */ public int getRotationZ(); + /** + * Sets the X-axis rotation in degrees. + * @param x the X rotation to set + */ public void setRotationX(int x); + /** + * Sets the Y-axis rotation in degrees. + * @param y the Y rotation to set + */ public void setRotationY(int y); /** - * @param z Default: 0.5 + * Sets the Z-axis rotation in degrees. + * @param z the Z rotation to set. Default: 0.5 */ public void setRotationZ(int z); + /** + * Gets the X-axis positional offset. + * @return the X offset + */ public float getOffsetX(); + /** + * Gets the Y-axis positional offset. + * @return the Y offset + */ public float getOffsetY(); + /** + * Gets the Z-axis positional offset. + * @return the Z offset + */ public float getOffsetZ(); + /** + * Sets the X-axis positional offset. + * @param x the X offset to set + */ public void setOffsetX(float x); + /** + * Sets the Y-axis positional offset. + * @param y the Y offset to set + */ public void setOffsetY(float y); + /** + * Sets the Z-axis positional offset. + * @param z the Z offset to set + */ public void setOffsetZ(float z); + /** + * Gets the scale of the text plane. + * @return the scale factor + */ public float getScale(); /** - * @param scale Default: 1 + * Sets the scale of the text plane. + * @param scale the scale factor to set. Default: 1 */ public void setScale(float scale); } diff --git a/java/noppes/npcs/api/entity/IArrow.java b/java/noppes/npcs/api/entity/IArrow.java index dcd23d7..276e213 100644 --- a/java/noppes/npcs/api/entity/IArrow.java +++ b/java/noppes/npcs/api/entity/IArrow.java @@ -9,9 +9,20 @@ import net.minecraft.entity.projectile.EntityArrow; */ public interface IArrow extends IEntity { + /** + * Gets the entity that shot this arrow. + * @return the shooter entity, or null if none + */ IEntity getShooter(); + /** + * Gets the base damage of this arrow. + * @return the damage value + */ double getDamage(); + /** + * Removes this arrow from the world. + */ void kill(); } diff --git a/java/noppes/npcs/api/entity/IEnergyBarrier.java b/java/noppes/npcs/api/entity/IEnergyBarrier.java index 36999cf..724364d 100644 --- a/java/noppes/npcs/api/entity/IEnergyBarrier.java +++ b/java/noppes/npcs/api/entity/IEnergyBarrier.java @@ -63,6 +63,7 @@ public interface IEnergyBarrier extends IEnergyAbility { /** * Returns the barrier type: 0=Dome, 1=Panel + * @return the barrier type ordinal */ int getBarrierType(); diff --git a/java/noppes/npcs/api/entity/IEnergyBeam.java b/java/noppes/npcs/api/entity/IEnergyBeam.java index 7d9d739..c18c250 100644 --- a/java/noppes/npcs/api/entity/IEnergyBeam.java +++ b/java/noppes/npcs/api/entity/IEnergyBeam.java @@ -13,7 +13,10 @@ import net.minecraft.entity.Entity; */ public interface IEnergyBeam extends IEnergyProjectile { - /** Width of the beam trail. */ + /** + * Width of the beam trail. + * @return the beam width in blocks + */ float getBeamWidth(); void setBeamWidth(float width); diff --git a/java/noppes/npcs/api/entity/IEnergyDisc.java b/java/noppes/npcs/api/entity/IEnergyDisc.java index 17b27df..7e19791 100644 --- a/java/noppes/npcs/api/entity/IEnergyDisc.java +++ b/java/noppes/npcs/api/entity/IEnergyDisc.java @@ -10,7 +10,10 @@ import net.minecraft.entity.Entity; */ public interface IEnergyDisc extends IEnergyProjectile { - /** Radius of the disc. */ + /** + * Radius of the disc. + * @return the disc radius in blocks + */ float getDiscRadius(); void setDiscRadius(float radius); diff --git a/java/noppes/npcs/api/entity/IEnergyDome.java b/java/noppes/npcs/api/entity/IEnergyDome.java index 0a6fcbf..20c6492 100644 --- a/java/noppes/npcs/api/entity/IEnergyDome.java +++ b/java/noppes/npcs/api/entity/IEnergyDome.java @@ -7,7 +7,9 @@ import net.minecraft.entity.Entity; */ public interface IEnergyDome extends IEnergyBarrier { + /** @return The radius of the dome in blocks. */ float getDomeRadius(); + /** @param radius The radius of the dome in blocks. */ void setDomeRadius(float radius); } diff --git a/java/noppes/npcs/api/entity/IEnergyExplosion.java b/java/noppes/npcs/api/entity/IEnergyExplosion.java index 6121dc9..2a9fe91 100644 --- a/java/noppes/npcs/api/entity/IEnergyExplosion.java +++ b/java/noppes/npcs/api/entity/IEnergyExplosion.java @@ -8,7 +8,7 @@ import noppes.npcs.api.INbt; * Created via {@link noppes.npcs.api.IEnergyController#createExplosion}. * Configure visual/damage properties, then call {@link #spawn()} to place in the world. * - * When damage is set (> 0), the explosion will deal area damage on the first tick + * When damage is set (> 0), the explosion will deal area damage on the first tick * with distance-based falloff, routing through energy damage handlers for addon integration. */ public interface IEnergyExplosion extends IEnergyAbility { @@ -29,7 +29,7 @@ public interface IEnergyExplosion extends IEnergyAbility { /** @return Base damage dealt at the center. 0 means visual-only. */ float getDamage(); - /** @param damage Base damage at the center. Setting > 0 enables damage. */ + /** @param damage Base damage at the center. Setting > 0 enables damage. */ void setDamage(float damage); /** @return Base knockback strength. */ @@ -54,7 +54,7 @@ public interface IEnergyExplosion extends IEnergyAbility { /** * Spawn this explosion entity into the world. - * Sends the visual to nearby clients and, if damage > 0, applies area damage on the first tick. + * Sends the visual to nearby clients and, if damage > 0, applies area damage on the first tick. */ void spawn(); } diff --git a/java/noppes/npcs/api/entity/IEnergyLaser.java b/java/noppes/npcs/api/entity/IEnergyLaser.java index 844b1c0..432ab8b 100644 --- a/java/noppes/npcs/api/entity/IEnergyLaser.java +++ b/java/noppes/npcs/api/entity/IEnergyLaser.java @@ -14,7 +14,10 @@ import net.minecraft.entity.Entity; */ public interface IEnergyLaser extends IEnergyProjectile { - /** Width of the laser beam. */ + /** + * Width of the laser beam. + * @return the laser width in blocks + */ float getLaserWidth(); void setLaserWidth(float width); diff --git a/java/noppes/npcs/api/entity/IEnergyPanel.java b/java/noppes/npcs/api/entity/IEnergyPanel.java index 6371973..daa97cc 100644 --- a/java/noppes/npcs/api/entity/IEnergyPanel.java +++ b/java/noppes/npcs/api/entity/IEnergyPanel.java @@ -21,6 +21,7 @@ public interface IEnergyPanel extends IEnergyBarrier { /** * Panel mode: 0=PLACED, 1=HELD, 2=LAUNCHED + * @return the panel mode ordinal */ int getPanelMode(); diff --git a/java/noppes/npcs/api/entity/IEnergyProjectile.java b/java/noppes/npcs/api/entity/IEnergyProjectile.java index 0a339e3..fd93d65 100644 --- a/java/noppes/npcs/api/entity/IEnergyProjectile.java +++ b/java/noppes/npcs/api/entity/IEnergyProjectile.java @@ -23,7 +23,10 @@ public interface IEnergyProjectile extends IEnergyAbility { // ==================== OWNER & TARGET ==================== - /** Sets the owner entity (used for homing return, damage attribution, etc.). */ + /** + * Sets the owner entity (used for homing return, damage attribution, etc.). + * @param owner the entity that owns this projectile + */ void setOwner(IEntity owner); /** @return the entity ID of the current homing/tracking target, or -1 if none */ @@ -32,7 +35,10 @@ public interface IEnergyProjectile extends IEnergyAbility { /** @return the current homing/tracking target entity, or null if none */ IEntity getTarget(); - /** Sets the homing/tracking target entity. Pass null to clear. */ + /** + * Sets the homing/tracking target entity. Pass null to clear. + * @param target the entity to home towards + */ void setTarget(IEntity target); // ==================== SIZE ==================== @@ -40,7 +46,10 @@ public interface IEnergyProjectile extends IEnergyAbility { /** @return the projectile's visual and collision size */ float getSize(); - /** Sets the projectile's visual and collision size. */ + /** + * Sets the projectile's visual and collision size. + * @param size the projectile size + */ void setSize(float size); // ==================== DISPLAY (PROJECTILE-SPECIFIC) ==================== diff --git a/java/noppes/npcs/api/entity/IEnergySlicer.java b/java/noppes/npcs/api/entity/IEnergySlicer.java index 7a20182..5eb0478 100644 --- a/java/noppes/npcs/api/entity/IEnergySlicer.java +++ b/java/noppes/npcs/api/entity/IEnergySlicer.java @@ -9,7 +9,10 @@ import net.minecraft.entity.Entity; */ public interface IEnergySlicer extends IEnergyProjectile { - /** Width of the slicer blade. */ + /** + * Width of the slicer blade. + * @return the width of each slice in blocks + */ float getSliceWidth(); void setSliceWidth(float width); diff --git a/java/noppes/npcs/api/entity/IEnergySweeper.java b/java/noppes/npcs/api/entity/IEnergySweeper.java index 334679e..da0f545 100644 --- a/java/noppes/npcs/api/entity/IEnergySweeper.java +++ b/java/noppes/npcs/api/entity/IEnergySweeper.java @@ -11,35 +11,53 @@ public interface IEnergySweeper extends IEnergyAbility { // ==================== BEAM DIMENSIONS ==================== + /** @return Length of the sweeping beam in blocks. */ float getBeamLength(); + /** @param length Beam length in blocks. */ void setBeamLength(float length); + /** @return Width of the sweeping beam in blocks. */ float getBeamWidth(); + /** @param width Beam width in blocks. */ void setBeamWidth(float width); + /** @return Height of the sweeping beam in blocks. */ float getBeamHeight(); + /** @param height Beam height in blocks. */ void setBeamHeight(float height); // ==================== ROTATION ==================== + /** @return Rotation speed of the sweep in degrees per tick. */ float getSweepSpeed(); + /** @param degreesPerTick Sweep rotation speed in degrees per tick. */ void setSweepSpeed(float degreesPerTick); + /** @return Number of full rotations the beam completes before stopping. */ int getNumberOfRotations(); + /** @param rotations Number of full rotations. */ void setNumberOfRotations(int rotations); + /** @return Whether the beam pivot tracks the target instead of rotating freely. */ boolean isLockOnTarget(); + /** @param lock Whether the beam locks on to the target. */ void setLockOnTarget(boolean lock); // ==================== DAMAGE ==================== + /** @return Damage dealt per hit to entities caught in the beam. */ float getDamage(); + /** @param damage Damage per hit. */ void setDamage(float damage); + /** @return Interval in ticks between damage applications to the same target. */ int getDamageInterval(); + /** @param ticks Damage interval in ticks. */ void setDamageInterval(int ticks); + /** @return Whether the beam can hit through multiple targets. */ boolean isPiercing(); + /** @param piercing Whether the beam pierces through targets. */ void setPiercing(boolean piercing); // ==================== SPAWNING ==================== diff --git a/java/noppes/npcs/api/entity/IEnergyZone.java b/java/noppes/npcs/api/entity/IEnergyZone.java index 35235fc..2dad28a 100644 --- a/java/noppes/npcs/api/entity/IEnergyZone.java +++ b/java/noppes/npcs/api/entity/IEnergyZone.java @@ -90,10 +90,16 @@ public interface IEnergyZone extends IEntity { // ==================== CUSTOM DAMAGE DATA ==================== - /** Get custom damage data for addon handler routing (e.g. DBC damage stats). */ + /** + * Get custom damage data for addon handler routing (e.g. DBC damage stats). + * @return the zone's damage configuration as NBT + */ noppes.npcs.api.INbt getDamageData(); - /** Set custom damage data for addon handler routing. */ + /** + * Set custom damage data for addon handler routing. + * @param data the damage configuration NBT + */ void setDamageData(noppes.npcs.api.INbt data); // ==================== SPAWNING ==================== diff --git a/java/noppes/npcs/api/entity/IEntityLivingBase.java b/java/noppes/npcs/api/entity/IEntityLivingBase.java index fe5bb06..9f7c30c 100644 --- a/java/noppes/npcs/api/entity/IEntityLivingBase.java +++ b/java/noppes/npcs/api/entity/IEntityLivingBase.java @@ -437,6 +437,11 @@ public interface IEntityLivingBase extends IEntity extends IEntity { + /** + * Returns the player who cast this fish hook. + * + * @return the casting player, or null if none. + */ IPlayer getCaster(); + /** + * Removes this fish hook entity from the world. + */ void kill(); } diff --git a/java/noppes/npcs/api/entity/IPlayer.java b/java/noppes/npcs/api/entity/IPlayer.java index 328555a..961bf86 100644 --- a/java/noppes/npcs/api/entity/IPlayer.java +++ b/java/noppes/npcs/api/entity/IPlayer.java @@ -684,6 +684,11 @@ public interface IPlayer extends IEntityLivingBase, IActionManager getActionManager(); + /** + * Returns the members of the player's current party, excluding the player. + * + * @return an array of party members, or an empty array if the player is not in a party. + */ IPlayer[] getPartyMembers(); // ========================================= diff --git a/java/noppes/npcs/api/entity/IThrowable.java b/java/noppes/npcs/api/entity/IThrowable.java index 1321c26..a78e9d8 100644 --- a/java/noppes/npcs/api/entity/IThrowable.java +++ b/java/noppes/npcs/api/entity/IThrowable.java @@ -9,7 +9,15 @@ import net.minecraft.entity.projectile.EntityThrowable; */ public interface IThrowable extends IEntity { + /** + * Returns the entity that threw this throwable. + * + * @return the thrower, or null if unknown. + */ IEntityLivingBase getThrower(); + /** + * Removes this throwable entity from the world. + */ void kill(); } diff --git a/java/noppes/npcs/api/event/IAbilityEvent.java b/java/noppes/npcs/api/event/IAbilityEvent.java index ee47885..75adaa4 100644 --- a/java/noppes/npcs/api/event/IAbilityEvent.java +++ b/java/noppes/npcs/api/event/IAbilityEvent.java @@ -15,26 +15,31 @@ public interface IAbilityEvent extends INpcEvent { /** * Get the entity executing the ability (NPC or Player). + * @return the entity executing the ability */ IEntityLivingBase getEntity(); /** * Get the player executing the ability, or null if the caster is an NPC. + * @return the player executing the ability, or null if NPC */ IPlayer getPlayer(); /** * Whether the entity executing the ability is an NPC. + * @return true if the executor is an NPC */ boolean isNPC(); /** * Get the ability involved in this event. + * @return the ability being executed */ IAbility getAbility(); /** * Get the target of the ability, or null if no target. + * @return the current target entity */ IEntityLivingBase getTarget(); @@ -60,11 +65,13 @@ public interface IAbilityEvent extends INpcEvent { interface InterruptEvent extends IAbilityEvent { /** * Get the damage source that caused the interruption. + * @return the damage source */ IDamageSource getDamageSource(); /** * Get the amount of damage that caused the interruption. + * @return the final damage dealt */ float getDamage(); } @@ -105,36 +112,43 @@ public interface IAbilityEvent extends INpcEvent { interface HitEvent extends IAbilityEvent { /** * Get the entity that was hit by the ability. + * @return the entity that was hit */ IEntityLivingBase getHitEntity(); /** * Get the damage amount. + * @return the damage amount */ float getDamage(); /** * Set the damage amount. Allows scripts to modify damage. + * @param damage the new damage amount */ void setDamage(float damage); /** * Get the horizontal knockback amount. + * @return the knockback strength */ float getKnockback(); /** * Set the horizontal knockback amount. + * @param knockback the new knockback strength */ void setKnockback(float knockback); /** * Get the vertical knockback (upward force) amount. + * @return the upward knockback component */ float getKnockbackUp(); /** * Set the vertical knockback (upward force) amount. + * @param knockbackUp the new upward knockback component */ void setKnockbackUp(float knockbackUp); } @@ -147,11 +161,13 @@ public interface IAbilityEvent extends INpcEvent { /** * Get the current phase of the ability. * 0 = IDLE, 1 = WINDUP, 2 = ACTIVE, 3 = DAZED, 4 = BURST_DELAY + * @return the current ability phase (0=IDLE, 1=WINDUP, 2=ACTIVE, 3=DAZED, 4=BURST_DELAY) */ int getAbilityPhase(); /** * Get the current tick count within the phase. + * @return the current tick within the phase */ int getTick(); } diff --git a/java/noppes/npcs/api/event/IAnimationEvent.java b/java/noppes/npcs/api/event/IAnimationEvent.java index e5ce165..31d607c 100644 --- a/java/noppes/npcs/api/event/IAnimationEvent.java +++ b/java/noppes/npcs/api/event/IAnimationEvent.java @@ -6,15 +6,22 @@ import noppes.npcs.api.handler.data.IAnimation; import noppes.npcs.api.handler.data.IAnimationData; import noppes.npcs.api.handler.data.IFrame; +/** + * Events fired during entity animation playback. + */ public interface IAnimationEvent extends ICustomNPCsEvent { + /** @return the animation being played. */ IAnimation getAnimation(); + /** @return the animation data managing the playback. */ IAnimationData getAnimationData(); + /** @return the animatable entity playing the animation. */ IAnimatable getEntity(); /** + * Fired when an animation starts playing. Cancelable. * @hookName animationStart */ @Cancelable @@ -23,16 +30,20 @@ public interface IAnimationEvent extends ICustomNPCsEvent { } /** + * Fired when an animation finishes playing. * @hookName animationEnd */ interface Ended extends IAnimationEvent { } + /** Events fired when animation frames are entered or exited. */ interface IFrameEvent extends IAnimationEvent { + /** @return the frame index. */ int getIndex(); + /** @return the frame data. */ IFrame getFrame(); /** diff --git a/java/noppes/npcs/api/event/IBlockEvent.java b/java/noppes/npcs/api/event/IBlockEvent.java index 67bece3..f3e2046 100644 --- a/java/noppes/npcs/api/event/IBlockEvent.java +++ b/java/noppes/npcs/api/event/IBlockEvent.java @@ -6,7 +6,11 @@ import noppes.npcs.api.IPos; import noppes.npcs.api.entity.IEntity; import noppes.npcs.api.entity.IPlayer; +/** + * Events fired for scripted blocks, including interactions, redstone, and entity collisions. + */ public interface IBlockEvent extends ICustomNPCsEvent { + /** @return the scripted block associated with this event. */ IBlock getBlock(); /** diff --git a/java/noppes/npcs/api/event/IChainEvent.java b/java/noppes/npcs/api/event/IChainEvent.java index 7ab8fae..3829caf 100644 --- a/java/noppes/npcs/api/event/IChainEvent.java +++ b/java/noppes/npcs/api/event/IChainEvent.java @@ -15,36 +15,43 @@ public interface IChainEvent extends ICustomNPCsEvent { /** * Get the entity executing the chain (NPC or Player). + * @return the entity executing the chain */ IEntityLivingBase getEntity(); /** * Get the player executing the chain, or null if the caster is an NPC. + * @return the player executing the chain, or null if NPC */ IPlayer getPlayer(); /** * Get the NPC executing the chain, or null if the caster is a player. + * @return the NPC executing the chain, or null if player */ ICustomNpc getNpc(); /** * Whether the entity executing the chain is an NPC. + * @return true if the executor is an NPC */ boolean isNPC(); /** * Get the chained ability being executed. + * @return the chained ability being executed */ IChainedAbility getChain(); /** * Get the target of the chain, or null if no target. + * @return the current target entity */ IEntityLivingBase getTarget(); /** * Get the current entry index within the chain (0-based). + * @return the current entry index in the chain */ int getEntryIndex(); @@ -69,11 +76,13 @@ public interface IChainEvent extends ICustomNPCsEvent { interface InterruptEvent extends IChainEvent { /** * Get the damage source that caused the interruption. + * @return the damage source used for this hit */ IDamageSource getDamageSource(); /** * Get the amount of damage that caused the interruption. + * @return the damage amount */ float getDamage(); } diff --git a/java/noppes/npcs/api/event/ICustomGuiEvent.java b/java/noppes/npcs/api/event/ICustomGuiEvent.java index d5b3578..0e6ec3e 100644 --- a/java/noppes/npcs/api/event/ICustomGuiEvent.java +++ b/java/noppes/npcs/api/event/ICustomGuiEvent.java @@ -4,10 +4,15 @@ import cpw.mods.fml.common.eventhandler.Cancelable; import noppes.npcs.api.gui.ICustomGui; import noppes.npcs.api.item.IItemStack; +/** + * Events fired when a player interacts with a custom GUI. + */ public interface ICustomGuiEvent extends IPlayerEvent { + /** @return the custom GUI associated with this event. */ ICustomGui getGui(); + /** @return the component ID that triggered this event. */ int getId(); /** diff --git a/java/noppes/npcs/api/event/ICustomNPCsEvent.java b/java/noppes/npcs/api/event/ICustomNPCsEvent.java index 961ecf0..bb585a0 100644 --- a/java/noppes/npcs/api/event/ICustomNPCsEvent.java +++ b/java/noppes/npcs/api/event/ICustomNPCsEvent.java @@ -5,8 +5,12 @@ import noppes.npcs.api.IPos; import noppes.npcs.api.IWorld; import noppes.npcs.api.handler.data.INaturalSpawn; +/** + * Base interface for all CustomNPC+ script events. + */ public interface ICustomNPCsEvent { + /** @return the script hook name that triggered this event. */ String getHookName(); /** diff --git a/java/noppes/npcs/api/event/IDialogEvent.java b/java/noppes/npcs/api/event/IDialogEvent.java index 5b3d99a..6d37d15 100644 --- a/java/noppes/npcs/api/event/IDialogEvent.java +++ b/java/noppes/npcs/api/event/IDialogEvent.java @@ -3,23 +3,38 @@ package noppes.npcs.api.event; import cpw.mods.fml.common.eventhandler.Cancelable; import noppes.npcs.api.handler.data.IDialog; +/** + * Events fired during dialog interactions between a player and an NPC. + */ public interface IDialogEvent extends IPlayerEvent { + /** @return the dialog associated with this event. */ IDialog getDialog(); + /** @return the dialog's unique ID. */ int getDialogId(); + /** @return the selected dialog option ID. */ int getOptionId(); + /** + * Fired when a dialog is opened. Cancelable. + * @hookName dialogOpen + */ @Cancelable interface DialogOpen extends IDialogEvent { } + /** + * Fired when a dialog option is selected. Cancelable. + * @hookName dialogOption + */ @Cancelable interface DialogOption extends IDialogEvent { } /** + * Fired when a dialog is closed. * @hookName dialogClose */ interface DialogClosed extends IDialogEvent { diff --git a/java/noppes/npcs/api/event/IEnergyBarrierEvent.java b/java/noppes/npcs/api/event/IEnergyBarrierEvent.java index 3b7f602..2f7e6c2 100644 --- a/java/noppes/npcs/api/event/IEnergyBarrierEvent.java +++ b/java/noppes/npcs/api/event/IEnergyBarrierEvent.java @@ -4,36 +4,48 @@ import noppes.npcs.api.entity.IEnergyBarrier; import noppes.npcs.api.entity.IEnergyProjectile; import noppes.npcs.api.entity.IEntity; +/** + * Events fired during energy barrier lifecycle and interactions. + */ public interface IEnergyBarrierEvent extends ICustomNPCsEvent { + /** @return the energy barrier entity. */ IEnergyBarrier getBarrier(); + /** @return the entity that owns this barrier. */ IEntity getOwner(); /** + * Fired when an energy barrier is spawned. * @hookName energyBarrierSpawned */ interface SpawnedEvent extends IEnergyBarrierEvent { } /** + * Fired each tick while the barrier exists. * @hookName energyBarrierTick */ interface UpdateEvent extends IEnergyBarrierEvent { } /** + * Fired when the barrier is hit by an energy projectile. * @hookName energyBarrierHit */ interface HitEvent extends IEnergyBarrierEvent { + /** @return the projectile that hit the barrier. */ IEnergyProjectile getProjectile(); + /** @return the damage dealt. */ float getDamage(); + /** @param damage the new damage value. */ void setDamage(float damage); } /** + * Fired when the barrier is destroyed. * @hookName energyBarrierDestroyed */ interface DestroyedEvent extends IEnergyBarrierEvent { diff --git a/java/noppes/npcs/api/event/IEnergyProjectileEvent.java b/java/noppes/npcs/api/event/IEnergyProjectileEvent.java index 80461f2..d1498fd 100644 --- a/java/noppes/npcs/api/event/IEnergyProjectileEvent.java +++ b/java/noppes/npcs/api/event/IEnergyProjectileEvent.java @@ -4,43 +4,57 @@ import noppes.npcs.api.IBlock; import noppes.npcs.api.entity.IEnergyProjectile; import noppes.npcs.api.entity.IEntity; +/** + * Events fired during energy projectile lifecycle and impacts. + */ public interface IEnergyProjectileEvent extends ICustomNPCsEvent { + /** @return the energy projectile entity. */ IEnergyProjectile getProjectile(); + /** @return the entity that fired this projectile. */ IEntity getOwner(); /** + * Fired when an energy projectile is launched. * @hookName energyProjectileFired */ interface FiredEvent extends IEnergyProjectileEvent { } /** + * Fired each tick while the projectile exists. * @hookName energyProjectileTick */ interface UpdateEvent extends IEnergyProjectileEvent { } /** + * Fired when the projectile hits an entity. * @hookName energyProjectileEntityImpact */ interface EntityImpactEvent extends IEnergyProjectileEvent { + /** @return the entity that was hit. */ IEntity getTarget(); + /** @return the damage dealt. */ float getDamage(); + /** @param damage the new damage value. */ void setDamage(float damage); } /** + * Fired when the projectile hits a block. * @hookName energyProjectileBlockImpact */ interface BlockImpactEvent extends IEnergyProjectileEvent { + /** @return the block that was hit. */ IBlock getBlock(); } /** + * Fired when the projectile expires without hitting anything. * @hookName energyProjectileExpired */ interface ExpiredEvent extends IEnergyProjectileEvent { diff --git a/java/noppes/npcs/api/event/IFactionEvent.java b/java/noppes/npcs/api/event/IFactionEvent.java index 6750588..8a0c8fe 100644 --- a/java/noppes/npcs/api/event/IFactionEvent.java +++ b/java/noppes/npcs/api/event/IFactionEvent.java @@ -3,14 +3,24 @@ package noppes.npcs.api.event; import cpw.mods.fml.common.eventhandler.Cancelable; import noppes.npcs.api.handler.data.IFaction; +/** + * Events fired when a player's faction standing changes. + */ public interface IFactionEvent extends IPlayerEvent { + /** @return the faction involved in this event. */ IFaction getFaction(); + /** + * Fired when a player's faction points change. Cancelable. + * @hookName factionPoints + */ @Cancelable interface FactionPoints extends IFactionEvent { + /** @return true if the points decreased, false if increased. */ boolean decreased(); + /** @return the amount of points changed. */ int getPoints(); } } diff --git a/java/noppes/npcs/api/event/IForgeEvent.java b/java/noppes/npcs/api/event/IForgeEvent.java index a88934c..028e041 100644 --- a/java/noppes/npcs/api/event/IForgeEvent.java +++ b/java/noppes/npcs/api/event/IForgeEvent.java @@ -4,25 +4,34 @@ import cpw.mods.fml.common.eventhandler.Event; import noppes.npcs.api.IWorld; import noppes.npcs.api.entity.IEntity; +/** + * Wrapper events for Forge events, allowing scripts to listen for native Forge events. + */ public interface IForgeEvent extends ICustomNPCsEvent { + /** @return the underlying Forge event. */ Event getEvent(); /** + * Fired for Forge world events. * @hookName forgeWorld */ interface WorldEvent extends IForgeEvent { + /** @return the world associated with this event. */ IWorld getWorld(); } /** + * Fired for Forge entity events. * @hookName forgeEntity */ interface EntityEvent extends IForgeEvent { + /** @return the entity associated with this event. */ IEntity getEntity(); } /** + * Fired during Forge initialization. * @hookName forgeInit */ interface InitEvent extends IForgeEvent { diff --git a/java/noppes/npcs/api/event/IItemEvent.java b/java/noppes/npcs/api/event/IItemEvent.java index c6c2bde..44a1c7e 100644 --- a/java/noppes/npcs/api/event/IItemEvent.java +++ b/java/noppes/npcs/api/event/IItemEvent.java @@ -6,113 +6,185 @@ import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.item.IItemCustomizable; import noppes.npcs.api.item.IItemStack; +/** + * Events fired for scripted/customizable items during their lifecycle and interactions. + */ public interface IItemEvent extends ICustomNPCsEvent { + /** @return the customizable item associated with this event. */ IItemCustomizable getItem(); + /** + * Fired when the item is initialized. + * @hookName init + */ interface InitEvent extends IItemEvent { } /** + * Fired each tick while the item exists in an entity's inventory. * @hookName tick */ interface UpdateEvent extends IItemEvent { + /** @return the entity holding the item. */ IEntity getEntity(); } + /** + * Fired when the item is tossed/dropped. Cancelable. + * @hookName tossed + */ @Cancelable interface TossedEvent extends IItemEvent { + /** @return the dropped item entity. */ IEntity getEntity(); + /** @return the player who dropped the item. */ IPlayer getPlayer(); } + /** + * Fired when the item is picked up. + * @hookName pickedUp + */ interface PickedUpEvent extends IItemEvent { + /** @return the player who picked up the item. */ IPlayer getPlayer(); } + /** + * Fired when the item entity spawns in the world. Cancelable. + * @hookName spawn + */ @Cancelable interface SpawnEvent extends IItemEvent { + /** @return the spawned item entity. */ IEntity getEntity(); } + /** + * Fired when the item is used to interact with an entity. Cancelable. + * @hookName interact + */ @Cancelable interface InteractEvent extends IItemEvent { + /** @return the interaction type. */ int getType(); + /** @return the target entity. */ IEntity getTarget(); + /** @return the player performing the interaction. */ IPlayer getPlayer(); } + /** + * Fired when the item is right-clicked. Cancelable. + * @hookName rightClick + */ @Cancelable interface RightClickEvent extends IItemEvent { + /** @return the click type. */ int getType(); + /** @return the target (entity or block). */ Object getTarget(); + /** @return the player who right-clicked. */ IPlayer getPlayer(); } + /** + * Fired when the item is used to attack an entity. Cancelable. + * @hookName attack + */ @Cancelable interface AttackEvent extends IItemEvent { + /** @return the attack type. */ int getType(); + /** @return the entity being attacked. */ IEntity getTarget(); + /** @return the entity swinging the item. */ IEntity getSwingingEntity(); } /** + * Fired when the player starts using the item (e.g., drawing a bow). * @hookName startItem */ interface StartUsingItem extends IItemEvent { + /** @return the player using the item. */ IPlayer getPlayer(); - int getDuration(); - } - - interface UsingItem extends IItemEvent { - IPlayer getPlayer(); - + /** @return the use duration in ticks. */ int getDuration(); } /** + * Fired each tick while the player is using the item. + * @hookName usingItem + */ + interface UsingItem extends IItemEvent { + /** @return the player using the item. */ + IPlayer getPlayer(); + + /** @return the remaining use duration in ticks. */ + int getDuration(); + } + + /** + * Fired when the player stops using the item before completion. * @hookName stopItem */ interface StopUsingItem extends IItemEvent { + /** @return the player who stopped using the item. */ IPlayer getPlayer(); + /** @return the remaining use duration in ticks. */ int getDuration(); } /** + * Fired when the player finishes using the item (full duration). * @hookName finishItem */ interface FinishUsingItem extends IItemEvent { + /** @return the player who finished using the item. */ IPlayer getPlayer(); + /** @return the total use duration in ticks. */ int getDuration(); } - // onBreakEvent if Durability Expires or Consumed + /** + * Fired when the item breaks due to durability loss or consumption. + * @hookName breakItem + */ interface BreakItem extends IItemEvent { - + /** @return the item stack that broke. */ IItemStack getBrokenStack(); + /** @return the player whose item broke. */ IPlayer getPlayer(); } - // onRepairEvent + /** + * Fired when the item is repaired on an anvil. + * @hookName repairItem + */ interface RepairItem extends IItemEvent { - + /** @return the left input item. */ IItemStack getLeft(); + /** @return the right input item (repair material). */ IItemStack getRight(); + /** @return the resulting output item. */ IItemStack getOutput(); + /** @return the chance the anvil breaks after this repair. */ float getAnvilBreakChance(); } } diff --git a/java/noppes/npcs/api/event/ILinkedItemEvent.java b/java/noppes/npcs/api/event/ILinkedItemEvent.java index 6e9194c..6e15606 100644 --- a/java/noppes/npcs/api/event/ILinkedItemEvent.java +++ b/java/noppes/npcs/api/event/ILinkedItemEvent.java @@ -1,18 +1,24 @@ package noppes.npcs.api.event; +/** + * Events fired for linked items when their version changes or when they are being built. + */ public interface ILinkedItemEvent extends IItemEvent { /** + * Fired when the linked item's version changes. * @hookName versionChanged */ interface VersionChangeEvent extends IItemEvent { - + /** @return the new version number. */ int getVersion(); + /** @return the previous version number. */ int getPreviousVersion(); } /** + * Fired when the linked item is being built/constructed. * @hookName buildingItem */ interface BuildEvent extends IItemEvent { diff --git a/java/noppes/npcs/api/event/INpcEvent.java b/java/noppes/npcs/api/event/INpcEvent.java index 4c4bac9..ee22b0e 100644 --- a/java/noppes/npcs/api/event/INpcEvent.java +++ b/java/noppes/npcs/api/event/INpcEvent.java @@ -9,55 +9,94 @@ import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.handler.data.IDialog; import noppes.npcs.api.item.IItemStack; +/** + * Events fired for CustomNPC entities during their lifecycle and interactions. + */ public interface INpcEvent extends ICustomNPCsEvent { + /** @return the NPC associated with this event. */ ICustomNpc getNpc(); + /** + * Fired when an NPC timer triggers. + * @hookName timer + */ interface TimerEvent extends INpcEvent { + /** @return the timer ID. */ int getId(); } + /** + * Fired when an entity collides with the NPC. + * @hookName collide + */ interface CollideEvent extends INpcEvent { + /** @return the colliding entity. */ IEntity getEntity(); } + /** + * Fired when the NPC takes damage. Cancelable. + * @hookName damaged + */ @Cancelable interface DamagedEvent extends INpcEvent { - + /** @return the entity that caused the damage, or null. */ IEntity getSource(); + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the damage amount. */ float getDamage(); + /** @param damage the new damage amount. */ void setDamage(float damage); + /** @param bo whether to clear the NPC's current target after damage. */ void setClearTarget(boolean bo); + /** @return whether the NPC's target will be cleared after damage. */ boolean getClearTarget(); + /** @return the damage type string. */ String getType(); } + /** + * Fired when the NPC launches a ranged attack. Cancelable. + * @hookName rangedLaunched + */ @Cancelable interface RangedLaunchedEvent extends INpcEvent { + /** @return the target entity. */ IEntityLivingBase getTarget(); + /** @param damage the new ranged damage. */ void setDamage(float damage); - float getDamage(); - } - - @Cancelable - interface MeleeAttackEvent extends INpcEvent { - IEntityLivingBase getTarget(); - - void setDamage(float damage); - + /** @return the ranged damage. */ float getDamage(); } /** + * Fired when the NPC performs a melee attack. Cancelable. + * @hookName meleeAttack + */ + @Cancelable + interface MeleeAttackEvent extends INpcEvent { + /** @return the target entity. */ + IEntityLivingBase getTarget(); + + /** @param damage the new melee damage. */ + void setDamage(float damage); + + /** @return the melee damage. */ + float getDamage(); + } + + /** + * Fired when the NPC swings its weapon. * @hookName meleeSwing */ interface SwingEvent extends INpcEvent { @@ -71,78 +110,126 @@ public interface INpcEvent extends ICustomNPCsEvent { } /** + * Fired when the NPC kills an entity. * @hookName kills */ interface KilledEntityEvent { + /** @return the entity that was killed. */ IEntityLivingBase getEntity(); } /** + * Fired when the NPC dies. Cancelable. * @hookName killed */ @Cancelable interface DiedEvent extends INpcEvent { + /** @return the entity that killed this NPC, or null. */ IEntity getSource(); + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the damage type string. */ String getType(); + /** @param droppedItems the items to drop on death. */ void setDroppedItems(IItemStack[] droppedItems); + /** @return the items dropped on death. */ IItemStack[] getDroppedItems(); + /** @param expDropped the experience to drop on death. */ void setExpDropped(int expDropped); + /** @return the experience dropped on death. */ int getExpDropped(); } + /** + * Fired when a player interacts with the NPC. Cancelable. + * @hookName interact + */ @Cancelable interface InteractEvent extends INpcEvent { + /** @return the interacting player. */ IPlayer getPlayer(); } + /** + * Fired when a dialog opens with the NPC. Cancelable. + * @hookName dialog + */ @Cancelable interface DialogEvent extends INpcEvent { + /** @return the interacting player. */ IPlayer getPlayer(); + /** @return the dialog. */ IDialog getDialog(); + /** @return the dialog ID. */ int getDialogId(); + /** @return the selected option ID. */ int getOptionId(); } + /** + * Fired when a dialog with the NPC is closed. + * @hookName dialogClosed + */ interface DialogClosedEvent extends INpcEvent { + /** @return the player who closed the dialog. */ IPlayer getPlayer(); + /** @return the dialog. */ IDialog getDialog(); + /** @return the dialog ID. */ int getDialogId(); + /** @return the selected option ID. */ int getOptionId(); } + /** + * Fired when the NPC loses its current target. Cancelable. + * @hookName targetLost + */ @Cancelable interface TargetLostEvent extends INpcEvent { + /** @return the target being lost. */ IEntityLivingBase getTarget(); + /** @return the new target, or null. */ IEntityLivingBase getNewTarget(); } + /** + * Fired when the NPC acquires a new target. Cancelable. + * @hookName target + */ @Cancelable interface TargetEvent extends INpcEvent { + /** @param entity the new target to set. */ void setTarget(IEntityLivingBase entity); + /** @return the current target. */ IEntityLivingBase getTarget(); } /** + * Fired each tick for the NPC. * @hookName tick */ interface UpdateEvent extends INpcEvent { } + /** + * Fired when the NPC is initialized. + * @hookName init + */ interface InitEvent extends INpcEvent { } } diff --git a/java/noppes/npcs/api/event/IPartyEvent.java b/java/noppes/npcs/api/event/IPartyEvent.java index d1994de..5005db5 100644 --- a/java/noppes/npcs/api/event/IPartyEvent.java +++ b/java/noppes/npcs/api/event/IPartyEvent.java @@ -5,45 +5,82 @@ import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.handler.data.IParty; import noppes.npcs.api.handler.data.IQuest; +/** + * Events fired during party operations such as quest progress, invitations, kicks, and disbanding. + */ public interface IPartyEvent { + /** @return the party involved in this event. */ IParty getParty(); + /** @return the quest associated with this party event. */ IQuest getQuest(); + /** + * Fired when a party quest is completed. + * @hookName partyQuestCompleted + */ interface PartyQuestCompletedEvent extends IPartyEvent { } + /** + * Fired when a quest is assigned to the party. Cancelable. + * @hookName partyQuestSet + */ @Cancelable interface PartyQuestSetEvent extends IPartyEvent { } + /** + * Fired when a party quest is turned in. Cancelable. + * @hookName partyQuestTurnedIn + */ @Cancelable interface PartyQuestTurnedInEvent extends IPartyEvent { } + /** + * Fired when a player is invited to the party. Cancelable. + * @hookName partyInvite + */ @Cancelable interface PartyInviteEvent extends IPartyEvent { - + /** @return the invited player. */ IPlayer getPlayer(); + /** @return the invited player's name. */ String getPlayerName(); - } + /** + * Fired when a player is kicked from the party. Cancelable. + * @hookName partyKick + */ @Cancelable interface PartyKickEvent extends IPartyEvent { + /** @return the kicked player. */ IPlayer getPlayer(); + /** @return the kicked player's name. */ String getPlayerName(); } + /** + * Fired when a player voluntarily leaves the party. + * @hookName partyLeave + */ interface PartyLeaveEvent extends IPartyEvent { + /** @return the leaving player. */ IPlayer getPlayer(); + /** @return the leaving player's name. */ String getPlayerName(); } + /** + * Fired when the party is disbanded. + * @hookName partyDisband + */ interface PartyDisbandEvent extends IPartyEvent { } } diff --git a/java/noppes/npcs/api/event/IPlayerEvent.java b/java/noppes/npcs/api/event/IPlayerEvent.java index 2d36189..88c8fd4 100644 --- a/java/noppes/npcs/api/event/IPlayerEvent.java +++ b/java/noppes/npcs/api/event/IPlayerEvent.java @@ -11,307 +11,537 @@ import noppes.npcs.api.handler.data.IPlayerEffect; import noppes.npcs.api.handler.data.IProfile; import noppes.npcs.api.item.IItemStack; +/** + * Events fired for player actions including combat, items, movement, and interactions. + */ public interface IPlayerEvent extends ICustomNPCsEvent { + /** @return the player associated with this event. */ IPlayer getPlayer(); + /** + * Fired when the player sends a chat message. Cancelable. + * @hookName chat + */ @Cancelable interface ChatEvent extends IPlayerEvent { + /** @param message the new chat message. */ void setMessage(String message); + /** @return the chat message. */ String getMessage(); } + /** + * Fired when the player presses or releases a key. + * @hookName keyPressed + */ interface KeyPressedEvent extends IPlayerEvent { + /** @return the key code. */ int getKey(); + /** @return true if Ctrl is held. */ boolean isCtrlPressed(); + /** @return true if Alt is held. */ boolean isAltPressed(); + /** @return true if Shift is held. */ boolean isShiftPressed(); + /** @return true if Meta is held. */ boolean isMetaPressed(); + /** @return true if the key is being pressed down, false if released. */ boolean keyDown(); + /** @return array of currently held key codes. */ int[] getKeysDown(); } + /** + * Fired when the player clicks a mouse button. + * @hookName mouseClicked + */ interface MouseClickedEvent extends IPlayerEvent { + /** @return the mouse button index. */ int getButton(); + /** @return the mouse wheel scroll delta. */ int getMouseWheel(); + /** @return true if the button is being pressed down. */ boolean buttonDown(); + /** @return true if Ctrl is held. */ boolean isCtrlPressed(); + /** @return true if Alt is held. */ boolean isAltPressed(); + /** @return true if Shift is held. */ boolean isShiftPressed(); + /** @return true if Meta is held. */ boolean isMetaPressed(); + /** @return array of currently held key codes. */ int[] getKeysDown(); } + /** + * Fired when the player picks up experience orbs. + * @hookName pickupXP + */ interface PickupXPEvent extends IPlayerEvent { + /** @return the amount of XP picked up. */ int getAmount(); } + /** + * Fired when the player levels up. + * @hookName levelUp + */ interface LevelUpEvent extends IPlayerEvent { + /** @return the number of levels gained. */ int getChange(); } + /** + * Fired when the player logs out. + * @hookName logout + */ interface LogoutEvent extends IPlayerEvent { } + /** + * Fired when the player logs in. + * @hookName login + */ interface LoginEvent extends IPlayerEvent { } + /** + * Fired when the player respawns after death. + * @hookName respawn + */ interface RespawnEvent extends IPlayerEvent { } /** + * Fired when the player changes dimensions. * @hookName changedDim */ interface ChangedDimension extends IPlayerEvent { + /** @return the dimension ID the player came from. */ int getFromDim(); + /** @return the dimension ID the player traveled to. */ int getToDim(); } + /** + * Fired when a player timer triggers. + * @hookName timer + */ interface TimerEvent extends IPlayerEvent { + /** @return the timer ID. */ int getId(); } + /** + * Fired when the player is attacked (before armor reduction). Cancelable. + * @hookName attacked + */ @Cancelable interface AttackedEvent extends IPlayerEvent { + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the attacking entity, or null. */ IEntity getSource(); + /** @return the raw damage amount. */ float getDamage(); } + /** + * Fired when the player takes damage (after armor reduction). Cancelable. + * @hookName damaged + */ @Cancelable interface DamagedEvent extends IPlayerEvent { + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the damaging entity, or null. */ IEntity getSource(); + /** @return the damage amount after reduction. */ float getDamage(); } + /** + * Fired when the player is about to be struck by lightning. Cancelable. + * @hookName lightning + */ @Cancelable interface LightningEvent extends IPlayerEvent { } /** + * Fired when a sound is played for the player. Cancelable. * @hookName playSound */ @Cancelable interface SoundEvent extends IPlayerEvent { + /** @return the sound resource name. */ String getName(); + /** @return the sound pitch. */ float getPitch(); + /** @return the sound volume. */ float getVolume(); } + /** + * Fired when the player falls. Cancelable. + * @hookName fall + */ @Cancelable interface FallEvent extends IPlayerEvent { + /** @return the fall distance in blocks. */ float getDistance(); } + /** + * Fired when the player jumps. + * @hookName jump + */ interface JumpEvent extends IPlayerEvent { } /** + * Fired when the player kills an entity. * @hookName kills */ interface KilledEntityEvent extends IPlayerEvent { + /** @return the killed entity. */ IEntityLivingBase getEntity(); } /** + * Fired when the player dies. * @hookName killed */ interface DiedEvent extends IPlayerEvent { + /** @return the damage source that killed the player. */ IDamageSource getDamageSource(); + /** @return the damage type string. */ String getType(); + /** @return the entity that killed the player, or null. */ IEntity getSource(); } + /** + * Fired when the player launches a ranged weapon (e.g., bow). Cancelable. + * @hookName rangedLaunched + */ @Cancelable interface RangedLaunchedEvent extends IPlayerEvent { + /** @return the bow item. */ IItemStack getBow(); + /** @return the charge level of the bow. */ int getCharge(); } + /** + * Fired when the player attacks an entity. Cancelable. + * @hookName attack + */ @Cancelable interface AttackEvent extends IPlayerEvent { + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the target entity. */ IEntity getTarget(); + /** @return the attack damage. */ float getDamage(); } + /** + * Fired when the player deals damage to an entity (after hit). Cancelable. + * @hookName damagedEntity + */ @Cancelable interface DamagedEntityEvent extends IPlayerEvent { + /** @return the damage source details. */ IDamageSource getDamageSource(); + /** @return the damaged entity. */ IEntity getTarget(); + /** @return the damage dealt. */ float getDamage(); } + /** + * Fired when the player closes a container. + * @hookName containerClosed + */ interface ContainerClosed extends IPlayerEvent { + /** @return the closed container. */ IContainer getContainer(); } + /** + * Fired when the player opens a container. + * @hookName containerOpen + */ interface ContainerOpen extends IPlayerEvent { + /** @return the opened container. */ IContainer getContainer(); } + /** + * Fired when the player picks up an item. Cancelable. + * @hookName pickUp + */ @Cancelable interface PickUpEvent extends IPlayerEvent { + /** @return the picked up item. */ IItemStack getItem(); } + /** + * Fired when items are dropped from the player's inventory (e.g., on death). Cancelable. + * @hookName drop + */ @Cancelable interface DropEvent extends IPlayerEvent { + /** @return the dropped items. */ IItemStack[] getItems(); } + /** + * Fired when the player tosses a single item. Cancelable. + * @hookName toss + */ @Cancelable interface TossEvent extends IPlayerEvent { + /** @return the tossed item. */ IItemStack getItem(); } + /** + * Fired when the player interacts with an entity. Cancelable. + * @hookName interact + */ @Cancelable interface InteractEvent extends IPlayerEvent { + /** @return the interaction type. */ int getType(); + /** @return the target entity. */ IEntity getTarget(); } + /** + * Fired when the player right-clicks. Cancelable. + * @hookName rightClick + */ @Cancelable interface RightClickEvent extends IPlayerEvent { + /** @return the click type. */ int getType(); + /** @return the target (entity, block, or null). */ Object getTarget(); + /** @return the player. */ IPlayer getPlayer(); } /** + * Fired each tick for the player. * @hookName tick */ interface UpdateEvent extends IPlayerEvent { } + /** + * Fired when the player script is initialized. + * @hookName init + */ interface InitEvent extends IPlayerEvent { } /** + * Fired when the player starts using an item (e.g., drawing a bow). * @hookName startItem */ interface StartUsingItem extends IPlayerEvent { + /** @return the item being used. */ IItemStack getItem(); - int getDuration(); - } - - interface UsingItem extends IPlayerEvent { - IItemStack getItem(); - + /** @return the use duration in ticks. */ int getDuration(); } /** + * Fired each tick while the player is using an item. + * @hookName usingItem + */ + interface UsingItem extends IPlayerEvent { + /** @return the item being used. */ + IItemStack getItem(); + + /** @return the remaining use duration in ticks. */ + int getDuration(); + } + + /** + * Fired when the player stops using an item before completion. * @hookName stopItem */ interface StopUsingItem extends IPlayerEvent { + /** @return the item that was being used. */ IItemStack getItem(); + /** @return the remaining use duration in ticks. */ int getDuration(); } /** + * Fired when the player finishes using an item (full duration). * @hookName finishItem */ interface FinishUsingItem extends IPlayerEvent { + /** @return the item that was used. */ IItemStack getItem(); + /** @return the total use duration in ticks. */ int getDuration(); } /** + * Fired when the player breaks a block. Cancelable. * @hookName breakBlock */ @Cancelable interface BreakEvent extends IPlayerEvent { + /** @return the block being broken. */ IBlock getBlock(); + /** @return the experience dropped from breaking the block. */ int getExp(); } + /** + * Fired when the player uses a hoe on a block. + * @hookName useHoe + */ interface UseHoeEvent extends IPlayerEvent { + /** @return the hoe item. */ IItemStack getHoe(); + /** @return the X coordinate of the hoed block. */ int getX(); + /** @return the Y coordinate of the hoed block. */ int getY(); + /** @return the Z coordinate of the hoed block. */ int getZ(); } + /** + * Fired when the player wakes up from a bed. + * @hookName wakeUp + */ interface WakeUpEvent extends IPlayerEvent { + /** @return true if the bed position was set as spawn. */ boolean setSpawn(); } + /** + * Fired when the player sleeps in a bed. + * @hookName sleep + */ interface SleepEvent extends IPlayerEvent { + /** @return the X coordinate of the bed. */ int getX(); + /** @return the Y coordinate of the bed. */ int getY(); + /** @return the Z coordinate of the bed. */ int getZ(); } + /** + * Fired when the player earns an achievement. + * @hookName achievement + */ interface AchievementEvent extends IPlayerEvent { + /** @return the achievement description. */ String getDescription(); } + /** + * Fired when the player fills a bucket. + * @hookName fillBucket + */ interface FillBucketEvent extends IPlayerEvent { + /** @return the empty bucket item. */ IItemStack getCurrent(); + /** @return the filled bucket item. */ IItemStack getFilled(); } + /** + * Fired when the player uses bonemeal on a block. + * @hookName bonemeal + */ interface BonemealEvent extends IPlayerEvent { + /** @return the block that was bonemealed. */ IBlock getBlock(); + /** @return the X coordinate. */ int getX(); + /** @return the Y coordinate. */ int getY(); + /** @return the Z coordinate. */ int getZ(); } + /** + * Fired when the player begins charging a ranged weapon. + * @hookName rangedCharge + */ interface RangedChargeEvent extends IPlayerEvent { } + /** + * Events fired for player custom effects (add, tick, remove). + * @hookName onEffect + */ interface EffectEvent extends IPlayerEvent { + /** @return the player effect. */ IPlayerEffect getEffect(); /** + * Fired when an effect is added to the player. * @hookName onEffectAdd */ interface Added extends EffectEvent { @@ -319,6 +549,7 @@ public interface IPlayerEvent extends ICustomNPCsEvent { } /** + * Fired each tick while the effect is active. * @hookName onEffectTick */ interface Ticked extends EffectEvent { @@ -326,6 +557,7 @@ public interface IPlayerEvent extends ICustomNPCsEvent { } /** + * Fired when an effect is removed from the player. * @hookName onEffectRemove */ interface Removed extends EffectEvent { @@ -343,6 +575,10 @@ public interface IPlayerEvent extends ICustomNPCsEvent { } + /** + * Events fired for profile operations (create, change, remove). Cancelable. + * @hookName profile + */ @Cancelable interface ProfileEvent extends IPlayerEvent { @@ -362,6 +598,7 @@ public interface IPlayerEvent extends ICustomNPCsEvent { boolean isPost(); /** + * Fired when the player switches profile slots. Cancelable. * @hookName profileChange */ @Cancelable @@ -373,6 +610,7 @@ public interface IPlayerEvent extends ICustomNPCsEvent { } /** + * Fired when a new profile is created. Cancelable. * @hookName profileCreate */ @Cancelable @@ -380,6 +618,7 @@ public interface IPlayerEvent extends ICustomNPCsEvent { } /** + * Fired when a profile is removed. Cancelable. * @hookName profileRemove */ @Cancelable diff --git a/java/noppes/npcs/api/event/IProjectileEvent.java b/java/noppes/npcs/api/event/IProjectileEvent.java index 5137273..0a05178 100644 --- a/java/noppes/npcs/api/event/IProjectileEvent.java +++ b/java/noppes/npcs/api/event/IProjectileEvent.java @@ -4,26 +4,36 @@ import noppes.npcs.api.IBlock; import noppes.npcs.api.entity.IEntity; import noppes.npcs.api.entity.IProjectile; +/** + * Events fired during NPC projectile lifecycle and impacts. + */ public interface IProjectileEvent extends ICustomNPCsEvent { + /** @return the projectile entity. */ public IProjectile getProjectile(); + /** @return the entity that launched this projectile. */ public IEntity getSource(); /** + * Fired each tick while the projectile exists. * @hookName projectileTick */ interface UpdateEvent extends IProjectileEvent { } /** + * Fired when the projectile hits something. * @hookName projectileImpact */ interface ImpactEvent extends IProjectileEvent { + /** @return the impact type. */ public int getType(); + /** @return the entity hit, or null if a block was hit. */ public IEntity getEntity(); + /** @return the block hit, or null if an entity was hit. */ public IBlock getBlock(); } diff --git a/java/noppes/npcs/api/event/IQuestEvent.java b/java/noppes/npcs/api/event/IQuestEvent.java index a871bc6..e4ddd18 100644 --- a/java/noppes/npcs/api/event/IQuestEvent.java +++ b/java/noppes/npcs/api/event/IQuestEvent.java @@ -4,28 +4,45 @@ import cpw.mods.fml.common.eventhandler.Cancelable; import noppes.npcs.api.handler.data.IQuest; import noppes.npcs.api.item.IItemStack; +/** + * Events fired during quest lifecycle: starting, completing, and turning in. + */ public interface IQuestEvent extends IPlayerEvent { + /** @return the quest associated with this event. */ IQuest getQuest(); + /** + * Fired when a quest's objectives are all completed. + * @hookName questCompleted + */ interface QuestCompletedEvent extends IQuestEvent { } + /** + * Fired when a quest is started/accepted. Cancelable. + * @hookName questStart + */ @Cancelable interface QuestStartEvent extends IQuestEvent { } /** + * Fired when a completed quest is turned in. Cancelable. * @hookName questTurnIn */ @Cancelable interface QuestTurnedInEvent extends IQuestEvent { + /** @param expReward the experience reward to give. */ void setExpReward(int expReward); + /** @param itemRewards the item rewards to give. */ void setItemRewards(IItemStack[] itemRewards); + /** @return the experience reward. */ int getExpReward(); + /** @return the item rewards. */ IItemStack[] getItemRewards(); } } diff --git a/java/noppes/npcs/api/event/IRecipeEvent.java b/java/noppes/npcs/api/event/IRecipeEvent.java index 78b81be..128703b 100644 --- a/java/noppes/npcs/api/event/IRecipeEvent.java +++ b/java/noppes/npcs/api/event/IRecipeEvent.java @@ -3,6 +3,9 @@ package noppes.npcs.api.event; import cpw.mods.fml.common.eventhandler.Cancelable; import noppes.npcs.api.item.IItemStack; +/** + * Events fired before and after recipe crafting, for both crafting table and anvil recipes. + */ public interface IRecipeEvent extends IPlayerEvent { /** @@ -13,14 +16,22 @@ public interface IRecipeEvent extends IPlayerEvent { */ Object getRecipe(); + /** @return the input item stacks used in the recipe. */ IItemStack[] getItems(); + /** @return true if this is an anvil recipe, false for crafting table. */ boolean isAnvil(); + /** + * Fired before a recipe is crafted. Cancelable. + * @hookName recipeCraftPre + */ @Cancelable interface Pre extends IRecipeEvent { + /** @param message the denial message shown when canceled. */ void setMessage(String message); + /** @return the denial message. */ String getMessage(); /** @@ -52,9 +63,15 @@ public interface IRecipeEvent extends IPlayerEvent { void setMaterialUsage(int materialUsage); } + /** + * Fired after a recipe is crafted. + * @hookName recipeCraftPost + */ interface Post extends IRecipeEvent { + /** @return the crafted item. */ IItemStack getCraft(); + /** @param stack the item to set as the crafting result. */ void setResult(IItemStack stack); } } diff --git a/java/noppes/npcs/api/gui/ICustomGui.java b/java/noppes/npcs/api/gui/ICustomGui.java index 3a92495..ee3bc80 100644 --- a/java/noppes/npcs/api/gui/ICustomGui.java +++ b/java/noppes/npcs/api/gui/ICustomGui.java @@ -231,12 +231,19 @@ public interface ICustomGui { IItemSlot addItemSlot(int id, int x, int y, IItemStack itemStack); /** + * @param x the X position in the GUI + * @param y the Y position in the GUI + * @return the created item slot * @deprecated Use addItemSlot(int, int, IItemStack) with an ID instead. */ @Deprecated IItemSlot addItemSlot(int x, int y); /** + * @param x the X position in the GUI + * @param y the Y position in the GUI + * @param itemStack the item to display in the slot + * @return the created item slot * @deprecated Use addItemSlot(int, int, IItemStack) with an ID instead. */ @Deprecated diff --git a/java/noppes/npcs/api/handler/IAbilityHandler.java b/java/noppes/npcs/api/handler/IAbilityHandler.java index 2c51777..e3882b5 100644 --- a/java/noppes/npcs/api/handler/IAbilityHandler.java +++ b/java/noppes/npcs/api/handler/IAbilityHandler.java @@ -12,54 +12,76 @@ public interface IAbilityHandler { /** * Get all registered ability type IDs. + * + * @return array of all registered ability type IDs */ String[] getTypes(); /** * Check if an ability type is registered. + * + * @param typeId the ability type ID to check + * @return true if the type is registered */ boolean hasType(String typeId); /** * Get all built-in ability names. + * + * @return array of all registered ability names (built-in and custom) */ String[] getAbilityNameArray(); /** * Check if a built-in ability exists by name. + * + * @param name the ability name to check + * @return true if an ability with this name exists */ boolean hasAbilityName(String name); /** * Get all custom ability preset names. + * + * @return array of all custom (user-created) ability names */ String[] getCustomAbilityNameArray(); /** * Check if a custom ability preset exists by name. + * + * @param name the custom ability name to check + * @return true if a custom ability with this name exists */ boolean hasCustomAbilityName(String name); /** * Delete a custom ability preset by name. * + * @param name the custom ability name to delete * @return true if deleted successfully */ boolean deleteCustomAbilityByName(String name); /** * Get all chained ability names. + * + * @return array of all chained ability names */ String[] getChainedAbilityNames(); /** * Check if a chained ability exists by name. + * + * @param name the chained ability name to check + * @return true if a chained ability with this name exists */ boolean hasChainedAbilityName(String name); /** * Delete a chained ability by name. * + * @param name the chained ability name to delete * @return true if deleted successfully */ boolean deleteChainedAbilityByName(String name); @@ -67,6 +89,7 @@ public interface IAbilityHandler { /** * Get a chained ability by name. * + * @param name the chained ability name * @return the chained ability, or null if not found */ IChainedAbility getChainedAbility(String name); @@ -74,6 +97,7 @@ public interface IAbilityHandler { /** * Save a chained ability. If a chain with the same name exists, it is overwritten. * + * @param chain the chained ability to save * @return true if saved successfully */ boolean saveChainedAbility(IChainedAbility chain); diff --git a/java/noppes/npcs/api/handler/IActionManager.java b/java/noppes/npcs/api/handler/IActionManager.java index 683f410..cdb89a9 100644 --- a/java/noppes/npcs/api/handler/IActionManager.java +++ b/java/noppes/npcs/api/handler/IActionManager.java @@ -18,12 +18,16 @@ public interface IActionManager { /** * Begin processing scheduled actions. Must be called once. + * + * @return this action manager */ IActionManager start(); /** * Halt processing of actions. Queued actions remain but will not run until * {@link #start()} is called again. + * + * @return this action manager */ IActionManager stop(); @@ -59,8 +63,8 @@ public interface IActionManager { /** * Enabling prints to the console the life cycle of IActionManager, it's IActionQueues and the scheduled IActions * - * @param debug - * @return + * @param debug whether to enable debug logging + * @return this action manager */ IActionManager setDebugMode(boolean debug); @@ -148,7 +152,7 @@ public interface IActionManager { boolean hasQueue(String name); /** - * @param name + * @param name the name for the new action * @return True if queue successfully removed from IActionManager and cleared */ boolean removeQueue(String name); @@ -176,7 +180,7 @@ public interface IActionManager { * Multiple actions chained one after another * i.e schedule(act1,act2,act3,...) * - * @param actions + * @param actions the actions to schedule */ void schedule(IAction... actions); @@ -192,7 +196,7 @@ public interface IActionManager { * Multiple tasks chained one after another * i.e schedule(task1,task2,task3,...) * - * @param tasks + * @param tasks the task consumers to schedule */ void schedule(Consumer... tasks); @@ -261,7 +265,7 @@ public interface IActionManager { * Multiple conditionals * i.e schedule(act1,act2,act3,...) * - * @param actions + * @param actions the conditional actions to schedule */ void schedule(IConditionalAction... actions); @@ -340,8 +344,8 @@ public interface IActionManager { /** * Schedules actions on the parallelQueue, where all actions are executed simultaneously * - * @param action - * @return + * @param action the action to add to the parallel chain + * @return the parallel action */ IAction scheduleParallel(IAction action); @@ -350,7 +354,7 @@ public interface IActionManager { * Multiple actions in parallel * i.e scheduleParallel(act1,act2,act3,...) * - * @param actions + * @param actions the actions to run in parallel */ void scheduleParallel(IAction... actions); @@ -380,7 +384,7 @@ public interface IActionManager { boolean hasAny(String name); /** - * @param name + * @param name the name for the new parallel action * @return Checks through all available queues and fetches the first IAction with given name */ IAction getAny(String name); diff --git a/java/noppes/npcs/api/handler/IAnimationHandler.java b/java/noppes/npcs/api/handler/IAnimationHandler.java index 31dec79..c5173ff 100644 --- a/java/noppes/npcs/api/handler/IAnimationHandler.java +++ b/java/noppes/npcs/api/handler/IAnimationHandler.java @@ -20,11 +20,15 @@ public interface IAnimationHandler { /** * Get all built-in animations. * Built-in animations are read-only and cannot be modified or deleted. + * + * @return array of all built-in animations */ IAnimation[] getBuiltInAnimations(); /** * Get all animations (both built-in and user-created). + * + * @return array of all animations (built-in and custom) */ IAnimation[] getAllAnimations(); @@ -38,6 +42,8 @@ public interface IAnimationHandler { /** * Get names of all built-in animations. + * + * @return array of all built-in animation names */ String[] getBuiltInAnimationNames(); } diff --git a/java/noppes/npcs/api/handler/IAuctionHandler.java b/java/noppes/npcs/api/handler/IAuctionHandler.java index 8b00df9..8ae9bf5 100644 --- a/java/noppes/npcs/api/handler/IAuctionHandler.java +++ b/java/noppes/npcs/api/handler/IAuctionHandler.java @@ -12,11 +12,13 @@ public interface IAuctionHandler { /** * Check if the auction system is enabled. + * @return true if the auction system is enabled */ boolean isEnabled(); /** * Get all active listings. + * @return array of all currently active auction listings */ IAuctionListing[] getActiveListings(); @@ -32,6 +34,7 @@ public interface IAuctionHandler { * Get all active listings by a specific seller. * * @param sellerUUID The seller's UUID as a string + * @return array of listings created by this seller */ IAuctionListing[] getListingsBySeller(String sellerUUID); @@ -39,11 +42,13 @@ public interface IAuctionHandler { * Get all listings where a player is the current high bidder. * * @param bidderUUID The bidder's UUID as a string + * @return array of listings this player has bid on */ IAuctionListing[] getListingsByBidder(String bidderUUID); /** * Get total count of active listings. + * @return the number of currently active listings */ int getActiveListingCount(); @@ -89,36 +94,43 @@ public interface IAuctionHandler { /** * Get the listing fee amount. + * @return the currency fee charged when creating a listing */ long getListingFee(); /** * Get the sales tax percentage (0.0 to 1.0). + * @return the sales tax percentage applied to completed sales */ double getSalesTaxPercent(); /** * Get the minimum bid increment percentage (0.0 to 1.0). + * @return the minimum bid increment as a percentage of current bid */ double getMinBidIncrementPercent(); /** * Get the auction duration in hours. + * @return the default auction duration in hours */ int getAuctionDurationHours(); /** * Get the snipe protection time in minutes. + * @return the snipe protection window in minutes */ int getSnipeProtectionMinutes(); /** * Get the currency name used by the auction system. + * @return the display name of the auction currency */ String getCurrencyName(); /** * Get the minimum listing price. + * @return the minimum starting price for new listings */ long getMinimumListingPrice(); diff --git a/java/noppes/npcs/api/handler/ICloneHandler.java b/java/noppes/npcs/api/handler/ICloneHandler.java index 805fd6c..7cc4a76 100644 --- a/java/noppes/npcs/api/handler/ICloneHandler.java +++ b/java/noppes/npcs/api/handler/ICloneHandler.java @@ -4,47 +4,216 @@ import noppes.npcs.api.IPos; import noppes.npcs.api.IWorld; import noppes.npcs.api.entity.IEntity; +/** + * Handles storing and spawning cloned entities. + * Clones are organized by numbered tabs (0-based) or named folders. + */ public interface ICloneHandler { + /** + * Spawns a clone at the given coordinates. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param tab the tab index. + * @param name the clone name. + * @param world the world to spawn in. + * @param ignoreProtection whether to bypass spawn protection. + * @return the spawned entity, or null on failure. + */ IEntity spawn(double x, double y, double z, int tab, String name, IWorld world, boolean ignoreProtection); + /** + * Spawns a clone at the given position. + * + * @param pos the position. + * @param tab the tab index. + * @param name the clone name. + * @param world the world to spawn in. + * @param ignoreProtection whether to bypass spawn protection. + * @return the spawned entity, or null on failure. + */ IEntity spawn(IPos pos, int tab, String name, IWorld world, boolean ignoreProtection); + /** + * Spawns a clone at the given coordinates with default protection rules. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param tab the tab index. + * @param name the clone name. + * @param world the world to spawn in. + * @return the spawned entity, or null on failure. + */ IEntity spawn(double x, double y, double z, int tab, String name, IWorld world); + /** + * Spawns a clone at the given position with default protection rules. + * + * @param pos the position. + * @param tab the tab index. + * @param name the clone name. + * @param world the world to spawn in. + * @return the spawned entity, or null on failure. + */ IEntity spawn(IPos pos, int tab, String name, IWorld world); + /** + * Returns all clones stored in the specified tab. + * + * @param tab the tab index. + * @param world the world context for entity creation. + * @return an array of entities in the tab. + */ IEntity[] getTab(int tab, IWorld world); + /** + * Returns a specific clone from a tab by name. + * + * @param tab the tab index. + * @param name the clone name. + * @param world the world context for entity creation. + * @return the entity, or null if not found. + */ IEntity get(int tab, String name, IWorld world); + /** + * Checks whether a clone with the given name exists in the tab. + * + * @param tab the tab index. + * @param name the clone name. + * @return true if the clone exists; false otherwise. + */ boolean has(int tab, String name); + /** + * Stores an entity as a clone in the given tab with the specified name. + * + * @param tab the tab index. + * @param name the clone name. + * @param entity the entity to store. + */ void set(int tab, String name, IEntity entity); + /** + * Removes a clone from the given tab. + * + * @param tab the tab index. + * @param name the clone name. + */ void remove(int tab, String name); // --- Custom Folder Methods --- + /** + * Returns all custom folder names. + * + * @return an array of folder names. + */ String[] getFolders(); + /** + * Checks whether a custom folder exists. + * + * @param folderName the folder name. + * @return true if the folder exists; false otherwise. + */ boolean hasFolder(String folderName); + /** + * Spawns a clone from a custom folder at the given coordinates. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param folderName the folder name. + * @param name the clone name. + * @param world the world to spawn in. + * @param ignoreProtection whether to bypass spawn protection. + * @return the spawned entity, or null on failure. + */ IEntity spawn(double x, double y, double z, String folderName, String name, IWorld world, boolean ignoreProtection); + /** + * Spawns a clone from a custom folder at the given position. + * + * @param pos the position. + * @param folderName the folder name. + * @param name the clone name. + * @param world the world to spawn in. + * @param ignoreProtection whether to bypass spawn protection. + * @return the spawned entity, or null on failure. + */ IEntity spawn(IPos pos, String folderName, String name, IWorld world, boolean ignoreProtection); + /** + * Spawns a clone from a custom folder with default protection rules. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + * @param folderName the folder name. + * @param name the clone name. + * @param world the world to spawn in. + * @return the spawned entity, or null on failure. + */ IEntity spawn(double x, double y, double z, String folderName, String name, IWorld world); + /** + * Spawns a clone from a custom folder at the given position with default protection rules. + * + * @param pos the position. + * @param folderName the folder name. + * @param name the clone name. + * @param world the world to spawn in. + * @return the spawned entity, or null on failure. + */ IEntity spawn(IPos pos, String folderName, String name, IWorld world); + /** + * Returns all clones stored in the specified custom folder. + * + * @param folderName the folder name. + * @param world the world context for entity creation. + * @return an array of entities in the folder. + */ IEntity[] getFolder(String folderName, IWorld world); + /** + * Returns a specific clone from a custom folder by name. + * + * @param folderName the folder name. + * @param name the clone name. + * @param world the world context for entity creation. + * @return the entity, or null if not found. + */ IEntity get(String folderName, String name, IWorld world); + /** + * Checks whether a clone exists in a custom folder. + * + * @param folderName the folder name. + * @param name the clone name. + * @return true if the clone exists; false otherwise. + */ boolean has(String folderName, String name); + /** + * Stores an entity as a clone in a custom folder. + * + * @param folderName the folder name. + * @param name the clone name. + * @param entity the entity to store. + */ void set(String folderName, String name, IEntity entity); + /** + * Removes a clone from a custom folder. + * + * @param folderName the folder name. + * @param name the clone name. + */ void remove(String folderName, String name); } diff --git a/java/noppes/npcs/api/handler/IDialogHandler.java b/java/noppes/npcs/api/handler/IDialogHandler.java index 36d5789..901efbc 100644 --- a/java/noppes/npcs/api/handler/IDialogHandler.java +++ b/java/noppes/npcs/api/handler/IDialogHandler.java @@ -5,8 +5,23 @@ import noppes.npcs.api.handler.data.IDialogCategory; import java.util.List; +/** + * Handles retrieval of dialogs and dialog categories. + */ public interface IDialogHandler { + + /** + * Returns all dialog categories. + * + * @return a list of dialog categories. + */ List categories(); - IDialog get(int var1); + /** + * Returns the dialog with the specified ID. + * + * @param id the dialog ID. + * @return the dialog, or null if not found. + */ + IDialog get(int id); } diff --git a/java/noppes/npcs/api/handler/IFactionHandler.java b/java/noppes/npcs/api/handler/IFactionHandler.java index 5bade90..58444d8 100644 --- a/java/noppes/npcs/api/handler/IFactionHandler.java +++ b/java/noppes/npcs/api/handler/IFactionHandler.java @@ -4,12 +4,40 @@ import noppes.npcs.api.handler.data.IFaction; import java.util.List; +/** + * Handles creation, deletion, and retrieval of factions. + */ public interface IFactionHandler { + + /** + * Returns all registered factions. + * + * @return a list of factions. + */ List list(); - IFaction delete(int var1); + /** + * Deletes the faction with the given ID. + * + * @param id the faction ID. + * @return the deleted faction, or null if not found. + */ + IFaction delete(int id); - IFaction create(String var1, int var2); + /** + * Creates a new faction with the given name and default points. + * + * @param name the faction name. + * @param defaultPoints the default standing points for new players. + * @return the created faction. + */ + IFaction create(String name, int defaultPoints); - IFaction get(int var1); + /** + * Returns the faction with the given ID. + * + * @param id the faction ID. + * @return the faction, or null if not found. + */ + IFaction get(int id); } diff --git a/java/noppes/npcs/api/handler/ILinkedItemHandler.java b/java/noppes/npcs/api/handler/ILinkedItemHandler.java index 056be78..d1dc310 100644 --- a/java/noppes/npcs/api/handler/ILinkedItemHandler.java +++ b/java/noppes/npcs/api/handler/ILinkedItemHandler.java @@ -3,18 +3,64 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.ILinkedItem; import noppes.npcs.api.item.IItemStack; +/** + * Handles registration and retrieval of linked items. + * Linked items are custom item definitions that can be updated globally. + */ public interface ILinkedItemHandler { + + /** + * Creates a new linked item with the given name. + * + * @param name the item name. + * @return the created linked item. + */ ILinkedItem createItem(String name); + /** + * Creates an ItemStack from a linked item by its ID. + * + * @param id the linked item ID. + * @return the item stack, or null if the ID is invalid. + */ IItemStack createItemStack(int id); + /** + * Registers a linked item with this handler. + * + * @param linkedItem the linked item to add. + */ void add(ILinkedItem linkedItem); + /** + * Removes and returns the linked item with the given ID. + * + * @param id the linked item ID. + * @return the removed linked item, or null if not found. + */ ILinkedItem remove(int id); + /** + * Returns the linked item with the given ID. + * + * @param id the linked item ID. + * @return the linked item, or null if not found. + */ ILinkedItem get(int id); + /** + * Checks whether a linked item with the given ID exists. + * + * @param id the linked item ID. + * @return true if it exists; false otherwise. + */ boolean contains(int id); + /** + * Checks whether the given linked item is registered. + * + * @param linkedItem the linked item to check. + * @return true if it exists; false otherwise. + */ boolean contains(ILinkedItem linkedItem); } diff --git a/java/noppes/npcs/api/handler/INaturalSpawnsHandler.java b/java/noppes/npcs/api/handler/INaturalSpawnsHandler.java index b851d11..ece4c58 100644 --- a/java/noppes/npcs/api/handler/INaturalSpawnsHandler.java +++ b/java/noppes/npcs/api/handler/INaturalSpawnsHandler.java @@ -2,17 +2,49 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.INaturalSpawn; +/** + * Handles natural spawn configurations for custom NPCs. + */ public interface INaturalSpawnsHandler { + /** + * Saves all spawn configurations to disk. + */ void save(); + /** + * Returns all registered natural spawn configurations. + * + * @return an array of spawn configurations. + */ INaturalSpawn[] getSpawns(); + /** + * Returns spawn configurations that include the specified biome. + * + * @param biome the biome name. + * @return an array of matching spawn configurations. + */ INaturalSpawn[] getSpawns(String biome); + /** + * Registers a new natural spawn configuration. + * + * @param spawn the spawn to add. + */ void addSpawn(INaturalSpawn spawn); + /** + * Removes a natural spawn configuration. + * + * @param spawn the spawn to remove. + */ void removeSpawn(INaturalSpawn spawn); + /** + * Creates a new empty natural spawn configuration. + * + * @return the created spawn. + */ INaturalSpawn createSpawn(); } diff --git a/java/noppes/npcs/api/handler/IOverlayHandler.java b/java/noppes/npcs/api/handler/IOverlayHandler.java index 81750fc..6036a3d 100644 --- a/java/noppes/npcs/api/handler/IOverlayHandler.java +++ b/java/noppes/npcs/api/handler/IOverlayHandler.java @@ -2,17 +2,53 @@ package noppes.npcs.api.handler; import noppes.npcs.api.ISkinOverlay; +/** + * Manages skin overlays applied to an entity or player. + * Overlays are indexed by ID and rendered on top of the base skin. + */ public interface IOverlayHandler { + /** + * Adds or replaces an overlay at the given ID. + * + * @param id the overlay ID. + * @param overlay the skin overlay to add. + */ void add(int id, ISkinOverlay overlay); + /** + * Returns the overlay at the given ID. + * + * @param id the overlay ID. + * @return the skin overlay, or null if not found. + */ ISkinOverlay get(int id); + /** + * Checks whether an overlay exists at the given ID. + * + * @param id the overlay ID. + * @return true if an overlay exists; false otherwise. + */ boolean has(int id); + /** + * Removes the overlay at the given ID. + * + * @param id the overlay ID. + * @return true if an overlay was removed; false otherwise. + */ boolean remove(int id); + /** + * Returns the number of active overlays. + * + * @return the overlay count. + */ int size(); + /** + * Removes all overlays. + */ void clear(); } diff --git a/java/noppes/npcs/api/handler/IPlayerBankData.java b/java/noppes/npcs/api/handler/IPlayerBankData.java index 642e82d..bd88b59 100644 --- a/java/noppes/npcs/api/handler/IPlayerBankData.java +++ b/java/noppes/npcs/api/handler/IPlayerBankData.java @@ -1,4 +1,8 @@ package noppes.npcs.api.handler; +/** + * Holds bank-related data for a player. + * Currently a marker interface. + */ public interface IPlayerBankData { } diff --git a/java/noppes/npcs/api/handler/IPlayerData.java b/java/noppes/npcs/api/handler/IPlayerData.java index 8927fef..d69a23e 100644 --- a/java/noppes/npcs/api/handler/IPlayerData.java +++ b/java/noppes/npcs/api/handler/IPlayerData.java @@ -3,33 +3,65 @@ package noppes.npcs.api.handler; import noppes.npcs.api.ability.IPlayerAbilityData; import noppes.npcs.api.entity.ICustomNpc; +/** + * Provides access to all persistent data categories for a player, + * including companion, dialog, quest, faction, transport, mail, trade, and ability data. + */ public interface IPlayerData { + /** + * Sets the player's companion NPC. + * + * @param npc the companion NPC, or null to clear. + */ void setCompanion(ICustomNpc npc); + /** + * Returns the player's companion NPC. + * + * @return the companion NPC, or null if none. + */ ICustomNpc getCompanion(); + /** + * @return true if the player currently has a companion NPC. + */ boolean hasCompanion(); + /** + * @return the entity ID of the companion, or -1 if none. + */ int getCompanionID(); + /** @return the player's dialog data. */ IPlayerDialogData getDialogData(); + /** @return the player's bank data. */ IPlayerBankData getBankData(); + /** @return the player's quest data. */ IPlayerQuestData getQuestData(); + /** @return the player's transport data. */ IPlayerTransportData getTransportData(); + /** @return the player's faction data. */ IPlayerFactionData getFactionData(); + /** @return the player's item giver data. */ IPlayerItemGiverData getItemGiverData(); + /** @return the player's mail data. */ IPlayerMailData getMailData(); + /** @return the player's trade data. */ IPlayerTradeData getTradeData(); + /** @return the player's ability data. */ IPlayerAbilityData getAbilityData(); + /** + * Saves all player data to disk. + */ void save(); } diff --git a/java/noppes/npcs/api/handler/IPlayerDialogData.java b/java/noppes/npcs/api/handler/IPlayerDialogData.java index ad79cc7..5ee3a83 100644 --- a/java/noppes/npcs/api/handler/IPlayerDialogData.java +++ b/java/noppes/npcs/api/handler/IPlayerDialogData.java @@ -1,10 +1,29 @@ package noppes.npcs.api.handler; +/** + * Tracks which dialogs a player has read. + */ public interface IPlayerDialogData { + /** + * Checks if the player has read the dialog with the given ID. + * + * @param id the dialog ID. + * @return true if the dialog has been read; false otherwise. + */ boolean hasReadDialog(int id); + /** + * Marks the dialog with the given ID as read. + * + * @param id the dialog ID. + */ void readDialog(int id); + /** + * Marks the dialog with the given ID as unread. + * + * @param id the dialog ID. + */ void unreadDialog(int id); } diff --git a/java/noppes/npcs/api/handler/IPlayerFactionData.java b/java/noppes/npcs/api/handler/IPlayerFactionData.java index f4e7128..9de6700 100644 --- a/java/noppes/npcs/api/handler/IPlayerFactionData.java +++ b/java/noppes/npcs/api/handler/IPlayerFactionData.java @@ -1,10 +1,32 @@ package noppes.npcs.api.handler; +/** + * Tracks a player's faction standing points. + */ public interface IPlayerFactionData { + /** + * Returns the player's points for the given faction. + * + * @param id the faction ID. + * @return the faction points. + */ int getPoints(int id); + /** + * Adds points to the player's standing with the given faction. + * Use negative values to decrease. + * + * @param id the faction ID. + * @param points the points to add. + */ void addPoints(int id, int points); + /** + * Sets the player's points for the given faction. + * + * @param id the faction ID. + * @param points the new point value. + */ void setPoints(int id, int points); } diff --git a/java/noppes/npcs/api/handler/IPlayerItemGiverData.java b/java/noppes/npcs/api/handler/IPlayerItemGiverData.java index 67dc129..7c95083 100644 --- a/java/noppes/npcs/api/handler/IPlayerItemGiverData.java +++ b/java/noppes/npcs/api/handler/IPlayerItemGiverData.java @@ -2,11 +2,33 @@ package noppes.npcs.api.handler; import noppes.npcs.api.jobs.IJobItemGiver; +/** + * Tracks item giver interaction data for a player, including + * cooldown timestamps and interaction history. + */ public interface IPlayerItemGiverData { + /** + * Returns the last interaction time for the given item giver job. + * + * @param jobItemGiver the item giver job. + * @return the last interaction time in game ticks. + */ long getTime(IJobItemGiver jobItemGiver); + /** + * Sets the last interaction time for the given item giver job. + * + * @param jobItemGiver the item giver job. + * @param day the time to set in game ticks. + */ void setTime(IJobItemGiver jobItemGiver, long day); + /** + * Checks whether the player has interacted with the item giver before. + * + * @param jobItemGiver the item giver job. + * @return true if previously interacted; false otherwise. + */ boolean hasInteractedBefore(IJobItemGiver jobItemGiver); } diff --git a/java/noppes/npcs/api/handler/IPlayerMailData.java b/java/noppes/npcs/api/handler/IPlayerMailData.java index 8f3dc4e..bb24828 100644 --- a/java/noppes/npcs/api/handler/IPlayerMailData.java +++ b/java/noppes/npcs/api/handler/IPlayerMailData.java @@ -2,21 +2,50 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.IPlayerMail; +/** + * Manages a player's mail inbox, including sending, removing, and querying mail. + */ public interface IPlayerMailData { + /** @return true if the player has any mail. */ boolean hasMail(); + /** + * Adds mail to the player's inbox. + * + * @param mail the mail to add. + */ void addMail(IPlayerMail mail); + /** + * Removes specific mail from the player's inbox. + * + * @param mail the mail to remove. + */ void removeMail(IPlayerMail mail); + /** + * Checks if the player has the specified mail. + * + * @param mail the mail to check. + * @return true if the mail exists in the inbox. + */ boolean hasMail(IPlayerMail mail); + /** @return all mail in the player's inbox. */ IPlayerMail[] getAllMail(); + /** @return all unread mail in the player's inbox. */ IPlayerMail[] getUnreadMail(); + /** @return all read mail in the player's inbox. */ IPlayerMail[] getReadMail(); + /** + * Returns all mail from the given sender. + * + * @param sender the sender name. + * @return an array of matching mail. + */ IPlayerMail[] getMailFrom(String sender); } diff --git a/java/noppes/npcs/api/handler/IPlayerQuestData.java b/java/noppes/npcs/api/handler/IPlayerQuestData.java index 0e7afae..82efa23 100644 --- a/java/noppes/npcs/api/handler/IPlayerQuestData.java +++ b/java/noppes/npcs/api/handler/IPlayerQuestData.java @@ -2,27 +2,73 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.IQuest; +/** + * Tracks a player's quest progress, including active, finished, and tracked quests. + */ public interface IPlayerQuestData { + /** @return the quest currently being tracked by the player, or null if none. */ IQuest getTrackedQuest(); + /** + * Starts the quest with the given ID for the player. + * + * @param id the quest ID. + */ void startQuest(int id); + /** + * Marks the quest with the given ID as finished. + * + * @param id the quest ID. + */ void finishQuest(int id); + /** + * Removes the quest from the player's active quest list. + * + * @param id the quest ID. + */ void stopQuest(int id); + /** + * Removes the quest from both active and finished lists. + * + * @param id the quest ID. + */ void removeQuest(int id); + /** + * @param id the quest ID. + * @return true if the player has finished the quest. + */ boolean hasFinishedQuest(int id); - public boolean hasActiveQuest(int id); + /** + * @param id the quest ID. + * @return true if the player has the quest active. + */ + boolean hasActiveQuest(int id); + /** @return all active quests for the player. */ IQuest[] getActiveQuests(); + /** @return all finished quests for the player. */ IQuest[] getFinishedQuests(); + /** + * Returns the timestamp when the quest was last completed. + * + * @param id the quest ID. + * @return the completion time, or 0 if never completed. + */ long getLastCompletedTime(int id); + /** + * Sets the last completed time for the quest. + * + * @param id the quest ID. + * @param time the completion timestamp. + */ void setLastCompletedTime(int id, long time); } diff --git a/java/noppes/npcs/api/handler/IPlayerTradeData.java b/java/noppes/npcs/api/handler/IPlayerTradeData.java index ef8086e..1d05b2f 100644 --- a/java/noppes/npcs/api/handler/IPlayerTradeData.java +++ b/java/noppes/npcs/api/handler/IPlayerTradeData.java @@ -11,6 +11,8 @@ public interface IPlayerTradeData { /** * Get the current balance + * + * @return the player's current currency balance */ long getBalance(); @@ -47,16 +49,22 @@ public interface IPlayerTradeData { /** * Get lifetime earned currency + * + * @return the total currency earned over the player's lifetime */ long getLifetimeEarned(); /** * Get lifetime spent currency + * + * @return the total currency spent over the player's lifetime */ long getLifetimeSpent(); /** * Format the balance for display + * + * @return the balance formatted as a human-readable string */ String formatBalance(); @@ -69,16 +77,22 @@ public interface IPlayerTradeData { /** * Get the number of pending auction claims + * + * @return the number of pending auction claims */ int getClaimCount(); /** * Check if player has any pending auction claims + * + * @return true if the player has pending auction claims */ boolean hasClaims(); /** * Get all pending auction claims for this player. + * + * @return array of the player's pending auction claims */ IAuctionClaim[] getClaims(); diff --git a/java/noppes/npcs/api/handler/IPlayerTransportData.java b/java/noppes/npcs/api/handler/IPlayerTransportData.java index e55f91f..64ec7c8 100644 --- a/java/noppes/npcs/api/handler/IPlayerTransportData.java +++ b/java/noppes/npcs/api/handler/IPlayerTransportData.java @@ -2,17 +2,50 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.ITransportLocation; +/** + * Tracks which transport locations a player has unlocked. + */ public interface IPlayerTransportData { + /** + * @param id the transport location ID. + * @return true if the player has unlocked this transport. + */ boolean hasTransport(int id); + /** + * Unlocks a transport location by ID. + * + * @param id the transport location ID. + */ void addTransport(int id); + /** + * Unlocks the given transport location. + * + * @param location the transport location. + */ void addTransport(ITransportLocation location); + /** + * Returns the transport location with the given ID. + * + * @param id the transport location ID. + * @return the transport location, or null if not found. + */ ITransportLocation getTransport(int id); + /** + * Returns all unlocked transport locations for the player. + * + * @return an array of transport locations. + */ ITransportLocation[] getTransports(); + /** + * Removes an unlocked transport location by ID. + * + * @param id the transport location ID. + */ void removeTransport(int id); } diff --git a/java/noppes/npcs/api/handler/IProfileHandler.java b/java/noppes/npcs/api/handler/IProfileHandler.java index 46d5774..65fbd6c 100644 --- a/java/noppes/npcs/api/handler/IProfileHandler.java +++ b/java/noppes/npcs/api/handler/IProfileHandler.java @@ -3,17 +3,60 @@ package noppes.npcs.api.handler; import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.handler.data.IProfile; +/** + * Manages player profiles, which allow players to have multiple save slots + * for their CNPC+ data. + */ public interface IProfileHandler { + /** + * Returns the profile for the given player. + * + * @param player the player. + * @return the player's profile. + */ IProfile getProfile(IPlayer player); + /** + * Switches the player to a different profile slot. + * + * @param player the player. + * @param slotID the slot ID to switch to. + * @return true if the switch was successful. + */ boolean changeSlot(IPlayer player, int slotID); + /** + * Checks whether a profile slot exists for the player. + * + * @param player the player. + * @param slotID the slot ID. + * @return true if the slot exists. + */ boolean hasSlot(IPlayer player, int slotID); + /** + * Removes a profile slot from the player. + * + * @param player the player. + * @param slotID the slot ID to remove. + * @return true if the slot was removed. + */ boolean removeSlot(IPlayer player, int slotID); + /** + * Returns the player data for a specific profile slot without switching to it. + * + * @param player the player. + * @param slotID the slot ID. + * @return the player data for the slot. + */ IPlayerData getSlotPlayerData(IPlayer player, int slotID); + /** + * Saves the current slot data for the player. + * + * @param player the player. + */ void saveSlotData(IPlayer player); } diff --git a/java/noppes/npcs/api/handler/IQuestHandler.java b/java/noppes/npcs/api/handler/IQuestHandler.java index 9bbf54b..4733c3b 100644 --- a/java/noppes/npcs/api/handler/IQuestHandler.java +++ b/java/noppes/npcs/api/handler/IQuestHandler.java @@ -5,8 +5,23 @@ import noppes.npcs.api.handler.data.IQuestCategory; import java.util.List; +/** + * Handles retrieval of quests and quest categories. + */ public interface IQuestHandler { + + /** + * Returns all quest categories. + * + * @return a list of quest categories. + */ List categories(); - IQuest get(int var1); + /** + * Returns the quest with the given ID. + * + * @param id the quest ID. + * @return the quest, or null if not found. + */ + IQuest get(int id); } diff --git a/java/noppes/npcs/api/handler/IRecipeHandler.java b/java/noppes/npcs/api/handler/IRecipeHandler.java index 5791feb..eae1694 100644 --- a/java/noppes/npcs/api/handler/IRecipeHandler.java +++ b/java/noppes/npcs/api/handler/IRecipeHandler.java @@ -6,20 +6,67 @@ import noppes.npcs.api.handler.data.IRecipe; import java.util.List; +/** + * Handles custom crafting recipes and anvil recipes. + */ public interface IRecipeHandler { + + /** @return all global (vanilla workbench) recipes. */ List getGlobalList(); + /** @return all carpentry table recipes. */ List getCarpentryList(); + /** @return all custom anvil recipes. */ List getAnvilList(); - void addRecipe(String var1, boolean var2, ItemStack var3, Object... var4); + /** + * Adds a shaped crafting recipe. + * + * @param name the recipe name. + * @param global true for global (vanilla workbench); false for carpentry. + * @param result the resulting item stack. + * @param recipe the recipe pattern and ingredient mappings. + */ + void addRecipe(String name, boolean global, ItemStack result, Object... recipe); - void addRecipe(String var1, boolean var2, ItemStack var3, int var4, int var5, ItemStack... var6); + /** + * Adds a shaped crafting recipe with explicit dimensions. + * + * @param name the recipe name. + * @param global true for global; false for carpentry. + * @param result the resulting item stack. + * @param width the recipe grid width. + * @param height the recipe grid height. + * @param items the ingredient item stacks. + */ + void addRecipe(String name, boolean global, ItemStack result, int width, int height, ItemStack... items); - IRecipe delete(int var1); + /** + * Deletes a crafting recipe by ID. + * + * @param id the recipe ID. + * @return the deleted recipe, or null if not found. + */ + IRecipe delete(int id); - IAnvilRecipe deleteAnvil(int var1); + /** + * Deletes an anvil recipe by ID. + * + * @param id the recipe ID. + * @return the deleted anvil recipe, or null if not found. + */ + IAnvilRecipe deleteAnvil(int id); + /** + * Adds a custom anvil recipe. + * + * @param name the recipe name. + * @param global true for global; false for carpentry. + * @param itemToRepair the item to be repaired. + * @param repairMaterial the material used for repair. + * @param xpCost the experience cost. + * @param repairPercentage the percentage of durability restored per material. + */ void addAnvilRecipe(String name, boolean global, ItemStack itemToRepair, ItemStack repairMaterial, int xpCost, float repairPercentage); } diff --git a/java/noppes/npcs/api/handler/ITagHandler.java b/java/noppes/npcs/api/handler/ITagHandler.java index 9f3e210..9fd20ce 100644 --- a/java/noppes/npcs/api/handler/ITagHandler.java +++ b/java/noppes/npcs/api/handler/ITagHandler.java @@ -4,12 +4,41 @@ import noppes.npcs.api.handler.data.ITag; import java.util.List; +/** + * Handles creation, deletion, and retrieval of tags. + * Tags are labels that can be applied to entities for categorization. + */ public interface ITagHandler { + + /** + * Returns all registered tags. + * + * @return a list of tags. + */ List list(); - ITag delete(int var1); + /** + * Deletes the tag with the given ID. + * + * @param id the tag ID. + * @return the deleted tag, or null if not found. + */ + ITag delete(int id); - ITag create(String var1, int var2); + /** + * Creates a new tag with the given name and color. + * + * @param name the tag name. + * @param color the tag color as a packed RGB integer. + * @return the created tag. + */ + ITag create(String name, int color); - ITag get(int var1); + /** + * Returns the tag with the given ID. + * + * @param id the tag ID. + * @return the tag, or null if not found. + */ + ITag get(int id); } diff --git a/java/noppes/npcs/api/handler/ITelegraphHandler.java b/java/noppes/npcs/api/handler/ITelegraphHandler.java index c73b2c6..7bb0a69 100644 --- a/java/noppes/npcs/api/handler/ITelegraphHandler.java +++ b/java/noppes/npcs/api/handler/ITelegraphHandler.java @@ -29,9 +29,9 @@ import noppes.npcs.api.entity.IEntity; */ public interface ITelegraphHandler { - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // FACTORY METHODS - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Create a circle telegraph. @@ -83,9 +83,9 @@ public interface ITelegraphHandler { */ ITelegraph create(String type); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // SPAWN METHODS - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Spawn a telegraph at a position. @@ -131,9 +131,9 @@ public interface ITelegraphHandler { */ ITelegraphInstance spawn(ITelegraph telegraph, IEntity entity, float yaw); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // PRESET MANAGEMENT - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Get a saved telegraph preset by name. @@ -173,9 +173,9 @@ public interface ITelegraphHandler { */ String[] getSavedNames(); - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== // REMOVAL - // ═══════════════════════════════════════════════════════════════════════════ + // ========================================================================== /** * Remove an active telegraph by instance ID. diff --git a/java/noppes/npcs/api/handler/ITransportHandler.java b/java/noppes/npcs/api/handler/ITransportHandler.java index 8ee2ea9..e93bb7d 100644 --- a/java/noppes/npcs/api/handler/ITransportHandler.java +++ b/java/noppes/npcs/api/handler/ITransportHandler.java @@ -2,13 +2,37 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.ITransportCategory; +/** + * Handles transport categories and their locations. + */ public interface ITransportHandler { + /** + * Returns all transport categories. + * + * @return an array of transport categories. + */ ITransportCategory[] categories(); + /** + * Creates a new transport category with the given title. + * + * @param title the category title. + */ void createCategory(String title); + /** + * Returns the transport category with the given title. + * + * @param title the category title. + * @return the category, or null if not found. + */ ITransportCategory getCategory(String title); + /** + * Removes the transport category with the given title. + * + * @param title the category title. + */ void removeCategory(String title); } diff --git a/java/noppes/npcs/api/handler/data/IAction.java b/java/noppes/npcs/api/handler/data/IAction.java index 29e3d9e..ae04d69 100644 --- a/java/noppes/npcs/api/handler/data/IAction.java +++ b/java/noppes/npcs/api/handler/data/IAction.java @@ -20,13 +20,13 @@ public interface IAction { /** * @param queue Schedules action on this queue. If action was scheduled on different queue, transfers it over from that to this. - * @return + * @return this action */ IAction setQueue(IActionQueue queue); /** * @param task code to execute each time the action fires - * @return + * @return this action */ IAction setTask(Consumer task); @@ -49,14 +49,14 @@ public interface IAction { /** * * @param task Fires right after action gets scheduled at duration 0 - * @return + * @return this action */ IAction onStart(Consumer task); /** * * @param task Fires right before a marked done action gets removed from it's IActionQueue - * @return + * @return this action */ IAction onDone(Consumer task); @@ -81,7 +81,7 @@ public interface IAction { /** * @param ticks max duration * default: -1, infinite - * @return + * @return this action */ IAction setMaxDuration(int ticks); @@ -93,7 +93,7 @@ public interface IAction { /** * @param n max count, task auto marks done after running for n counts * default: -1, infinite - * @return + * @return this action */ IAction times(int n); @@ -101,7 +101,7 @@ public interface IAction { * Execute task only once, mark done * equivalent to times(1) * - * @return + * @return this action */ IAction once(); @@ -135,6 +135,7 @@ public interface IAction { * * @param key a string key * @param value any object to associate with this action + * @return this action */ IAction setData(String key, Object value); @@ -143,7 +144,7 @@ public interface IAction { /** * * @param copyTo copies all of this IAction's data to copyTo - * @return + * @return this action */ IAction copyDataTo(IAction copyTo); @@ -166,20 +167,21 @@ public interface IAction { * Set how many ticks between each execution of the action task. * * @param ticks tick interval (e.g. 1 = every tick, 20 = once per second) + * @return this action */ IAction updateEvery(int ticks); /** * Executes task every tick (Sets updateEvery to 1) * - * @return + * @return this action */ IAction everyTick(); /** * Executes task every second (Sets updateEvery to 20) * - * @return + * @return this action */ IAction everySecond(); @@ -192,7 +194,7 @@ public interface IAction { * @param ticks pauses action for this number of ticks (any subsequent action is paused too) * If action was threaded using {@link #threadify()}, sleeps the thread. * Can be forcibly resumed using {@link #resume()} - * @return + * @return this action */ IAction pauseFor(int ticks); @@ -207,6 +209,8 @@ public interface IAction { /** * Must call {@link #threadify()} before using, else throws exception. * Pauses IAction's thread until the supplied condition is satisfied or {@link #resume()} is called. + * + * @param until condition to check each tick */ void pauseUntil(Function until); @@ -217,7 +221,7 @@ public interface IAction { void resume(); /** - * @return checks if IAction's getStartAfterTicks > 0, or if IAction's thread is paused if threaded + * @return checks if IAction's getStartAfterTicks > 0, or if IAction's thread is paused if threaded * Preferably called from a different thread than the IAction one if it's paused. */ boolean isPaused(); @@ -230,6 +234,8 @@ public interface IAction { /** * Creates a new thread for task to run into. Allows for pausing and sleeping just this IAction's thread. + * + * @return this action */ IAction threadify(); @@ -253,6 +259,7 @@ public interface IAction { * Enqueue another action immediately after this one. * * @param after the action to run next + * @return the chained action */ IAction after(IAction after); @@ -260,7 +267,7 @@ public interface IAction { * Multiple actions chained one after another * i.e after(act1,act2,act3,...) * - * @param actions + * @param actions the actions to chain */ void after(IAction... actions); @@ -268,7 +275,7 @@ public interface IAction { * Multiple tasks chained one after another * i.e after(task1,task2,task3,...) * - * @param tasks + * @param tasks the tasks to chain */ void after(Consumer... tasks); @@ -286,6 +293,7 @@ public interface IAction { * Enqueue another action immediately before this one (pausing this one until done). * * @param before the action to run prior + * @return the chained action */ IAction before(IAction before); @@ -303,6 +311,7 @@ public interface IAction { * Enqueue an IConditionalAction on the conditional chain * * @param after the scheduled IConditionalAction + * @return the conditional action */ IConditionalAction conditional(IConditionalAction after); @@ -324,6 +333,7 @@ public interface IAction { * Enqueue another IAction on the parallel chain which starts firing simultaneously as this. * * @param after the scheduled parallel action + * @return the parallel action */ IAction parallel(IAction after); diff --git a/java/noppes/npcs/api/handler/data/IActionChain.java b/java/noppes/npcs/api/handler/data/IActionChain.java index 7192c27..58c51ad 100644 --- a/java/noppes/npcs/api/handler/data/IActionChain.java +++ b/java/noppes/npcs/api/handler/data/IActionChain.java @@ -8,7 +8,7 @@ public interface IActionChain { /** * @param name of chain - * @return + * @return this IActionChain for method chaining */ IActionChain setName(String name); @@ -23,7 +23,7 @@ public interface IActionChain { * @param delay ticks between an IAction and another * @param name name of IAction * @param task task of IAction - * @return + * @return this IActionChain for method chaining */ IActionChain after(int delay, String name, Consumer task); @@ -32,7 +32,7 @@ public interface IActionChain { /** * Start IActionManager * - * @return + * @return this IActionChain for method chaining */ IActionChain start(); } diff --git a/java/noppes/npcs/api/handler/data/IActionListener.java b/java/noppes/npcs/api/handler/data/IActionListener.java index 56cdf51..a471b0e 100644 --- a/java/noppes/npcs/api/handler/data/IActionListener.java +++ b/java/noppes/npcs/api/handler/data/IActionListener.java @@ -1,5 +1,9 @@ package noppes.npcs.api.handler.data; +/** + * Listener interface for action hooks. + * Currently a placeholder for future hook-based action firing. + */ public interface IActionListener { // IActionListener Comments // ActionListener.Hook getOrCreateHook(String name); diff --git a/java/noppes/npcs/api/handler/data/IActionQueue.java b/java/noppes/npcs/api/handler/data/IActionQueue.java index 4b1b55a..8af2a18 100644 --- a/java/noppes/npcs/api/handler/data/IActionQueue.java +++ b/java/noppes/npcs/api/handler/data/IActionQueue.java @@ -36,7 +36,7 @@ public interface IActionQueue { /** * * @param parallel True to turn queue into parallel, false for sequential - * @return + * @return this IActionQueue for method chaining */ IActionQueue setParallel(boolean parallel); @@ -49,7 +49,7 @@ public interface IActionQueue { /** * * @param stopWhenEmpty to auto-stop queue when empty/no active Actions scheduled using {{@link #stop()}} - * @return + * @return this IActionQueue for method chaining */ IActionQueue stopWhenEmpty(boolean stopWhenEmpty); @@ -71,7 +71,7 @@ public interface IActionQueue { /** * @param ticks to kill queue after when killWhenEmpty and queue has no active tasks * If an IAction is scheduled during the kill process, process is aborted - * @return + * @return this IActionQueue for method chaining */ IActionQueue killWhenEmptyAfter(int ticks); @@ -109,7 +109,7 @@ public interface IActionQueue { /** * - * @param action + * @param action the action to find in the queue * @return index of action in {{@link #getQueue()}} * -1 if not in queue. */ diff --git a/java/noppes/npcs/api/handler/data/IAnimation.java b/java/noppes/npcs/api/handler/data/IAnimation.java index 2344454..5d049b5 100644 --- a/java/noppes/npcs/api/handler/data/IAnimation.java +++ b/java/noppes/npcs/api/handler/data/IAnimation.java @@ -55,6 +55,8 @@ public interface IAnimation { /** * Do not use this unless you know what you are changing. Dangerous to change. + * + * @param id the animation ID */ void setID(int id); diff --git a/java/noppes/npcs/api/handler/data/IAnvilRecipe.java b/java/noppes/npcs/api/handler/data/IAnvilRecipe.java index 9de714b..40eb026 100644 --- a/java/noppes/npcs/api/handler/data/IAnvilRecipe.java +++ b/java/noppes/npcs/api/handler/data/IAnvilRecipe.java @@ -5,16 +5,22 @@ import net.minecraft.item.ItemStack; public interface IAnvilRecipe { /** * Returns the unique name of this anvil recipe. + * + * @return the recipe name */ String getName(); /** * The XP cost per repair tick (e.g., 10 levels per tick). + * + * @return the experience level cost */ int getXpCost(); /** * The repair percentage (e.g., 0.1f repairs 10% of max damage per tick). + * + * @return the repair percentage (0.0 to 1.0) */ float getRepairPercentage(); diff --git a/java/noppes/npcs/api/handler/data/IAuctionClaim.java b/java/noppes/npcs/api/handler/data/IAuctionClaim.java index 92b0331..cccc7ac 100644 --- a/java/noppes/npcs/api/handler/data/IAuctionClaim.java +++ b/java/noppes/npcs/api/handler/data/IAuctionClaim.java @@ -9,21 +9,25 @@ public interface IAuctionClaim { /** * Get the unique claim ID. + * @return the unique claim ID */ String getId(); /** * Get the player's UUID who can claim this. + * @return the UUID of the player who can claim this */ String getPlayerUUID(); /** * Get the player's display name. + * @return the name of the player who can claim this */ String getPlayerName(); /** * Get the related listing ID. + * @return the ID of the original auction listing */ String getListingId(); @@ -36,16 +40,19 @@ public interface IAuctionClaim { /** * Check if this is an item claim. + * @return true if this claim contains an item to collect */ boolean isItemClaim(); /** * Check if this is a currency claim (sale proceeds or refund). + * @return true if this claim contains currency to collect */ boolean isCurrencyClaim(); /** * Check if this is a refund claim (outbid). + * @return true if this is a refund from an outbid or cancelled auction */ boolean isRefundClaim(); @@ -58,11 +65,13 @@ public interface IAuctionClaim { /** * Get the item display name (for currency/refund claims tooltip). + * @return the display name of the claimed item */ String getItemName(); /** * Get the currency amount (for currency/refund claims). + * @return the currency amount to claim */ long getCurrency(); @@ -70,32 +79,38 @@ public interface IAuctionClaim { * Get the other player's name involved. * For currency claims: the buyer's name. * For refund claims: the player who outbid. + * @return the name of the other party in the transaction */ String getOtherPlayerName(); /** * Get when this claim was created (Unix timestamp in ms). + * @return the timestamp when this claim was created */ long getCreatedTime(); /** * Check if this claim has been claimed. + * @return true if this claim has already been collected */ boolean isClaimed(); /** * Check if this is a returned item (expired/cancelled listing) vs won item. * Only relevant for item claims. + * @return true if this is a returned unsold item */ boolean isReturnedItem(); /** * Get days until this claim expires. + * @return the number of days until this claim expires */ long getDaysUntilExpiration(); /** * Check if this claim has expired. + * @return true if this claim has expired */ boolean isExpired(); } diff --git a/java/noppes/npcs/api/handler/data/IAuctionListing.java b/java/noppes/npcs/api/handler/data/IAuctionListing.java index a49496e..d6285ee 100644 --- a/java/noppes/npcs/api/handler/data/IAuctionListing.java +++ b/java/noppes/npcs/api/handler/data/IAuctionListing.java @@ -9,86 +9,103 @@ public interface IAuctionListing { /** * Get the unique listing ID. + * @return the unique listing ID */ String getId(); /** * Get the seller's UUID as a string. + * @return the seller's UUID */ String getSellerUUID(); /** * Get the seller's display name. + * @return the seller's display name */ String getSellerName(); /** * Get the item being sold. + * @return the item being auctioned */ IItemStack getItem(); /** * Get the starting price. + * @return the starting bid price in currency */ long getStartingPrice(); /** * Get the buyout price (0 if no buyout). + * @return the instant buyout price in currency */ long getBuyoutPrice(); /** * Check if this listing has a buyout option. + * @return true if this listing has a buyout option */ boolean hasBuyout(); /** * Get the current highest bid. + * @return the current highest bid amount */ long getCurrentBid(); /** * Get the high bidder's UUID as a string (null if no bids). + * @return the UUID of the current highest bidder */ String getHighBidderUUID(); /** * Get the high bidder's display name (null if no bids). + * @return the name of the current highest bidder */ String getHighBidderName(); /** * Check if there are any bids on this listing. + * @return true if any bids have been placed */ boolean hasBids(); /** * Get the total number of bids placed. + * @return the total number of bids placed */ int getBidCount(); /** * Get when the listing was created (Unix timestamp in ms). + * @return the timestamp when this listing was created */ long getCreatedTime(); /** * Get when the auction ends (Unix timestamp in ms). + * @return the timestamp when this listing ends */ long getEndTime(); /** * Get the remaining time in milliseconds. + * @return the remaining time in milliseconds */ long getRemainingTime(); /** * Check if the auction has expired. + * @return true if the listing has ended */ boolean isExpired(); /** * Check if the auction is still active (can be bid on). + * @return true if the listing is still accepting bids */ boolean isActive(); @@ -101,21 +118,27 @@ public interface IAuctionListing { /** * Get the minimum bid amount (current bid + increment). + * @return the minimum bid amount required */ long getMinimumBid(); /** * Check if a player UUID is the seller. + * @param playerUUID the player UUID to check + * @return true if this player is the seller */ boolean isSeller(String playerUUID); /** * Check if a player UUID is the current high bidder. + * @param playerUUID the player UUID to check + * @return true if this player is the current highest bidder */ boolean isHighBidder(String playerUUID); /** * Get the remaining time formatted as a string (e.g., "2h 30m"). + * @return the remaining time as a human-readable string */ String getRemainingTimeFormatted(); } diff --git a/java/noppes/npcs/api/handler/data/ICustomEffect.java b/java/noppes/npcs/api/handler/data/ICustomEffect.java index e180049..7a5a543 100644 --- a/java/noppes/npcs/api/handler/data/ICustomEffect.java +++ b/java/noppes/npcs/api/handler/data/ICustomEffect.java @@ -2,46 +2,152 @@ package noppes.npcs.api.handler.data; public interface ICustomEffect { + /** + * Returns the unique ID of this custom effect. + * + * @return the effect ID, or -1 if not yet assigned + */ int getID(); + /** + * Returns the internal name of this custom effect. + * + * @return the effect name + */ String getName(); + /** + * Sets the display name shown in menus. Supports color codes using '&' (converted to section signs). + * + * @param name the display name to set; ignored if null or empty + */ void setMenuName(String name); + /** + * Returns the display name shown in menus. + * + * @return the menu display name + */ String getMenuName(); + /** + * Sets the internal name of this custom effect. + * + * @param name the name to set; ignored if null or empty + */ void setName(String name); + /** + * Returns the resource path of the icon texture. + * + * @return the icon texture path + */ String getIcon(); + /** + * Sets the resource path of the icon texture. + * + * @param icon the icon texture path + */ void setIcon(String icon); + /** + * Returns the tick interval at which this effect fires its script tick event. + * + * @return the tick interval (always a multiple of 10, minimum 10) + */ int getEveryXTick(); + /** + * Sets the tick interval at which this effect fires its script tick event. + * The value is rounded to the nearest multiple of 10 with a minimum of 10. + * + * @param everyXTick the desired tick interval + */ void setEveryXTick(int everyXTick); + /** + * Returns the X offset of the icon within the texture. + * + * @return the icon X offset in pixels + */ int getIconX(); + /** + * Sets the X offset of the icon within the texture. + * + * @param iconX the icon X offset in pixels + */ void setIconX(int iconX); + /** + * Returns the Y offset of the icon within the texture. + * + * @return the icon Y offset in pixels + */ int getIconY(); + /** + * Sets the Y offset of the icon within the texture. + * + * @param iconY the icon Y offset in pixels + */ void setIconY(int iconY); + /** + * Returns the width of the icon. + * + * @return the icon width in pixels + */ int getWidth(); + /** + * Sets the width of the icon. + * + * @param width the icon width in pixels + */ void setWidth(int width); + /** + * Returns the height of the icon. + * + * @return the icon height in pixels + */ int getHeight(); + /** + * Sets the height of the icon. + * + * @param height the icon height in pixels + */ void setHeight(int height); + /** + * Returns whether this effect is removed when the player dies. + * + * @return true if the effect is lost on death + */ boolean isLossOnDeath(); + /** + * Sets whether this effect is removed when the player dies. + * + * @param lossOnDeath true to remove the effect on death + */ void setLossOnDeath(boolean lossOnDeath); + /** + * Saves this custom effect to the effect controller. + * + * @return the saved effect instance + */ ICustomEffect save(); + /** + * Sets the unique ID of this custom effect. + * + * @param id the effect ID to assign + */ void setID(int id); /** @@ -49,19 +155,53 @@ public interface ICustomEffect { * which map of Effects to Match to. * Index: 0 - CNPC+ * Index: 1 - DBC Addon + * + * @return the effect's index in the effect list */ int getIndex(); + /** + * Returns whether the icon texture is animated. + * + * @return true if the icon is animated + */ boolean isAnimated(); + /** + * Sets whether the icon texture is animated. + * + * @param animated true to enable icon animation + */ void setAnimated(boolean animated); + /** + * Returns the number of frames in the icon animation. + * + * @return the frame count (minimum 1) + */ int getFrameCount(); + /** + * Sets the number of frames in the icon animation. + * Values less than 1 are clamped to 1. + * + * @param frameCount the number of animation frames + */ void setFrameCount(int frameCount); + /** + * Returns the duration of each animation frame in ticks. + * + * @return the frame time in ticks (minimum 1) + */ int getFrameTime(); + /** + * Sets the duration of each animation frame in ticks. + * Values less than 1 are clamped to 1. + * + * @param frametime the frame duration in ticks + */ void setFrameTime(int frametime); } diff --git a/java/noppes/npcs/api/handler/data/IDialog.java b/java/noppes/npcs/api/handler/data/IDialog.java index 620f286..3d6fa64 100644 --- a/java/noppes/npcs/api/handler/data/IDialog.java +++ b/java/noppes/npcs/api/handler/data/IDialog.java @@ -3,137 +3,378 @@ package noppes.npcs.api.handler.data; import java.util.List; public interface IDialog { + /** + * @return The unique ID of this dialog + */ int getId(); + /** + * @return The title/name of this dialog + */ String getName(); + /** + * Sets the title/name of this dialog. + * @param var1 The new dialog title + */ void setName(String var1); + /** + * @return The dialog body text displayed to the player + */ String getText(); + /** + * Sets the dialog body text displayed to the player. + * @param var1 The new dialog text + */ void setText(String var1); + /** + * @return The quest associated with this dialog, or null if none + */ IQuest getQuest(); + /** + * Sets the quest associated with this dialog. + * @param var1 The quest to associate, or null to remove + */ void setQuest(IQuest var1); + /** + * @return The command executed when this dialog is shown + */ String getCommand(); + /** + * Sets the command executed when this dialog is shown. + * @param var1 The command string + */ void setCommand(String var1); + /** + * @return A list of all dialog options + */ List getOptions(); + /** + * Gets a dialog option by its slot index. + * @param var1 The option slot index + * @return The dialog option at the given slot + */ IDialogOption getOption(int var1); + /** + * @return The availability settings for this dialog + */ IAvailability getAvailability(); + /** + * @return The category this dialog belongs to + */ IDialogCategory getCategory(); + /** + * Sets whether the screen darkens when this dialog is displayed. + * @param darkenScreen True to darken the screen + */ void setDarkenScreen(boolean darkenScreen); + /** + * @return Whether the screen darkens when this dialog is displayed + */ boolean getDarkenScreen(); + /** + * Sets whether the Escape key is disabled while this dialog is open. + * @param disableEsc True to disable the Escape key + */ void setDisableEsc(boolean disableEsc); + /** + * @return Whether the Escape key is disabled while this dialog is open + */ boolean getDisableEsc(); + /** + * Sets whether the dialog option wheel is shown. + * @param showWheel True to show the option wheel + */ void setShowWheel(boolean showWheel); + /** + * @return Whether the dialog option wheel is shown + */ boolean getShowWheel(); + /** + * Sets whether the NPC is hidden during this dialog. + * @param hideNPC True to hide the NPC + */ void setHideNPC(boolean hideNPC); + /** + * @return Whether the NPC is hidden during this dialog + */ boolean getHideNPC(); + /** + * Sets the sound played when this dialog opens. + * @param sound The resource location of the sound + */ void setSound(String sound); + /** + * @return The resource location of the sound played when this dialog opens + */ String getSound(); + /** + * Saves this dialog to the dialog controller. + */ void save(); + /** + * Sets the text color of the dialog body. + * @param color The color as an integer (e.g. 0xe0e0e0) + */ void setColor(int color); + /** + * @return The text color of the dialog body + */ int getColor(); + /** + * Sets the color of the dialog title. + * @param titleColor The color as an integer (e.g. 0xe0e0e0) + */ void setTitleColor(int titleColor); + /** + * @return The color of the dialog title + */ int getTitleColor(); + /** + * Sets whether the dialog text renders character by character. + * @param gradual True to enable gradual text rendering + */ void renderGradual(boolean gradual); + /** + * @return Whether the dialog text renders character by character + */ boolean renderGradual(); + /** + * Sets whether previous dialog text blocks are shown. + * @param show True to show previous dialog blocks + */ void showPreviousBlocks(boolean show); + /** + * @return Whether previous dialog text blocks are shown + */ boolean showPreviousBlocks(); + /** + * Sets whether the separator line above dialog options is shown. + * @param show True to show the option line + */ void showOptionLine(boolean show); + /** + * @return Whether the separator line above dialog options is shown + */ boolean showOptionLine(); + /** + * Sets the sound played per character during gradual text rendering. + * @param textSound The resource location of the text sound + */ void setTextSound(String textSound); + /** + * @return The resource location of the sound played per character during gradual text rendering + */ String getTextSound(); + /** + * Sets the pitch of the per-character text sound. + * @param textPitch The pitch value (default 1.0) + */ void setTextPitch(float textPitch); + /** + * @return The pitch of the per-character text sound + */ float getTextPitch(); + /** + * Sets the position of the dialog title. + * @param pos The title position value + */ void setTitlePos(int pos); + /** + * @return The position of the dialog title + */ int getTitlePos(); + /** + * Sets the render scale of the NPC in the dialog. + * @param scale The NPC scale (default 1.0) + */ void setNPCScale(float scale); + /** + * @return The render scale of the NPC in the dialog + */ float getNpcScale(); + /** + * Sets the NPC render offset in the dialog. + * @param offsetX The horizontal offset in pixels + * @param offsetY The vertical offset in pixels + */ void setNpcOffset(int offsetX, int offsetY); + /** + * @return The horizontal offset of the NPC render in pixels + */ int getNpcOffsetX(); + /** + * @return The vertical offset of the NPC render in pixels + */ int getNpcOffsetY(); + /** + * Sets the width and height of the dialog text area. + * @param textWidth The text area width in pixels + * @param textHeight The text area height in pixels + */ void textWidthHeight(int textWidth, int textHeight); + /** + * @return The width of the dialog text area in pixels + */ int getTextWidth(); + /** + * @return The height of the dialog text area in pixels + */ int setTextHeight(); + /** + * Sets the offset of the dialog text area. + * @param offsetX The horizontal offset in pixels + * @param offsetY The vertical offset in pixels + */ void setTextOffset(int offsetX, int offsetY); + /** + * @return The horizontal offset of the dialog text area in pixels + */ int getTextOffsetX(); + /** + * @return The vertical offset of the dialog text area in pixels + */ int getTextOffsetY(); + /** + * Sets the offset of the dialog title. + * @param offsetX The horizontal offset in pixels + * @param offsetY The vertical offset in pixels + */ void setTitleOffset(int offsetX, int offsetY); + /** + * @return The horizontal offset of the dialog title in pixels + */ int getTitleOffsetX(); + /** + * @return The vertical offset of the dialog title in pixels + */ int getTitleOffsetY(); + /** + * Sets the offset of the dialog options area. + * @param offsetX The horizontal offset in pixels + * @param offsetY The vertical offset in pixels + */ void setOptionOffset(int offsetX, int offsetY); + /** + * @return The horizontal offset of the dialog options area in pixels + */ int getOptionOffsetX(); + /** + * @return The vertical offset of the dialog options area in pixels + */ int getOptionOffsetY(); + /** + * Sets the spacing between dialog options. + * @param spaceX The horizontal spacing in pixels + * @param spaceY The vertical spacing in pixels + */ void setOptionSpacing(int spaceX, int spaceY); + /** + * @return The horizontal spacing between dialog options in pixels + */ int getOptionSpaceX(); + /** + * @return The vertical spacing between dialog options in pixels + */ int getOptionSpaceY(); + /** + * Adds an image to the dialog at the given ID. + * @param id The image ID + * @param image The dialog image to add + */ void addImage(int id, IDialogImage image); + /** + * Gets a dialog image by its ID. + * @param id The image ID + * @return The dialog image, or null if not found + */ IDialogImage getImage(int id); + /** + * Creates a new empty dialog image instance. + * @return A new {@link IDialogImage} + */ IDialogImage createImage(); + /** + * @return An array of all dialog images + */ IDialogImage[] getImages(); + /** + * Checks whether an image with the given ID exists. + * @param id The image ID + * @return True if the image exists + */ boolean hasImage(int id); + /** + * Removes the image with the given ID. + * @param id The image ID to remove + */ void removeImage(int id); + /** + * Removes all images from this dialog. + */ void clearImages(); } diff --git a/java/noppes/npcs/api/handler/data/IDialogCategory.java b/java/noppes/npcs/api/handler/data/IDialogCategory.java index f7a6c09..2b35736 100644 --- a/java/noppes/npcs/api/handler/data/IDialogCategory.java +++ b/java/noppes/npcs/api/handler/data/IDialogCategory.java @@ -3,11 +3,24 @@ package noppes.npcs.api.handler.data; import java.util.List; public interface IDialogCategory { + /** + * @return A list of all dialogs in this category + */ List dialogs(); + /** + * @return The name of this dialog category + */ String getName(); + /** + * Creates a new empty dialog in this category. + * @return The newly created {@link IDialog} + */ IDialog create(); + /** + * @return The unique ID of this dialog category + */ int getId(); } diff --git a/java/noppes/npcs/api/handler/data/IDialogImage.java b/java/noppes/npcs/api/handler/data/IDialogImage.java index f48cefd..a446c2e 100644 --- a/java/noppes/npcs/api/handler/data/IDialogImage.java +++ b/java/noppes/npcs/api/handler/data/IDialogImage.java @@ -1,55 +1,147 @@ package noppes.npcs.api.handler.data; public interface IDialogImage { + /** + * @return The unique ID of this dialog image + */ int getId(); + /** + * Sets the texture resource location for this image. + * @param texture The resource location string + */ void setTexture(String texture); + /** + * @return The texture resource location for this image + */ String getTexture(); + /** + * Sets the screen position of this image. + * @param x The X position in pixels + * @param y The Y position in pixels + */ void setPosition(int x, int y); + /** + * @return The X position of this image in pixels + */ int getX(); + /** + * @return The Y position of this image in pixels + */ int getY(); + /** + * Sets the rendered width and height of this image. + * @param width The width in pixels + * @param height The height in pixels + */ void setWidthHeight(int width, int height); + /** + * @return The rendered width of this image in pixels + */ int getWidth(); + /** + * @return The rendered height of this image in pixels + */ int getHeight(); + /** + * Sets the texture UV offset for this image. + * @param offsetX The horizontal texture offset in pixels + * @param offsetY The vertical texture offset in pixels + */ void setTextureOffset(int offsetX, int offsetY); + /** + * @return The horizontal texture UV offset in pixels + */ int getTextureX(); + /** + * @return The vertical texture UV offset in pixels + */ int getTextureY(); + /** + * Sets the tint color of this image. + * @param color The color as an integer (e.g. 0xFFFFFF) + */ void setColor(int color); + /** + * @return The tint color of this image + */ int getColor(); + /** + * Sets the tint color used when this image is selected/hovered. + * @param color The selected color as an integer (e.g. 0xFFFFFF) + */ void setSelectedColor(int color); + /** + * @return The tint color used when this image is selected/hovered + */ int getSelectedColor(); + /** + * Sets the render scale of this image. + * @param scale The scale factor (default 1.0) + */ void setScale(float scale); + /** + * @return The render scale of this image + */ float getScale(); + /** + * Sets the alpha transparency of this image. + * @param alpha The alpha value from 0.0 (transparent) to 1.0 (opaque) + */ void setAlpha(float alpha); + /** + * @return The alpha transparency of this image (0.0 to 1.0) + */ float getAlpha(); + /** + * Sets the rotation angle of this image. + * @param rotation The rotation in degrees + */ void setRotation(float rotation); + /** + * @return The rotation angle of this image in degrees + */ float getRotation(); + /** + * Sets the image type which determines where the image is rendered. + * @param imageType The image type: 0 = Default, 1 = Text, 2 = Option + */ void setImageType(int imageType); + /** + * @return The image type: 0 = Default, 1 = Text, 2 = Option + */ int getImageType(); + /** + * Sets the alignment of this image. + * @param alignment The alignment value + */ void setAlignment(int alignment); + /** + * @return The alignment value of this image + */ int getAlignment(); } diff --git a/java/noppes/npcs/api/handler/data/IDialogOption.java b/java/noppes/npcs/api/handler/data/IDialogOption.java index 6c7a3e3..c98b75f 100644 --- a/java/noppes/npcs/api/handler/data/IDialogOption.java +++ b/java/noppes/npcs/api/handler/data/IDialogOption.java @@ -1,9 +1,18 @@ package noppes.npcs.api.handler.data; public interface IDialogOption { + /** + * @return The slot index of this dialog option + */ int getSlot(); + /** + * @return The display name/title of this dialog option + */ String getName(); + /** + * @return The option type ordinal: 0 = QuitOption, 1 = DialogOption, 2 = Disabled, 3 = RoleOption, 4 = CommandBlock + */ int getType(); } diff --git a/java/noppes/npcs/api/handler/data/IFaction.java b/java/noppes/npcs/api/handler/data/IFaction.java index 71ffff2..e4f5f57 100644 --- a/java/noppes/npcs/api/handler/data/IFaction.java +++ b/java/noppes/npcs/api/handler/data/IFaction.java @@ -4,51 +4,139 @@ import noppes.npcs.api.entity.ICustomNpc; import noppes.npcs.api.entity.IPlayer; public interface IFaction { + /** + * @return The faction's unique ID + */ int getId(); + /** + * @return The faction's display name + */ String getName(); + /** + * Sets the faction's display name. + * @param name The new name + */ void setName(String name); + /** + * Sets the default faction points assigned to new players. + * @param var1 The default point value + */ void setDefaultPoints(int var1); + /** + * @return The default faction points assigned to new players + */ int getDefaultPoints(); + /** + * Sets the point threshold at or above which a player is considered friendly. + * @param p The friendly point threshold + */ void setFriendlyPoints(int p); + /** + * @return The point threshold at or above which a player is considered friendly + */ int getFriendlyPoints(); + /** + * Sets the point threshold below which a player is considered an enemy. + * @param p The neutral point threshold + */ void setNeutralPoints(int p); + /** + * @return The point threshold below which a player is considered an enemy + */ int getNeutralPoints(); + /** + * Sets the faction's display color. + * @param c The color as an RGB integer + */ void setColor(int c); + /** + * @return The faction's display color as an RGB integer + */ int getColor(); + /** + * Returns the player's standing with this faction. + * @param player The player to check + * @return 1 for friendly, 0 for neutral, -1 for enemy + */ int playerStatus(IPlayer player); + /** + * Checks whether this faction is hostile toward the given NPC's faction. + * @param npc The NPC to check against + * @return True if this faction is aggressive toward the NPC + */ boolean isAggressiveToNpc(ICustomNpc npc); + /** + * @return Whether this faction is hidden from the player's faction list + */ boolean getIsHidden(); + /** + * Sets whether this faction is hidden from the player's faction list. + * @param hidden True to hide the faction + */ void setIsHidden(boolean hidden); + /** + * @return Whether NPCs in this faction are passive and will not attack + */ boolean isPassive(); + /** + * Sets whether NPCs in this faction are passive. + * @param passive True to make faction NPCs passive + */ void setIsPassive(boolean passive); + /** + * @return Whether NPCs in this faction can be attacked by hostile mobs + */ boolean attackedByMobs(); + /** + * Sets whether NPCs in this faction can be attacked by hostile mobs. + * @param attacked True to allow mobs to attack faction NPCs + */ void setAttackedByMobs(boolean attacked); + /** + * Checks whether the given faction is an enemy of this faction. + * @param faction The faction to check + * @return True if the given faction is an enemy + */ boolean isEnemyFaction(IFaction faction); + /** + * @return An array of all factions that are enemies of this faction + */ IFaction[] getEnemyFactions(); + /** + * Adds a faction as an enemy of this faction. + * @param faction The faction to add as an enemy + */ void addEnemyFaction(IFaction faction); + /** + * Removes a faction from this faction's enemy list. + * @param faction The faction to remove + */ void removeEnemyFaction(IFaction faction); + /** + * Saves the faction data to the server. + */ void save(); } diff --git a/java/noppes/npcs/api/handler/data/IFrame.java b/java/noppes/npcs/api/handler/data/IFrame.java index f75657f..574a4ea 100644 --- a/java/noppes/npcs/api/handler/data/IFrame.java +++ b/java/noppes/npcs/api/handler/data/IFrame.java @@ -2,29 +2,83 @@ package noppes.npcs.api.handler.data; public interface IFrame { + /** + * @return An array of all frame parts in this frame + */ IFramePart[] getParts(); + /** + * Adds a frame part to this frame. + * @param partConfig The frame part to add + * @return This frame for chaining + */ IFrame addPart(IFramePart partConfig); + /** + * Removes a frame part by its name. + * @param partName The animation part name (e.g. HEAD, BODY, RIGHT_ARM, LEFT_ARM, RIGHT_LEG, LEFT_LEG, FULL_MODEL) + * @return This frame for chaining + */ IFrame removePart(String partName); + /** + * Removes a frame part by its ordinal ID. + * @param partId The animation part ordinal ID + * @return This frame for chaining + */ IFrame removePart(int partId); + /** + * Removes all frame parts from this frame. + * @return This frame for chaining + */ IFrame clearParts(); + /** + * @return The duration of this frame in ticks + */ int getDuration(); + /** + * Sets the duration of this frame. + * @param duration The duration in ticks + * @return This frame for chaining + */ IFrame setDuration(int duration); + /** + * @return Whether this frame has custom speed and smooth settings that override the parent animation + */ boolean isCustomized(); + /** + * Sets whether this frame uses custom speed and smooth settings. + * @param customized True to use frame-level settings instead of the parent animation's + * @return This frame for chaining + */ IFrame setCustomized(boolean customized); + /** + * @return The interpolation speed of this frame + */ float getSpeed(); + /** + * Sets the interpolation speed of this frame. + * @param speed The speed value + * @return This frame for chaining + */ IFrame setSpeed(float speed); + /** + * @return The smooth interpolation type: 0 = Interpolated, 1 = Linear, 2 = None + */ byte smoothType(); + /** + * Sets the smooth interpolation type. + * @param smooth The smooth type: 0 = Interpolated, 1 = Linear, 2 = None + * @return This frame for chaining + */ IFrame setSmooth(byte smooth); } diff --git a/java/noppes/npcs/api/handler/data/IFramePart.java b/java/noppes/npcs/api/handler/data/IFramePart.java index 3bb63e2..1b2dd8a 100644 --- a/java/noppes/npcs/api/handler/data/IFramePart.java +++ b/java/noppes/npcs/api/handler/data/IFramePart.java @@ -2,31 +2,87 @@ package noppes.npcs.api.handler.data; public interface IFramePart { + /** + * @return The name of the animation part (e.g. HEAD, BODY, RIGHT_ARM, LEFT_ARM, RIGHT_LEG, LEFT_LEG, FULL_MODEL) + */ String getName(); + /** + * @return The ordinal ID of the animation part + */ int getPartId(); + /** + * Sets the animation part by name. + * @param name The part name (e.g. HEAD, BODY, RIGHT_ARM, LEFT_ARM, RIGHT_LEG, LEFT_LEG, FULL_MODEL) + * @return This frame part for chaining + */ IFramePart setPart(String name); + /** + * Sets the animation part by ordinal ID. + * @param partId The part ordinal ID + * @return This frame part for chaining + */ IFramePart setPart(int partId); + /** + * @return The rotation angles as a float array [x, y, z] in degrees + */ float[] getRotations(); + /** + * Sets the rotation angles. + * @param rotation A float array [x, y, z] in degrees + * @return This frame part for chaining + */ IFramePart setRotations(float[] rotation); + /** + * @return The pivot offsets as a float array [x, y, z] + */ float[] getPivots(); + /** + * Sets the pivot offsets. + * @param pivot A float array [x, y, z] + * @return This frame part for chaining + */ IFramePart setPivots(float[] pivot); + /** + * @return Whether this part has custom speed and smooth settings that override the parent frame + */ boolean isCustomized(); + /** + * Sets whether this part uses custom speed and smooth settings. + * @param customized True to use part-level settings instead of the parent frame's + * @return This frame part for chaining + */ IFramePart setCustomized(boolean customized); + /** + * @return The interpolation speed of this part + */ float getSpeed(); + /** + * Sets the interpolation speed of this part. + * @param speed The speed value + * @return This frame part for chaining + */ IFramePart setSpeed(float speed); + /** + * @return The smooth interpolation type: 0 = Interpolated, 1 = Linear, 2 = None + */ byte isSmooth(); + /** + * Sets the smooth interpolation type. + * @param smooth The smooth type: 0 = Interpolated, 1 = Linear, 2 = None + * @return This frame part for chaining + */ IFramePart setSmooth(byte smooth); } diff --git a/java/noppes/npcs/api/handler/data/ILine.java b/java/noppes/npcs/api/handler/data/ILine.java index 42ae759..99c53a0 100644 --- a/java/noppes/npcs/api/handler/data/ILine.java +++ b/java/noppes/npcs/api/handler/data/ILine.java @@ -2,19 +2,46 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.entity.IEntityLivingBase; +/** + * Represents a single NPC dialog line with text, an optional sound, and target formatting. + */ public interface ILine { + /** + * Returns a copy of this line with target-specific placeholders resolved. + * + * @param entityLivingBase the target entity used for placeholder substitution. + * @return the formatted line. + */ ILine formatTarget(IEntityLivingBase entityLivingBase); + /** @return the text content of this line. */ String getText(); + /** + * Sets the text content of this line. + * + * @param text the new text. + */ void setText(String text); + /** @return the sound resource to play with this line, or null if none. */ String getSound(); + /** + * Sets the sound resource to play with this line. + * + * @param sound the sound resource path, or null for none. + */ void setSound(String sound); + /** + * Sets whether the text of this line should be hidden when spoken. + * + * @param hide true to hide the text; false to show. + */ void hideText(boolean hide); + /** @return true if the text is hidden when this line is spoken. */ boolean hideText(); } diff --git a/java/noppes/npcs/api/handler/data/ILines.java b/java/noppes/npcs/api/handler/data/ILines.java index 39ede57..0c69251 100644 --- a/java/noppes/npcs/api/handler/data/ILines.java +++ b/java/noppes/npcs/api/handler/data/ILines.java @@ -1,20 +1,57 @@ package noppes.npcs.api.handler.data; +/** + * A collection of dialog lines, supporting creation, indexed access, and random retrieval. + */ public interface ILines { + /** + * Creates and adds a new line with the given text. + * + * @param text the line text. + * @return the created line. + */ ILine createLine(String text); + /** + * Returns a line, either randomly or sequentially. + * + * @param isRandom true to return a random line; false for sequential. + * @return the selected line, or null if empty. + */ ILine getLine(boolean isRandom); + /** + * Returns the line at the given index. + * + * @param lineIndex the line index. + * @return the line, or null if the index is invalid. + */ ILine getLine(int lineIndex); + /** + * Sets the line at the given index. + * + * @param lineIndex the line index. + * @param line the line to set. + */ void setLine(int lineIndex, ILine line); + /** + * Removes the line at the given index. + * + * @param lineIndex the line index. + */ void removeLine(int lineIndex); + /** + * Removes all lines. + */ void clear(); + /** @return true if there are no lines. */ boolean isEmpty(); + /** @return the indices of all stored lines. */ Integer[] getKeys(); } diff --git a/java/noppes/npcs/api/handler/data/ILinkedItem.java b/java/noppes/npcs/api/handler/data/ILinkedItem.java index 2417872..e561dfe 100644 --- a/java/noppes/npcs/api/handler/data/ILinkedItem.java +++ b/java/noppes/npcs/api/handler/data/ILinkedItem.java @@ -2,61 +2,107 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.item.IItemStack; +/** + * Represents a linked item definition. Linked items are custom item templates + * that can be globally updated; all existing instances inherit the new properties. + */ public interface ILinkedItem { + /** + * Persists this linked item and returns the saved instance. + * + * @return the saved linked item. + */ ILinkedItem save(); + /** + * Creates an ItemStack from this linked item definition. + * + * @return the created item stack. + */ IItemStack createStack(); + /** @return the unique ID of this linked item. */ int getId(); + /** @param id the unique ID. */ void setId(int id); + /** @return the version number of this linked item. */ int getVersion(); + /** @param version the new version number. */ void setVersion(int version); + /** @return the display name. */ String getName(); + /** @param name the display name. */ void setName(String name); + /** @return the durability value (max damage). */ double getDurabilityValue(); + /** @param durabilityValue the durability value. */ void setDurabilityValue(double durabilityValue); + /** @return the maximum stack size. */ int getStackSize(); + /** @param stackSize the maximum stack size. */ void setStackSize(int stackSize); + /** @return the maximum item use duration in ticks. */ int getMaxItemUseDuration(); + /** @param maxItemUseDuration the use duration in ticks. */ void setMaxItemUseDuration(int maxItemUseDuration); + /** + * @return the item use action type. + * @see net.minecraft.item.EnumAction + */ int getItemUseAction(); + /** @param itemUseAction the item use action type ordinal. */ void setItemUseAction(int itemUseAction); + /** @return true if this is a normal (non-tool, non-armor) item. */ boolean isNormalItem(); + /** @param normalItem true for a normal item. */ void setNormalItem(boolean normalItem); + /** @return true if this item functions as a tool. */ boolean isTool(); + /** @param tool true to mark as a tool. */ void setTool(boolean tool); + /** @return the dig speed for tool items. */ int getDigSpeed(); + /** @param digSpeed the dig speed. */ void setDigSpeed(int digSpeed); + /** + * @return the armor type slot. + * 0: helmet, 1: chestplate, 2: leggings, 3: boots, -1: not armor. + */ int getArmorType(); + /** @param armorType the armor type slot. */ void setArmorType(int armorType); + /** @return the enchantability value. */ int getEnchantability(); + /** @param enchantability the enchantability value. */ void setEnchantability(int enchantability); - public int getAttackSpeed(); + /** @return the attack speed in ticks between attacks. */ + int getAttackSpeed(); - public void setAttackSpeed(int time); + /** @param time attack speed in ticks. */ + void setAttackSpeed(int time); } diff --git a/java/noppes/npcs/api/handler/data/INaturalSpawn.java b/java/noppes/npcs/api/handler/data/INaturalSpawn.java index 92601de..fee02bf 100644 --- a/java/noppes/npcs/api/handler/data/INaturalSpawn.java +++ b/java/noppes/npcs/api/handler/data/INaturalSpawn.java @@ -3,70 +3,125 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.IWorld; import noppes.npcs.api.entity.IEntity; +/** + * Configures a natural spawn entry for custom NPCs, including entity templates, + * biome restrictions, spawn conditions, and cooldowns. + */ public interface INaturalSpawn { + /** Despawn mode: force natural despawn behavior. */ int DESPAWN_FORCE_NATURAL = 0; + /** Despawn mode: preserve the entity template's despawn setting. */ int DESPAWN_PRESERVE_TEMPLATE = 1; + /** Despawn mode: force persistent (never despawn). */ int DESPAWN_FORCE_PERSISTENT = 2; + /** @param name the display name for this spawn entry. */ void setName(String name); + /** @return the display name of this spawn entry. */ String getName(); + /** + * Sets the entity template for a specific spawn slot. + * + * @param entity the entity template. + * @param slot the slot index. + */ void setEntity(IEntity entity, int slot); + /** + * Returns the entity for a specific spawn slot. + * + * @param world the world context for entity creation. + * @param slot the slot index. + * @return the entity, or null if the slot is empty. + */ IEntity getEntity(IWorld world, int slot); + /** @return the populated slot indices. */ Integer[] getSlots(); + /** @param weight the spawn weight (higher = more frequent). */ void setWeight(int weight); + /** @return the spawn weight. */ int getWeight(); + /** @param height the minimum Y-level for spawning. */ void setMinHeight(int height); + /** @return the minimum Y-level. */ int getMinHeight(); + /** @param height the maximum Y-level for spawning. */ void setMaxHeight(int height); + /** @return the maximum Y-level. */ int getMaxHeight(); + /** @param spawns whether entities can spawn using animal spawn rules. */ void spawnsLikeAnimal(boolean spawns); + /** @return true if animal spawn rules apply. */ boolean spawnsLikeAnimal(); + /** @param spawns whether entities can spawn using monster spawn rules. */ void spawnsLikeMonster(boolean spawns); + /** @return true if monster spawn rules apply. */ boolean spawnsLikeMonster(); + /** @param spawns whether entities can spawn in liquid. */ void spawnsInLiquid(boolean spawns); + /** @return true if spawning in liquid is allowed. */ boolean spawnsInLiquid(); + /** @param spawns whether entities can spawn in the air. */ void spawnsInAir(boolean spawns); + /** @return true if spawning in air is allowed. */ boolean spawnsInAir(); + /** @return the biome names this spawn is restricted to. */ String[] getBiomes(); + /** @param biomes the biome names to restrict spawning to. */ void setBiomes(String[] biomes); + /** @param maxAlive the maximum number of alive entities from this spawn at once. */ void setMaxAlive(int maxAlive); + /** @return the maximum alive entity count. */ int getMaxAlive(); + /** @param ticks the cooldown in ticks between spawn attempts. */ void setCooldownTicks(int ticks); + /** @return the cooldown in ticks. */ int getCooldownTicks(); + /** @param attempts the number of spawn attempts per cycle. */ void setAttemptsPerCycle(int attempts); + /** @return the number of spawn attempts per cycle. */ int getAttemptsPerCycle(); + /** @param distance the minimum distance from a player for spawning. */ void setPlayerMinDistance(int distance); + /** @return the minimum distance from a player. */ int getPlayerMinDistance(); + /** + * Sets the despawn mode. + * + * @param mode 0: DESPAWN_FORCE_NATURAL, 1: DESPAWN_PRESERVE_TEMPLATE, 2: DESPAWN_FORCE_PERSISTENT. + */ void setDespawnMode(int mode); + /** + * @return the despawn mode (0: force natural, 1: preserve template, 2: force persistent). + */ int getDespawnMode(); } diff --git a/java/noppes/npcs/api/handler/data/IParty.java b/java/noppes/npcs/api/handler/data/IParty.java index 9595d0e..fbd0987 100644 --- a/java/noppes/npcs/api/handler/data/IParty.java +++ b/java/noppes/npcs/api/handler/data/IParty.java @@ -73,6 +73,7 @@ public interface IParty { /** * Check if Player is in Party with IPlayer * + * @param player the player to check * @return true/false if player is in party */ boolean hasPlayer(IPlayer player); @@ -80,6 +81,7 @@ public interface IParty { /** * Check if Player is in Party with Player Name * + * @param playerName the player name to check * @return true/false if player is in party */ boolean hasPlayer(String playerName); diff --git a/java/noppes/npcs/api/handler/data/IPartyOptions.java b/java/noppes/npcs/api/handler/data/IPartyOptions.java index 4ce1b72..2205500 100644 --- a/java/noppes/npcs/api/handler/data/IPartyOptions.java +++ b/java/noppes/npcs/api/handler/data/IPartyOptions.java @@ -1,15 +1,22 @@ package noppes.npcs.api.handler.data; +/** + * Configures party-related options for quests, controlling membership requirements, + * reward distribution, completion rules, and party size limits. + */ public interface IPartyOptions { + /** @return true if party participation is allowed. */ + boolean isAllowParty(); - public boolean isAllowParty(); + /** @param allowParty true to allow party participation. */ + void setAllowParty(boolean allowParty); - public void setAllowParty(boolean allowParty); + /** @return true if only party members can participate. */ + boolean isOnlyParty(); - public boolean isOnlyParty(); - - public void setOnlyParty(boolean onlyParty); + /** @param onlyParty true to require party membership. */ + void setOnlyParty(boolean onlyParty); /** * @return 0:Leader, 1:All, 2:Valid @@ -61,12 +68,15 @@ public interface IPartyOptions { */ public void setObjectiveRequirement(int requirement); - public int getMinPartySize(); + /** @return the minimum party size required. */ + int getMinPartySize(); - public void setMinPartySize(int newSize); + /** @param newSize the minimum party size. */ + void setMinPartySize(int newSize); + /** @return the maximum party size allowed. */ + int getMaxPartySize(); - public int getMaxPartySize(); - - public void setMaxPartySize(int newSize); + /** @param newSize the maximum party size. */ + void setMaxPartySize(int newSize); } diff --git a/java/noppes/npcs/api/handler/data/IPlayerAttributes.java b/java/noppes/npcs/api/handler/data/IPlayerAttributes.java index c0855c0..a1f5854 100644 --- a/java/noppes/npcs/api/handler/data/IPlayerAttributes.java +++ b/java/noppes/npcs/api/handler/data/IPlayerAttributes.java @@ -13,6 +13,8 @@ public interface IPlayerAttributes { /** * Recalulates Item Attributes on a Player + * + * @param player the player whose attributes to recalculate */ void recalculate(IPlayer player); diff --git a/java/noppes/npcs/api/handler/data/IPlayerEffect.java b/java/noppes/npcs/api/handler/data/IPlayerEffect.java index c59bd12..e8851e5 100644 --- a/java/noppes/npcs/api/handler/data/IPlayerEffect.java +++ b/java/noppes/npcs/api/handler/data/IPlayerEffect.java @@ -2,25 +2,42 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.entity.IPlayer; +/** + * Represents an active custom effect instance on a player. + */ public interface IPlayerEffect { + /** Removes this effect from the player. */ void kill(); + /** @return the custom effect ID. */ int getId(); + /** @return the remaining duration in seconds (-100 for infinite). */ int getDuration(); + /** @param duration the remaining duration in seconds (-100 for infinite). */ void setDuration(int duration); + /** @return the effect level/amplifier. */ byte getLevel(); + /** @param level the effect level/amplifier. */ void setLevel(byte level); + /** @return the display name of the effect. */ String getName(); + /** + * Applies this effect's tick logic to the given player. + * + * @param player the player to apply the effect to. + */ void performEffect(IPlayer player); + /** @return the effect source index (0: CNPC+, 1: DBC Addon). */ int getIndex(); + /** @param index the effect source index (0: CNPC+, 1: DBC Addon). */ void setIndex(int index); } diff --git a/java/noppes/npcs/api/handler/data/IPlayerMail.java b/java/noppes/npcs/api/handler/data/IPlayerMail.java index 7c01902..f2e27db 100644 --- a/java/noppes/npcs/api/handler/data/IPlayerMail.java +++ b/java/noppes/npcs/api/handler/data/IPlayerMail.java @@ -2,31 +2,52 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.item.IItemStack; +/** + * Represents a mail message sent to a player, containing pages of text, + * sender info, optional quest, and item attachments. + */ public interface IPlayerMail { + /** + * Sets the page text content. + * + * @param pages an array of strings, one per page. + */ void setPageText(String[] pages); + /** @return the page text as an array of strings. */ String[] getPageText(); + /** @return the number of pages. */ int getPageCount(); + /** @param sender the sender name. */ void setSender(String sender); + /** @return the sender name. */ String getSender(); + /** @param subject the mail subject line. */ void setSubject(String subject); + /** @return the mail subject line. */ String getSubject(); + /** @return milliseconds since the mail was sent. */ long getTimePast(); + /** @return the timestamp when the mail was sent. */ long getTimeSent(); + /** @return true if this mail has an associated quest. */ boolean hasQuest(); + /** @return the quest attached to this mail, or null if none. */ IQuest getQuest(); + /** @return the item attachments. */ IItemStack[] getItems(); + /** @param items the item attachments. */ void setItems(IItemStack[] items); } diff --git a/java/noppes/npcs/api/handler/data/IQuest.java b/java/noppes/npcs/api/handler/data/IQuest.java index 6aa4294..cb75503 100644 --- a/java/noppes/npcs/api/handler/data/IQuest.java +++ b/java/noppes/npcs/api/handler/data/IQuest.java @@ -3,56 +3,100 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.IContainer; import noppes.npcs.api.entity.IPlayer; +/** + * Represents a quest with objectives, rewards, repeatability, and party/profile options. + */ public interface IQuest { + + /** @return the unique quest ID. */ int getId(); + /** @return the quest display name. */ String getName(); - void setName(String var1); + /** @param name the quest display name. */ + void setName(String name); + /** @return the quest type ordinal (0: Item, 1: Dialog, 2: Kill, 3: Location, 4: AreaKill, 5: Manual). */ int getType(); - void setType(int var1); + /** @param type the quest type ordinal. */ + void setType(int type); + /** @return the quest log description text. */ String getLogText(); - void setLogText(String var1); + /** @param text the quest log description text. */ + void setLogText(String text); + /** @return the text displayed on quest completion. */ String getCompleteText(); - void setCompleteText(String var1); + /** @param text the completion text. */ + void setCompleteText(String text); + /** @return the next quest in the chain, or null if none. */ IQuest getNextQuest(); - void setNextQuest(IQuest var1); + /** @param quest the next quest in the chain, or null to clear. */ + void setNextQuest(IQuest quest); - IQuestObjective[] getObjectives(IPlayer var1); + /** + * Returns the quest objectives for the given player. + * + * @param player the player whose objectives to retrieve. + * @return an array of quest objectives. + */ + IQuestObjective[] getObjectives(IPlayer player); + /** @return the category this quest belongs to. */ IQuestCategory getCategory(); + /** @return the reward container with items given on completion. */ IContainer getRewards(); + /** @return the NPC name associated with this quest. */ String getNpcName(); - void setNpcName(String var1); + /** @param name the NPC name. */ + void setNpcName(String name); + /** Saves this quest to disk. */ void save(); + /** @return true if this quest can be repeated. */ boolean getIsRepeatable(); + /** + * Returns the time remaining before the quest can be repeated. + * + * @param player the player. + * @return milliseconds until repeatable, or 0 if ready. + */ long getTimeUntilRepeat(IPlayer player); + /** + * Sets the repeat type. + * + * @param type 0: None, 1: Instant, 2: Daily, 3: Weekly, 4: Custom. + */ void setRepeatType(int type); + /** @return the repeat type ordinal. */ int getRepeatType(); + /** @return the quest interface (type-specific objective data). */ IQuestInterface getQuestInterface(); + /** @return the party options for this quest. */ IPartyOptions getPartyOptions(); + /** @return the profile options for this quest. */ IProfileOptions getProfileOptions(); + /** @return the custom cooldown in milliseconds for the Custom repeat type. */ long getCustomCooldown(); + /** @param newCooldown the custom cooldown in milliseconds. */ void setCustomCooldown(long newCooldown); } diff --git a/java/noppes/npcs/api/handler/data/IQuestCategory.java b/java/noppes/npcs/api/handler/data/IQuestCategory.java index 04ff487..991f62d 100644 --- a/java/noppes/npcs/api/handler/data/IQuestCategory.java +++ b/java/noppes/npcs/api/handler/data/IQuestCategory.java @@ -2,12 +2,24 @@ package noppes.npcs.api.handler.data; import java.util.List; +/** + * Represents a category that groups related quests together. + */ public interface IQuestCategory { + + /** @return all quests in this category. */ List quests(); + /** @return the category display name. */ String getName(); + /** + * Creates a new quest in this category. + * + * @return the newly created quest. + */ IQuest create(); + /** @return the unique category ID. */ int getId(); } diff --git a/java/noppes/npcs/api/handler/data/IQuestDialog.java b/java/noppes/npcs/api/handler/data/IQuestDialog.java index cf5e275..2a300e7 100644 --- a/java/noppes/npcs/api/handler/data/IQuestDialog.java +++ b/java/noppes/npcs/api/handler/data/IQuestDialog.java @@ -1,4 +1,8 @@ package noppes.npcs.api.handler.data; +/** + * Quest objective interface for dialog-type quests. + * Players must interact with specific dialogs to complete the quest. + */ public interface IQuestDialog extends IQuestInterface { } diff --git a/java/noppes/npcs/api/handler/data/IQuestInterface.java b/java/noppes/npcs/api/handler/data/IQuestInterface.java index d6c6055..3b5703a 100644 --- a/java/noppes/npcs/api/handler/data/IQuestInterface.java +++ b/java/noppes/npcs/api/handler/data/IQuestInterface.java @@ -1,4 +1,7 @@ package noppes.npcs.api.handler.data; +/** + * Marker interface for quest objective types (e.g., kill, item, location, dialog). + */ public interface IQuestInterface { } diff --git a/java/noppes/npcs/api/handler/data/IQuestItem.java b/java/noppes/npcs/api/handler/data/IQuestItem.java index 883634b..9b719f0 100644 --- a/java/noppes/npcs/api/handler/data/IQuestItem.java +++ b/java/noppes/npcs/api/handler/data/IQuestItem.java @@ -1,15 +1,26 @@ package noppes.npcs.api.handler.data; +/** + * Quest objective interface for item-collection quests. + * Configures whether items are consumed on turn-in and matching criteria. + */ public interface IQuestItem extends IQuestInterface { + + /** @param leaveItems true to leave items in the player's inventory on turn-in. */ void setLeaveItems(boolean leaveItems); + /** @return true if items remain in the player's inventory on turn-in. */ boolean getLeaveItems(); + /** @param ignoreDamage true to ignore item damage when matching. */ void setIgnoreDamage(boolean ignoreDamage); + /** @return true if item damage is ignored when matching. */ boolean getIgnoreDamage(); + /** @param ignoreNbt true to ignore NBT data when matching. */ void setIgnoreNbt(boolean ignoreNbt); + /** @return true if NBT data is ignored when matching. */ boolean getIgnoreNbt(); } diff --git a/java/noppes/npcs/api/handler/data/IQuestKill.java b/java/noppes/npcs/api/handler/data/IQuestKill.java index 86074d1..7da896c 100644 --- a/java/noppes/npcs/api/handler/data/IQuestKill.java +++ b/java/noppes/npcs/api/handler/data/IQuestKill.java @@ -1,7 +1,20 @@ package noppes.npcs.api.handler.data; +/** + * Quest objective interface for kill-type quests. + * Configures the target type for kill counting. + */ public interface IQuestKill extends IQuestInterface { + + /** + * Sets the target matching type. + * + * @param type 0: by entity name, 1: by faction. + */ void setTargetType(int type); + /** + * @return the target matching type (0: entity name, 1: faction). + */ int getTargetType(); } diff --git a/java/noppes/npcs/api/handler/data/IQuestLocation.java b/java/noppes/npcs/api/handler/data/IQuestLocation.java index 27e43b5..e5b49a1 100644 --- a/java/noppes/npcs/api/handler/data/IQuestLocation.java +++ b/java/noppes/npcs/api/handler/data/IQuestLocation.java @@ -1,15 +1,26 @@ package noppes.npcs.api.handler.data; +/** + * Quest objective interface for location-based quests. + * Players must visit up to three named locations to complete the quest. + */ public interface IQuestLocation extends IQuestInterface { + + /** @param loc1 the name of the first location objective. */ void setLocation1(String loc1); + /** @return the name of the first location objective. */ String getLocation1(); + /** @param loc2 the name of the second location objective. */ void setLocation2(String loc2); + /** @return the name of the second location objective. */ String getLocation2(); + /** @param loc3 the name of the third location objective. */ void setLocation3(String loc3); + /** @return the name of the third location objective. */ String getLocation3(); } diff --git a/java/noppes/npcs/api/handler/data/IQuestObjective.java b/java/noppes/npcs/api/handler/data/IQuestObjective.java index d909a08..4adc6e0 100644 --- a/java/noppes/npcs/api/handler/data/IQuestObjective.java +++ b/java/noppes/npcs/api/handler/data/IQuestObjective.java @@ -32,11 +32,15 @@ public interface IQuestObjective { */ void setPlayerProgress(String playerName, int progress); + /** @return the target progress value needed to complete this objective. */ int getMaxProgress(); + /** @return true if this objective has been completed. */ boolean isCompleted(); + /** @return the objective description text. */ String getText(); + /** @return additional display text for this objective, or null. */ String getAdditionalText(); } diff --git a/java/noppes/npcs/api/handler/data/IRecipe.java b/java/noppes/npcs/api/handler/data/IRecipe.java index 347664e..2170dae 100644 --- a/java/noppes/npcs/api/handler/data/IRecipe.java +++ b/java/noppes/npcs/api/handler/data/IRecipe.java @@ -2,30 +2,47 @@ package noppes.npcs.api.handler.data; import net.minecraft.item.ItemStack; +/** + * Represents a custom crafting recipe for the carpentry table or vanilla workbench. + */ public interface IRecipe { + + /** @return the recipe display name. */ String getName(); + /** @return true if this is a global (vanilla workbench) recipe. */ boolean isGlobal(); - void setIsGlobal(boolean var1); + /** @param global true for global; false for carpentry only. */ + void setIsGlobal(boolean global); + /** @return true if NBT data is ignored when matching ingredients. */ boolean getIgnoreNBT(); - void setIgnoreNBT(boolean var1); + /** @param ignoreNBT true to ignore NBT in ingredient matching. */ + void setIgnoreNBT(boolean ignoreNBT); + /** @return true if damage values are ignored when matching ingredients. */ boolean getIgnoreDamage(); - void setIgnoreDamage(boolean var1); + /** @param ignoreDamage true to ignore damage in ingredient matching. */ + void setIgnoreDamage(boolean ignoreDamage); + /** @return the recipe grid width. */ int getWidth(); + /** @return the recipe grid height. */ int getHeight(); + /** @return the resulting item stack. */ ItemStack getResult(); + /** @return the ingredient item stacks in grid order. */ ItemStack[] getRecipe(); + /** Deletes this recipe from the handler. */ void delete(); + /** @return the unique recipe ID. */ int getId(); } diff --git a/java/noppes/npcs/api/handler/data/ISlot.java b/java/noppes/npcs/api/handler/data/ISlot.java index c76f67c..e92466c 100644 --- a/java/noppes/npcs/api/handler/data/ISlot.java +++ b/java/noppes/npcs/api/handler/data/ISlot.java @@ -46,6 +46,12 @@ public interface ISlot { */ Map getComponents(); + /** + * Sets the NBT data for a specific component key. + * + * @param key the component key (e.g. "CNPC+", "DBC"). + * @param data the NBT data to store. + */ void setComponentData(String key, NBTTagCompound data); /** diff --git a/java/noppes/npcs/api/handler/data/ISound.java b/java/noppes/npcs/api/handler/data/ISound.java index d5a65b8..3cade21 100644 --- a/java/noppes/npcs/api/handler/data/ISound.java +++ b/java/noppes/npcs/api/handler/data/ISound.java @@ -3,35 +3,68 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.IPos; import noppes.npcs.api.entity.IEntity; +/** + * Represents a sound that can be played at a position or attached to an entity, + * with configurable volume, pitch, repeat behavior, and position. + */ public interface ISound { + /** + * Attaches this sound to an entity. The sound follows the entity. + * + * @param entity the entity to attach to, or null to detach. + */ void setEntity(IEntity entity); + /** @return the entity this sound is attached to, or null. */ IEntity getEntity(); + /** @param repeat true to loop this sound. */ void setRepeat(boolean repeat); + /** @return true if this sound loops. */ boolean repeats(); + /** @param delay the delay in ticks between repeats. */ void setRepeatDelay(int delay); + /** @return the delay in ticks between repeats. */ int getRepeatDelay(); + /** @param volume the playback volume (1.0 = normal). */ void setVolume(float volume); + /** @return the playback volume. */ float getVolume(); + /** @param pitch the playback pitch (1.0 = normal). */ void setPitch(float pitch); + /** @return the playback pitch. */ float getPitch(); + /** + * Sets the position where this sound plays. + * + * @param pos the position. + */ void setPosition(IPos pos); + /** + * Sets the position where this sound plays. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + */ void setPosition(float x, float y, float z); + /** @return the x coordinate of the sound position. */ float getX(); + /** @return the y coordinate of the sound position. */ float getY(); + /** @return the z coordinate of the sound position. */ float getZ(); } diff --git a/java/noppes/npcs/api/handler/data/ITag.java b/java/noppes/npcs/api/handler/data/ITag.java index 97cebee..1ef328b 100644 --- a/java/noppes/npcs/api/handler/data/ITag.java +++ b/java/noppes/npcs/api/handler/data/ITag.java @@ -1,21 +1,34 @@ package noppes.npcs.api.handler.data; +/** + * Represents a tag that can be applied to NPCs for categorization and filtering. + */ public interface ITag { + + /** @return the unique UUID string for this tag. */ String getUuid(); + /** @return the tag display name. */ String getName(); + /** @param name the tag display name. */ void setName(String name); + /** @param c the tag color as a packed RGB integer. */ void setColor(int c); + /** @return the unique tag ID. */ int getId(); + /** @return the tag color as a packed RGB integer. */ int getColor(); + /** @return true if this tag is hidden from display. */ boolean getIsHidden(); + /** @param hidden true to hide this tag from display. */ void setIsHidden(boolean hidden); + /** Saves this tag to disk. */ void save(); } diff --git a/java/noppes/npcs/api/handler/data/ITransportCategory.java b/java/noppes/npcs/api/handler/data/ITransportCategory.java index 154839b..73d1ec1 100644 --- a/java/noppes/npcs/api/handler/data/ITransportCategory.java +++ b/java/noppes/npcs/api/handler/data/ITransportCategory.java @@ -1,16 +1,38 @@ package noppes.npcs.api.handler.data; +/** + * Represents a category that groups transport locations together. + */ public interface ITransportCategory { + /** @return the unique category ID. */ int getId(); + /** @param title the category title. */ void setTitle(String title); + /** @return the category title. */ String getTitle(); + /** + * Adds a new transport location with the given name to this category. + * + * @param name the location name. + */ void addLocation(String name); + /** + * Returns the transport location with the given name. + * + * @param name the location name. + * @return the transport location, or null if not found. + */ ITransportLocation getLocation(String name); + /** + * Removes the transport location with the given name. + * + * @param name the location name. + */ void removeLocation(String name); } diff --git a/java/noppes/npcs/api/handler/data/ITransportLocation.java b/java/noppes/npcs/api/handler/data/ITransportLocation.java index 08c9b3c..9ed0c15 100644 --- a/java/noppes/npcs/api/handler/data/ITransportLocation.java +++ b/java/noppes/npcs/api/handler/data/ITransportLocation.java @@ -2,31 +2,61 @@ package noppes.npcs.api.handler.data; import noppes.npcs.api.IPos; +/** + * Represents a transport destination that players can teleport to. + */ public interface ITransportLocation { + /** @return the unique transport location ID. */ int getId(); + /** @param name the location display name. */ void setName(String name); + /** @return the location display name. */ String getName(); + /** @param dimension the dimension ID where this transport is located. */ void setDimension(int dimension); + /** @return the dimension ID. */ int getDimension(); + /** + * Sets the transport type. + * + * @param type the type ordinal. + */ void setType(int type); + /** @return the transport type ordinal. */ int getType(); + /** + * Sets the transport destination coordinates. + * + * @param x the x coordinate. + * @param y the y coordinate. + * @param z the z coordinate. + */ void setPosition(int x, int y, int z); + /** + * Sets the transport destination position. + * + * @param pos the position. + */ void setPosition(IPos pos); + /** @return the x coordinate. */ double getX(); + /** @return the y coordinate. */ double getY(); + /** @return the z coordinate. */ double getZ(); + /** Saves this transport location to disk. */ void save(); } diff --git a/java/noppes/npcs/api/handler/data/actions/IConditionalAction.java b/java/noppes/npcs/api/handler/data/actions/IConditionalAction.java index 63b5f30..baae8ce 100644 --- a/java/noppes/npcs/api/handler/data/actions/IConditionalAction.java +++ b/java/noppes/npcs/api/handler/data/actions/IConditionalAction.java @@ -9,7 +9,7 @@ public interface IConditionalAction extends IAction { /** * @param condition checked every tick, if it returns true, task is fired - * @return + * @return this action */ IConditionalAction setCondition(Function condition); diff --git a/java/noppes/npcs/api/roles/IRole.java b/java/noppes/npcs/api/roles/IRole.java index dacd119..84b74e5 100644 --- a/java/noppes/npcs/api/roles/IRole.java +++ b/java/noppes/npcs/api/roles/IRole.java @@ -2,9 +2,17 @@ package noppes.npcs.api.roles; import net.minecraft.entity.INpc; +/** + * Base interface for all NPC roles (Trader, Follower, Bank, Mailman, Transporter). + */ public interface IRole { + /** @return the NPC this role is assigned to. */ INpc getNpc(); + /** + * @return the role type ordinal. + * 0: None, 1: Trader, 2: Follower, 3: Bank, 4: Transporter, 5: Mailman. + */ int getType(); } diff --git a/java/noppes/npcs/api/roles/IRoleBank.java b/java/noppes/npcs/api/roles/IRoleBank.java index 0a21f41..e0a7a18 100644 --- a/java/noppes/npcs/api/roles/IRoleBank.java +++ b/java/noppes/npcs/api/roles/IRoleBank.java @@ -1,5 +1,8 @@ package noppes.npcs.api.roles; +/** + * Represents the banker role for an NPC, providing storage access to players. + */ public interface IRoleBank extends IRole { } diff --git a/java/noppes/npcs/api/roles/IRoleFollower.java b/java/noppes/npcs/api/roles/IRoleFollower.java index 78b2aed..88d90f5 100644 --- a/java/noppes/npcs/api/roles/IRoleFollower.java +++ b/java/noppes/npcs/api/roles/IRoleFollower.java @@ -22,8 +22,10 @@ public interface IRoleFollower extends IRole { */ boolean hasOwner(); + /** @return true if the follower is currently following the owner. */ boolean isFollowing(); + /** @param following true to make the follower follow the owner. */ void setIsFollowing(boolean following); /** diff --git a/java/noppes/npcs/api/roles/IRoleMailman.java b/java/noppes/npcs/api/roles/IRoleMailman.java index 912b0a9..4013200 100644 --- a/java/noppes/npcs/api/roles/IRoleMailman.java +++ b/java/noppes/npcs/api/roles/IRoleMailman.java @@ -1,5 +1,8 @@ package noppes.npcs.api.roles; +/** + * Represents the mailman role for an NPC, enabling mail delivery to players. + */ public interface IRoleMailman extends IRole { } diff --git a/java/noppes/npcs/api/roles/IRoleTrader.java b/java/noppes/npcs/api/roles/IRoleTrader.java index b76a39e..ad90a60 100644 --- a/java/noppes/npcs/api/roles/IRoleTrader.java +++ b/java/noppes/npcs/api/roles/IRoleTrader.java @@ -285,7 +285,7 @@ public interface IRoleTrader extends IRole { /** * @param slot Slot number 0-17 - * @return Whether this slot has a currency cost > 0 + * @return Whether this slot has a currency cost > 0 */ boolean hasCurrencyCost(int slot); } diff --git a/java/noppes/npcs/api/roles/IRoleTransporter.java b/java/noppes/npcs/api/roles/IRoleTransporter.java index 6d535d3..4406aa2 100644 --- a/java/noppes/npcs/api/roles/IRoleTransporter.java +++ b/java/noppes/npcs/api/roles/IRoleTransporter.java @@ -4,16 +4,36 @@ import net.minecraft.entity.player.EntityPlayerMP; import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.handler.data.ITransportLocation; +/** + * Represents the transporter role for an NPC, allowing players to teleport + * between unlocked transport locations. + */ public interface IRoleTransporter extends IRole { + + /** @return the display name of this transporter NPC. */ String getName(); + /** @return the transport location ID assigned to this NPC. */ int getTransportId(); + /** + * Unlocks the given transport location for the player. + * + * @param player the player. + * @param location the transport location to unlock. + */ void unlock(IPlayer player, ITransportLocation location); + /** @return the transport location assigned to this NPC, or null if none. */ ITransportLocation getTransport(); + /** @return true if this NPC has a transport location assigned. */ boolean hasTransport(); + /** + * Assigns a transport location to this NPC. + * + * @param location the transport location. + */ void setTransport(ITransportLocation location); }