Developer API

Player Journal features an API which developers can use to interact with the mod.

Table of Contents

• 1. Registration Methods (Code-Based Restrictions)
• 2. Player Query & Check Methods
• 3. Progression & XP Methods

---

1. Registration Methods (Code-Based Restrictions)

Use these in your addon's common setup or mod initialization to restrict items, crafting, and blocks via pure Java code.

registerUsageRestriction

Syntax: registerUsageRestriction(String itemId, String skill, int requiredLevel)

• What it does: Locks the right-click / equip / use action of an item behind a required skill level.
• Example: PlayerJournalAPI.registerUsageRestriction("mymod:fire_wand", "alchemy", 10);

registerInteractRestriction

Syntax: registerInteractRestriction(String itemId, String skill, int requiredLevel)

• What it does: Locks specific right-click interactions with an item unless the player meets the required skill level.
• Example: PlayerJournalAPI.registerInteractRestriction("mymod:magic_staff", "alchemy", 15);

registerCraftingRestriction

Syntax: registerCraftingRestriction(String itemId, String skill, int requiredLevel, float xpReward)

• What it does: Locks crafting in a table or smelting in a furnace behind a skill level, and optionally rewards skill XP when crafted.
• Example: PlayerJournalAPI.registerCraftingRestriction("mymod:steel_ingot", "smithing", 5, 20.0f);

registerBlockRestriction

Syntax: registerBlockRestriction(String blockId, String skill, int requiredLevel, float xpReward)

• What it does: Locks block breaking / crop harvesting behind a skill level and rewards skill XP when broken/harvested.
• Example: PlayerJournalAPI.registerBlockRestriction("mymod:magic_crop", "farming", 8, 15.0f);

---

2. Player Query & Check Methods

Use these to inspect a player’s current level, unlocked classes, or check if they can perform actions.

getPlayerLevel

Syntax: getPlayerLevel(Player player, String skillName)

• Returns: int
• What it does: Returns the player's level (0–100) for any given skill ("mining", "combat", "vitality", etc.). Returns 0 if invalid or on the client side.

hasUnlockedPage

Syntax: hasUnlockedPage(Player player, String skillName)

• Returns: boolean
• What it does: Checks if the player has unlocked that chapter/class. Always returns true for base skills (vitality, agility, combat, defense). For specialized skills, returns true only if their level is 1 or higher.

getTornPagesBalance

Syntax: getTornPagesBalance(Player player)

• Returns: int
• What it does: Returns the current number of Torn Pages the player has in their balance.

canPlayerUseItem

Syntax: canPlayerUseItem(ServerPlayer player, String itemId)

• Returns: boolean
• What it does: The ultimate check method. Checks the Java API injections first, then Datapacks, then the TOML config. Returns true if the player meets all skill requirements (or if in Creative/Spectator mode), and false if restricted.

getItemUsageRestrictions

Syntax: getItemUsageRestrictions(String itemId)

• Returns: Map<String, Integer>
• What it does: Returns the raw map of skill requirements defined for an item inside the JSON datapacks (e.g., {"alchemy": 5, "combat": 2}).

---

3. Progression & XP Methods

grantCustomXp

Syntax: grantCustomXp(ServerPlayer player, String skillName, float amount)

• What it does: Grants raw XP to a player for a specific skill.
• Features built-in:
  • Automatically applies the player's active XP multiplier buff.
  • Only grants XP if the player has unlocked that skill chapter.
  • Handles level-up calculations and stat recalculation.
  • Automatically syncs the updated data packet to the client.
  • Automatically shares a portion of the XP with nearby party members.
• Example: PlayerJournalAPI.grantCustomXp(serverPlayer, "alchemy", 50.0f);