Package tfagaming.projects.minecraft.homestead.managers

Class LevelManager

java.lang.Object
tfagaming.projects.minecraft.homestead.managers.LevelManager
public final class LevelManager extends Object
A utility class that manages Level progression for regions.

  • Method Summary

    Modifier and Type
    Method
    Description
    static long
    addRandomXp(long regionId, double min, double max)
    Add random XP between min and max (inclusive).
    static long
    addRandomXp(long regionId, long min, long max)
    Add random XP with integer bounds.
    static void
    addXp(long regionId, long amount)
    Add fixed XP to a region.
    static void
    addXpPercentage(long regionId, double percentage)
    Add XP as a percentage of the XP required for the next level.
    static int
    cleanupInvalidLevels()
    Removes all level entries with invalid references:
    - Regions that no longer exist
    static Level
    createLevel(long regionId)
    Create a new level entry for a region.
    static void
    deleteLevel(long id)
    Permanently deletes the specified level.
    static void
    deleteLevelByRegion(long regionId)
    Delete level by region ID.
    static void
    delevel(long regionId, int levels)
    Removes levels from a region without going below 0.
    static Level
    findLevel(long id)
    Retrieves the level with the exact ID, or null if none exists.
    static List<Level>
    getAll()
    Returns an immutable view of every loaded level.
    static List<Long>
    getAllRegions()
    Returns all region IDs that have a level entry.
    static double
    getAverageLevel()
    Returns the server-wide average region level.
    static Level
    getHighestLevel()
    Finds the region with the highest level.
    static long
    getHighestLevelRegion()
    Finds the region ID with the highest level.
    static long
    getLevelAge(long regionId)
    Returns how many milliseconds ago the level entry was created.
    static Level
    getLevelByRegion(long regionId)
    Get level by region ID.
    static int
    getLevelCount()
    Returns the number of levels in the server.
    static int
    getLevelDifference(long regionIdA, long regionIdB)
    Calculates the level difference between two regions.
    static Map<Integer,Integer>
    getLevelDistribution()
    Returns a histogram of level distribution.
    static double
    getLevelProgressPercentage(long regionId)
    Returns the current progress percentage toward the next level.
    static Level
    getOrCreateLevel(long regionId)
    Get or create level for a region.
    static int
    getRank(long regionId)
    Get region's rank on leaderboard.
    static List<Long>
    getRegionsAboveLevel(int minLevel)
    Returns all region IDs above the specified level threshold.
    static List<Long>
    getRegionsAtLevel(int level)
    Returns all region IDs at exactly the specified level.
    static List<Level>
    getTopLevels(int limit)
    Get top levels sorted by level (desc), then by XP (desc).
    static long
    getTotalXpForLevel(int targetLevel)
    Returns the XP required to reach a specific level from level 0.
    static long
    getTotalXpOfRegion(long regionId)
    Returns the total accumulated XP (including spent on levels) for a region.
    static long
    getXpUntilNextLevel(long regionId)
    Returns the remaining XP needed to reach the next level.
    static void
    grantLevels(long regionId, int levels)
    Grants multiple levels at once.
    static boolean
    isMaxLevel(long regionId, int maxLevel)
    Checks if a region has reached or exceeded a maximum level cap.
    static void
    multiplyXp(long regionId, double factor)
    Multiplies the current XP progress by a factor (useful for boosters).
    static void
    removeXp(long regionId, long amount)
    Remove XP from a region (won't decrease level, only progress).
    static int
    resetAllLevels()
    Resets every level in the cache.
    static void
    resetLevel(long regionId)
    Reset level to 0.
    static void
    setLevel(long regionId, int level)
    Set exact level (resets progress to 0).
    static void
    setXp(long regionId, long experience)
    Set exact XP amount (triggers level re-calculation).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • createLevel

      public static Level createLevel(long regionId)
      Create a new level entry for a region.
      Parameters:
      regionId - The region ID
      Returns:
      The created Level, or null if one already exists.

    • getAll

      public static List<Level> getAll()
      Returns an immutable view of every loaded level.
      Returns:
      List of all levels.

    • getAllRegions

      public static List<Long> getAllRegions()
      Returns all region IDs that have a level entry.
      Returns:
      List of region IDs.

    • getLevelByRegion

      public static Level getLevelByRegion(long regionId)
      Get level by region ID.
      Parameters:
      regionId - The region ID
      Returns:
      The Level, or null if not found.

    • findLevel

      public static Level findLevel(long id)
      Retrieves the level with the exact ID, or null if none exists.
      Parameters:
      id - The level ID
      Returns:
      The Level, or null.

    • getOrCreateLevel

      public static Level getOrCreateLevel(long regionId)
      Get or create level for a region.
      Parameters:
      regionId - The region ID
      Returns:
      The existing or newly created Level.

    • getLevelCount

      public static int getLevelCount()
      Returns the number of levels in the server.
      Returns:
      The level count.

    • deleteLevel

      public static void deleteLevel(long id)
      Permanently deletes the specified level.
      Parameters:
      id - The level ID

    • deleteLevelByRegion

      public static void deleteLevelByRegion(long regionId)
      Delete level by region ID.
      Parameters:
      regionId - The region ID

    • addXp

      public static void addXp(long regionId, long amount)
      Add fixed XP to a region.
      Parameters:
      regionId - The region ID
      amount - Amount of XP to add

    • addXpPercentage

      public static void addXpPercentage(long regionId, double percentage)
      Add XP as a percentage of the XP required for the next level.
      Parameters:
      regionId - The region ID
      percentage - Percentage of next level XP (0.0–100.0)

    • multiplyXp

      public static void multiplyXp(long regionId, double factor)
      Multiplies the current XP progress by a factor (useful for boosters).
      Parameters:
      regionId - The region ID
      factor - The multiplier (e.g., 2.0 for double)

    • addRandomXp

      public static long addRandomXp(long regionId, double min, double max)
      Add random XP between min and max (inclusive).
      Parameters:
      regionId - The region ID
      min - Minimum XP (can be double, will be floored)
      max - Maximum XP (can be double, will be floored)
      Returns:
      The actual amount of XP added.

    • addRandomXp

      public static long addRandomXp(long regionId, long min, long max)
      Add random XP with integer bounds.
      Parameters:
      regionId - The region ID
      min - Minimum XP
      max - Maximum XP
      Returns:
      The actual amount of XP added.

    • removeXp

      public static void removeXp(long regionId, long amount)
      Remove XP from a region (won't decrease level, only progress).
      Parameters:
      regionId - The region ID
      amount - Amount of XP to remove

    • setXp

      public static void setXp(long regionId, long experience)
      Set exact XP amount (triggers level re-calculation).
      Parameters:
      regionId - The region ID
      experience - XP amount

    • setLevel

      public static void setLevel(long regionId, int level)
      Set exact level (resets progress to 0).
      Parameters:
      regionId - The region ID
      level - Level to set

    • grantLevels

      public static void grantLevels(long regionId, int levels)
      Grants multiple levels at once.
      Parameters:
      regionId - The region ID
      levels - Number of levels to add

    • delevel

      public static void delevel(long regionId, int levels)
      Removes levels from a region without going below 0.
      Parameters:
      regionId - The region ID
      levels - Number of levels to remove

    • resetLevel

      public static void resetLevel(long regionId)
      Reset level to 0.
      Parameters:
      regionId - The region ID

    • resetAllLevels

      public static int resetAllLevels()
      Resets every level in the cache. Use with caution.
      Returns:
      The number of levels reset.

    • getTotalXpOfRegion

      public static long getTotalXpOfRegion(long regionId)
      Returns the total accumulated XP (including spent on levels) for a region.
      Parameters:
      regionId - The region ID
      Returns:
      Total XP, or 0 if no level exists.

    • getLevelProgressPercentage

      public static double getLevelProgressPercentage(long regionId)
      Returns the current progress percentage toward the next level.
      Parameters:
      regionId - The region ID
      Returns:
      Progress from 0.0 to 100.0, or 0.0 if no level exists.

    • getXpUntilNextLevel

      public static long getXpUntilNextLevel(long regionId)
      Returns the remaining XP needed to reach the next level.
      Parameters:
      regionId - The region ID
      Returns:
      XP remaining, or 0 if no level exists.

    • getTotalXpForLevel

      public static long getTotalXpForLevel(int targetLevel)
      Returns the XP required to reach a specific level from level 0.
      Parameters:
      targetLevel - The target level
      Returns:
      Total XP required.

    • getLevelDifference

      public static int getLevelDifference(long regionIdA, long regionIdB)
      Calculates the level difference between two regions.
      Parameters:
      regionIdA - First region ID
      regionIdB - Second region ID
      Returns:
      Positive if A > B, negative if A < B, 0 if equal or missing.

    • getAverageLevel

      public static double getAverageLevel()
      Returns the server-wide average region level.
      Returns:
      Average level, or 0.0 if no levels exist.

    • getRegionsAtLevel

      public static List<Long> getRegionsAtLevel(int level)
      Returns all region IDs at exactly the specified level.
      Parameters:
      level - The level to search for
      Returns:
      List of region IDs.

    • getRegionsAboveLevel

      public static List<Long> getRegionsAboveLevel(int minLevel)
      Returns all region IDs above the specified level threshold.
      Parameters:
      minLevel - The minimum level (exclusive)
      Returns:
      List of region IDs.

    • getHighestLevel

      public static Level getHighestLevel()
      Finds the region with the highest level. In case of ties, the one with most XP wins.
      Returns:
      The highest level, or null if no levels exist.

    • getHighestLevelRegion

      public static long getHighestLevelRegion()
      Finds the region ID with the highest level.
      Returns:
      The region ID, or -1 if no levels exist.

    • getLevelDistribution

      public static Map<Integer,Integer> getLevelDistribution()
      Returns a histogram of level distribution.
      Returns:
      Map of level -> count.

    • isMaxLevel

      public static boolean isMaxLevel(long regionId, int maxLevel)
      Checks if a region has reached or exceeded a maximum level cap.
      Parameters:
      regionId - The region ID
      maxLevel - The maximum allowed level
      Returns:
      true if at or above cap.

    • getLevelAge

      public static long getLevelAge(long regionId)
      Returns how many milliseconds ago the level entry was created.
      Parameters:
      regionId - The region ID
      Returns:
      Age in milliseconds, or -1 if not found.

    • getTopLevels

      public static List<Level> getTopLevels(int limit)
      Get top levels sorted by level (desc), then by XP (desc).
      Parameters:
      limit - Maximum results
      Returns:
      Sorted list of top levels.

    • getRank

      public static int getRank(long regionId)
      Get region's rank on leaderboard.
      Parameters:
      regionId - The region ID
      Returns:
      1-based rank, or -1 if not found.

    • cleanupInvalidLevels

      public static int cleanupInvalidLevels()
      Removes all level entries with invalid references:
      - Regions that no longer exist
      Returns:
      Number of corrupted levels removed.