API Conventions

BetaMoon API conventions

Lua API

On this page

• Declarations, references and contexts
• Examples
• Naming and identities
• Callback results
• Lua environment

Declarations, references and contexts

A BetaMoon declaration configures content, a reference identifies registered content, and a live context provides access during a callback. APIs requiring a structural or material handle expect the original returned handle, not a copied table with the same fields.

Examples

Unless shown as a complete script, declaration and registration snippets belong inside modInit(). Callback snippets belong in the named declaration. Variables such as ctx, match, or tile mean the object described by that entry, not globals supplied to every script.

IDs in examples may be in use by other mods, so you may need to change them in the scripts when you try them out.
Registration does not give items to the player.
Texture indices and block/item IDs are different values.

Naming and identities

Scripts use their name metadata for dependencies. Exported module names and script filenames are separate identifiers.

mymod in wiki snippets is a placeholder namespace. Replace it consistently in content keys and default asset paths when making your own mod. The example namespace is reserved for BetaMoon's bundled numbered lessons.

Blocks and items accept internalName, name, or key, in that precedence order. A namespace prefix before : is stripped from the internal name. Current block/item name lookup also accepts the part after :; it does not enforce namespace isolation.

Fluid and fluid-interaction registrations use canonical typed keys such as my_mod:fluid/acid and my_mod:fluid_interaction/acid_water. Use your own namespace; betamoon and minecraft are reserved. A shorthand without the type segment, such as my_mod:acid, is accepted where a declaration explicitly expects that resource type. References and lookup results expose the canonical key.

Do not change saved numeric identities or persistent slot mappings casually. See reload and compatibility.

Callback results

Interaction callbacks accept "pass", "deny", and "handled". Prefer the read-only constants so a misspelled result fails when the script reads it:

return betamoon.callbackResults.handled

callbackResults.pass continues normal handling, callbackResults.deny refuses the interaction and suppresses applicable fallback, and callbackResults.handled completes it successfully. The equivalent literal strings remain accepted.

Lua environment

Each discovered script receives its own isolated Lua environment with betamoon installed globally and registered as a loaded module. require("betamoon") returns that module. Cross-script sharing uses BetaMoon modules.