For players

Download the OS Cobblemon Library JAR matching your loader and place it in the normal mods folder when another mod requires it.

Build from source

The Gradle wrapper is committed to the repository.

# Windows
.\gradlew.bat build

# Linux / macOS
./gradlew build

Individual loader builds are also available:

.\gradlew.bat :fabric:build
.\gradlew.bat :neoforge:build

Publish to Maven Local

For local development against another project:

powershell -ExecutionPolicy Bypass -File .\scripts\publish-local.ps1

The script reads the active version from gradle.properties and publishes the common, Fabric and NeoForge artifacts to Maven Local.

Gradle dependency pattern

repositories {
    mavenLocal()
}

val osCobblemonLibraryVersion = "1.5.0"

dependencies {
    compileOnly(
        "com.ourstory:os-cobblemon-library-common:$osCobblemonLibraryVersion"
    )
}

Fabric runtime module:

dependencies {
    modImplementation(
        "com.ourstory:os-cobblemon-library-fabric:$osCobblemonLibraryVersion"
    )
}

NeoForge runtime module:

dependencies {
    modImplementation(
        "com.ourstory:os-cobblemon-library-neoforge:$osCobblemonLibraryVersion"
    )
}

Loader metadata

Consuming mods should also declare OS Cobblemon Library as a required dependency.

// Fabric fabric.mod.json
"depends": {
  "os_cobblemon_library": ">=1.0.0"
}

# NeoForge neoforge.mods.toml
[[dependencies.your_mod_id]]
modId="os_cobblemon_library"
type="required"
versionRange="[1.0.0,)"
ordering="AFTER"
side="BOTH"

Pokémon

PokemonIdentity

Canonical species and form identity, aspects, marks, Alpha compatibility and immutable identity snapshots.

PokemonMatcher

Immutable reusable matcher built on Cobblemon's native PokemonProperties. It also supports Alpha, aspects, marks, labels and native size categories.

PokemonSpeciesResolver

Namespace-aware species lookup. Bare IDs default to the Cobblemon namespace while addon namespaces remain intact.

PokemonCreation

Command-free Pokémon parsing, creation, entity creation and server-level spawning through Cobblemon's native property API.

PokemonData

Namespaced persistent Pokémon data with defensive reads, string or ResourceLocation keys, typed codec access, explicit decode errors and Cobblemon change notification.

PokemonSnapshot and PokemonBalls

Copied Pokémon identity, display and condition values, plus canonical Cobblemon Poké Ball IDs and translated item names.

PokemonIVs

Natural and effective IV inspection, Hyper Training awareness, totals, perfect IV counts and minimum guaranteed perfect natural IVs.

PokemonEVs

EV snapshots and totals over Cobblemon's registered permanent stats, plus source-aware additions through Cobblemon's EV API.

PokemonAbilities

Classifies active abilities as common, hidden, forced or unknown using Cobblemon ability-pool data.

PokemonTypes

Current-form type inspection and matching.

PokemonLabels

Generic access to data-driven Cobblemon form labels without hard-coding category semantics.

PokemonSize

Native size category helpers, translation keys and safe positive scale values for Pokémon and Pokémon entities.

Entities

PokemonEntities

Read-only bridge helpers for Pokémon access, UUID identity, ownership, battle state, busy/evolution state, presence checks and matcher integration. nearestPlayerDistanceSquared caches the nearest player's squared distance per entity for the current server tick; call it on the server thread. It returns Double.MAX_VALUE outside a server level or when there are no players in that level.

Fabric and NeoForge clear the cache automatically when the server stops. Custom lifecycle integrations can call clearNearestPlayerDistanceCache() directly.

Storage

PokemonStorage

Server Party and PC access, UUID lookup, membership queries, predicate counts and slot-preserving value snapshots.

ClientPokemonStorage

Client-only party lookup and snapshots, including immutable values that retain empty slots and slot indexes.

Events

CobblemonEventHooks

Java-friendly subscriptions for repeated Cobblemon event use cases including capture, evolution eligibility and completion, battle completion, held and cosmetic item swaps, sending, recalling, healing, fainting, spawning, persistence, Pokédex updates, hatching, fossil revival, trade, release, nickname, level-up and experience changes.

EventSubscriptionGroup

Tracks multiple subscriptions and unsubscribes them together for reloadable or optional systems.

Battles

BattleInspector

Read-only helpers for wild, trainer and PvP classification, actor filtering, player UUIDs, Pokémon extraction, faint events, victory participants and battle-end winners/losers.

BattleKind

High-level classification: WILD, TRAINER, PVP or OTHER.

BattleWeatherInitializer, BattleWeatherController and AmbientBattleWeather

Version-gated initial field weather before player entry and startup abilities, plus queued world-weather updates during an active battle. Move- or ability-controlled weather takes priority. The bridge is verified for Cobblemon 1.8.2+1.21.1 and 1.8.3+1.21.1; a queued request does not confirm that the simulator applied it.

Pokédex

PokedexQueries

Read-only helpers for seen/caught species, forms, aspects, shiny knowledge, counts and completion percentages.

ClientPokedexQueries and PokedexSnapshot

Read-only client Pokédex access and immutable snapshots of synchronized species, aspects, forms and shiny states.

Resolve species IDs

Species species =
        PokemonSpeciesResolver.require(configuredSpecies);

Bare IDs default to the Cobblemon namespace while explicit addon namespaces are preserved.

Spawn without commands

PokemonCreation.spawnSpecies(
        level,
        position,
        configuredSpecies,
        rolledLevel,
        shiny
);

Complex properties can be passed directly:

PokemonCreation.spawn(
        level,
        position,
        "species=pikachu level=25 shiny=true"
);

Build a reusable matcher

PokemonMatcher matcher = PokemonMatcher
        .fromProperties("type=fire level=50")
        .alpha(false)
        .anyLabel(List.of("legendary", "mythical"));

Query player-owned Pokémon

Optional<Pokemon> first =
        PokemonStorage.findFirstOwned(player, matcher);

List<Pokemon> all =
        PokemonStorage.findAllOwned(player, matcher);

int count =
        PokemonStorage.countOwned(player, matcher);

Check Pokémon proximity

double distanceSquared =
        PokemonEntities.nearestPlayerDistanceSquared(entity);
boolean withinRadius = distanceSquared <= radius * radius;

Call this on the server thread. The distance is cached for the current server tick, and a level with no players returns Double.MAX_VALUE.

Persistent Pokémon data

PokemonData.update(pokemon, "examplemod:quest_state", data -> {
    data.putBoolean("completed", true);
    data.putInt("attempts", data.getInt("attempts") + 1);
});

boolean completed = PokemonData.read(pokemon, "examplemod:quest_state")
        .map(data -> data.getBoolean("completed"))
        .orElse(false);

Type-based compatibility

boolean compatible = PokemonTypes.hasAnyType(
        pokemon,
        List.of("grass", "bug", "flying")
);

Lifecycle-safe event subscriptions

EventSubscriptionGroup subscriptions =
        new EventSubscriptionGroup();

subscriptions.track(
        CobblemonEventHooks.onCapture(this::handleCapture)
);

subscriptions.track(
        CobblemonEventHooks.onBattleVictory(this::handleVictory)
);

// Feature shutdown or reload:
subscriptions.close();

Handle all battle endings

CobblemonEventHooks.onBattleEnded(event -> {
    if (event.getResult() == BattleEndResult.CAPTURE) {
        Set<UUID> winners = BattleInspector.winningPlayerIds(event);
        // Handle a battle that ended with a capture.
    }
});

Observe Pokémon item swaps

CobblemonEventHooks.onHeldItemPre(event -> {
    if (shouldBlock(event.getPokemon(), event.getReceiving())) {
        event.cancel();
    }
});

CobblemonEventHooks.onCosmeticItemPost(event -> {
    recordCosmeticSwap(event.getPokemon(), event.getReceived(), event.getReturned());
});

Battle progression

Pokemon defeated =
        BattleInspector.faintedPokemon(event);

if (BattleInspector.isWild(event.getBattle())) {
    // Wild battle progression.
}

boolean won =
        BattleInspector.didPlayerWin(event, player.getUUID());

Queue ambient battle weather

if (BattleWeatherController.isAvailable()) {
    BattleWeatherController.queueAmbientWeather(
            battle,
            AmbientBattleWeather.RAIN);
}

Queue the latest world-weather snapshot again after move- or ability-controlled weather clears. Use AmbientBattleWeather.CLEAR when the world contributes no ambient battle weather.

Pokédex-aware behavior

if (PokedexQueries.hasSeen(player, pokemon)) {
    // Species has been encountered.
}

if (PokedexQueries.hasCaughtForm(player, pokemon)) {
    // Current form has been caught.
}

Current compatibility line

In scope

• Pokémon identity and reusable property access.
• Species, forms, aspects, marks, types and size data.
• Read-only Pokémon entity bridge helpers, including cached nearest-player distance queries.
• Party and PC access and lookups.
• Cobblemon event integration.
• Battle inspection, classification and version-gated initial and active-weather integration.
• Pokédex queries.
• Small adapters that isolate meaningful Cobblemon API changes.

Out of scope

• Gameplay rules or progression systems specific to one mod.
• Custom balancing formulas.
• Mod-specific user interfaces or spawning systems.
• Entity AI, movement, navigation or despawn systems.
• Leaderboards and scoring systems.
• Generic networking, permission, registry or configuration frameworks.

API stability

OS Cobblemon Library follows semantic versioning for its documented public API.

Internal API

com.ourstory.oscobblemon.internal

This package is not supported for consuming mods and may change without notice.

License

Redistribution, modified builds, rebranding and source-code reuse of the Library itself require separate permission from LevelsFR.

1.5.0 - Cobblemon API and lifecycle improvements (2026-10-27)

Added

• A Java hook for Cobblemon evolution eligibility checks.
• Registered-stat EV snapshots, totals and source-aware additions.
• ResourceLocation key overloads for persistent Pokémon data.
• Automatic nearest-player cache cleanup when Fabric or NeoForge servers stop.

1.4.1 - 2026-10-27

Changed

• Extended the initial and active battle-weather bridge to Cobblemon 1.8.3 while retaining Cobblemon 1.8.2 support.
• Requires NeoForge 21.1.195 or newer.

1.4.0 - 2026-10-25

Added

• PokemonEntities.nearestPlayerDistanceSquared, a server-thread query cached per Pokémon entity for the current server tick.
• BattleWeatherController.queueAmbientWeather and AmbientBattleWeather for version-gated ambient weather updates during Cobblemon 1.8.2 battles.
• Ambient weather updates are written through the normal Showdown battle stream and yield to weather controlled by moves or abilities.
• Initial ambient field weather is tracked separately so world-weather changes can update or clear it.

Compatibility

• At the 1.4.0 release, the battle-weather bridge was verified only for Cobblemon 1.8.2+1.21.1; 1.4.1 extends support to 1.8.3.

1.3.1 - Release candidate (2026-10-17)

Added

• A public pre-battle weather initializer for Cobblemon 1.8.2.
• A version-gated Showdown bridge that applies the baseline before player entry and startup abilities.

1.3.0 - 2026-10-11

Added

• Compatibility with Cobblemon 1.8.2.
• A battle-ended hook for victories, captures, forfeits, fleeing and stopped battles.
• Battle winner/loser inspection for completed battles.
• A fossil revival hook.
• Pre/post hooks for Pokémon held-item and cosmetic-item swaps.

1.2.0 - 2026-10-08

Added

• Client-side Pokédex snapshots and client party lookup.
• Immutable Pokémon display and condition snapshots, slot-preserving party snapshots, and Cobblemon Poké Ball ID/name helpers.
• Server Party/PC store-change subscriptions.
• Codec-backed persistent Pokémon data reads with defaults and explicit decode errors.

1.1.0 - 2026-09-18

Added

• Persistent Pokémon data for storing custom mod data safely.
• Reusable Cobblemon event hooks for captures, evolutions, battles, gimmicks, healing, fainting, sending, recalling, spawning and Pokédex updates.

1.0.1 - 2026-09-17

Added

• Official OS Cobblemon Library logo in Fabric and NeoForge mod listings.

Changed

• Updated the public mod description to better reflect the API and compatibility role.
• Normalized in-game metadata text and resource processing to avoid accented-character encoding issues on Windows builds.
• Clarified the proprietary license so third-party mods may use the documented public API without source-disclosure requirements while the Library itself remains protected.

1.0.0 - 2026-09-16

Added

• Multi-loader Fabric and NeoForge project structure.
• Pokémon identity, matching, species resolution and command-free creation helpers.
• IV, ability, type and data-driven label helpers.
• Native Pokémon size-category, translation-key and safe scale helpers.
• Read-only PokemonEntity bridge helpers for Pokémon access, ownership and Cobblemon entity state.
• Party and PC storage queries, matching and counts.
• Cobblemon event subscription and lifecycle helpers.
• Battle classification and event inspection helpers.
• Pokédex species, form, variation and completion queries.
• Local Maven development publishing.
• Public integration, API stability and release documentation.

Changed

• Runtime metadata explicitly targets Minecraft 1.21.1 and Cobblemon 1.8.x.
• CI builds and Maven publication use the committed Gradle wrapper.
• Architectury build plugins are pinned to reproducible versions.
• Public API boundaries are documented and internal packages are excluded from the supported API.