Jobs

Minimal example

(Trimmed from the shipped jobs/miner.yml, which carries ~90 actions entries and 200 rewards tiers.)

Top-level fields

All five shipped jobs follow the same <primary/secondary/text>_color placeholder convention for display-name/menu-secondary-icon.name/menu-secondary-icon.lore and the same %img_*%/%stacksuppliers_*% placeholders for menu-title /icons, but nothing in Job enforces that — it's just the house style.

Leveling equations

Each job compiles three Crunch expressions once at load (CompiledExpression, cached per-thread) and evaluates them per action or per level-up check:

In the shipped jobs, level-progress-equation is a single expression made of &-gated bands ((level>=0&level<1)*10 + (level>=1&level<25)*(...) + …), each band scaled by (1 + (level-1)*0.08) and mostly a cubic polynomial in (level - bandStart) (the first band, 0–1, and the last, 199–201, are flat constants instead), covering ranges up to level 201; a non-positive result signals the equation's domain is exhausted (used to detect "maxed" — see Level-up flow). experience-progress-equation and experience-income-equation are both shipped as <var>*(1+(level-1)*0.08) — an 8%-per-level multiplier on top of the action's base experience/reward. All five shipped jobs use the same constants; nothing requires that.

Actions

actions is a map of Key (a bare name like coal_ore or cat deserializes to minecraft:<name>) to a map of action-type key → JobActionValue(reward, experience, operation). JobService#load warns (but does not reject the job) if an action-type key isn't one of the ten registered keys below. At load time JobService#buildCache re-indexes every job's actions by action-type key then by Key, so an incoming event resolves straight to the set of (jobId, JobActionValue) pairs that match, across all jobs.

operation (UP/DOWN/NONE, rendered as ↑/↓/-) is not authored in YAML — no shipped job file sets it. RandomUtils#randomizeValues, run once per job right after load, deterministically perturbs every action's reward/experience by up to ±25% (seeded from the job id, action-type key, material/entity key, and the current ISO week — so the perturbation is stable for a week and changes only when the week rolls over) and sets operation to UP/DOWN/NONE depending on whether the perturbed reward came out above, below, or equal to the value written in the YAML file. The perturbed values are what actually get cached and paid out; operation exists purely to drive the up/down indicator shown in the menu-computed action rows.

Rewards

rewards maps a level (int) to a JobReward(description, actions):

The shipped jobs pair a [message] line per granted item/currency with a [console] line that actually performs the grant (eco give %player_name% default <amount>, give %player_name% <item> [amount], …) — [message] doesn't grant anything by itself, it only informs the player.

Rewards are not granted automatically on level-up. A player claims them with /jobs claim, which walks every job, finds every level <= the player's current level not yet in their JobsPlayerData claimed set, marks it claimed, fires a JobClaimRewardEvent, and runs that tier's actions. The same claim path is exposed as the claim-job-reward action for a menu button targeting one specific job/level.

Action resolution — how a gain is computed

When a tracked event fires, ActionService resolves the affected block/entity/item's Key on the main thread, looks up matching cached actions (JobService#findActionsByType), and — if any match — moves the rest of the work to a 2-thread worker pool:

1. For each matching (jobId, JobActionValue), load that job and the player's JobLevelEntity.

2. Multiply the action's base reward/experience by the event's item amount (1 for block/entity actions).

3. Snapshot the player's current (level, experience) under the level entity's lock.

4. Run the scaled base values through the job's equations at the snapshotted level: job.computeExperienceProgress(level, baseExperience) and job.computeExperienceIncome(level, baseMoney).

5. Apply the player's stacked modifiers: ModifierService#compute(playerId, JobModifierScope.EXPERIENCE, …, jobId) and the same for MONEY — folding in both timed boosters and permissions-boosters-derived modifiers cached for that player.

6. Fire a cancellable JobExperienceGainEvent and JobMoneyGainEvent; a cancelled event zeroes that gain, a listener may rewrite newExperience/newAmount.

7. Apply the surviving experience under the lock and run the level-up loop.

The same job/scope math is also exposed as ModifierService#computeWithLevel(player, job, scope, baseValue) — it looks up the player's live level via LevelService (rather than a snapshot) and applies the equations plus modifiers in one call. This is what the jobs-main menu uses to show a player what an action is currently worth — see Menu integration — rather than the action-gain path above, which snapshots the level once per event for lock-scoping reasons.

Level-up flow

Still under the level entity's lock, after experience is applied:

max-level (from config.yml, default 200) caps leveling; a value <= 0 is treated as uncapped. Once computeLevelProgress returns a non-positive value the equation's domain is exhausted and the loop stops, treating the player as maxed — this is what prevents an uncapped config from spinning forever once a band-based equation like the shipped ones runs out of bands. Players past the cap (or past the equation's domain) keep accumulating experience but stop gaining levels.

The surviving experience/money from step 6 above (not just level-ups) are handed to NotificationService#update, which accumulates them per player+job into a NotificationEntry. The level/experience fields on JobLevelEntity are already updated in-memory by ActionService itself, but persisting them to the database and depositing the accumulated money via EconomyService#deposit both happen only when that entry later flushes — after 5 seconds with no further gain for that player+job (NotificationCleanUpTask, polled every second), or immediately when the player quits. The 350 ms cooldown only governs how often the action-bar notification itself re-renders in the meantime (see Overview → Integrations). Money is granted independently of whether a level-up occurred on that particular action.

Menu integration

/jobs opens the jobs-main menu blueprint (MenuContainer#computeAndOpen(player, "jobs-main"), see Commands). A job's placeholder tree (namespace jobs, sub-key job, then the job id — Job itself is a ComplexPlaceholder reached that way) feeds that menu:

The computed sub-key on an action entry (JobActionPlaceholder) is what actually renders an action row: for each action-type value on that material/entity, it looks up the display name from config.yml's action-type-displays map (e.g. block-break: "Casser"), computes the live experience/money via ModifierService#computeWithLevel for the viewing player, and formats one line per config.yml's action-display template list (%experience%, %money%, %formattedName%, %operation% — the ↑/↓/- indicator from operation). See Placeholders for the full jobs namespace.

Where to go next

• Overview — how jobs, actions, and rewards fit together across the plugin.

• Configuration — max-level, permissions-boosters, action-display, action-type-displays, leaderboards.

• Commands — /jobs, /jobs claim, /jobs level, /jobs experience.

• Boosters — the other source of ModifierService modifiers.

• Placeholders — the full %jobs_*% namespace.

• Developer API — JobExperienceGainEvent, JobMoneyGainEvent, JobLevelUpEvent, JobClaimRewardEvent, and the claim-job-reward action.