API Recipe Types

Recipe types

Lua API / Recipe types

On this page

• betamoon.recipeTypes:add(definition)
• Field definitions
  • Ingredient roles
  • Output roles
  • Data field schemas
  • Context field schemas
  • Ingredient values
    • Single item
    • Remainder
    • Item pool
    • Item grid
    • Item output pool
• Recipe-type lookup
  • betamoon.recipeTypes:get(name)
  • betamoon.recipeTypes:getRequired(name)
  • betamoon.recipeTypes:find(criteria)
  • betamoon.recipeTypes:first(criteria)
  • betamoon.recipeTypes:one(criteria)
• Type reference

betamoon.recipeTypes:add(definition)

Registers a schema for custom recipes and returns a type reference. Requires script initialization ownership. A retained schema may be redeclared identically by its owner; schema changes require restart.

local pressing = betamoon.recipeTypes:add {
    name = "mymod:recipe_type/pressing",
    ingredients = { input = {} },
    outputs = { output = {} },
    data = { duration = { type = "integer", min = 1, default = 40 } }
}

Field definitions

Field	Type	Requirement / default
name	string	Required; unqualified names receive script-file namespace. minecraft namespace reserved.
displayName	string	Defaults to part after namespace.
ingredients	map of roles	Required nonempty map.
outputs	map of roles	Required nonempty map.
primaryOutput	string	Required when multiple outputs; otherwise sole output. Must be a required single-item role.
data	map of field schemas	Optional recipe metadata schema.
context	map of field schemas	Optional machine-condition schema.
matcher	name/matcher handle	Optional custom allocation matcher.

Names normalize to lowercase and use namespace:name syntax; namespaces contain letters, digits and underscores, while local names additionally permit dot, slash and hyphen. Use qualified names for lookup outside initialization.

Ingredient roles

Role names contain letters/digits/underscores and start with a letter or underscore.

ingredients = {
    materials = { type = "item_pool", allowExtra = false },
    mold = { type = "item", optional = true, consume = false }
}

Field	Default / meaning
type	item; also item_pool or item_grid.
optional	False. Missing recipe role then requires an empty bound input.
consume	True. False requires the ingredient but retains it during application.
allowExtra	Pool only, false; permits extra occupied input slots not used by the recipe.
width, height	Grid only, required integers 1–16.
allowSmaller	Grid only, true; permits smaller recipe patterns.
placement	Grid only, anywhere (default) or fixed.
transformations	Grid only, empty by default; extra permitted transforms.
emptyCells	Grid only, required (default) or ignored.

Transforms: mirror_horizontal, mirror_vertical, rotate_90, rotate_180, rotate_270. Original orientation remains available. Duplicates normalize away. Pool/grid options on unrelated role kinds are errors.

Output roles

type is item (default) or item_output_pool. optional defaults false. Output roles do not accept consume or input-layout options. A primary output must be required and type=item.

Data field schemas

Field	Meaning
type	Required integer, number, boolean or string.
min, max	Optional inclusive numeric bounds, only on numeric fields; min ≤ max.
values	Optional nonempty list of allowed values of the declared type.
default	Optional valid default; without it each recipe must supply the field.

Context field schemas

Supports the type, min, max and values fields described above. Supplied matching context values must conform; unknown fields fail. Missing fields do not satisfy conditions that require them.

context = {
    heat = { type = "integer", min = 0 },
    powered = { type = "boolean" }
}

Ingredient values

Single item

A stack description specifies exact item/damage and count. An ingredient descriptor supports alternatives:

{ anyOf = { 3, 4 }, count = 4, damage = "any" }

Field	Meaning
item	Single item/stack alternative; mutually exclusive with anyOf.
anyOf	Nonempty list of alternatives.
count	Positive required count, default 1.
damage	Optional exact nonnegative damage or string any.
remainder	Optional explicit remainder descriptor for a consumed ingredient.

Do not combine descriptor-only fields with a top-level stack id.

Remainder

remainder = { output = "role", stack = ... } routes a byproduct to a declared single-item output role. Retained ingredients cannot emit remainders. Incompatible combined outputs/remainders are rejected.

Where no explicit remainder is supplied, container-item handling may produce a remainder; application validates its placement together with all outputs.

Item pool

A nonempty list of ingredient values. Requirements can be allocated across the role's bound pool. Use allowExtra to control unmatched occupied slots.

materials = { { item = 12, count = 2 }, { item = 13, count = 2 } }

Item grid

Required pattern list of row strings and key character-to-ingredient map. ingredients is an alias for key. Patterns must be rectangular and conform to the role's dimensions/transform rules.

work = { pattern = { "I ", " I" }, key = { I = 265 } }

Item output pool

A nonempty list of output stacks. Application inserts all outputs across the bound output pool or fails without committing the recipe.

Recipe-type lookup

betamoon.recipeTypes:get(name)

Returns type reference or nil. Accepts a type handle or name, including shaped/shapeless/smelting native aliases.

local type = betamoon.recipeTypes:get("mymod:recipe_type/pressing")

betamoon.recipeTypes:getRequired(name)

Returns type reference or raises an error if absent.

local type = betamoon.recipeTypes:getRequired("smelting")

betamoon.recipeTypes:find(criteria)

Returns a result list with first(), last(), one() and isEmpty() helpers. Optional criteria: name (exact resolved name), owner (exact string), nameContains (substring), ignoreCase (false by default, applies to substring). Unknown fields are errors.

local types = betamoon.recipeTypes:find { nameContains = "mymod:" }

betamoon.recipeTypes:first(criteria)

Returns first match or nil. Same criteria as find, default empty.

local type = betamoon.recipeTypes:first { name = "smelting" }

betamoon.recipeTypes:one(criteria)

Returns sole match, nil if none, error if multiple. Same criteria as find.

local type = betamoon.recipeTypes:one { name = "mymod:recipe_type/pressing" }

Type reference

Properties: name, displayName, owner, exists, ingredients, outputs, primaryOutput, data, context, optional matcher. Schema tables are detached views; modifying them does not change the type.

Native schema views additionally describe list, list, and map<char, item> roles for shapeless/shaped adapters. These role kinds cannot be used for custom ingredient declarations.

Examples: Simple type, advanced types.