Overview

BestiaryJS is a small, dependency-free Java helper shipped with Araxer's Bestiary that exposes read-only player progression data to KubeJS scripts. You can load and call it from kubejs/server_scripts without installing any extra addons.

• Class: com.araxer.araxers_bestiary.integration.kubejs.BestiaryJS
• Load in KubeJS: const BestiaryJS = Java.loadClass('com.araxer.araxers_bestiary.integration.kubejs.BestiaryJS');
• Minecraft: 1.20.1
• KubeJS: v6 (Forge)
• No KubeJS addon dependency is required.

Rank code mapping

• No Rank (empty string "") → 0
• E → 1
• D → 2
• C → 3
• B → 4
• A → 5
• S → 6
• X → 7

Notes about inputs and defaults

• player parameter: All methods accept either a ServerPlayer (from events) or a string identifying the player (exact name or UUID). For convenience in scripts, pass event.player.username or event.player.uuid.
• entityId: A string resource location like minecraft:zombie or modid:my_mob.
• If inputs are invalid or the player/entity can’t be resolved, methods return safe defaults:
  • rankCode → 0
  • meets → false
  • rank/rankName → "" (No Rank)
  • isObserved/isDiscovered → false
• Threshold validation: meets(...) requires a letter in E, D, C, B, A, S, X. The empty rank "" never meets any threshold.
• Internals: BestiaryJS queries a Forge capability (IBestiaryProgress) attached to players; if not available, it falls back to the global progression store. There is no data duplication.

API reference

Each method has two overloads: one that takes a ServerPlayer and one that takes a player identifier (name or UUID as String). Signatures are shown in KubeJS-friendly terms below.

1. rankCode(player, entityId) → int

• Overloads:
  • rankCode(ServerPlayer player, String entityId)
  • rankCode(String playerNameOrUuid, String entityId)
• Returns the numeric rank code 0..7 using the mapping above.
• Defaults to 0 for unknown player/entity or if the rank is empty.

2. rank(player, entityId) → string

• Overloads:
  • rank(ServerPlayer player, String entityId)
  • rank(String playerNameOrUuid, String entityId)
• Returns the letter rank: "" | E | D | C | B | A | S | X.
• "" means No Rank (undiscovered).

3. rankName(player, entityId) → string

• Overloads:
  • rankName(ServerPlayer player, String entityId)
  • rankName(String playerNameOrUuid, String entityId)
• Alias of rank(...). Provided for compatibility with some examples.

4. meets(player, entityId, threshold) → boolean

• Overloads:
  • meets(ServerPlayer player, String entityId, String threshold)
  • meets(String playerNameOrUuid, String entityId, String threshold)
• Returns true if the player’s rank for the entity meets or exceeds threshold.
• threshold must be one of: E, D, C, B, A, S, X. "" never meets.

5. isObserved(player, entityId) → boolean

• Overloads:
  • isObserved(ServerPlayer player, String entityId)
  • isObserved(String playerNameOrUuid, String entityId)
• Returns true if the entity is marked as observed (e.g., spyglass) for that player.

6. isDiscovered(player, entityId) → boolean

• Overloads:
  • isDiscovered(ServerPlayer player, String entityId)
  • isDiscovered(String playerNameOrUuid, String entityId)
• Returns true if the entity is marked as newly discovered for that player. Note: this flag can clear after viewing even if the player still has a non-empty rank.

KubeJS usage examples (v6, MC 1.20.1)

Load and use in server scripts

// kubejs/server_scripts/bestiary_examples.js
const BestiaryJS = Java.loadClass('com.araxer.araxers_bestiary.integration.kubejs.BestiaryJS');

PlayerEvents.loggedIn(event => {
  const p = event.player;
  // Numeric rank code for zombie
  const code = BestiaryJS.rankCode(p.username, 'minecraft:zombie'); // 0..7
  p.tell('Your zombie rank code: ' + code);

  // Check for S on blaze
  if (BestiaryJS.meets(p.username, 'minecraft:blaze', 'S')) {
    p.tell('You have S on blaze!');
  }

  // Letter rank and flags
  const r = BestiaryJS.rank(p.username, 'minecraft:warden'); // '', E..X
  const seen = BestiaryJS.isObserved(p.username, 'minecraft:warden');
  const disc = BestiaryJS.isDiscovered(p.username, 'minecraft:warden');
  p.tell(`Warden rank: ${r}, observed: ${seen}, discovered: ${disc}`);
});

React to rank changes (no ForgeEvents global required)

Use the KubeJS-friendly helper on the event class to subscribe directly to the Forge bus.

const RankEvent = Java.loadClass('com.araxer.araxers_bestiary.api.BestiaryRankChangedEvent');

RankEvent.rankChanged(event => {
  // Helper getters: getEntityId(), getPlayerName(), getPlayerUUID(), getOldRankCode(), getNewRankCode()
  if (event.getEntityId() === 'minecraft:zombie' && event.getNewRank() === 'S') {
    event.getPlayer().tell('You reached S on zombie!');
  }
});

Tips and behavior details

• Player identifier: When using the String overloads, BestiaryJS tries UUID first, then exact name. If the player is offline, methods will return safe defaults.
• Performance: Methods are lightweight. For bulk checks across many entities per tick, consider caching or event-driven updates.
• Validation: meets(...) silently returns false for invalid thresholds; check your input when debugging.
• Interop: These helpers mirror the underlying capability API (IBestiaryProgress). Java mods can use that capability directly without KubeJS.

Related docs

• Quests and KubeJS Integration: integration:quests-and-kubejs
• FTB Quests Integration (No Advancements): integration:ftb-quests
• Rank utilities (Java): src/main/java/com/araxer/araxers_bestiary/data/RankUtils.java