This page covers typed ids, state helpers, pattern helpers, PiSerializeKit-backed interop, and ProbeJS support.

Typed Ids

MnaJS favors typed ids and stable string ids over loose Object surfaces.

Current typed id family:

Guideline:

• If a surface accepts an id type, prefer that typed id or a matching id string.
• For construct slots and construct capabilities, prefer lower-case strings such as "head" and "cast_spell".

PiSerializeKit Typed-Id Interop

MnaJS also bootstraps typed-id serializers through MnaTypedIdPiSerializers.

Current scope:

• resource-location-backed serializers for ids such as advancement, faction, casting resource, ritual, shape, modifier, cantrip, item, block, loot table, sound, structure, and texture
• string-backed serializers for construct slot ids and construct capability ids
• shared codec, NBT, and packet support through PiSerializeKit's serializer service

Practical meaning:

• the same typed ids used in KubeJS-facing APIs can be serialized consistently for editor, packet, or stored-document workflows
• construct slot and construct capability remain lower-case string style at the serialized boundary even though they are wrapped in typed classes on the MnaJS side
• pattern editor document state is built on the same PiSerializeKit-oriented infrastructure rather than ad-hoc string blobs

MnaRitualReagent

Use this helper for readable ritual reagent definitions.

Core methods:

• MnaRitualReagent.of(symbol, itemOrTag)
• optional()
• keep()
• manualReturn()
• dynamic()
• dynamicSource()

Example:

const reagent = MnaRitualReagent.of("A", "minecraft:amethyst_shard")
    .optional()
    .keep();

MnaPatternHelper

Use it for quick creation of ritual, reagent, and manaweave grids.

Available helpers:

• ritualGrid(size)
• ritualFilled(size, value)
• ritualRows(...rows)
• reagentGrid(size)
• reagentRows(...rows)
• manaweaveGrid()
• manaweaveFilled(value)
• manaweaveRows(...rows)
• filledGrid(rows, columns, value)

Examples:

const ritualGrid = MnaPatternHelper.ritualRows("0 1 0", "1 1 1", "0 1 0");
const reagentGrid = MnaPatternHelper.reagentRows(" A ", "BCD", " A ");
const manaweaveGrid = MnaPatternHelper.manaweaveGrid();

Notes:

• These helpers are for script ergonomics and examples.
• They are not a replacement for a proper visual editor.
• Ritual pattern values use int, not byte.

PlayerMagic

Binding name: PlayerMagic

Use it for M&A player magic state access.

Entry points:

• PlayerMagic.of(player)
• PlayerMagic.get(player)
• PlayerMagic.raw(player)

State methods on PlayerMagicState:

• getMana()
• setMana(float)
• addMana(float)
• subtractMana(float)
• getMaxMana()
• getMagicLevel()
• setMagicLevel(int)
• getMagicXP()
• setMagicXP(int)
• addMagicXP(int)
• isMagicUnlocked()
• unlockMagic()
• getAffinityDepth(Affinity)
• setAffinityDepth(Affinity, float)
• getCastingResourceId()
• setCastingResourceId(MnaCastingResourceId)
• getCastingResource()
• getProgression()

PlayerProgression

Binding name: PlayerProgression

Use it for progression and faction-standing state.

Entry point:

• PlayerProgression.of(player)

State methods on PlayerProgressionState:

• getTier()
• setTier(int)
• getTierProgress()
• getCompletedSteps()
• hasCompletedStep(MnaProgressionEventId)
• addCompletedStep(MnaProgressionEventId)
• getAlliedFactionId()
• setAlliedFaction(MnaFactionId)
• getFactionStanding()
• setFactionStanding(int)
• increaseFactionStanding(int)
• canBeRaided()
• canBeRaidedBy(MnaFactionId)
• getRelativeRaidStrength(MnaFactionId)
• getRaidChance(MnaFactionId)
• setRaidChance(MnaFactionId, double)
• forceRaid(MnaFactionId)
• hasForcedRaid()
• getForcedRaidFactionId()
• clearForceRaid()

ProgressionEvents

Binding name: ProgressionEvents

Use it for typed built-in progression event constants.

Current built-ins include:

• CONSTRUCT_LODESTAR_ASSIGNED
• APPLY_POUCH_PATCH
• ELDRIN_FUME_LIT
• STUDY_DESK_USED
• SPELL_AFFINITY_TINKERED
• REMOVE_ENCHANTMENT
• TRANSCRIBE_SPELL
• CAPTURE_WELLSPRING
• OPEN_CACHE
• values()

WorldMagic

Binding name: WorldMagic

Use it for world magic state and wellspring power manipulation.

Entry points:

• WorldMagic.get(level)
• WorldMagic.of(level)
• WorldMagic.addNode(level, pos, affinity, strength, force)
• WorldMagic.getPower(level, player, affinity)
• WorldMagic.addPower(level, player, affinity, amount)
• WorldMagic.subtractPower(level, player, affinity, amount)
• WorldMagic.setPower(level, player, affinity, amount)

State methods on WorldMagicState:

• hasWellspringRegistry()
• addNode(...)
• getPower(...)
• addPower(...)
• subtractPower(...)
• setPower(...)

General Utility Bindings

These are exposed as direct bindings:

• CollectionUtils
• MathUtils
• MATags
• BiomeUtils
• ProjectileHelper
• InventoryUtilities
• RecipeUtil

Good use cases:

• random selection
• clamping and interpolation
• tag contents and item-tag comparisons
• biome enumeration
• inventory-room checks
• recipe lookup helpers

Server-Only Utility Bindings

Only exposed on server scripts:

• MNARecipesHelper
• ProgressionEventIDs
• StructureUtils
• EntityUtil
• SummonUtils
• ShearHelper
• MnaFactionUtil
• ManaItemUtil
• MnaEntityHelper
• MnaFactionRaidHelper

Use these for:

• low-level recipe JSON builders
• structure queries
• cone-based entity searches
• summon management
• shearing checks
• faction and raid integration
• mana item charge lookups
• present-item entity spawning

Client-Only Utility Bindings

Only exposed on client scripts:

• WorldRenderUtils
• GuiRenderUtils
• ParticleConfigurations

These are direct Java-side rendering helpers and should stay on client-side execution paths.

ProbeJS Support

MnaJS installs compatibility layers for:

• modern ProbeJS through MnaJSProbeCompat
• ProbeJS Legacy through MnaJSLegacyProbeCompat

Current Probe support goals:

• typed ids resolve to narrow string unions where possible
• custom builders and recipe classes are added to exposed Java surfaces
• snippets are registered for M&A recipe chains
• modern and legacy ProbeJS both receive MnaJS plugin installation

Practical guidance:

• keep a typed local builder for best completions
• prefer typed ids and narrow string ids
• use the generated Internal.CustomXxx$Builder builder types in JSDoc when event.create(...) alone is not enough

Example typing pattern:

/**
 * @type {Internal.CustomConstructMaterial$Builder}
 */
const builder = event.create("kubejs:moonsteel", "basic");

Pattern Editor Documents

Pattern document helpers are exposed through Java utilities rather than plain KubeJS globals, but they are part of the current pattern-editor support layer.

Available document helpers:

• MnaPatternEditorDocuments.newManaweaveDocument()
• MnaPatternEditorDocuments.newRitualDocument(size)
• MnaPatternEditorDocuments.replaceGrid(document, int[][])
• MnaPatternEditorDocuments.toGrid(document)

These utilities are backed by the repo's PiSerializeKit-based document state and are intended for editor-oriented tooling rather than everyday handwritten scripts.