From c22c5f9d7926c007009fcf434dbb4075a022e923 Mon Sep 17 00:00:00 2001 From: Kam Date: Tue, 11 Mar 2025 20:24:47 -0400 Subject: [PATCH] Update ICustomEffectHandler.java --- .../api/handler/ICustomEffectHandler.java | 224 ++++++++++++++++-- 1 file changed, 209 insertions(+), 15 deletions(-) diff --git a/java/noppes/npcs/api/handler/ICustomEffectHandler.java b/java/noppes/npcs/api/handler/ICustomEffectHandler.java index 0a376e6..6ae5e30 100644 --- a/java/noppes/npcs/api/handler/ICustomEffectHandler.java +++ b/java/noppes/npcs/api/handler/ICustomEffectHandler.java @@ -3,56 +3,250 @@ package noppes.npcs.api.handler; import noppes.npcs.api.entity.IPlayer; import noppes.npcs.api.handler.data.ICustomEffect; +/** + * Handler interface for managing custom effects. + * Provides methods to create, retrieve, apply, remove, and save custom effects. + */ public interface ICustomEffectHandler { + /** + * Creates a new custom effect with the specified name. + * If an effect with the given name already exists, the existing effect is returned. + * + * @param name the name of the custom effect to create + * @return the newly created or existing custom effect + */ ICustomEffect createEffect(String name); + /** + * Retrieves the custom effect with the specified name. + * + * @param name the name of the custom effect to retrieve + * @return the custom effect with the given name, or null if not found + */ ICustomEffect getEffect(String name); + /** + * Deletes the custom effect with the specified name. + * + * @param name the name of the custom effect to delete + */ void deleteEffect(String name); /** + * Checks if the specified player currently has an effect with the given ID. * - * @param player Player - * @param id ID of Status Effect -- Only DBC Addon - * @return True if Player has Effect + * @param player the player to check + * @param id the ID of the status effect + * @return true if the player has the effect, false otherwise */ boolean hasEffect(IPlayer player, int id); + /** + * Checks if the specified player currently has the given custom effect. + * + * @param player the player to check + * @param effect the custom effect to check for + * @return true if the player has the effect, false otherwise + */ boolean hasEffect(IPlayer player, ICustomEffect effect); /** + * Retrieves the remaining duration of the effect with the specified ID for the given player. + *

+ * Return values: + *

* - * -1 : Does not have effect - * -100 : Has infinite effect - * - * @param player Player - * @param id ID of Status Effect -- Only DBC Addon - * @return Effect Time + * @param player the player whose effect duration is queried + * @param id the ID of the status effect + * @return the remaining effect time in seconds */ int getEffectDuration(IPlayer player, int id); + /** + * Retrieves the remaining duration of the given custom effect for the specified player. + *

+ * Return values: + *

+ * + * @param player the player whose effect duration is queried + * @param effect the custom effect to check + * @return the remaining effect time in seconds + */ int getEffectDuration(IPlayer player, ICustomEffect effect); /** - * @param player Player - * @param id ID of Status Effect - * @param duration Duration of Effect in Seconds | -100 : Has infinite effect - * @param level Level of Effect [Some effects not affected by level] + * Applies the effect with the specified ID to the player. + * + * @param player the player to apply the effect to + * @param id the ID of the status effect + * @param duration the duration of the effect in seconds (-100 for infinite duration) + * @param level the level of the effect (some effects may ignore this value) */ void applyEffect(IPlayer player, int id, int duration, byte level); + /** + * Applies the specified custom effect to the player. + * + * @param player the player to apply the effect to + * @param effect the custom effect to apply + * @param duration the duration of the effect in seconds (-100 for infinite duration) + * @param level the level of the effect (some effects may ignore this value) + */ void applyEffect(IPlayer player, ICustomEffect effect, int duration, byte level); /** - * @param player Player - * @param id ID of Status Effect + * Removes the effect with the specified ID from the player. + * + * @param player the player to remove the effect from + * @param id the ID of the status effect to remove */ void removeEffect(IPlayer player, int id); + /** + * Removes the specified custom effect from the player. + * + * @param player the player to remove the effect from + * @param effect the custom effect to remove + */ void removeEffect(IPlayer player, ICustomEffect effect); + /** + * Clears all custom effects from the specified player. + * + * @param player the player whose effects should be cleared + */ void clearEffects(IPlayer player); + /** + * Applies the effect with the specified ID and index to the player. + * The index parameter allows for multiple variants of the same effect. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player to apply the effect to + * @param id the ID of the status effect + * @param duration the duration of the effect in seconds (-100 for infinite duration) + * @param level the level of the effect + * @param index the index to differentiate between variants of the effect (INDEX: 0: CNPC+, 1: DBC Addon) + */ + void applyEffect(IPlayer player, int id, int duration, byte level, int index); + + /** + * Applies the specified custom effect (with the given index) to the player. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player to apply the effect to + * @param effect the custom effect to apply + * @param duration the duration of the effect in seconds (-100 for infinite duration) + * @param level the level of the effect + * @param index the index to differentiate between variants of the effect (INDEX: 0: CNPC+, 1: DBC Addon) + */ + void applyEffect(IPlayer player, ICustomEffect effect, int duration, byte level, int index); + + /** + * Removes the effect with the specified ID and index from the player. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player to remove the effect from + * @param id the ID of the status effect to remove + * @param index the index of the effect variant to remove (INDEX: 0: CNPC+, 1: DBC Addon) + */ + void removeEffect(IPlayer player, int id, int index); + + /** + * Removes the specified custom effect (with the given index) from the player. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player to remove the effect from + * @param effect the custom effect to remove + * @param index the index of the effect variant to remove (INDEX: 0: CNPC+, 1: DBC Addon) + */ + void removeEffect(IPlayer player, ICustomEffect effect, int index); + + /** + * Clears all custom effects with the specified index from the player. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player whose effects should be cleared + * @param index the index of the effect variants to clear (INDEX: 0: CNPC+, 1: DBC Addon) + */ + void clearEffects(IPlayer player, int index); + + /** + * Retrieves the remaining duration of the effect with the specified ID and index for the given player. + *

+ * Return values: + *

+ *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player whose effect duration is queried + * @param id the ID of the status effect + * @param index the index of the effect variant (INDEX: 0: CNPC+, 1: DBC Addon) + * @return the remaining effect time in seconds + */ + int getEffectDuration(IPlayer player, int id, int index); + + /** + * Retrieves the remaining duration of the specified custom effect (with the given index) for the player. + *

+ * Return values: + *

+ *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param player the player whose effect duration is queried + * @param effect the custom effect to check + * @param index the index of the effect variant (INDEX: 0: CNPC+, 1: DBC Addon) + * @return the remaining effect time in seconds + */ + int getEffectDuration(IPlayer player, ICustomEffect effect, int index); + + /** + * Retrieves the custom effect with the specified name and index. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param name the name of the custom effect + * @param index the index of the effect variant (INDEX: 0: CNPC+, 1: DBC Addon) + * @return the custom effect matching the name and index, or null if not found + */ + ICustomEffect getEffect(String name, int index); + + /** + * Retrieves the custom effect with the specified ID and index. + *

+ * Note: INDEX: 0: CNPC+, 1: DBC Addon + * + * @param id the ID of the custom effect + * @param index the index of the effect variant (INDEX: 0: CNPC+, 1: DBC Addon) + * @return the custom effect matching the ID and index, or null if not found + */ + ICustomEffect getEffect(int id, int index); + + /** + * Persists the given custom effect. + * This method saves the effect and returns the saved instance, potentially with an updated ID or name. + * + * @param customEffect the custom effect to save + * @return the saved custom effect instance + */ ICustomEffect saveEffect(ICustomEffect customEffect); }