Package net.pottercraft.ollivanders2.divination

Class O2Prophecies

java.lang.Object
net.pottercraft.ollivanders2.divination.O2Prophecies
public class O2Prophecies extends Object
Central manager for all divination prophecies in the server.

O2Prophecies maintains two separate lists of prophecies: active prophecies for online players and offline prophecies waiting for players to return. Every game tick, the upkeep() method processes all active prophecies, aging them by one tick and fulfilling those whose time has reached zero. Prophecies are automatically persisted to disk using JSON serialization, allowing them to survive server restarts.

This class is responsible for:

  • Adding new prophecies created by divination spells
  • Processing active prophecies each tick (age and fulfill)
  • Managing offline prophecies that wait for players to log back in
  • Serializing prophecies to JSON for persistent storage
  • Deserializing prophecies from JSON when the server starts
  • Querying prophecies by target player or prophet player
See Also:

  • Constructor Details

    • O2Prophecies

      public O2Prophecies(@NotNull @NotNull Ollivanders2 plugin)
      Constructor
      Parameters:
      plugin - a callback to the plugin

  • Method Details

    • addProphecy

      public void addProphecy(@NotNull @NotNull O2Prophecy prophecy)
      Add a newly created prophecy to the active prophecies list.

      This method is called by O2Divination.divine() when a divination prophecy is created. The prophecy is added to the active list and will be processed by upkeep() every game tick.

      Parameters:
      prophecy - the newly created prophecy to add

    • getProphecyAboutPlayer

      @Nullable public @Nullable O2Prophecy getProphecyAboutPlayer(@NotNull @NotNull UUID pid)
      Get the first active prophecy where the given player is the target (subject of the prophecy).

      Searches only the active prophecies list (prophecies scheduled for online players). If you need to check for offline prophecies as well, use getProphecy() instead.

      Parameters:
      pid - the unique ID of the target player
      Returns:
      the prophecy about this player if found in active list, or null if not found

    • getProphecies

      @NotNull public @NotNull List<String> getProphecies()
      Get a list of all pending prophecy messages (both active and offline).

      Returns the human-readable prophecy text messages from both active and offline prophecies combined. Useful for displaying all pending prophecies to a player or admin.

      Returns:
      a list of prophecy message strings from all pending prophecies

    • getProphecyByPlayer

      @Nullable public @Nullable O2Prophecy getProphecyByPlayer(@NotNull @NotNull UUID pid)
      Get the first active prophecy made by (created by) the given player.

      Searches only the active prophecies list to find a prophecy where this player is the prophet (creator). This is distinct from getProphecyAboutPlayer() which finds prophecies where the player is the target.

      Parameters:
      pid - the unique ID of the prophet (spell caster)
      Returns:
      the prophecy created by this player if found in active list, or null if not found

    • upkeep

      public void upkeep()
      Process all active prophecies for one game tick.

      This method is called every server tick and handles the lifecycle of all active prophecies:

      1. Iterates through a snapshot of all active prophecies (to allow safe removal during iteration)
      2. For each non-killed prophecy: ages it by one tick (decrements time counter)
      3. If time reaches zero or below: calls fulfill() to execute the prophecy
      4. If the fulfilled prophecy is in the offline list: removes it from active list
      5. Removes any killed prophecies from the active list

      A snapshot of the active prophecies list is used to avoid ConcurrentModificationException when removing prophecies during iteration.

    • onDisable

      public void onDisable()
      Cleanup when the plugin disables.

      Called when the Ollivanders2 plugin is being shut down. The O2Prophecies manager persists all pending prophecies to disk before the plugin terminates. This ensures that divination prophecies created by players are preserved across server restarts, maintaining continuity of long-term prophecy mechanics.

      Saved Data:

      • All active prophecies (scheduled for online players)
      • All offline prophecies (waiting for players to log back in)
      • Prophecy metadata: target player, prophet, effect type, duration, accuracy
      • Prophecy aging state: remaining time until fulfillment
      • Data is persisted as JSON via GsonDAO for restoration on server startup
      See Also:

    • saveProphecies

      public void saveProphecies()
      Persist all prophecies to disk in JSON format.

      Called when the server shuts down (via the prophecy save scheduler). Serializes all active and offline prophecies to JSON Maps and writes them to the prophecies save file. Only non-killed prophecies are saved.

    • loadProphecies

      public void loadProphecies()
      Load all saved prophecies from disk.

      Called during plugin initialization to restore prophecies from the last server session. Deserializes JSON data back into O2Prophecy objects and adds them to the active prophecies list. If no save file exists, logs a message and continues without any prophecies.

    • onJoin

      public void onJoin(@NotNull @NotNull UUID pid)
      Move any prophecies for the newly joined player from offline to active list.

      When a player logs in, check if there are any prophecies waiting in the offline list for them. If so, move those prophecies to the active list so they resume being processed by upkeep().

      A snapshot of the offline prophecies list is used to allow safe removal during iteration.

      Parameters:
      pid - the unique ID of the player that just logged in

    • getProphecy

      @Nullable public @Nullable String getProphecy(@NotNull @NotNull UUID targetID)
      Get the prophecy message text for a specific player (searches both active and offline prophecies).

      Returns the first prophecy message found for the player, checking active prophecies first, then offline prophecies. Only returns the message text, not the full O2Prophecy object. Use getProphecyAboutPlayer() if you need the full prophecy object.

      Parameters:
      targetID - the unique ID of the target player
      Returns:
      the prophecy message text if found, or null if no prophecy exists for this player

    • resetProphecies

      public void resetProphecies()
      Clear all pending prophecies (both active and offline).

      Removes all prophecies from both lists. Used primarily for testing and configuration resets.

    • activeProphecyCount

      public int activeProphecyCount()
      Get the count of active prophecies currently pending.

      Returns the number of prophecies in the active list only (not including offline prophecies). Useful for status checking and debugging.

      Returns:
      the number of active prophecies