From 57f0381731ad8e7e1301459d4861698342b79c96 Mon Sep 17 00:00:00 2001 From: Paul Reilly Date: Wed, 19 Jul 2023 22:49:17 -0500 Subject: [PATCH] documentation, mostly --- build.gradle | 1 + .../arcanumocculta/ArcanumOcculta.java | 5 +- .../api/caster/AbstractCaster.java | 21 +++++ .../api/caster/AbstractSpellBook.java | 14 +++- .../arcanumocculta/api/caster/Caster.java | 77 ++++++++++++++++++ .../api/caster/CasterLevel.java | 10 +-- .../arcanumocculta/api/caster/SpellBook.java | 56 ++++++++++++- .../api/event/ExperienceUpdateEvent.java | 78 +++++++++++++++++++ .../api/spell/AbstractSpell.java | 2 +- .../arcanumocculta/api/spell/Spell.java | 43 ++++++++++ .../arcanumocculta/api/spell/SpellEffect.java | 6 ++ 11 files changed, 303 insertions(+), 10 deletions(-) create mode 100644 src/main/java/app/simplexdev/arcanumocculta/api/event/ExperienceUpdateEvent.java diff --git a/build.gradle b/build.gradle index 2c51c4f..c19c03c 100644 --- a/build.gradle +++ b/build.gradle @@ -20,6 +20,7 @@ repositories { dependencies { compileOnly "org.spigotmc:spigot-api:1.20.1-R0.1-SNAPSHOT" compileOnly "org.reflections:reflections:0.10.2" + implementation "org.jetbrains:annotations:23.0.0" } def targetJavaVersion = 17 diff --git a/src/main/java/app/simplexdev/arcanumocculta/ArcanumOcculta.java b/src/main/java/app/simplexdev/arcanumocculta/ArcanumOcculta.java index 0ed3c62..3eaabc8 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/ArcanumOcculta.java +++ b/src/main/java/app/simplexdev/arcanumocculta/ArcanumOcculta.java @@ -1,12 +1,15 @@ package app.simplexdev.arcanumocculta; +import app.simplexdev.arcanumocculta.api.event.ExperienceUpdateEvent; +import org.bukkit.Bukkit; import org.bukkit.plugin.java.JavaPlugin; public class ArcanumOcculta extends JavaPlugin { + @Override public void onEnable() { - + ; } public static ArcanumOcculta getInstance() diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractCaster.java b/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractCaster.java index 4c9bfe1..bbc1292 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractCaster.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractCaster.java @@ -1,5 +1,6 @@ package app.simplexdev.arcanumocculta.api.caster; +import app.simplexdev.arcanumocculta.api.event.ExperienceUpdateEvent; import app.simplexdev.arcanumocculta.api.wand.Wand; import java.util.UUID; import org.bukkit.Bukkit; @@ -31,6 +32,7 @@ public abstract class AbstractCaster implements Caster return this.wand; } + @Override public void setWand(final Wand wand) { this.wand = wand; @@ -60,6 +62,7 @@ public abstract class AbstractCaster implements Caster return this.level; } + @Override public void setCurrentLevel(final CasterLevel level) { this.level = level; @@ -71,9 +74,12 @@ public abstract class AbstractCaster implements Caster return this.currentExperience; } + @Override public void setCurrentExperience(final double experience) { this.currentExperience = experience; + final ExperienceUpdateEvent event = new ExperienceUpdateEvent(this, experience); + Bukkit.getPluginManager().callEvent(event); } @Override @@ -82,6 +88,7 @@ public abstract class AbstractCaster implements Caster return this.currentMana; } + @Override public void setCurrentMana(final double mana) { this.currentMana = mana; @@ -99,34 +106,48 @@ public abstract class AbstractCaster implements Caster this.maxMana = mana; } + @Override public void addExperience(final double experience) { this.currentExperience = this.currentExperience + experience; + final ExperienceUpdateEvent event = new ExperienceUpdateEvent(this, getCurrentExperience()); + Bukkit.getPluginManager().callEvent(event); } + @Override public void removeExperience(final double experience) { this.currentExperience = this.currentExperience - experience; + final ExperienceUpdateEvent event = new ExperienceUpdateEvent(this, getCurrentExperience()); + Bukkit.getPluginManager().callEvent(event); } + @Override public void addMana(final double mana) { this.currentMana = this.currentMana + mana; } + @Override public void removeMana(final double mana) { this.currentMana = this.currentMana - mana; } + /** + * Sets the current mana to the max mana. + */ public void setManaToMax() { this.currentMana = this.maxMana; } + @Override public void setExperienceToZero() { this.currentExperience = 0; + final ExperienceUpdateEvent event = new ExperienceUpdateEvent(this, getCurrentExperience()); + Bukkit.getPluginManager().callEvent(event); } @Override diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractSpellBook.java b/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractSpellBook.java index c805a0a..d5a7541 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractSpellBook.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/caster/AbstractSpellBook.java @@ -44,6 +44,12 @@ public abstract class AbstractSpellBook implements SpellBook .orElse(getSpells().get(0)); } + /** + * Get a spell by its unique id + * + * @param uuid the unique id of the spell + * @return The spell, or null if none found. + */ public Spell getSpell(UUID uuid) { return getSpells().stream() @@ -84,7 +90,13 @@ public abstract class AbstractSpellBook implements SpellBook this.spells.clear(); } - public void addAll(Collection spells) { + /** + * Add a collection of spells to the spell book + * + * @param spells The spells to add + */ + public void addAll(Collection spells) + { this.spells.addAll(spells); } diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/caster/Caster.java b/src/main/java/app/simplexdev/arcanumocculta/api/caster/Caster.java index 67b55b6..3ab6b02 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/caster/Caster.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/caster/Caster.java @@ -6,39 +6,116 @@ import org.bukkit.entity.Player; public interface Caster { + /** + * @return The Caster's currently attuned wand. + */ Wand getWand(); + /** + * Sets the Caster's currently attuned wand. + * + * @param wand The wand to attune to. + */ void setWand(Wand wand); + /** + * @return The Caster's spellbook. + */ SpellBook getSpellBook(); + /** + * @return The Caster's name. + */ String getName(); + /** + * @return The Caster's unique ID, as provided by Bukkit's {@link Player#getUniqueId()}. + */ UUID getUniqueId(); + /** + * @return The Caster's current mana. + */ double getCurrentMana(); + /** + * Sets the Caster's current mana. + * + * @param mana The amount of mana to set. + */ void setCurrentMana(double mana); + /** + * @return The Caster's maximum mana. + */ double getMaxMana(); + /** + * Sets the Caster's maximum mana. + * + * @param maxMana The amount of mana to set. + */ void setMaxMana(double maxMana); + /** + * @return The Caster's current level. + */ CasterLevel getCurrentLevel(); + /** + * Sets the Caster's current level. + * + * @param level The level to set. + */ void setCurrentLevel(CasterLevel level); + /** + * @return The Caster's current experience. + */ double getCurrentExperience(); + /** + * Sets the Caster's current experience. + * + * @param experience The amount of experience to set. + */ void setCurrentExperience(double experience); + /** + * Adds mana to the Caster's current mana. + * + * @param mana The amount of mana to add. + */ void addMana(double mana); + /** + * Removes mana from the Caster's current mana. + * + * @param mana The amount of mana to remove. + */ void removeMana(double mana); + /** + * Adds experience to the Caster's current experience. + * + * @param experience The amount of experience to add. + */ void addExperience(double experience); + /** + * Removes experience from the Caster's current experience. + * + * @param experience The amount of experience to remove. + */ void removeExperience(double experience); + /** + * @return The Caster's Bukkit Player object. + */ Player bukkit(); + + /** + * Resets the Caster's current experience back to zero. + */ + void setExperienceToZero(); } diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/caster/CasterLevel.java b/src/main/java/app/simplexdev/arcanumocculta/api/caster/CasterLevel.java index 78ec485..95c50a9 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/caster/CasterLevel.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/caster/CasterLevel.java @@ -18,17 +18,17 @@ public enum CasterLevel ARCH_MAGE(9, 4000D, "Arch-Mage", "an Arch-Mage", ChatColor.BLACK, "Lvl9"); private final int level; - private final double experienceMarker; + private final double nextLevelExp; private final String name; private final String plural; private final ChatColor rankColor; private final String suffix; - CasterLevel(final int level, final double experienceMarker, final String name, final String plural, + CasterLevel(final int level, final double nextLevelExp, final String name, final String plural, final ChatColor rankColor, final String suffix) { - this.experienceMarker = experienceMarker; + this.nextLevelExp = nextLevelExp; this.level = level; this.name = name; this.plural = plural; @@ -74,9 +74,9 @@ public enum CasterLevel return this.suffix; } - public double getExperienceMarker() + public double getNextLevelExp() { - return this.experienceMarker; + return this.nextLevelExp; } public boolean isAtLeast(final CasterLevel level) { diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/caster/SpellBook.java b/src/main/java/app/simplexdev/arcanumocculta/api/caster/SpellBook.java index a2916d0..7cf67f0 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/caster/SpellBook.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/caster/SpellBook.java @@ -5,25 +5,77 @@ import java.util.List; public interface SpellBook { + /** + * @return A list of all spells in the spell book. + */ List getSpells(); + /** + * Adds a spell to the spell book. + * + * @param spell The spell to add. + */ void addSpell(Spell spell); + /** + * Removes a spell from the spell book. + * + * @param spell The spell to remove. + */ void removeSpell(Spell spell); - Spell getSpell(String name); + /** + * Retrieves a spell from the spell book. + * + * @param id The id of the spell to retrieve. + * @return The spell with the given id. + */ + Spell getSpell(String id); + /** + * Retrieves a spell from the spell book with the given index. + * + * @param index The index of the spell to retrieve. + * @return The spell at the given index. + */ Spell getSpell(int index); + /** + * @return The number of spells in the spell book. + */ int getSpellCount(); + /** + * Sets the spell at the given index to the given spell. + * + * @param index The index of the spell to set. + * @param spell The spell to set. + */ void setSpell(int index, Spell spell); - void setSpell(String name, Spell spell); + /** + * Sets the spell with the given id to the given spell. + * + * @param id The id of the spell to set. + * @param spell The spell to set. + */ + void setSpell(String id, Spell spell); + /** + * Clears all spells from the spell book. + */ void clearSpells(); + /** + * @return A random spell from the spell book. + */ Spell randomSpell(); + /** + * Checks if the spell book contains the given spell. + * + * @param spell The spell to check for. + * @return True if the spell book contains the given spell, false otherwise. + */ boolean hasSpell(final Spell spell); } diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/event/ExperienceUpdateEvent.java b/src/main/java/app/simplexdev/arcanumocculta/api/event/ExperienceUpdateEvent.java new file mode 100644 index 0000000..e9179c8 --- /dev/null +++ b/src/main/java/app/simplexdev/arcanumocculta/api/event/ExperienceUpdateEvent.java @@ -0,0 +1,78 @@ +/* + * Copyright (c) 2023 Simplex Development Group + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * with the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package app.simplexdev.arcanumocculta.api.event; + +import app.simplexdev.arcanumocculta.api.caster.Caster; +import app.simplexdev.arcanumocculta.api.caster.CasterLevel; +import org.bukkit.event.HandlerList; +import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.NotNull; + +public final class ExperienceUpdateEvent extends PlayerEvent +{ + private final HandlerList handlerList = new HandlerList(); + private final double newExperience; + private final Caster caster; + + private final boolean didLevel; + + public ExperienceUpdateEvent(final Caster who, final double newExperience) + { + super(who.bukkit()); + + this.newExperience = newExperience; + this.caster = who; + this.didLevel = checkLevelUp(); + } + + @Override + @NotNull + public HandlerList getHandlers() + { + return handlerList; + } + + public double getNewExperience() { + return newExperience; + } + + public Caster getCaster() { + return caster; + } + + private boolean checkLevelUp() { + final double expReq = caster.getCurrentLevel().getNextLevelExp(); + + if (newExperience >= expReq) { + caster.setExperienceToZero(); + caster.setCurrentLevel(CasterLevel.fromOrdinal(caster.getCurrentLevel().getLevel() + 1)); + caster.bukkit().sendMessage("You have leveled up to " + caster.getCurrentLevel().getName() + "!"); + return true; + } + return false; + } + + public boolean didCasterLevelUp() { + return didLevel; + } +} diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/spell/AbstractSpell.java b/src/main/java/app/simplexdev/arcanumocculta/api/spell/AbstractSpell.java index e05d3e3..a53cbf8 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/spell/AbstractSpell.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/spell/AbstractSpell.java @@ -194,7 +194,7 @@ public abstract class AbstractSpell implements Spell public Entity prepareProjectile(final Caster caster, final Material visual, final Vector velocity) { - final double expMod = getLevelRequirement().getExperienceMarker(); + final double expMod = getLevelRequirement().getNextLevelExp(); final Player player = caster.bukkit(); final Location location = player.getLocation().clone().add(0, player.getEyeHeight(), 0); diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/spell/Spell.java b/src/main/java/app/simplexdev/arcanumocculta/api/spell/Spell.java index 5d3fe9d..4045601 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/spell/Spell.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/spell/Spell.java @@ -10,31 +10,74 @@ import java.util.UUID; public interface Spell { + /** + * @return The display name of the spell. + */ String getName(); + /** + * @return The id of the spell. + */ String getId(); + /** + * @return The unique id of the spell. + */ default UUID getUniqueId() { return UUID.nameUUIDFromBytes(this.getName().getBytes()); } + /** + * @return The description of the spell. + */ String getDescription(); + /** + * @return The level requirement of the spell. + */ CasterLevel getLevelRequirement(); + /** + * @return The base damage of the spell. + */ Damages baseDamage(); + /** + * @return An array of all the applicable spell effects. + */ SpellEffect[] getSpellEffects(); + /** + * @return How long each effect should last. + */ Durations effectDuration(); + /** + * @return How much mana this spell consumes. + */ ManaCosts manaCost(); + /** + * @return How long until the spell can be used again. + */ long coolDown(); + /** + * Checks if the caster has this spell unlocked. + * This is based on their level and if the spell is in their spell book. + * + * @param caster The caster to check. + * @return True if the caster has this spell unlocked. + */ boolean isUnlocked(final Caster caster); + /** + * Casts the spell. + * + * @param caster The caster casting the spell. + * @param wand The wand the caster is using. + */ void cast(final Caster caster, final Wand wand); /** diff --git a/src/main/java/app/simplexdev/arcanumocculta/api/spell/SpellEffect.java b/src/main/java/app/simplexdev/arcanumocculta/api/spell/SpellEffect.java index f180e46..243f40a 100644 --- a/src/main/java/app/simplexdev/arcanumocculta/api/spell/SpellEffect.java +++ b/src/main/java/app/simplexdev/arcanumocculta/api/spell/SpellEffect.java @@ -6,5 +6,11 @@ import org.bukkit.entity.LivingEntity; @FunctionalInterface public interface SpellEffect { + /** + * Apply this spell effect to the given target, from the given caster. + * + * @param target The target of the spell. + * @param caster The caster of the spell. + */ void apply(final LivingEntity target, final Caster caster); }