diff --git a/.gitignore b/.gitignore index 539988a..ba8d38c 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,5 @@ build/ target/ *.iml /bin/ -/doc/ +/docs/ /images/ diff --git a/src/main/java/dev/esophose/playerparticles/api/PlayerParticlesAPI.java b/src/main/java/dev/esophose/playerparticles/api/PlayerParticlesAPI.java index 9152fac..dddbaf2 100644 --- a/src/main/java/dev/esophose/playerparticles/api/PlayerParticlesAPI.java +++ b/src/main/java/dev/esophose/playerparticles/api/PlayerParticlesAPI.java @@ -44,6 +44,9 @@ public final class PlayerParticlesAPI { this.playerParticles = PlayerParticles.getInstance(); } + /** + * @return the instance of the PlayerParticlesAPI + */ public static PlayerParticlesAPI getInstance() { if (INSTANCE == null) INSTANCE = new PlayerParticlesAPI(); @@ -51,6 +54,13 @@ public final class PlayerParticlesAPI { } //region Get PPlayer + + /** + * Gets a PPlayer from their UUID + * + * @param uuid The UUID of the PPlayer + * @return The PPlayer, or null if not found + */ @Nullable public PPlayer getPPlayer(@NotNull UUID uuid) { Objects.requireNonNull(uuid); @@ -58,15 +68,29 @@ public final class PlayerParticlesAPI { return this.playerParticles.getManager(DataManager.class).getPPlayer(uuid); } + /** + * Gets a PPlayer from a Player + * + * @param player The Player + * @return The PPlayer, or null if not found + */ @Nullable public PPlayer getPPlayer(@NotNull Player player) { Objects.requireNonNull(player); return this.getPPlayer(player.getUniqueId()); } + //endregion //region Manage Active Player Particles + + /** + * Adds an active particle to a Player's particles + * + * @param player The player to add to + * @param particle The particle to add + */ public void addActivePlayerParticle(@NotNull Player player, @NotNull ParticlePair particle) { Objects.requireNonNull(particle); @@ -83,22 +107,61 @@ public final class PlayerParticlesAPI { dataManager.saveParticleGroup(player.getUniqueId(), pplayer.getActiveParticleGroup()); } + /** + * Adds an active particle to a Player's particles + * + * @param player The player to add to + * @param effect The effect of the particle + * @param style The style of the particle + */ public void addActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect, @NotNull ParticleStyle style) { this.addActivePlayerParticle(player, effect, style, null, null, null); } + /** + * Adds an active particle to a Player's particles + * + * @param player The player to add to + * @param effect The effect of the particle + * @param style The style of the particle + * @param colorData The color data of the particle + */ public void addActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull OrdinaryColor colorData) { this.addActivePlayerParticle(player, effect, style, colorData, null, null); } + /** + * Adds an active particle to a Player's particles + * + * @param player The player to add to + * @param effect The effect of the particle + * @param style The style of the particle + * @param noteColorData The note color data of the particle + */ public void addActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull NoteColor noteColorData) { this.addActivePlayerParticle(player, effect, style, null, noteColorData, null); } + /** + * Adds an active particle to a Player's particles + * + * @param player The player to add to + * @param effect The effect of the particle + * @param style The style of the particle + * @param materialData The material data of the particle + */ public void addActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull Material materialData) { this.addActivePlayerParticle(player, effect, style, null, null, materialData); } + /** + * @param player The player to add to + * @param effect The effect of the particle + * @param style The style of the particle + * @param colorData The color data of the particle + * @param noteColorData The note color data of the particle + * @param materialData The material data of the particle + */ private void addActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @Nullable OrdinaryColor colorData, @Nullable NoteColor noteColorData, @Nullable Material materialData) { Objects.requireNonNull(effect); Objects.requireNonNull(style); @@ -121,6 +184,13 @@ public final class PlayerParticlesAPI { this.addActivePlayerParticle(player, particle); } + /** + * Edits an active particle of a Player + * + * @param player The player to edit from + * @param id The ID of the target particle + * @param effect The new effect for the particle + */ public void editActivePlayerParticle(@NotNull Player player, int id, @NotNull ParticleEffect effect) { Objects.requireNonNull(effect); @@ -132,6 +202,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits an active particle of a Player + * + * @param player The player to edit from + * @param id The ID of the target particle + * @param style The new style for the particle + */ public void editActivePlayerParticle(@NotNull Player player, int id, @NotNull ParticleStyle style) { Objects.requireNonNull(style); @@ -143,6 +220,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits an active particle of a Player + * + * @param player The player to edit from + * @param id The ID of the target particle + * @param colorData The new color data for the particle + */ public void editActivePlayerParticle(@NotNull Player player, int id, @NotNull OrdinaryColor colorData) { Objects.requireNonNull(colorData); @@ -154,6 +238,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits an active particle of a Player + * + * @param player The player to edit from + * @param id The ID of the target particle + * @param noteColorData The new note color data for the particle + */ public void editActivePlayerParticle(@NotNull Player player, int id, @NotNull NoteColor noteColorData) { Objects.requireNonNull(noteColorData); @@ -165,6 +256,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits an active particle of a Player + * + * @param player The player to edit from + * @param id The ID of the target particle + * @param materialData The new material data for the particle + */ public void editActivePlayerParticle(@NotNull Player player, int id, @NotNull Material materialData) { Objects.requireNonNull(materialData); @@ -180,6 +278,12 @@ public final class PlayerParticlesAPI { } } + /** + * Removes an active particle from a player by ID + * + * @param player The player to remove from + * @param id The ID of the particle to remove + */ public void removeActivePlayerParticle(@NotNull Player player, int id) { DataManager dataManager = this.playerParticles.getManager(DataManager.class); ParticleGroup group = this.validateActivePlayerParticle(player, id); @@ -189,6 +293,12 @@ public final class PlayerParticlesAPI { } } + /** + * Removes active particles from a player by effect + * + * @param player The player to remove from + * @param effect The effect of the particle(s) to remove + */ public void removeActivePlayerParticle(@NotNull Player player, @NotNull ParticleEffect effect) { Objects.requireNonNull(effect); @@ -202,6 +312,12 @@ public final class PlayerParticlesAPI { dataManager.saveParticleGroup(player.getUniqueId(), group); } + /** + * Removes active particles from a player by style + * + * @param player The player to remove from + * @param style The style of the particle(s) to remove + */ public void removeActivePlayerParticle(@NotNull Player player, @NotNull ParticleStyle style) { Objects.requireNonNull(style); @@ -215,6 +331,13 @@ public final class PlayerParticlesAPI { dataManager.saveParticleGroup(player.getUniqueId(), group); } + /** + * Ensures a particle with a given ID exists for a player + * + * @param player The player to check + * @param id The ID of the particle + * @return The active particle group for the player + */ @Nullable private ParticleGroup validateActivePlayerParticle(@NotNull Player player, int id) { PPlayer pplayer = this.getPPlayer(player); @@ -228,6 +351,11 @@ public final class PlayerParticlesAPI { return particleGroup; } + /** + * Removes all active particles from a player + * + * @param player The player to remove from + */ public void resetActivePlayerParticles(@NotNull Player player) { DataManager dataManager = this.playerParticles.getManager(DataManager.class); PPlayer pplayer = this.getPPlayer(player); @@ -238,6 +366,12 @@ public final class PlayerParticlesAPI { dataManager.saveParticleGroup(pplayer.getUniqueId(), pplayer.getActiveParticleGroup()); } + /** + * Gets all active particles from a player + * + * @param player The player to get from + * @return A collection of the player's active particles + */ @NotNull public Collection getActivePlayerParticles(@NotNull Player player) { PPlayer pplayer = this.getPPlayer(player); @@ -247,6 +381,13 @@ public final class PlayerParticlesAPI { return pplayer.getActiveParticles(); } + /** + * Gets an active particle from a player + * + * @param player The player to get from + * @param id The ID of the particle to get + * @return A particle or null if one doesn't exist + */ @Nullable public ParticlePair getActivePlayerParticle(@NotNull Player player, int id) { PPlayer pplayer = this.getPPlayer(player); @@ -255,9 +396,17 @@ public final class PlayerParticlesAPI { return pplayer.getActiveParticle(id); } + //endregion //region Manage Player Particle Groups + + /** + * Saves a particle group to a player + * + * @param player The player to save to + * @param particleGroup The particle group to save + */ public void savePlayerParticleGroup(@NotNull Player player, @NotNull ParticleGroup particleGroup) { Objects.requireNonNull(particleGroup); @@ -273,6 +422,13 @@ public final class PlayerParticlesAPI { dataManager.saveParticleGroup(player.getUniqueId(), particleGroup); } + /** + * Saves a particle group to a player + * + * @param player The player to save to + * @param groupName The name of the group to save + * @param particles Particles that are part of the group + */ public void savePlayerParticleGroup(@NotNull Player player, @NotNull String groupName, @NotNull Collection particles) { Objects.requireNonNull(groupName); Objects.requireNonNull(particles); @@ -283,6 +439,12 @@ public final class PlayerParticlesAPI { this.savePlayerParticleGroup(player, particleGroup); } + /** + * Removes a particle group from a player + * + * @param player The player to remove from + * @param groupName The name of the particle group to remove + */ public void removePlayerParticleGroup(@NotNull Player player, @NotNull String groupName) { DataManager dataManager = this.playerParticles.getManager(DataManager.class); PPlayer pplayer = this.getPPlayer(player); @@ -293,12 +455,24 @@ public final class PlayerParticlesAPI { dataManager.removeParticleGroup(player.getUniqueId(), groupName); } + /** + * Removes a particle group from a player + * + * @param player The player to remove from + * @param particleGroup The particle group + */ public void removePlayerParticleGroup(@NotNull Player player, @NotNull ParticleGroup particleGroup) { Objects.requireNonNull(particleGroup); this.removePlayerParticleGroup(player, particleGroup.getName()); } + /** + * Gets a collection of the player's particle groups + * + * @param player The player to get from + * @return A collection of the player's particle groups + */ @NotNull public Collection getPlayerParticleGroups(@NotNull Player player) { PPlayer pplayer = this.getPPlayer(player); @@ -307,9 +481,18 @@ public final class PlayerParticlesAPI { return pplayer.getParticleGroups().values(); } + //endregion //region Fixed Effect Management + + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param particle The particle to display + */ public void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticlePair particle) { Objects.requireNonNull(location); Objects.requireNonNull(location.getWorld()); @@ -325,22 +508,68 @@ public final class PlayerParticlesAPI { dataManager.saveFixedEffect(fixedEffect); } + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param effect The effect of the particle + * @param style The style of the particle + */ public void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticleEffect effect, @NotNull ParticleStyle style) { this.createFixedParticleEffect(player, location, effect, style, null, null, null); } + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param effect The effect of the particle + * @param style The style of the particle + * @param colorData The color data of the particle + */ public void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull OrdinaryColor colorData) { this.createFixedParticleEffect(player, location, effect, style, colorData, null, null); } + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param effect The effect of the particle + * @param style The style of the particle + * @param noteColorData The note color data of the particle + */ public void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull NoteColor noteColorData) { this.createFixedParticleEffect(player, location, effect, style, null, noteColorData, null); } + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param effect The effect of the particle + * @param style The style of the particle + * @param materialData The material data of the particle + */ public void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @NotNull Material materialData) { this.createFixedParticleEffect(player, location, effect, style, null, null, materialData); } + /** + * Creates a fixed particle effect for a player + * + * @param player The player to create for + * @param location The location to create at + * @param effect The effect of the particle + * @param style The style of the particle + * @param colorData The color data of the particle + * @param noteColorData The note color data of the particle + * @param materialData The material data of the particle + */ private void createFixedParticleEffect(@NotNull Player player, @NotNull Location location, @NotNull ParticleEffect effect, @NotNull ParticleStyle style, @Nullable OrdinaryColor colorData, @Nullable NoteColor noteColorData, @Nullable Material materialData) { Objects.requireNonNull(location); Objects.requireNonNull(location.getWorld()); @@ -365,6 +594,12 @@ public final class PlayerParticlesAPI { this.createFixedParticleEffect(player, location, particle); } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param fixedEffect The modified fixed effect to edit + */ public void editFixedParticleEffect(@NotNull Player player, @NotNull FixedParticleEffect fixedEffect) { Objects.requireNonNull(fixedEffect); @@ -380,6 +615,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param location The new location + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull Location location) { Objects.requireNonNull(location); Objects.requireNonNull(location.getWorld()); @@ -392,6 +634,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param effect The new effect + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull ParticleEffect effect) { Objects.requireNonNull(effect); @@ -403,6 +652,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param style The new style + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull ParticleStyle style) { Objects.requireNonNull(style); @@ -414,6 +670,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param colorData The new color data + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull OrdinaryColor colorData) { Objects.requireNonNull(colorData); @@ -425,6 +688,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param noteColorData The new note color data + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull NoteColor noteColorData) { Objects.requireNonNull(noteColorData); @@ -436,6 +706,13 @@ public final class PlayerParticlesAPI { } } + /** + * Edits a fixed particle effect for a player + * + * @param player The player to edit from + * @param id The ID of the fixed particle effect + * @param materialData The new material data + */ public void editFixedParticleEffect(@NotNull Player player, int id, @NotNull Material materialData) { Objects.requireNonNull(materialData); @@ -451,6 +728,12 @@ public final class PlayerParticlesAPI { } } + /** + * Removes a fixed particle effect from a player + * + * @param player The player to remove from + * @param id The ID of the fixed particle effect + */ public void removeFixedEffect(@NotNull Player player, int id) { DataManager dataManager = this.playerParticles.getManager(DataManager.class); FixedParticleEffect fixedEffect = this.validateFixedParticleEffect(player, id); @@ -494,6 +777,13 @@ public final class PlayerParticlesAPI { return removedAmount; } + /** + * Validates that a fixed particle effect with the given ID exists for a player + * + * @param player The player to check + * @param id The ID of the fixed particle effect + * @return The fixed particle effect + */ @Nullable private FixedParticleEffect validateFixedParticleEffect(@NotNull Player player, int id) { PPlayer pplayer = this.getPPlayer(player); @@ -507,6 +797,13 @@ public final class PlayerParticlesAPI { return fixedEffect; } + /** + * Gets a fixed particle effect for a player + * + * @param player The player to get from + * @param id The ID of the fixed particle effect + * @return The fixed particle effect, or null if not found + */ @Nullable public FixedParticleEffect getFixedParticleEffect(@NotNull Player player, int id) { PPlayer pplayer = this.getPPlayer(player); @@ -516,6 +813,12 @@ public final class PlayerParticlesAPI { return pplayer.getFixedEffectById(id); } + /** + * Gets a collection of a player's fixed particle effects + * + * @param player The player to get from + * @return A collection of the player's fixed particle effects + */ @NotNull public Collection getFixedParticleEffects(@NotNull Player player) { PPlayer pplayer = this.getPPlayer(player); @@ -524,9 +827,16 @@ public final class PlayerParticlesAPI { return pplayer.getFixedParticlesMap().values(); } + //endregion //region GUI Management + + /** + * Opens the particles gui for a player + * + * @param player The player to open the gui for + */ public void openParticlesGui(@NotNull Player player) { PPlayer pplayer = this.getPPlayer(player); if (pplayer == null) @@ -534,9 +844,17 @@ public final class PlayerParticlesAPI { this.playerParticles.getManager(GuiManager.class).openDefault(pplayer); } + //endregion //region Player Settings + + /** + * Toggles a player's particle visibility on/off + * + * @param player The player to toggle visibility for + * @param particlesHidden true if the particles should be hidden, or false for visible + */ public void togglePlayerParticleVisibility(@NotNull Player player, boolean particlesHidden) { DataManager dataManager = this.playerParticles.getManager(DataManager.class); PPlayer pplayer = this.getPPlayer(player); @@ -546,20 +864,33 @@ public final class PlayerParticlesAPI { pplayer.setParticlesHidden(particlesHidden); dataManager.updateSettingParticlesHidden(player.getUniqueId(), particlesHidden); } + //endregion //region Registering Custom Styles + + /** + * Registers a particle style with the plugin + * + * @param particleStyle The particle style to register + */ public void registerParticleStyle(@NotNull ParticleStyle particleStyle) { Objects.requireNonNull(particleStyle); this.playerParticles.getManager(ParticleStyleManager.class).registerStyle(particleStyle); } + /** + * Registers an event-based particle style with the plugin + * + * @param particleStyle The particle style to register + */ public void registerEventParticleStyle(@NotNull ParticleStyle particleStyle) { Objects.requireNonNull(particleStyle); this.playerParticles.getManager(ParticleStyleManager.class).registerEventStyle(particleStyle); } + //endregion } diff --git a/src/main/java/dev/esophose/playerparticles/config/CommentedFileConfigurationHelper.java b/src/main/java/dev/esophose/playerparticles/config/CommentedFileConfigurationHelper.java index 3ad3b69..427e52a 100644 --- a/src/main/java/dev/esophose/playerparticles/config/CommentedFileConfigurationHelper.java +++ b/src/main/java/dev/esophose/playerparticles/config/CommentedFileConfigurationHelper.java @@ -22,6 +22,8 @@ public class CommentedFileConfigurationHelper { /** * Manage custom configurations and files + * + * @param plugin The JavaPlugin the configuration is for */ public CommentedFileConfigurationHelper(JavaPlugin plugin) { this.plugin = plugin; diff --git a/src/main/java/dev/esophose/playerparticles/particles/ParticleEffect.java b/src/main/java/dev/esophose/playerparticles/particles/ParticleEffect.java index d358dc4..0d5f992 100644 --- a/src/main/java/dev/esophose/playerparticles/particles/ParticleEffect.java +++ b/src/main/java/dev/esophose/playerparticles/particles/ParticleEffect.java @@ -113,7 +113,7 @@ public enum ParticleEffect { * Construct a new particle effect * * @param enumName Name of the Particle Enum when the server version is greater than or equal to 1.13 -* * @param enabledByDefault If the particle type is enabled by default + * @param enabledByDefault If the particle type is enabled by default * @param properties Properties of this particle effect */ ParticleEffect(String enumName, boolean enabledByDefault, ParticleProperty... properties) { @@ -148,6 +148,8 @@ public enum ParticleEffect { /** * Loads the settings shared for each style then calls loadSettings(CommentedFileConfiguration) + * + * @param reloadConfig If the settings should be reloaded or not */ public void loadSettings(boolean reloadConfig) { if (!this.isSupported()) @@ -165,6 +167,7 @@ public enum ParticleEffect { * * @param setting The setting name * @param value The setting value + * @param comments Comments for the setting */ private void setIfNotExists(String setting, Object value, String... comments) { if (this.config.get(setting) != null) diff --git a/src/main/java/dev/esophose/playerparticles/styles/DefaultParticleStyle.java b/src/main/java/dev/esophose/playerparticles/styles/DefaultParticleStyle.java index b2836ee..770f66b 100644 --- a/src/main/java/dev/esophose/playerparticles/styles/DefaultParticleStyle.java +++ b/src/main/java/dev/esophose/playerparticles/styles/DefaultParticleStyle.java @@ -54,6 +54,8 @@ public abstract class DefaultParticleStyle implements ParticleStyle { /** * Loads the settings shared for each style then calls loadSettings(CommentedFileConfiguration) + * + * @param reloadConfig If the settings should be reloaded or not */ public final void loadSettings(boolean reloadConfig) { if (reloadConfig) @@ -73,6 +75,7 @@ public abstract class DefaultParticleStyle implements ParticleStyle { * * @param setting The setting name * @param value The setting value + * @param comments Comments for the setting */ protected final void setIfNotExists(String setting, Object value, String... comments) { if (this.config.get(setting) != null) diff --git a/src/main/java/dev/esophose/playerparticles/styles/DefaultStyles.java b/src/main/java/dev/esophose/playerparticles/styles/DefaultStyles.java index c669904..436450a 100644 --- a/src/main/java/dev/esophose/playerparticles/styles/DefaultStyles.java +++ b/src/main/java/dev/esophose/playerparticles/styles/DefaultStyles.java @@ -47,6 +47,8 @@ public class DefaultStyles { /** * Registers all the default styles to the ParticleStyleManager * Registered in alphabetical order + * + * @param particleStyleManager The ParticleStyleManager instance */ public static void registerStyles(ParticleStyleManager particleStyleManager) { particleStyleManager.registerStyle(ARROWS); @@ -95,6 +97,8 @@ public class DefaultStyles { /** * Reloads the settings for all default styles + * + * @param particleStyleManager The ParticleStyleManager instance */ public static void reloadSettings(ParticleStyleManager particleStyleManager) { for (ParticleStyle style : particleStyleManager.getStylesWithDisabled())