API Documentation and small Fixes.

Documented all important API Components down to the Details.
Introduced Lombok Getters.
Added NBT Data Updating to the stopEvent() Method in CelestialEvent.
Removed some redundant Code.
Added Newline to CelestialRegisterEvent as requested.

Author: Atilist

station-world-events-v0/src/main/java/net/modificationstation/stationapi/api/celestial/CelestialEvent.java

@@ -1,12 +1,19 @@
 package net.modificationstation.stationapi.api.celestial;
 
+import lombok.Getter;
 import net.minecraft.world.World;
 
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Random;
 
+/**
+ * Contains the most important logic for automatically starting and stopping the event.
+ * It is recommended to add the event to CelestialTimeManger for automatic management.
+ * Inheritance is possible to add custom logic.
+ */
 public class CelestialEvent {
+    @Getter
     private final String name;
     private final int frequency;
     private float chance = 1;
@@ -15,37 +22,81 @@ public class CelestialEvent {
     private int startingDaytime = 0;
     private int endingDaytime = 0;
     private int extraDays = 0;
+    @Getter
     private boolean active;
     private boolean initializationNeeded = true;
     private final List<CelestialEvent> incompatibleEvents = new LinkedList<>();
     public final World world;
 
+    /**
+     * Primary constructor for the event, containing the required parameters.
+     *
+     * @param frequency Specifies how many day apart the events should be. The bigger the number, the longer the distance.
+     * @param name Event name, snake_casing is recommended.
+     * @param world World object, obtained from the register event.
+     */
     public CelestialEvent(int frequency, String name, World world) {
         this.frequency = frequency;
         this.name = name;
         this.world = world;
     }
 
+    /**
+     * Builder method for optional chance value.
+     *
+     * @param chance Value ranging from 0.0F to 1.0F, representing percentage chance.
+     * @return The object itself.
+     */
     public CelestialEvent setChance(float chance) {
         this.chance = chance;
         return this;
     }
 
+    /**
+     * Builder method for optional day length value.
+     * Intended to be used in dimensions where day time is different.
+     * This will however need a custom time manager to account for the different day length.
+     *
+     * @param dayLength Length of day specified in ticks.
+     * @return The object itself.
+     */
     public CelestialEvent setDayLength(int dayLength) {
         this.dayLength = dayLength;
         return this;
     }
 
+    /**
+     * Builder method for optional day offset.
+     *
+     * @param dayOffset Offsets the frequency by the specified number of days.
+     * @return The object itself.
+     */
     public CelestialEvent setDayOffset(int dayOffset) {
         this.dayOffset = dayOffset;
         return this;
     }
 
+    /**
+     * Builder method for optional extra days.
+     *
+     * @param extraDays Extends the event duration by the specified number of days.
+     * @return The object itself.
+     */
     public CelestialEvent setExtraDays(int extraDays) {
         this.extraDays = extraDays;
         return this;
     }
 
+    /**
+     * Attempts to activate the event. Checks if the activation already was attempted within the valid time frame.
+     * Takes activation chance and incompatible events into account.
+     * Method gets called by CelestialTimeManager in case the event is added to it.
+     * Can be called manually as well.
+     *
+     * @param worldTime Current time in the world measured in ticks.
+     * @param random Locally used randomizer, seed is irrelevant.
+     * @return True if the event met the criteria to be activated, otherwise false.
+     */
     public boolean activateEvent(long worldTime, Random random) {
         CelestialEventActivityState activityState = (CelestialEventActivityState) this.world.getOrCreateState(CelestialEventActivityState.class, this.name);
         if (initializationNeeded) {
@@ -60,7 +111,6 @@ public boolean activateEvent(long worldTime, Random random) {
         for (CelestialEvent otherEvent : incompatibleEvents) {
             if (otherEvent == null) continue;
             if (otherEvent.isActive()) {
-                active = false;
                 activityState.active = false;
                 activityState.attemptedActivation = true;
                 activityState.markDirty();
@@ -80,12 +130,29 @@ public boolean activateEvent(long worldTime, Random random) {
         return active;
     }
 
+    /**
+     * Called precisely on event activation.
+     * Can be customized by inheriting from this class.
+     * Has access to the world object for more versatility.
+     */
     public void onActivation() {
     }
 
+    /**
+     * Called precisely on event deactivation.
+     * Can be customized by inheriting from this class.
+     * Has access to the world object for more versatility.
+     */
     public void onDeactivation() {
     }
 
+    /**
+     * Updates the activity status of an already active event.
+     * Used by CelestialTimeManager 4 times per day.
+     * Checks for validity of the time interval but not for chance and incompatibility.
+     *
+     * @param worldTime Current time in the world measured in ticks.
+     */
     public void updateEvent(long worldTime) {
         CelestialEventActivityState activityState = (CelestialEventActivityState) this.world.getOrCreateState(CelestialEventActivityState.class, this.name);
         if (initializationNeeded) {
@@ -104,6 +171,13 @@ public void updateEvent(long worldTime) {
         activityState.markDirty();
     }
 
+    /**
+     * Initializes the event by synchronizing it with NBT data.
+     * Only used internally.
+     *
+     * @param activityState CelestialEventActivityState (custom PersistentState) used for accessing NBT data.
+     * @return The initialized CelestialEventActivityState.
+     */
     private CelestialEventActivityState initializeEvent(CelestialEventActivityState activityState) {
         initializationNeeded = false;
         activityState = (CelestialEventActivityState) this.world.getOrCreateState(CelestialEventActivityState.class, this.name);
@@ -116,38 +190,52 @@ private CelestialEventActivityState initializeEvent(CelestialEventActivityState
         return activityState;
     }
 
+    /**
+     * Manual way of stopping event.
+     * Intended for command systems.
+     */
     public void stopEvent() {
         onDeactivation();
         if (active) {
+            CelestialEventActivityState activityState = (CelestialEventActivityState) this.world.getOrCreateState(CelestialEventActivityState.class, this.name);
+            if (initializationNeeded) {
+                activityState = initializeEvent(activityState);
+            }
+            activityState.active = false;
+            activityState.markDirty();
             System.out.println("Stopping event " + name);
             active = false;
         }
     }
 
+    /**
+     * Called by CelestialTimeManager to specify the valid time frame of the event.
+     * Time values can be specified as 4 values representing ticks in a day:
+     * Morning: 0, Noon: 6000, Evening: 12000, Midnight: 18000
+     *
+     * @param startingDaytime Beginning daytime of the event.
+     * @param endingDaytime Ending daytime of the event.
+     */
     public void setInterval(int startingDaytime, int endingDaytime) {
         this.startingDaytime = startingDaytime;
         this.endingDaytime = endingDaytime;
     }
 
-    public boolean isActive() {
-        return active;
-    }
-
-    public String getName() {
-        return this.name;
-    }
-
     /**
      * Adds events to prevent them from happening simultaneously.
      * Automatically adds incompatibility for both directions.
-     * @param otherEvent
+     *
+     * @param otherEvent Event to be added to the incompatibility list.
      */
     public void addIncompatibleEvent(CelestialEvent otherEvent) {
         if (incompatibleEvents.contains(otherEvent)) return;
         incompatibleEvents.add(otherEvent);
         otherEvent.addIncompatibleEvent(this);
     }
 
+    /**
+     * Used by CelestialTimeManager to handle an edge-case where events would not be loaded when reloading the same world.
+     */
     public void markForInitialization() {
         CelestialEventActivityState activityState = (CelestialEventActivityState) this.world.getOrCreateState(CelestialEventActivityState.class, this.name);
         initializeEvent(activityState);

station-world-events-v0/src/main/java/net/modificationstation/stationapi/api/celestial/CelestialEventActivityState.java

@@ -3,6 +3,9 @@
 import net.minecraft.nbt.NbtCompound;
 import net.minecraft.world.PersistentState;
 
+/**
+ * Manages important NBT data to ensure correct saving and loading of active celestial events.
+ */
 public class CelestialEventActivityState extends PersistentState {
     public boolean active;
     public boolean attemptedActivation;

station-world-events-v0/src/main/java/net/modificationstation/stationapi/api/celestial/CelestialTimeManager.java

@@ -4,6 +4,13 @@
 import java.util.List;
 import java.util.Random;
 
+/**
+ * Manages the activation and deactivation of celestial events.
+ * Has been injected into WorldProperties using the WorldPropertiesMixin in station-world-events, does not need to be handled by mods.
+ * Events need to be added during the registering process.
+ * Uses lists to schedule event updates during the correct time of day.
+ * Called four times per day.
+ */
 public class CelestialTimeManager {
     private static final List<CelestialEvent> MORNING_START = new LinkedList<>();
     private static final List<CelestialEvent> NOON_START = new LinkedList<>();
@@ -20,6 +27,13 @@ public class CelestialTimeManager {
 
     private static final Random RANDOM = new Random();
 
+    /**
+     * Add a celestial event to the time manager.
+     *
+     * @param celestialEvent Event to be added.
+     * @param start Time of day at which the event begins.
+     * @param stop Time of day at which the event ends.
+     */
     public static void addCelestialEvent(CelestialEvent celestialEvent, DayQuarter start, DayQuarter stop) {
         switch (start) {
             case MORNING -> MORNING_START.add(celestialEvent);
@@ -31,6 +45,12 @@ public static void addCelestialEvent(CelestialEvent celestialEvent, DayQuarter s
         celestialEvent.setInterval(start.ordinal() * 6000, Math.abs(stop.ordinal() * 6000 - start.ordinal() * 6000));
     }
 
+    /**
+     * Attempts to start all morning events. Called once per day.
+     *
+     * @param time World time in ticks.
+     * @param currentDay Current day in the world.
+     */
     public static void startMorningEvents(long time, long currentDay) {
         if (morningActivation && lastCheckedDay == currentDay) return;
         lastCheckedDay = currentDay;
@@ -45,6 +65,12 @@ public static void startMorningEvents(long time, long currentDay) {
         }
     }
 
+    /**
+     * Attempts to start all noon events. Called once per day.
+     *
+     * @param time World time in ticks.
+     * @param currentDay Current day in the world.
+     */
     public static void startNoonEvents(long time, long currentDay) {
         if (noonActivation && lastCheckedDay == currentDay) return;
         lastCheckedDay = currentDay;
@@ -59,6 +85,12 @@ public static void startNoonEvents(long time, long currentDay) {
         }
     }
 
+    /**
+     * Attempts to start all evening events. Called once per day.
+     *
+     * @param time World time in ticks.
+     * @param currentDay Current day in the world.
+     */
     public static void startEveningEvents(long time, long currentDay) {
         if (eveningActivation && lastCheckedDay == currentDay) return;
         lastCheckedDay = currentDay;
@@ -73,6 +105,12 @@ public static void startEveningEvents(long time, long currentDay) {
         }
     }
 
+    /**
+     * Attempts to start all midnight events. Called once per day.
+     *
+     * @param time World time in ticks.
+     * @param currentDay Current day in the world.
+     */
     public static void startMidnightEvents(long time, long currentDay) {
         if (midnightActivation && lastCheckedDay == currentDay) return;
         lastCheckedDay = currentDay;
@@ -87,13 +125,21 @@ public static void startMidnightEvents(long time, long currentDay) {
         }
     }
 
+    /**
+     * Updates activity state of all events. Called four times per day.
+     *
+     * @param time World time in ticks.
+     */
     public static void updateEvents(long time) {
         for (CelestialEvent celestialEvent : ALL_EVENTS) {
             if (celestialEvent == null) continue;
             celestialEvent.updateEvent(time);
         }
     }
 
+    /**
+     * Clears all lists. Ensures that no duplicates show up after switching worlds.
+     */
     public static void clearLists() {
         MORNING_START.clear();
         NOON_START.clear();
@@ -102,6 +148,9 @@ public static void clearLists() {
         ALL_EVENTS.clear();
     }
 
+    /**
+     * Initializes all events when the world is loaded, ensures correct loading of active events.
+     */
     public static void initializeEvents() {
         for (CelestialEvent celestialEvent : ALL_EVENTS) {
             if (celestialEvent == null) continue;

station-world-events-v0/src/main/java/net/modificationstation/stationapi/api/celestial/DayQuarter.java

@@ -1,5 +1,8 @@
 package net.modificationstation.stationapi.api.celestial;
 
+/**
+ * Used for celestial event time management.
+ */
 public enum DayQuarter {
     MORNING, NOON, EVENING, MIDNIGHT
 }

station-world-events-v0/src/main/java/net/modificationstation/stationapi/api/event/celestial/CelestialRegisterEvent.java

@@ -4,4 +4,4 @@
 import net.modificationstation.stationapi.api.event.world.WorldEvent;
 
 @SuperBuilder
-public class CelestialRegisterEvent extends WorldEvent {}
+public class CelestialRegisterEvent extends WorldEvent {}