Skip to main content

KubeJS

KubeJS is well suited to registering concrete items, blocks, recipes and content objects; MiXianTu reads those objects and gives them rules through binding tables. Do not modify server attachments directly in a script, and do not bypass cost validation.

What the Integration Gives You​

The KubeJS bridge is optional. It exposes one global object per domain instead of a single Mxt root object:

GlobalResponsibility
MxtActionsRegister mxt:js action callbacks, or run a built-in action.
MxtConditionsRegister mxt:js condition callbacks, or test a built-in condition.
MxtValuesRegister or evaluate number providers and resource value providers.
MxtCostsCheck or pay a single complete cost.
MxtResourcesPay a whole Cost array atomically.
MxtAbilitiesCast, grant, revoke and query the abilities an entity holds.
MxtCultivationAdd cultivation progress and attempt a realm breakthrough.
MxtCursesApply (with an optional duration), release, remove and query curses.
MxtAuraQuery, add and remove server-side aura areas.
MxtElementsRead the elements and element accumulation on an entity, and apply accumulation.
MxtSpiritRootsQuery, grant, remove and switch spirit roots on and off.
MxtPhysiquesQuery, grant, remove and switch physiques on and off.
MxtTechniquesQuery, learn and forget techniques, and read the progression level one is at.
MxtProgressionRead and write the progression level a body holds, per owner, shared by techniques and spirit beasts.
MxtQualityRead the quality a stack resolves to and its chain, write the override component, or climb one tier.
MxtSoulsReclaim the transferable soul of an entity.
MxtTriggersPublish custom trigger signals and subscribe scripts to them.
MxtLootRegister script loot conditions and loot functions.
MxtEventsEvery MiXianTu server lifecycle event.

Every object has its own page; the full method tables, the common data rules (number providers, mxt:js callbacks) and the error model are in the KubeJS API Reference.

Every API that changes game state must be called from kubejs/server_scripts/, and it goes through the mod's existing server transactions and event flow; a client script should only read.

Lifespan scripts are provided by Reincarnation through ReincarnationLifespan and ReincarnationEvents.

When You Need KubeJS​

The mod is a framework, not a content pack:

  • A data pack can define rules, but it cannot create a new item, block or recipe.
  • If everything you need to bind already exists — vanilla items, items from another mod, or items the mod ships with — plain data pack JSON is enough, and KubeJS stays optional.
  • Register content with KubeJS when you want your own items, food, tools or recipes, then bind those real item IDs to the framework.
  • Scripted callbacks are optional too: conditions, actions and number providers can also be written entirely as data pack JSON with the built-in types.

The Shortest Path​

One. Register the item in a startup script:

// kubejs/startup_scripts/mxt_items.js
StartupEvents.registry('item', event => {
  event.create('fire_root_pellet')
    .displayName('Fire Root Pellet')
    .food(food => food.hunger(2).saturation(0.2))
})

Two. Attach rules to its real ID with a registry or a binding table:

// kubejs/data/example/mxt/item_binding/fire_root_pellet.json
{
  "items": "kubejs:fire_root_pellet",
  "actions": [
    { "type": "mxt:grant_spirit_root", "spirit_root": "example:fire_root" }
  ]
}

The six tables (item, weapon, pill, tool, blueprint and technique) are documented with examples in Items and Bindings; all six are registries, one file is one definition, they live under kubejs/data/<namespace>/mxt/<table>/, and an entry claims its items through items.

Three. (Optional) provide a callback from a server script, then name it from a data pack field:

MxtActions.entity('example:heal', (entity, params, context) => {
  entity.heal(params.amount || 1)
})
{ "type": "saturn:js", "id": "example:heal", "params": { "amount": 4 } }

Four. Use the table below to make the change take effect.

Reloading and Restarting​

What changedHow it takes effect
Startup scripts (items, blocks, recipes)Restart the game; /reload never re-runs startup scripts.
Binding tables and other data pack definitionsReload the world; they are read while the world loads.
Server scripts (callbacks, event subscriptions)/reload clears every callback and re-runs the scripts, so callbacks register again; runtime subscriptions a script armed are its own to re-arm.

Next​