From 1ddf509f89063f520e70272b06f6367444192e34 Mon Sep 17 00:00:00 2001 From: D3v1s0m Date: Wed, 1 Nov 2023 00:39:58 +0530 Subject: [PATCH] more javadocs --- .../java/lol/pyr/znpcsplus/api/NpcApi.java | 22 +++++ .../lol/pyr/znpcsplus/api/NpcApiProvider.java | 3 + .../znpcsplus/api/event/NpcDespawnEvent.java | 8 ++ .../znpcsplus/api/event/NpcInteractEvent.java | 13 +++ .../znpcsplus/api/event/NpcSpawnEvent.java | 8 ++ .../api/event/util/CancellableNpcEvent.java | 7 ++ .../znpcsplus/api/event/util/NpcEvent.java | 19 +++++ .../pyr/znpcsplus/api/hologram/Hologram.java | 34 ++++++++ .../api/interaction/InteractionAction.java | 39 +++++++++ .../api/interaction/InteractionType.java | 6 ++ .../java/lol/pyr/znpcsplus/api/npc/Npc.java | 85 +++++++++++++++++++ .../lol/pyr/znpcsplus/api/npc/NpcEntry.java | 39 +++++++++ .../pyr/znpcsplus/api/npc/NpcRegistry.java | 49 +++++++++++ .../lol/pyr/znpcsplus/api/npc/NpcType.java | 18 ++++ .../znpcsplus/api/npc/NpcTypeRegistry.java | 11 +++ .../api/skin/SkinDescriptorFactory.java | 3 + 16 files changed, 364 insertions(+) diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/NpcApi.java b/api/src/main/java/lol/pyr/znpcsplus/api/NpcApi.java index fe98d71..fe25878 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/NpcApi.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/NpcApi.java @@ -5,9 +5,31 @@ import lol.pyr.znpcsplus.api.npc.NpcRegistry; import lol.pyr.znpcsplus.api.npc.NpcTypeRegistry; import lol.pyr.znpcsplus.api.skin.SkinDescriptorFactory; +/** + * Main API class for ZNPCsPlus. + */ public interface NpcApi { + /** + * Gets the NPC registry. + * @return the NPC registry + */ NpcRegistry getNpcRegistry(); + + /** + * Gets the NPC type registry. + * @return the NPC type registry + */ NpcTypeRegistry getNpcTypeRegistry(); + + /** + * Gets the entity property registry. + * @return the entity property registry + */ EntityPropertyRegistry getPropertyRegistry(); + + /** + * Gets the skin descriptor factory. + * @return the skin descriptor factory + */ SkinDescriptorFactory getSkinDescriptorFactory(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/NpcApiProvider.java b/api/src/main/java/lol/pyr/znpcsplus/api/NpcApiProvider.java index 29e2abb..16dd426 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/NpcApiProvider.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/NpcApiProvider.java @@ -4,6 +4,9 @@ import org.bukkit.Bukkit; import org.bukkit.plugin.Plugin; import org.bukkit.plugin.ServicePriority; +/** + * Provider for the registered api instance + */ public class NpcApiProvider { private static NpcApi api = null; diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcDespawnEvent.java b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcDespawnEvent.java index 41cf652..f9fcc01 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcDespawnEvent.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcDespawnEvent.java @@ -6,9 +6,17 @@ import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; +/** + * Event called when an NPC is despawned for a player + * Note: This event is async + */ public class NpcDespawnEvent extends CancellableNpcEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); + /** + * @param player The player involved in the event + * @param entry The NPC entry involved in the event + */ public NpcDespawnEvent(Player player, NpcEntry entry) { super(player, entry); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcInteractEvent.java b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcInteractEvent.java index 9ec4f0d..84f63b8 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcInteractEvent.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcInteractEvent.java @@ -7,11 +7,20 @@ import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; +/** + * Event called when an NPC is interacted with by a player + * Note: This event is async + */ public class NpcInteractEvent extends CancellableNpcEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); private final InteractionType clickType; + /** + * @param player The player involved in the event + * @param entry The NPC entry involved in the event + * @param clickType The type of interaction. See {@link InteractionType} + */ public NpcInteractEvent(Player player, NpcEntry entry, InteractionType clickType) { super(player, entry); this.clickType = clickType; @@ -22,6 +31,10 @@ public class NpcInteractEvent extends CancellableNpcEvent implements Cancellable return handlers; } + /** + * Returns the type of interaction. See {@link InteractionType} + * @return The type of interaction + */ public InteractionType getClickType() { return clickType; } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcSpawnEvent.java b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcSpawnEvent.java index 56dcbd5..1edeec6 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcSpawnEvent.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/event/NpcSpawnEvent.java @@ -6,9 +6,17 @@ import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; +/** + * Event called when an NPC is spawned for a player + * Note: This event is async + */ public class NpcSpawnEvent extends CancellableNpcEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); + /** + * @param player The player involved in the event + * @param entry The NPC entry involved in the event + */ public NpcSpawnEvent(Player player, NpcEntry entry) { super(player, entry); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/event/util/CancellableNpcEvent.java b/api/src/main/java/lol/pyr/znpcsplus/api/event/util/CancellableNpcEvent.java index 1eeba55..558a55e 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/event/util/CancellableNpcEvent.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/event/util/CancellableNpcEvent.java @@ -4,9 +4,16 @@ import lol.pyr.znpcsplus.api.npc.NpcEntry; import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; +/** + * Base class for all NPC events that can be cancelled + */ public abstract class CancellableNpcEvent extends NpcEvent implements Cancellable { private boolean cancelled = false; + /** + * @param player The player involved in the event + * @param entry The NPC entry involved in the event + */ public CancellableNpcEvent(Player player, NpcEntry entry) { super(player, entry); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/event/util/NpcEvent.java b/api/src/main/java/lol/pyr/znpcsplus/api/event/util/NpcEvent.java index 7e6e8dd..cc5483f 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/event/util/NpcEvent.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/event/util/NpcEvent.java @@ -5,24 +5,43 @@ import lol.pyr.znpcsplus.api.npc.NpcEntry; import org.bukkit.entity.Player; import org.bukkit.event.Event; +/** + * Base class for all NPC events + */ public abstract class NpcEvent extends Event { private final NpcEntry entry; private final Player player; + /** + * @param player The player involved in the event + * @param entry The NPC entry involved in the event + */ public NpcEvent(Player player, NpcEntry entry) { super(true); // All events are async since 99% of the plugin is async this.entry = entry; this.player = player; } + /** + * Returns the player involved in the event + * @return The player involved in the event + */ public Player getPlayer() { return player; } + /** + * Returns the NPC entry involved in the event + * @return The NPC entry involved in the event + */ public NpcEntry getEntry() { return entry; } + /** + * Returns the NPC involved in the event + * @return The NPC involved in the event + */ public Npc getNpc() { return entry.getNpc(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/hologram/Hologram.java b/api/src/main/java/lol/pyr/znpcsplus/api/hologram/Hologram.java index 38b2586..fceaab0 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/hologram/Hologram.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/hologram/Hologram.java @@ -1,10 +1,44 @@ package lol.pyr.znpcsplus.api.hologram; +/** + * Represents a hologram + */ public interface Hologram { + /** + * Adds a line to the hologram + * Note: to add an item line, pass "item:" as the line + * @param line The line to add + */ void addLine(String line); + + /** + * Gets a line from the hologram + * @param index The index of the line to get + * @return The line at the index + */ String getLine(int index); + + /** + * Removes a line from the hologram + * @param index The index of the line to remove + */ void removeLine(int index); + + /** + * Clears all lines from the hologram + */ void clearLines(); + + /** + * Inserts a line into the hologram + * @param index The index to insert the line at + * @param line The line to insert + */ void insertLine(int index, String line); + + /** + * Gets the number of lines in the hologram + * @return The number of lines in the hologram + */ int lineCount(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionAction.java b/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionAction.java index 6d9668a..401784a 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionAction.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionAction.java @@ -4,12 +4,35 @@ import org.bukkit.entity.Player; import java.util.UUID; +/** + * Base class for all NPC interactions + */ public abstract class InteractionAction { + /** + * The unique ID of this interaction + */ private final UUID id; + + /** + * The cooldown of this interaction in seconds + */ private final long cooldown; + + /** + * The delay of this interaction in ticks + */ private final long delay; + + /** + * The type of this interaction + */ private final InteractionType interactionType; + /** + * @param cooldown The cooldown of this interaction in seconds + * @param delay The delay of this interaction in ticks + * @param interactionType The type of this interaction + */ protected InteractionAction(long cooldown, long delay, InteractionType interactionType) { this.interactionType = interactionType; this.id = UUID.randomUUID(); @@ -17,21 +40,37 @@ public abstract class InteractionAction { this.delay = delay; } + /** + * @return The unique ID of this interaction + */ public UUID getUuid() { return id; } + /** + * @return The cooldown of this interaction in seconds + */ public long getCooldown() { return cooldown; } + /** + * @return The delay of this interaction in ticks + */ public long getDelay() { return delay; } + /** + * @return The type of this interaction + */ public InteractionType getInteractionType() { return interactionType; } + /** + * Runs this interaction + * @param player The player that triggered this interaction + */ public abstract void run(Player player); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionType.java b/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionType.java index 4c88f8f..27121ef 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionType.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/interaction/InteractionType.java @@ -1,5 +1,11 @@ package lol.pyr.znpcsplus.api.interaction; +/** + * The type of interaction + * ANY_CLICK: Any click type + * LEFT_CLICK: Only left clicks + * RIGHT_CLICK: Only right clicks + */ public enum InteractionType { ANY_CLICK, LEFT_CLICK, diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/npc/Npc.java b/api/src/main/java/lol/pyr/znpcsplus/api/npc/Npc.java index e84775a..cf20af2 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/npc/Npc.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/npc/Npc.java @@ -10,22 +10,107 @@ import org.bukkit.entity.Player; import java.util.List; import java.util.UUID; +/** + * Base class for all NPCs + */ public interface Npc extends PropertyHolder { + /** + * Sets the npc type of this NPC + * @param type The {@link NpcType} to set + */ void setType(NpcType type); + + /** + * @return The {@link NpcType} of this NPC + */ NpcType getType(); + + /** + * Gets the location of this NPC + * @return The {@link NpcLocation} of this NPC + */ NpcLocation getLocation(); + + /** + * Sets the location of this NPC + * @param location The {@link NpcLocation} to set + */ void setLocation(NpcLocation location); + + /** + * Gets the hologram of this NPC + * @return The {@link Hologram} of this NPC + */ Hologram getHologram(); + + /** + * Sets if the npc is enabled or not, i.e. if it should be visible to players + * @param enabled If the npc should be enabled + */ void setEnabled(boolean enabled); + + /** + * Gets if the npc is enabled or not, i.e. if it should be visible to players + * @return If the npc is enabled or not + */ boolean isEnabled(); + + /** + * Gets the unique ID of this NPC + * @return The unique ID of this NPC + */ UUID getUuid(); + + /** + * Gets the {@link World} this NPC is in + * Note: can be null if the world is unloaded or does not exist + * @return The {@link World} this NPC is in + */ World getWorld(); + + /** + * Gets the list of actions for this NPC + * @return The {@link List} of {@link InteractionAction}s for this NPC + */ List getActions(); + + /** + * Gets if this NPC is visible to a player + * @param player The {@link Player} to check + * @return If this NPC is visible to the player + */ boolean isVisibleTo(Player player); + + /** + * Hides this NPC from a player + * @param player The {@link Player} to hide from + */ void hide(Player player); + + /** + * Shows this NPC to a player + * @param player The {@link Player} to show to + */ void show(Player player); + + /** + * Respawns this NPC for a player + * @param player The {@link Player} to respawn for + */ void respawn(Player player); + /** + * Sets the head rotation of this NPC for a player + * @param player The {@link Player} to set the head rotation for + * @param yaw The yaw to set + * @param pitch The pitch to set + */ void setHeadRotation(Player player, float yaw, float pitch); + + /** + * Sets the head rotation of this NPC for all players/viewers + * @param yaw The yaw to set + * @param pitch The pitch to set + */ void setHeadRotation(float yaw, float pitch); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcEntry.java b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcEntry.java index 0f85f77..aca4bc3 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcEntry.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcEntry.java @@ -1,17 +1,56 @@ package lol.pyr.znpcsplus.api.npc; +/** + * Base class for all NPC entries + * An NPC entry is a wrapper around an NPC that contains additional information + */ public interface NpcEntry { + /** + * Gets the ID of this NPC entry + * @return The ID of this NPC entry + */ String getId(); + /** + * Gets the NPC of this NPC entry + * @return The {@link Npc} of this NPC entry + */ Npc getNpc(); + /** + * Gets if this NPC entry is processed or not + * @return If this NPC entry is processed or not + */ boolean isProcessed(); + /** + * Sets if this NPC entry is processed or not + * @param value If this NPC entry is processed or not + */ void setProcessed(boolean value); + /** + * @return If this NPC entry SHOULD be saved into the storage or not + */ boolean isSave(); + /** + * Sets if this NPC should be saved or not + * @param value If this NPC entry should be saved or not + */ void setSave(boolean value); + /** + * Gets if this NPC can be modified by commands + * @return {@code true} if this NPC can be modified by commands, {@code false} otherwise + */ boolean isAllowCommandModification(); + /** + * Sets if this NPC can be modified by commands + * @param value {@code true} if this NPC can be modified by commands, {@code false} otherwise + */ void setAllowCommandModification(boolean value); + /** + * Enables everything for this NPC entry + * That is, it makes the NPC processed, saveable, and allows command modification + */ void enableEverything(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcRegistry.java b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcRegistry.java index fe5d538..51d8c19 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcRegistry.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcRegistry.java @@ -6,13 +6,62 @@ import org.bukkit.World; import java.util.Collection; import java.util.UUID; +/** + * Base class for all NPC registries + */ public interface NpcRegistry { + + /** + * Gets all NPC entries + * @return All NPC entries + */ Collection getAll(); + + /** + * Gets all NPC IDs + * @return All NPC IDs + */ Collection getAllIds(); + + /** + * Gets all NPC entries that are player made + * @return All player made NPC entries + */ Collection getAllPlayerMade(); + + /** + * Gets IDs of all player made NPCs + * @return IDs of all player made NPCs + */ Collection getAllPlayerMadeIds(); + + /** + * Creates a new NPC entry + * @param id The ID of the NPC entry + * @param world The {@link World} of the NPC entry + * @param type The {@link NpcType} of the NPC entry + * @param location The {@link NpcLocation} of the NPC entry + * @return + */ NpcEntry create(String id, World world, NpcType type, NpcLocation location); + + /** + * Gets an NPC entry by its ID + * @param id The ID of the NPC entry + * @return The NPC entry + */ NpcEntry getById(String id); + + /** + * Gets an NPC entry by its UUID + * @param uuid The UUID of the NPC entry + * @return The NPC entry + */ NpcEntry getByUuid(UUID uuid); + + /** + * Deletes an NPC entry by its ID + * @param id The ID of the NPC entry + */ void delete(String id); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcType.java b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcType.java index 99d591c..004f512 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcType.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcType.java @@ -4,8 +4,26 @@ import lol.pyr.znpcsplus.api.entity.EntityProperty; import java.util.Set; +/** + * Represents a type of NPC. + * This defines the {@link org.bukkit.entity.EntityType} of the NPC, as well as the properties that are allowed to be set on the NPC. + */ public interface NpcType { + /** + * The name of the NPC type. + * @return The name of the NPC type. + */ String getName(); + + /** + * The offset of the hologram above the NPC. + * @return the offset + */ double getHologramOffset(); + + /** + * Set of properties that are allowed to be set on the NPC. + * @return allowed properties + */ Set> getAllowedProperties(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcTypeRegistry.java b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcTypeRegistry.java index 9382869..63c64cb 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcTypeRegistry.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/npc/NpcTypeRegistry.java @@ -2,7 +2,18 @@ package lol.pyr.znpcsplus.api.npc; import java.util.Collection; +/** + * Base for NpcType registries. + */ public interface NpcTypeRegistry { + /** + * Gets a NPC type by name. + * @param name The name of the NPC type. + */ NpcType getByName(String name); + + /** + * Gets all NPC types. + */ Collection getAll(); } diff --git a/api/src/main/java/lol/pyr/znpcsplus/api/skin/SkinDescriptorFactory.java b/api/src/main/java/lol/pyr/znpcsplus/api/skin/SkinDescriptorFactory.java index 086aa0c..41313c1 100644 --- a/api/src/main/java/lol/pyr/znpcsplus/api/skin/SkinDescriptorFactory.java +++ b/api/src/main/java/lol/pyr/znpcsplus/api/skin/SkinDescriptorFactory.java @@ -2,6 +2,9 @@ package lol.pyr.znpcsplus.api.skin; import java.net.URL; +/** + * Factory for creating skin descriptors. + */ public interface SkinDescriptorFactory { SkinDescriptor createMirrorDescriptor(); SkinDescriptor createRefreshingDescriptor(String playerName);