KubeJS API Reference

The MiXianTu KubeJS bridge provides one global object per domain; it does not provide a Mxt root object carrying every method. Each object has its own page, listed below. All APIs that change game state must be called from kubejs/server_scripts/, and they enter the mod's existing server transactions and event flow.

The identifiers used here and on the sub-pages — id, resource, ability, curse, zone and so on — are all namespaced strings, for example mxt:spirit_power or example:fireball. Passing an invalid identifier, or JSON that cannot be decoded by the matching codec, throws a script error directly, so that data problems can be located.

Root Objects

Object	What it is for	Page
MxtActions	Register mxt:js action callbacks, or run a built-in action directly.	MxtActions
MxtConditions	Register mxt:js condition callbacks, or test a built-in condition directly.	MxtConditions
MxtValues	Register or evaluate number providers and resource value providers; the FormulaContext reference lives here.	MxtValues
MxtCosts	Check or pay one Cost.	MxtCosts
MxtResources	Pay a whole Cost array as a single atomic transaction.	MxtResources
MxtAbilities	Cast an ability, and grant, revoke or query the abilities and sources an entity holds.	MxtAbilities
MxtCultivation	Add cultivation progress and attempt a breakthrough along a resource chain.	MxtCultivation
MxtCurses	Apply (with an optional duration), release, remove and query curses.	MxtCurses
MxtAura	Query world aura, and add or remove server-side aura areas.	MxtAura
MxtElements	Read the elements and element accumulation on an entity, and apply accumulation.	MxtElements
MxtSpiritRoots	Query, grant, remove and switch spirit roots on and off.	MxtSpiritRoots
MxtPhysiques	Query, grant, remove and switch physiques on and off.	MxtPhysiques
MxtTechniques	Query, learn and forget techniques, and read the progression level one is at.	MxtTechniques
MxtProgression	Read and write the progression level a body holds, per owner, shared by techniques and spirit beasts.	MxtProgression
MxtQuality	Read the quality a stack resolves to and its chain, write the override component, or climb one tier.	MxtQuality
MxtSouls	Reclaim the transferable soul of an entity.	MxtSouls
MxtLifespan	Read the lifespan ledger (ticks left and the ceiling), rewrite or adjust it, and make a body be reborn on the spot.	MxtLifespan
MxtTriggers	Publish custom trigger signals and subscribe scripts to them.	MxtTriggers
MxtLoot	Register script loot conditions and loot functions.	MxtLoot
MxtEvents	Every MiXianTu server lifecycle event.	MxtEvents

The first four objects (MxtActions, MxtConditions, MxtValues, MxtCosts), together with MxtLoot and MxtTriggers.matcher, are where data pack callbacks are registered: they implement the pre-registered mxt:js types a data pack can name. The rest are runtime domain APIs: a script reads state or changes it on its own initiative.

Entity, LivingEntity, Player, Level, BlockPos, ItemStack and DamageSource are all vanilla Java objects exposed by KubeJS. A JsonObject/JsonElement parameter accepts a plain JavaScript object or array.

Common Data Rules

Number Provider

Every parameter that is a number provider, such as amount or value, accepts the following forms:

10                                      // constant
'level * 2 + 1'                         // formula
{ type: 'mxt:uniform', min: 1, max: 3 } // built-in typed object

The formula context is created automatically by the called API from the entity or the level. The result computed by a script callback or a provider must be a finite number; NaN, Infinity, an exception or a callback that is not registered is logged and treated as 0.

mxt:js Callback Definitions

Actions, conditions, number providers, resource value providers, trigger matchers, costs, ability target selectors, loot conditions and loot functions all have a pre-registered mxt:js type. First register the callback in a server script:

MxtActions.entity('example:heal', (entity, params) => {
  entity.heal(params.amount || 1)
})

Then use it in any matching data pack field:

{
  "type": "mxt:js",
  "id": "example:heal",
  "params": { "amount": 4 }
}

An id is unique within the same callback category. KubeJS clears every callback before reloading server scripts and then re-runs the scripts, which register them again; do not put a registration in a client script that only runs once. When no callback is found, an action does not run, a condition returns false, a value returns 0, and a warning is logged.

Each kind of callback is registered on its own page: MxtActions, MxtConditions, MxtValues, MxtCosts, MxtTriggers, MxtLoot and MxtAbilities.

Return Values and Errors

Java records returned by the service APIs always use Java accessors, for example result.committed(), rather than assuming that JavaScript fields exist. A failure usually does not throw: check the return values such as failure(), committed(), advanced() and applied(). An exception is only thrown when an API parameter is invalid, an identifier is invalid, JSON cannot be decoded by the matching codec, or a mutable setter is called on the wrong event phase.

An operation that only makes sense on the server refuses to run from a client script, so a script cannot desync a client: MxtCosts.consume and the state-changing methods of MxtAbilities, MxtCultivation, MxtCurses, MxtAura, MxtSouls, MxtLifespan, MxtElements, MxtSpiritRoots, MxtPhysiques, MxtTechniques, MxtQuality and MxtTriggers return their failure result unchanged — for MxtSpiritRoots, MxtPhysiques, MxtTechniques and MxtLifespan that is a result whose failure is SERVER_ONLY, while MxtElements.attach answers 0 — and MxtCosts.consume, MxtTriggers.subscribe and MxtTriggers.subscribeOnce also write a single warning to the log instead of throwing. MxtAura.addBox is the exception: it needs a ServerLevel and throws otherwise.

MxtActions.execute* is deliberately not guarded, because the built-in actions decide their own side: an action whose JSON opts into client execution, such as a velocity action with its client flag, is meant to run where it is called.

Related

• KubeJS overview — when you need a script at all, and how content is registered.
• Items and Bindings — attach the items a script registers to the binding tables.
• Examples — complete scripts that combine several objects.
• Full walkthrough: Create Items and Bind Actions with KubeJS.