KubeJS Events

English | 中文

Events

All server events live in the SkillAtlasEvents group and are used in kubejs/server_scripts.

Event list

Event	Cancellable	Filter ID	Purpose
definitions	Can reject the whole new definition	—	Overlay the base atlas with the staged builder
conditionTypes	Can reject the whole registration	—	Register condition types with validation, test and description
rewardTypes	Can reject the whole registration	—	Register one-shot and revocable persistent rewards
acquisitionTypes	Can reject the whole registration	—	Register external acquisition types
learningCost	Yes	Skill ID	Quote the cost of the next level
beforeLearn	Yes	Skill ID	Add a gate right before a normal learn pays
learned	No	Skill ID	A normal learn raised the skill by one level; native rewards are applied
learnFailed	No	Skill ID	An actual native learn failed; queries do not fire it
beforeReset	Yes	Node ID when one node is reset	Check before a reset; use an unfiltered listener for bulk resets
reset	No	Same as above	Reset and ledger refund are done
pointsChanging	Yes	Pool ID	Adjust the amount before a standalone balance change or a natural award
pointsChanged	No	Pool ID	Observe an actual balance change
progressing	Yes	Pool ID	Skill Atlas activity progress after matching
levelChanged	No	Skill ID	Level changed by learn, grant, reset or definition correction
reloaded	No	—	Start-up or reload succeeded; the effective atlas can be queried
reloadFailed	No	—	Definition parsing or a script overlay failed

Unfiltered listener:

SkillAtlasEvents.learned(event => { /* ... */ })

Listener for one ID:

SkillAtlasEvents.learned('haste', event => { /* ... */ })

A normal learn fires learned exactly once. Admin grants and login refreshes do not fire it.

Cancelling

• event.cancel() cancels.
• Decision events such as beforeLearn also offer event.deny(Text.red('reason')).
• An exception thrown before the commit is treated as a rejection.
• An exception thrown after the commit keeps the result that already happened. Errors cannot roll back external items or commands.

Common fields

Depending on the event: player, server, source, reason, transactionId, revision, nodeId, poolId, categoryId, oldLevel, newLevel, detail.

• In definition lifecycle events player is null.
• Do not treat an empty nodeId / poolId as a real ID.

Learn events

Learn events carry a cost snapshot of the next level. Changing cost, newLevel or other display fields in beforeLearn does not change the actual transaction. Use learningCost for dynamic prices.

Temporary gates added in beforeLearn do not appear in the client preview. If players should see a condition beforehand, register a condition type and attach it to the node or level.

A node blocked by its choice group fails the native check with code choice_excluded before beforeLearn runs.

Reset events

Reset events provide affectedNodes and refund.

• In beforeReset, refund is a preview from the payment ledger.
• In reset, it is the actual native result.

A reset only touches the nodes it names and does not cascade to successors. Forced corrections caused by deleting a node or lowering its max level cannot be blocked by beforeReset.

Points

pointsChanging exposes a writable delta, plus oldPoints, newPoints and requestedDelta for reference. The new value must be a valid integer, and you cannot turn an award into a deduction or the other way round. pointsChanged provides the actual actualDelta and the new balance.

Values of source:

Source	Meaning
learn	Normal learning
reset	Respec
script	Script balance operation
command	Native command or admin grant
acquire	Natural activity
definition_change	Definition correction
login	Initial points on login

Learn payments, respec refunds, initial points and definition corrections skip the cancellable pointsChanging and only fire pointsChanged after the change. So do not count every positive pointsChanged as a natural reward.

Activity progress

Cancelling progressing only cancels Skill Atlas progress. The block break, kill, harvest or catch still happened. The event provides poolId, acquisitionType, a writable units and unit (count, seconds or centimeters). It does not fake missing block, item or entity context. For extra filtering, decide in the original KubeJS event whether to call addProgress.

• Natural awards still respect matching, the creative/FakePlayer exclusion and award limits. Multipliers are applied before the limit.
• When an award is rejected or zero, the remaining progress is kept and the awarded count does not grow. A full balance does not swallow the progress.
• Movement is aggregated per player and pool and published every 20 ticks. Leftovers below the threshold are kept, and pending amounts are flushed on logout and server stop.
• Cancelling one pool does not cancel other pools matched by the same activity.

Re-entrancy

While a player is learning, resetting, being granted, receiving points or dispatching post-commit events, another write through the player helper returns reentrant_operation. If you need a follow-up action, schedule it for the next tick and use a distinct source to avoid point loops.