Developer API

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

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(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);
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(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);

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

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(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 (mining, farming, smithing, archery, fishing, alchemy), returns true only if their level is 1 or higher.
getTornPagesBalance(Player player)
Returns: int
What it does: Returns the current number of Torn Pages the player has in their balance.
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(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}).

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 (SyncJournalDataPayload) to the client.
Automatically shares a portion of the XP with nearby party members.
Example: PlayerJournalAPI.grantCustomXp(serverPlayer, "alchemy", 50.0f);

Used internally by server event listeners (JournalServerEvents) to read what other mods have registered:

getCustomUsage(String itemId) $\rightarrow$ Returns the map of code-registered usage restrictions for that item ID.
getCustomCrafting(String itemId) $\rightarrow$ Returns the map of code-registered crafting requirements for that item ID.
getCustomCraftingXp(String itemId) $\rightarrow$ Returns the float XP reward for crafting that item.
getCustomBlockUsage(String blockId) $\rightarrow$ Returns the map of code-registered block requirements for that block ID.
getCustomBlockXp(String blockId) $\rightarrow$ Returns the float XP reward for breaking/harvesting that block.