documentation, mostly

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

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()

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

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<? extends Spell> spells) {
+    /**
+     * Add a collection of spells to the spell book
+     *
+     * @param spells The spells to add
+     */
+    public void addAll(Collection<? extends Spell> spells)
+    {
         this.spells.addAll(spells);
     }
 

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();
 }

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) {

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<Spell> 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);
 }

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;
+    }
+}

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);

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);
 
     /**

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);
 }