MnaJS KubeJS Support

MnaJS is a KubeJS addon layer for Mana and Artifice on Forge 1.20.1. Its goal is to make M&A content scriptable with typed ids, ProbeJS-friendly builders, chainable recipes, and server/runtime helpers that feel like normal KubeJS instead of raw Java interop.

This document is the external overview. The detailed reference lives in MnaJS KubeJS reference.

What This Adds

MnaJS currently exposes:

startup registries for M&A factions, ritual effects, spell components, shapes, modifiers, construct tasks, construct materials, construct parts, mana items, and M&A-aware blocks
server recipe chains for ritual, transmutation, crushing, runeforging, runescribing, component, modifier, shape, progression, manaweaving altar, arcane furnace, eldrin altar, eldrin fume, manaweave cache effect, and manaweaving pattern recipes
startup and server events for guidebook registration, cantrip registration, player magic progression, spell casting, ritual completion, wandering wizard trades, and runeforge hooks
typed ids and wrappers for M&A resources such as factions, rituals, spell effects, shapes, modifiers, construct tasks, construct materials, construct slots, construct capabilities, cantrips, structures, sounds, loot tables, and textures
helper bindings for player magic state, player progression state, world magic state, ritual reagents, pattern grids, and lower-level recipe JSON generation
ProbeJS and ProbeJS Legacy integration for builder typing, typed-id completion, snippets, and generated Java surfaces
PiSerializeKit-backed typed-id serializers for editor, packet, codec, and stored-document workflows

Startup Content

Startup scripts can register new M&A-facing content through KubeJS registries:

mna:factions
mna:ritual-effects
mna:components
mna:shapes
mna:modifiers
mna:construct_task
mnajs:construct_material
item types construct_part, mana_battery_item, and tiered_item
block types spell_interactible and manaweave_notifiable

The intended style is typed and chainable:

StartupEvents.registry("mna:ritual-effects", (event) => {
    /**
     * @type {Internal.CustomRitualEffect$Builder}
     */
    const builder = event.create("kubejs:lightning_ritual_effect", "basic");

    builder
        .ritualName("kubejs:lightning_ritual")
        .applicationTicks(20)
        .applyEffect((context) => {
            const level = context.getLevel();
            if (level == null) return false;
            const lightning = EntityType.LIGHTNING_BOLT.create(level);
            if (lightning == null) return false;
            lightning.setPos(context.getCenter().x, context.getCenter().y, context.getCenter().z);
            level.addFreshEntity(lightning);
            return true;
        });
});

The explicit Internal.CustomXxx$Builder local type is intentional. It gives ProbeJS a concrete builder type when event.create(id, type) alone cannot narrow completions deeply enough.

Recipe Chains

Recipes are exposed as event.recipes.mna.*() chains instead of requiring users to hand-author every JSON payload.

Example ritual recipe:

ServerEvents.recipes((event) => {
    event.recipes.mna
        .ritual()
        .tier(1)
        .patternRows("1")
        .displayPatternRows("1")
        .reagentRows("A")
        .reagent(MnaRitualReagent.of("A", "minecraft:amethyst_shard"))
        .innerColor(0xffd54f)
        .outerColor(0xfff176)
        .beamColor(0xfbc02d)
        .connectBeam(true)
        .outputItem("minecraft:lightning_rod")
        .id("kubejs:lightning_ritual");
});

Covered recipe groups:

ritual recipes with pattern grids, display grids, reagent grids, colors, manaweave pattern requirements, commands, and output items
item conversion recipes such as crushing and arcane furnace
runeforging and runescribing recipes
spell part recipes for components, modifiers, and shapes
manaweaving altar, manaweaving pattern, and manaweave cache effect recipes
progression condition recipes
transmutation recipes with block replacement or loot table plus representation item
eldrin altar and eldrin fume recipes
low-level MNARecipesHelper builders for event.custom(...)
multiblock definition JSON generation through MNARecipesHelper.multiblockDefinitionBuilder

Events And Runtime Hooks

MnaJS registers four KubeJS event groups:

MnaEvent
MnaPlayerEvent
SpellEvent
RuneForgeEvent

Important hooks include:

MnaEvent.registerGuideBook
MnaEvent.registerCantrip
MnaEvent.wanderingWizardSelectingTrade
MnaPlayerEvent.ritualCompleteEvent
MnaPlayerEvent.affinityChangedEvent
MnaPlayerEvent.genericProgression
MnaPlayerEvent.levelUp
MnaPlayerEvent.magicXPGained
MnaPlayerEvent.masteryGained
MnaPlayerEvent.roteProgression
SpellEvent.costingMana
SpellEvent.casted
SpellEvent.calculatingCooldown
SpellEvent.componentApplying
RuneForgeEvent.shouldActivate
RuneForgeEvent.itemUsed

Example:

MnaPlayerEvent.magicXPGained((event) => {
    event.setAmount(event.getAmount() + 5);
});

SpellEvent.costingMana((event) => {
    event.setCost(Math.max(1, event.getCost() * 0.9));
});

Cantrip registration is handled as a startup event and supports typed ids, required advancements, sounds, icon textures, manaweave patterns, dynamic item providers, custom callbacks, delayed callbacks, and verified built-in effects such as firework, gust, ascend, ward, and apply_spell.

Typed Ids And ProbeJS

MnaJS intentionally avoids loose script APIs where possible. Common inputs are wrapped as typed ids, then exposed to ProbeJS so script authors get better completion.

Examples of typed id families:

MnaFactionId
MnaRitualEffectId
MnaSpellEffectId
MnaShapeId
MnaModifierId
MnaConstructTaskId
MnaConstructMaterialId
MnaConstructSlotId
MnaConstructCapabilityId
MnaRitualId
MnaManaweavePatternId
MnaCantripId
MnaItemId
MnaBlockId
MnaLootTableId
MnaSoundId
MnaStructureId
MnaTexture

Probe support is installed for both modern ProbeJS and ProbeJS Legacy. The main scripting guideline is:

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

This style gives better completion for builder methods, typed id parameters, and callback signatures.

Helper APIs

MnaJS exposes helper globals for common script tasks:

PlayerMagic for mana, magic XP, magic level, affinity, casting resource, and progression access
PlayerProgression for tier, completed progression steps, faction standing, allied faction, and raid state
WorldMagic for wellspring nodes and affinity power state
ProgressionEvents for built-in typed progression event constants
MnaRitualReagent for ritual reagent construction
MnaPatternHelper for ritual, reagent, and manaweave grids
MNARecipesHelper for low-level JSON builders in server scripts

Example:

MnaPlayerEvent.levelUp((event) => {
    const magic = PlayerMagic.of(event.getEntity());
    magic.addMana(25);
});

Pattern helpers are present for script ergonomics, while larger shape editing is expected to happen through editor tooling or the toolkit UI rather than handwritten Java-like helpers.

Current Limits

These limits are deliberate documentation points, not hidden behavior:

construct_task currently supports metadata and reuse of existing Java AI tasks through basedOn(...) or aiTask(...); it is not a JS-native AI task authoring system.
registerGuideBook currently exposes the raw M&A guidebook registry. Deep guidebook authoring is expected to be handled by guidebook JSON and external tooling.
ProbeJS compatibility is installed for modern and legacy ProbeJS, but the documented guarantee is support wiring and generated surfaces, not manual verification of every possible completion branch.

Reference

Detailed pages:

Validation noted in the reference:

./gradlew compileJava
./gradlew runServer
startup example registration chain
server recipe and event script load