Package org.ppvon.ultimateCobblemonProgression.api

Class UCPApi

java.lang.Object
org.ppvon.ultimateCobblemonProgression.api.UCPApi
public final class UCPApi extends Object
The public API surface for the Ultimate Cobblemon Progression (UCP) mod.

This class exposes stable, safe methods that other mods can use to:

  • Read or modify a player's trainer level
  • Access tier and level cap data
  • Inspect which Pokémon species belong to each tier
All methods are static and can be safely called from either client or server context, provided the trainer component is synchronized via CCA.
Since:
1.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    apiVersion()
    Returns the version tag for the UCP public API.
    static List<TierDefinition>
    getAllTiers()
    Retrieves all tier definitions in ascending order.
    static int
    getLevelCapForTier(int tier)
    Gets the level cap associated with a specific trainer tier.
    static int
    getMaxTier()
    Returns the maximum configured trainer tier.
    static int
    getMinTierFor(@NotNull net.minecraft.resources.ResourceLocation speciesId)
    Determines the minimum trainer tier required for a given Pokémon species.
    static Optional<TierDefinition>
    getTier(int index)
    Retrieves a single tier definition by index.
    static int
    getTier(com.cobblemon.mod.common.pokemon.Species sp)
    Returns the trainer tier value assigned to the given Cobblemon Species.
    static int
    getTrainerLevel(@NotNull net.minecraft.world.entity.player.Player player)
    Gets the current trainer level of the specified player.
    static void
    setTier(com.cobblemon.mod.common.pokemon.Species sp, int tier)
    Sets the trainer tier value on the given Cobblemon Species.
    static void
    trainerLevelUp(@NotNull net.minecraft.world.entity.player.Player player)
    Increases a player's trainer level by one.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • getTrainerLevel

      public static int getTrainerLevel(@NotNull @NotNull net.minecraft.world.entity.player.Player player)
      Gets the current trainer level of the specified player.

      This represents the player's progression tier. The value increases as the player unlocks higher tiers of Pokémon and corresponding level caps.

      Parameters:
      player - the player whose trainer level should be retrieved
      Returns:
      the current trainer level of the player (e.g., 1–7)
      Since:
      1.0.0

    • trainerLevelUp

      public static void trainerLevelUp(@NotNull @NotNull net.minecraft.world.entity.player.Player player)
      Increases a player's trainer level by one.

      This method is equivalent to leveling up the trainer, unlocking the next Pokémon tier and raising their level cap. It does not perform validation, so calling mods should ensure the player is eligible to advance.

      Parameters:
      player - the player whose trainer level will be incremented
      Since:
      1.0.0

    • getMaxTier

      public static int getMaxTier()
      Returns the maximum configured trainer tier.

      This value represents the highest available tier index in the tier registry (for example, 7 if there are seven progression tiers defined).

      Returns:
      the highest configured tier index
      Since:
      1.0.0

    • getLevelCapForTier

      public static int getLevelCapForTier(int tier)
      Gets the level cap associated with a specific trainer tier.

      For example, if tier 1 Pokémon are capped at level 15, calling getLevelCapForTier(1) will return 15.

      Parameters:
      tier - the tier index (1-based)
      Returns:
      the level cap value for the given tier
      Throws:
      NullPointerException - if the requested tier does not exist in the registry
      Since:
      1.0.0

    • getMinTierFor

      public static int getMinTierFor(@NotNull @NotNull net.minecraft.resources.ResourceLocation speciesId)
      Determines the minimum trainer tier required for a given Pokémon species.

      This can be used to gate spawning, capturing, or battling logic based on the player's current progression tier.

      Parameters:
      speciesId - the ResourceLocation identifier for a Pokémon species
      Returns:
      the minimum tier that species belongs to, or Integer.MAX_VALUE if unknown
      Since:
      1.0.0

    • getTier

      public static Optional<TierDefinition> getTier(int index)
      Retrieves a single tier definition by index.

      The returned TierDefinition contains the tier index, its level cap, and the full set of Pokémon species belonging to that tier.

      Parameters:
      index - the 1-based tier index to retrieve
      Returns:
      an Optional containing the tier definition if found, or an empty optional otherwise
      Since:
      1.0.0

    • getAllTiers

      public static List<TierDefinition> getAllTiers()
      Retrieves all tier definitions in ascending order.

      This includes all defined tiers from 1 through getMaxTier(), skipping any missing tiers. The returned list is immutable.

      Returns:
      an unmodifiable list of all defined TierDefinitions
      Since:
      1.0.0

    • apiVersion

      @AvailableSince("1.0.0") public static String apiVersion()
      Returns the version tag for the UCP public API.

      This version reflects the API surface only. It may differ from the mod's runtime version. Increment this when breaking changes are introduced to the API methods or signatures.

      Returns:
      the API version string (e.g., "1.0.0")
      Since:
      1.0.0

    • getTier

      public static int getTier(com.cobblemon.mod.common.pokemon.Species sp)
      Returns the trainer tier value assigned to the given Cobblemon Species.

      This value is stored in a runtime-only field injected into Species via the SpeciesTierMixin. It is not part of Cobblemon's base data or CODECs.

      When no tier has been applied, -1 is returned.

      Parameters:
      sp - the species instance
      Returns:
      the numeric tier for this species, or -1 if none
      Since:
      1.2.0

    • setTier

      public static void setTier(com.cobblemon.mod.common.pokemon.Species sp, int tier)
      Sets the trainer tier value on the given Cobblemon Species.

      This method assigns the in-memory tier field added by the SpeciesTierMixin. It should only be called on the server thread after datapack reloads (e.g. from TierSpeciesApplier.applyFromRegistry()).

      The cast through Object is required because the UltimateCobblemonProgressionTierExt interface is applied at runtime by Mixin and is not visible to the Java compiler.

      Parameters:
      sp - the species instance to modify
      tier - the numeric tier to assign, or -1 to clear
      Since:
      1.2.0