API Items

Items

Lua API / Items

On this page

• betamoon.items:add(definition)
• Field definitions
  • Identity and basic fields
  • Food
  • use
  • tool
  • render.variants
    • render.variants[metadata].appearance
  • Callbacks
• Item lookup
• Item references and overrides
• Errors and reload

betamoon.items:add(definition)

Registers an item from a required table and returns an item reference. Use type = "fluid_bucket" only with an unpublished token from the advanced fluid API; its stack/container behavior is fixed.

local token = betamoon.items:add {
    id = 5024, key = "mymod:item/token", displayName = "Token",
    icon = { x = 7, y = 3 }
}

Field definitions

Identity and basic fields

Field	Type	Default / meaning
id	integer	Required shifted item ID, at least 256 and below the runtime registry size. Choose an unused ID.
key	string	Recommended internal name field.
internalName	string	Identity alias taking precedence over name and key.
name	string	Identity alias, preferred over key. One identity field is required.
displayName	string	Resolved internal name when omitted.
type	string	Default item; also food, sword, pickaxe, axe, shovel, hoe, armor.
maxStackSize	integer	Ordinary item/food stack limit; omitted keeps the native default.
maxDamage	integer	Optional durability override for ordinary items, food and tools.
hasSubtypes	boolean	Optional metadata subtype flag for ordinary items and food.
full3D	boolean	Default false; enables full-3D held-item rendering.
icon.x, icon.y	integers	Both required when icon is supplied; column/row in the 16-column item atlas.
texture	texture reference or string	Optional registered texture asset/key or PNG path relative to betamoon/scripts; replaces icon texture. See Assets.
appearance	table	Default model appearance for inventory, held, and dropped presentation; variants may replace it.

See Tools and armor for material, slot, modelTexture, renderIndex, efficiency and damageVsEntity.

Food

Set type = "food".

type = "food",
food = { healing = 4, wolfFood = true }

Field	Type	Meaning
food.healing	integer	Required healing amount when food is a table.
healing	integer	Alternative required healing field when no food table is supplied.
food.wolfFood	boolean	Default false; permits feeding wolves.

Food consumes exactly one item. Explicit use.consume must therefore be 1, and food cannot also fire a projectile.

use

Optional policy table for item use.

use = { projectile = "snowball", ammunition = 332, cooldown = 20 }

Field	Type	Default / meaning
consume	integer 0–64	0 for ordinary items, 1 for food. Number consumed by successful use policy.
remainder	item ID/reference	Optional replacement/byproduct after consumption. Requires a registered non-air item and consumption.
cooldown	integer 0–1000000	0; delay in world ticks after successful use. Tracked per player and item definition.
projectile	string or entity type reference	Optional snowball, egg, arrow, or a namespaced registered custom projectile type.
ammunition	item ID/reference	Optional registered ammunition; requires projectile.

A cooldown of zero disables the delay. Remainders replace an exhausted held stack, otherwise go into the inventory or drop when it is full. Missing ammunition, insufficient count or an active cooldown prevents the use policy from proceeding. If projectile insertion fails, ammunition is not spent and no cooldown starts. See custom projectiles.

Use callbacks and their outcomes are documented in Item callbacks.

tool

Adds tool classes and durability policy independently of the item's vanilla kind.

tool = { classes = { pickaxe = 2, shovel = 2 }, efficiency = 6 }

Field	Type	Default / meaning
classes	map of strings to integers 0–255	No additional classes. Maps each Forge tool class to its harvest level.
efficiency	number, greater than 0 and at most 100000	Optional speed for effective blocks; cannot also specify top-level efficiency.
durabilityCost.mine	integer 0–32767	Omitted uses normal mining cost; zero disables that cost.
durabilityCost.hit	integer 0–32767	Omitted uses normal hit cost; zero disables that cost.

render.variants

Table keyed by damage/metadata integers 0–32767. Each entry accepts icon (atlas index 0–255, omitted uses normal icon), color (RGB integer 0–0xFFFFFF, default white), and appearance. Icon and color apply when no model is selected.

hasSubtypes = true,
render = { variants = { [1] = { icon = 12, color = 0xFFAA00 } } }

render.variants[metadata].appearance

Optional model appearance for that exact item damage/metadata value. It applies in inventory, held, and dropped contexts.

• A table completely replaces the top-level appearance; nested fields are not merged.
• Omit it to inherit the top-level appearance.
• Set it to false to use the ordinary item icon, including the variant's icon and color.

-- Fields inside an item declaration; register the named assets first:
hasSubtypes = true,
appearance = { model = "mymod:item/token", texture = "mymod:item/token" },
render = {
    variants = {
        [1] = { appearance = {
            model = "mymod:item/charged_token", texture = "mymod:item/charged_token"
        } },
        [2] = { appearance = false, icon = 12 }
    }
}

Unlisted metadata uses the default model. For material, animation, and pose callback fields, see model appearances.

Callbacks

See Item callbacks for every callback including inventory ticks.

Item lookup

Use betamoon.items:get, getRequired, find, first, or one to retrieve item references. See References and stacks for the method contracts and query fields.

Item references and overrides

Item references expose the item's live properties and support layered changes through reference:override(definition). See References and stacks for the reference properties and override behavior.

Errors and reload

Invalid IDs, missing fields, unsupported properties for an item kind, invalid use combinations and unresolved required resources fail initialization.

Examples: Simple item, subtypes.