KubeJS Server API

English | 中文

Server API

SkillAtlas is a global binding available in kubejs/server_scripts.

Global queries

Method	Returns
SkillAtlas.player(player)	The helper for an online player
getRevision()	Revision of the effective definition
hasNode(id)	Whether the node exists
getNode(id) / getCategory(id) / getPool(id)	Immutable data snapshot, or null
getNodeIds() / getNodeIds(categoryId)	All skill IDs, or the IDs in one category
getCategoryIds() / getPoolIds()	ID lists
exportDefinition()	Read-only JSON-shaped snapshot of the effective atlas
validateDefinition(jsonObject)	Validation result, without committing

Query results cannot be written back. Exports contain neither JavaScript functions nor player progress.

A node snapshot includes choice_group when the node belongs to a choice group.

Player helper

// The player must be a current server player, e.g. from an event.
const p = SkillAtlas.player(event.player)

Method	Meaning
getLevel(nodeId)	Current level
hasSkill(nodeId) / hasSkill(nodeId, minLevel)	Whether the level is at least minLevel (default 1)
isMaxed(nodeId)	Whether the skill is at max level
getLearnedSkills()	Snapshot of ID → level
getPoints(poolId)	Pool balance, up to 1000000000000
getProgress(poolId)	unitsText, targetText, awardedText, limit, unit; big integers are returned as text
getRawExperience()	Total experience points (not experience levels)
checkLearn(nodeId)	Check for the next level; detail is a snapshot of that level's cost and rewards
getLearningQuote(nodeId)	Read-only snapshot of the current server quote, condition results, extra reward descriptions and state
canLearn(nodeId)	Whether the native check passes; does not run beforeLearn
learn(nodeId)	Learn one level normally, reusing native validation, payment, rewards and sync
addPoints(poolId, amount, reason)	Add balance; does not count toward natural award limits
spendPoints(poolId, amount, reason)	Deduct balance; fails as a whole when short; not recorded in the skill payment ledger
setPoints(poolId, value, reason)	Set balance; keeps progress remainders and awarded counts
grant(nodeId, targetLevel)	Free admin grant; keeps native per-level command rewards; lowering refunds from the ledger
reset({scope:'all'})	Reset every defined skill
reset({scope:'category', id:'mining'})	Reset the skills in one category
reset({scope:'node', id:'haste'})	Reset exactly one node
addProgress(poolId, units, reason)	Report activity progress in the pool's unit, through events and native limits
emitAcquisition(typeId, payload, units)	Settle an external activity through registered types
resetAcquisition(poolId) / resetAcquisition()	Clear the activity progress and award limit of one pool / all pools
open() / open(categoryId)	Ask this player's client to open the atlas
focus(nodeId)	Ask this player's client to open the atlas and focus the skill

Results

Write methods return an outcome with ok, code, a localized message and transactionId. Depending on the operation, actualDelta, oldLevel, newLevel and detail are also set.

Programming errors such as a missing atlas or illegal arguments may throw directly from some queries and builders. Not every error is wrapped into an outcome.

Common codes from checkLearn / learn: ok, unknown_node, max_level, prerequisite, choice_excluded (blocked by a choice group), insufficient_points, insufficient_experience, insufficient_items, condition_failed and script_error. Writes during another operation return reentrant_operation.

Notes on learning

• checkLearn does not run beforeLearn. It does run custom conditions, descriptions and the pure learningCost quote, and checks native conditions, dynamic resource costs and visibility.
• learn uses a frozen quote and re-validates conditions and resources. A passing query does not guarantee that payment succeeds a moment later.
• Missing points, items and experience are reported in native order. Not every missing requirement is listed at once.
• getLearningQuote does not reserve a submittable token for the client. Scripts should simply call learn.

Notes on points and refunds

• Points spent with spendPoints are not refunded on respec.
• Refunds use the currency and amount actually paid, not the current price. Free grants produce no refund.
• Delivered items and executed one-shot commands are not reverted.
• Paying again after a respec fires learned again. Rewards that may only be claimed once need your own persistent flag.

External activities

Register a type in acquisitionTypes (see Custom Types), bind a pool to it, and report from the real KubeJS server event of the mod you integrate:

SkillAtlas.player(event.player).emitAcquisition('pack:machine', { machine: 'press' }, 1)

The report goes through progressing → pointsChanging → pointsChanged with source = acquire. reason and acquisitionType are the type ID, and progressing.detail is the payload.

• actualDelta is the total awarded.
• detail is a list of {poolId, ok, code, actualDelta} for each pool.
• If some pool rejects, code is partial_failure and the other pools are not rolled back.
• No matching pool means success with 0 awarded.

Eligibility follows the COUNT_CREATIVE config: creative and spectator players are excluded by default and allowed when the option is on. FakePlayers are always excluded. addProgress remains the explicit admin entry (source = script). Do not report the same activity through both entries.

Clearing activity progress

SkillAtlas.player(event.player).resetAcquisition('machine')
SkillAtlas.player(event.player).resetAcquisition()

This clears the persistent counter, the awarded amount and pending movement buffers.

• Kept: balance, skill levels, payment ledger, actual experience and the seeded initial points.
• Not done: initial points are not re-granted and no fake pointsChanged fires.

detail lists poolId, oldUnitsText, oldAwardedText, discardedPendingText, unitsText='0' and awardedText='0'. Resetting reopens the pool's award limit, so control when your pack calls it.