Scuffed Professions

Install, staff-command, permission, configuration, storage and recovery reference for server operators. For how the professions play (XP, skill trees, capstones, boosts and rewards) see the Scuffed Professions gameplay guide.

• Plugin version: 0.25.80-pre.8 (plugin name ScuffedProfessions)

Requirements

The plugin refuses to load without LuckPerms. It ships its own asset pack (blocks, items, models, UI pages and language files) inside the jar.

Tamework (Alec's Animal Husbandry), the Condensed Crops pack, PlaceholderAPI and an economy plugin are detected at runtime and are not in the manifest. Without them the matching features are simply unavailable (see Integrations).

First boot writes every default file under mods/ScuffedProfessions/. Existing files are never overwritten by a restart, so hand edits survive.

Admin & Staff Commands

All commands live under /professions (alias /prof). The command tree is opened to normal players so the player pages work, and every admin command checks in code for operator status or the scuffedprofessions.admin permission (see Permissions). From the console the admin commands are allowed and each use writes an [SP][AUDIT] line to the log.

General

Player XP and progression

Capstones

Boosts

The same four commands list, start, stop and grant also work as /professions boost <subcommand>, from the console too.

Backups, recovery and balance tools

Player-run staff commands

These three run in game only (they need a player sender) and check for admin access:

Test tools

The /professions test subcommands change only your own character: /professions test <profession> <level> and /professions test level <profession> <level> set your XP to that profession level (1 to 100, capped by curve.cap), /professions test threshold <profession> <level> sets your XP one point below that level (level 2 up), and /professions test kit delivers a cooking test kit (tools, ingredients and recipe scrolls). Bare /professions test prints this usage. They grant no level-up rewards. They work only when testing.commands is true in config.json (default false) and the sender is an admin or holds scuffedprofessions.test. Keep them off on live servers.

Permissions

Nodes are declared in code. The plugin writes no permission block to a manifest.

Notes:

• Wildcard and negated nodes (scuffedprofessions.*, -scuffedprofessions.admin) are read the way the engine reads them.
• A provider failure reads as "no access", never as access.
• The /professions, /professions leaderboard, /professions boost, /professions attune and /alchemy commands need no node. The first four are opened to the hytale:Adventurer group.
• Titles: master titles use the node endlesslink.title.master_<profession>, granted through LuckPerms when the player reaches 100.
• Shop unlocks: Building level rewards write LuckPerms nodes named shop.unlock.<set> (see Building shop unlocks). The plugin only ever removes nodes it granted itself.
• Boost templates can carry their own permission node for in-game purchase.

Configuration

All files are under mods/ScuffedProfessions/. Admin View exposes the common values in the normal professions menu, edits go into a draft and apply on Apply, stale drafts are refused, and dated backups keep older revisions. Hand edits need /professions reload. Provider and startup settings may need a restart.

Migrations back up the previous file next to it (for example config.json.pre-antifarm-guards.bak, *.pre-base-xp-v<version>.bak). Earned XP, levels, choices, claims and running boosts are never rewritten by a migration. Keep rewards.preserveOnMigrate on if you plan to merge changed reward defaults by hand.

Core settings (config.json)

Default xpMultiplier per profession: Mining 4, Woodcutting 0.6, Excavation 10.5, Farming 0.33, Fishing 10, Building 15, Smithing 0.65, Alchemy 3, Cooking 54, Husbandry 150, Exploration 2, Acrobatics 10. Values accept any finite number from 0 up; there is no upper clamp, and 0 pays nothing. A gain under one point is kept and added to the player's next gain. The shipped XP tables use MMOSkillTree 1.6.0 values as their base, with ore, wood and crop tiers scaled by this mod.

Profession-specific settings

Exploration

Fate Zone clears take their rank from the run's level band when EndlessFates exposes it: E below level 25, C below 60, A from 60. The limits are exploration.content.earlyLevelLimit (25) and exploration.content.lateLevelStart (60). A claim that spends a Fate charge pays the action row fate_complete_<rank> (shipped 750, 1,500, 3,000 for E, C, A), a claim with no charge or XP only pays fate_assist_<rank> (125, 250, 500), and the first clear of a rank pays fate_first_<rank> instead (4,500, 9,000, 18,000). These rows live in xp/EXPLORATION.json and are raw XP before the multiplier. To add landmarks, edit exploration-places.json. Each places entry has world, a permanent id, nameKey, tier (E to S), and min and max arrays of three coordinates. Keep ids stable when changing bounds. Earned-chest, clear and quest reward queues are stored under exploration-pending. Keep them in server backups.

Anti-farm guards (antifarm)

Several guards are kept in memory only: they survive a relog but not a restart.

Default perMinute tripwire limits are 40,000 for COOKING:dish, FISHING:catch, HUSBANDRY:feed, HUSBANDRY:harvest, HUSBANDRY:breeding, HUSBANDRY:combat, ACROBATICS:fall, SMITHING:vaporiser and FARMING:harvest, and 120,000 for SMITHING:craft. A trip pays up to the limit, pays nothing beyond it and logs one WARN line naming the player. Furnace and other processing payouts and first-time awards are never counted.

XP evidence and balancing

Each server logs its own XP payouts by player, profession and method (break:Ore_..., craft:..., area:, collapse:, fall:) for 14 UTC days in xp_evidence.json. /professions admin evidence turns that into suggested table or multiplier changes and writes reports/xp-evidence.txt and .csv (rewritten every hour). The suggestions are Cut (a method would take players to 100 faster than the floor), Lower or Raise (typical pace outside the target range), Review and Collect (not enough players yet).

After changing a table row or pace budget, run /professions admin evidence reset [--profession <skill>] twice within 10 seconds so old play does not blend in. A multiplier change needs no reset.

First finds (firsts)

Provider catalogs refresh within 30 seconds after startup and on reload. Only current eligible finds count toward the displayed percentage.

Storage settings

Boosts and store setup

A boost is never personal. Whoever buys it, every player gets the extra XP and the buyer is credited on the HUD badge and in the announcement.

Store commands for a purchase (run as an offline command; the buyer need not be online):

professions boost grant all_60 {username} --txn {transaction}
professions boost grant profession_60 {username} cooking --txn {transaction}

• Always pass --txn. It is the replay guard: the same transaction id delivers one purchase across servers, and a retry on another server is refused. A --txn value that still contains { or } is ignored with an [SP][AUDIT] ... UNUSABLE --txn id line and the boost starts without protection.
• Purchases multiply the running rate and add their time: at 1.15x with 30 minutes left, another purchase gives 1.3225x for 90 minutes. The fifth purchase reaches the 2x cap and further purchases only add time.
• Renewing within ten minutes of expiry multiplies the previous rate and starts a fresh hour. The gap pays normal XP.
• If the shared backend is down, a paid purchase waits in boost_queue.json and starts on every server with its full time once the table answers. An unreadable queue is kept as boost_queue.json.unreadable-<time> with a SEVERE log line.
• Each server records used transaction ids in boost_txns.txt too, so a replay during an outage is still refused.
• Reply lines start with Started #<id>, Already started, Recorded (saved, starts when the table answers, do not refund), WARNING: --txn id ignored or FAILED: .... After fixing a FAILED package, run the corrected command by hand with the same --txn value.
• Stopping a boost does not refund money. Upgrade every participating server together; an older jar does not understand cumulative totals.

Content packs

A pack adds to the profession tables without editing the files in mods/ScuffedProfessions/. Another mod can ship a pack inside its jar, or you can drop loose files in. Packs are read at boot and on every reload, and the log lists the files used and any problems.

• Inside any .jar or .zip in mods/, at Server/ScuffedProfessions/<Kind>/<name>.json.
• Loose, at mods/ScuffedProfessions/packs/<pack>/<Kind>/<name>.json.

<Kind> is XpMaps, Rewards, Drops or Vaporiser. Packs apply after your own files: jars and zips in file-name order, then loose packs in folder-name order. Every file may set "mode": add (default, merges key by key, pack wins on a clash, lists are added to) or replace (discards that section of your file and uses the pack's).

Reward row notes:

• "repeatable": true fires the row again on every climb after Transcend (blessings repeat by default).
• "scope" on a command, title or blessing row is network (paid once for the whole network on the server where the player levelled) or server (paid on each server). Commands and blessings default to per-server, titles to network. Items are always per server. Any other word is an error.
• Command rows replace {player}, {user} or %player% with the player's name.
• "retroactive": true grants a newly introduced row to players who passed the threshold earlier.

ScuffedProfessions ships a few packs of its own (Alchemy reagents and herbs in rare finds, level 90 finds, reagent drops, Alchemy refining XP, and two Drops packs). A pack of yours with "mode": "replace" overrides them.

Building shop unlocks

At certain Building levels a player earns a LuckPerms node shop.unlock.<set>. Nothing is locked until your shop listings ask for the node.

Nodes are checked on join, on level-up and when an admin changes a level, and an XP reset or lowered level removes the nodes the new level no longer covers. Transcending Building keeps every set. LuckPerms is shared across a network, so servers sharing a LuckPerms database share the unlocks. You can hand a node out yourself (/lp user <name> permission set shop.unlock.temple_masonry true) and the plugin will not remove it. To change the sets, edit the unlock rows in rewards/building.json (id becomes the node name, where is the line shown in the tree, "enabled": false removes it for everyone on their next check) and reload. An unlock row can be added to any tier of any profession.

Gates (gates.json)

Level gates are enforced only while gates.enabled is true (or skills.<SKILL>.gatesEnabled for one profession). The shipped file gates the four high-tier metals, by ore for Mining and by bar for Smithing: Mithril at level 40, Adamantite at 55, Thorium at 70 and Onyxium at 85. Shape:

"MINING": [ { "level": 40, "ids": ["Ore_Mithril"], "message": "gate.mining.mithril" } ]

ids match by prefix (the broken block id for Mining, Woodcutting, Excavation and Farming, the placed block id for Building, the recipe id for Smithing and Alchemy). The highest matching level wins. A refused action is cancelled with a short message.

Capstones and recovery

capstones.json holds attuneFee and remakePrice per profession (25,000 each by default), announceDraw (true), and two power blocks:

An S roll opens an A gate instead while an S gate or S-Gate event is already running. Each use is once per UTC day per server copy. On a server with no economy, attuning and remaking are free. capstone_world.json holds heartwood.regrowHours (6) and trinketsmith.cooldownDays (7), plus the trinket recipe list.

Capstone state is stored in capstone_ledger.json, capstone_placements.json, capstone_trades.json, capstone_stumps.json and related files, or in the shared backend when one is active. Do not delete player, purchase, artifact, capstone or delivery records to change balance.

Recovery workflow for a capstone loss, mistaken sale or wrong holder:

1. /professions admin capstonehistory <profession> <number> to read the custody history.
2. /professions admin capstonerepair <profession> <number> <recipient|revoke> "reason" for a preview and token.
3. /professions admin capstoneconfirm <token> within 60 seconds as the same admin. A changed ownership invalidates the preview, older copies on this server become void (a placed copy too, so inspect terrain), and a replacement waits durably for the recipient to join.
4. Use another recorded repair to compensate for a mistaken repair.

Other recovery tools:

• admin diagnose and admin reconcile for stuck deliveries, admin xp ... get/set/add for wrong XP, admin perk and admin claims reset for tree repair.
• admin boost stop and admin boost resolveorder for wrong or uncertain boosts.
• /professions artifact for relics and revival incense, /professions admin vaporisation for A/S Vaporiser destructions, /professions rejuvinator for an interrupted station purchase.
• Cooking pots, forge sessions, economy receipts, remote terrain and provider-owned animal records need their own evidence. The tools do not invent a lost item, clear an unresolved payment or reset a cooldown based on a player's report alone.

Data & storage

• Player progression (XP, levels, tree choices, Transcend flags, collections, boosts and capstones) is stored in the Endless Leveling shared backend when it is active, so servers on the same storage.namespace share levels, though not items or money. Otherwise it is stored locally in professions.db under the data folder. A server that previously used shared storage waits for it to return instead of starting a separate local count.
• Reset credits live in the entity namespace scuffedprofessions-tree-resets on shared storage, or in tree-resets locally. Switching from local reset wallets to shared storage is blocked until those wallets are migrated; there is no automatic merge. Keep profile and wallet backups together.
• Server-local state files include rejuvinator_claims.json, furnace_owners.json, forge_benches.json, vaporisation-history.json, purse_payments.json, coin_pouches.json, tablet_readings.json, boost_queue.json, boost_txns.txt, exploration-pending.json and xp_evidence.json. Amalgamation uses are recorded in shared storage when enabled, or locally in amalgamation_uses.json. Do not remove that ledger to recover a player's food, because a spent meal could become usable again.
• Items, claims and rewards are per server. Each server pays a player the reward rows their levels earned once, even if they levelled elsewhere.
• Backup sets and the checkpoint audit hold private player data. Keep them out of Git and public downloads.

Backups

Professions registers as professions in the Endless Leveling suite backups. EL takes a startup checkpoint and then one each hour. Retention keeps 48 hourly, 14 daily, 10 startup, 20 manual and 20 safety sets. Each Professions checkpoint holds saved player progression, reset balances, local JSON settings and state, and language files, plus (on shared storage) capstones, server-local rewards, legacy claims, relics, revival incense, Amalgamation uses and boosts.

• Every payload has a SHA-256 checksum, verified before a checkpoint is listed as usable. Failed exports keep the previous good sets.
• If EL's suite API is unavailable, checkpoints go to backups/checkpoints/ under the data folder with the same retention. A delayed check runs three minutes after startup if no usable checkpoint exists. There is no shutdown backup.
• These are local recovery points. Off-server backups stay the operator's job.
• EL's /el backup includes Professions, but EL's broad restore commands report Professions as unsupported and direct you to the selective commands below.

Selective restore: backup restore latest <player> <profession> xp,tree "reason" writes nothing and prints a token. backup confirm <token> first takes and verifies a safety checkpoint, checks for changes since the preview and then applies. Each result is recorded in checkpoint-audit/. XP restore recalculates levels with the current curve. Tree restore keeps the combined choice history. Reset restore keeps current grant receipts.

• Targets must be offline. With shared storage keep them offline on every network server and add --network-offline true. The plugin cannot verify another server's live session.
• Checkpoint namespace, server scope and storage lane must match. These commands do not migrate backups between networks.
• A restore keeps current item-delivery and reward-command receipts, inventories, money, boost purchases and timers, capstone numbers and custody, cooldowns, collections and recipe discoveries. It never replays reward commands or mints capstones.
• If a player's whole profile is missing, receipts, collections and discoveries are recovered and a recovery hold blocks XP, tree changes and reward delivery until an admin reviews post-checkpoint payouts and runs backup releasehold.

XP reset campaign

/professions admin resetandcompensate lowers profession XP earned under looser settings to what the same play pays today. It does not cap a pace or a level. The window is set in xp-reset.json: campaign, since (start of the window), maxIntervalHours, keepXpBeforeSince (false by default) and historyDirs (relative folders holding backup sets copied from sister servers).

• XP logged in xp_evidence.json is repriced per payout at today's row and multiplier.
• Gains before the log, or seen on another server, are revalued at today's multiplier against the lowest multiplier any running server had.
• Nobody is raised above the XP they had at the cutoff, transcended rows are kept, and a gain above what the log paid stays as earned.
• The first run only previews and writes every row to a report. Confirm within 120 seconds with the printed token. Later runs move players only by the difference.

Excavation, Smithing and other tuning files

• excavation.json: findChance 0.005, maxExposedFinds 32, restoreStrokes 3, restoreXp 150, firstFindXp 250, highTierChance 0.02, highTierTrinketShare 0.5, highTierVoidstoneWeight 1 (0 disables Voidstone), tabletLevelFraction 0.05, abandonedJobHours 24, keenEyeCap 0.9, prospectorTin (min 3, max 5, ores), coinPouch (min 150, max 350), frostCache, siftOres (copper 3, iron 1) and per-terrain artifacts weights.
• vaporiser.json: rarity rows, hourlyXpCap (0 by default, no ceiling), bag.payoutShare and bag.xpShare (both 1). No weapon ever pays more than 100,000 lowest-tier cores. A/S destruction history is kept 30 days or 5,000 records.
• alchemy.json: recipes, costs, levels and grade durations. Hunter's Flare duration is capped at 60 seconds, and radius and enemy count have fixed ceilings. One flare per player, four per world and sixteen per server can be active.
• cooking.json: recipes, ingredients and the amalgamation object (mastery level 95, duplicate scale 0.05, minimum quality 0.90, duration 3600 seconds, 24 attribute points, restored health 0.50, protection 3000 ms). The duplicate scale, duration and protection time cannot be raised above those defaults.
• Vault keys: the six rank costs, Smithing levels and XP actions (forge_vault_key_e to forge_vault_key_s in xp/SMITHING.json) are defined in this mod; the key items themselves come from Endless Rifts.

Integrations

Missing optional integrations disable their feature and never grant another player your XP. Third-party controls and configuration stay in the owning mod.

Placeholders

The professions expansion registers when PlaceholderAPI is present (see the PlaceholderAPI guide).

<id> is mining, woodcutting, excavation, farming, fishing, building, smithing, alchemy, exploration, cooking, acrobatics or husbandry.

Languages

English ships in the jar. For runtime overrides use mods/ScuffedProfessions/lang/<locale>.lang with underscores (for example lang/es_ES.lang); missing keys fall back to English. text.json is a flat language-independent override map that takes precedence. Keep keys, item ids, command tokens and {0} placeholders unchanged. Run /professions reload and reopen the page. Native item and UI changes in an asset pack may also need an asset reload or a restart. Custom recipe and ingredient names use the keys alchemy.brew.<item-id>, alchemy.reagent.<item-id> and cooking.ingredient.<item-id>.

API for other mods

Use com.zbeve.scuffedprofessions.api.ScuffedProfessionsAPI. All members are public static, so a call works without holding an instance.

Rules for callers:

• Read-only consumers can query levels, XP, Transcend state and tree bonuses without issuing XP.
• Use addXp only for a confirmed action by the supplied player. The source identity matters for anti-farming and audit. Do not award viewers, nearby players, spouses or unknown furnace owners.
• It returns false and changes nothing when the profession or world is off, the amount is not positive, the player is in Creative (admin grants excepted) or the gain is under a whole point after the multiplier (the fraction is kept for the next gain).
• Resets spend one credit for that profession. Use the admin recovery tools for capstone and artifact replacements. Raw item creation does not produce a valid numbered copy.
• Configuration and reward records are not stable integration APIs. Register content through packs where possible, compile against the versions you deploy and test missing-provider behavior separately.

Troubleshooting