Last reviewed: 2026-04-26

This reference documents the KubeJS-facing surface currently implemented in this repository for Mana and Artifice on Forge 1.20.1.

Audience

Use these docs if you are:

• writing KubeJS startup scripts for M&A content
• writing server scripts with event.recipes.mna
• wiring gameplay around M&A events
• relying on ProbeJS completion and typed ids

Conventions

• Prefer typed ids or id strings over raw Object-style inputs.
• For builder completion, keep the builder in a typed local before chaining.
• Startup content belongs in startup_scripts.
• Recipes and runtime hooks belong in server_scripts.
• Client-only rendering helpers should stay in client scripts or client-side code paths.

Builder Typing Pattern

event.create(id, type) does not always narrow completion strongly enough on its own. Prefer this pattern:

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

builder
    .ritualName("kubejs:lightning_ritual")
    .applicationTicks(20);

Document Map

• Bindings
  • direct KubeJS globals exposed by registerBindings
  • core spell constants and result types
  • construct-system Java bindings
  • server-only and client-only binding catalogs
• Registries
  • custom factions
  • ritual effects
  • spell effects, damage components, potion components
  • shapes, modifiers, construct tasks
  • construct materials and construct parts
  • items and blocks
• Recipes
  • all current event.recipes.mna.* chains
  • MNARecipesHelper
  • multiblock definition helper
• Events
  • startup events
  • player events
  • spell events
  • runeforge events
• Helpers And Probe
  • typed ids
  • reagent and pattern helpers
  • player and world state helpers
  • PiSerializeKit typed-id interop
  • ProbeJS modern and legacy support
  • pattern document utilities

Validation

These docs were checked against the current repo support surface, not against a wishlist.

Validated during this review:

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

Important Limits

• construct_task does not support authoring a brand-new JS-native ConstructAITask implementation. Current support is metadata plus reuse of an existing AI class via basedOn(...) or aiTask(...).
• registerGuideBook currently exposes the raw guidebook registry. Deep guidebook authoring is still driven by M&A guidebook JSON and surrounding tooling.
• Probe wiring is installed for modern ProbeJS and ProbeJS Legacy, but only runtime compatibility and support generation wiring are documented here. It is not a claim that every possible completion branch has already been manually exercised.