Skip to main content

MxtSpiritRoots: Spirit Roots

A spirit root is the element half of a body's cultivation identity: holding one binds that body to one or more elements (elements is a list), changes the cultivation speed of those elements' aura, and scales the abilities attuned to any of them. The element-independent half is MxtPhysiques. Granting and removal go through the authoritative service, so conflicting_elements conflicts and the abilities a root grants are handled as usual.

Methods​

MethodParametersReturn valueDescription
list(entity)EntityList<String>Every spirit root the entity holds, sorted by ID. A switched-off root, or one whose definition is no longer in the current pack, is still listed — it really is still held.
active(entity)EntityList<String>The roots that are in effect right now: switched-off ones do not count.
has(entity, root)Entity, root IDbooleanWhether it is held (the same meaning as mxt:has_spirit_root: a switched-off root still counts).
enabled(entity, root)Entity, root IDbooleanWhether that root is currently switched on; false when it is not held.
grant(entity, root)LivingEntity, root ID{changed, failure}Goes through the authoritative service, so conflicting_elements and the granted abilities are handled as usual.
remove(entity, root)LivingEntity, root IDbooleanGives up that root together with its element and everything it granted; false when it was not held.
setEnabled(entity, root, enabled)LivingEntity, root ID, boolean{changed, failure}"Switch off without losing": changed: true only when the state really changed and the grants were recomputed, and failure: "NOT_HELD" when it is not held.

Spirit roots and physiques share one failure vocabulary: DISABLED (that id is not in the registry, including a definition a neoforge:conditions block keeps out), ALREADY_HELD, CONDITIONS (the physique's holder_condition is not met), EXCLUSIVE_CONFLICT, ELEMENT_CONFLICT (the root's conflicting_elements), NOT_HELD and SERVER_ONLY (called on a client). The four readers work on either side — the spirit_identity attachment is synchronised, and an item tooltip asking "are you a fire root?" is exactly that use — while the state-changing methods are server operations.

// kubejs/server_scripts/mxt_identity.js
// Reshaping: swap one spirit root for another and switch the new physique on along the way.
const result = MxtSpiritRoots.grant(player, 'mxt_test:qingxiao_fire_root')
if (result.changed) {
  MxtSpiritRoots.remove(player, 'mxt_test:water_root')
  MxtPhysiques.setEnabled(player, 'mxt_test:blazing_body', true)
} else {
  console.warn(`grant refused: ${result.failure}`)
}
// "Is he on a fire root right now?" — a switched-off root is still held, so ask active rather than has.
const active = MxtSpiritRoots.active(player)