API References and Stacks

References and stacks

Lua API / References and stacks

On this page

• Registry methods
• get(identifier)
• getRequired(identifier)
• find(criteria)
• first(criteria)
• one(criteria)
• Resource references
  • Common reference properties
  • Block reference properties
  • Item reference properties
• reference:override(definition)
• betamoon.stack(item, count, damage)
• Stack input formats

Registry methods

The following lookup methods are available on betamoon.blocks, betamoon.items, betamoon.tools and betamoon.armor. Registration is documented in Blocks and Items.

get(identifier)

Returns a reference to existing content, or nil if missing. The required identifier is a numeric ID, registered-name string, or compatible block/item reference. Lookup by reference uses its ID and returns damage zero.

local optional = betamoon.items:get("optional_item")

Name lookup accepts internal names with or without the tile. / item. prefix and also accepts a namespace prefix before :. That prefix does not constrain ownership.

getRequired(identifier)

Same lookup as get, but raises a Lua error if content is missing. Returns a reference.

local stone = betamoon.blocks:getRequired(1)

find(criteria)

Returns all matching references in a result list. Optional criteria default to {}. See query criteria.

local picks = betamoon.tools:find { type = "pickaxe" }

first(criteria)

Returns the first matching reference, or nil. Optional criteria default to {}. Multiple matches are allowed; use specific filters when the selected identity matters.

local pick = betamoon.tools:first { type = "pickaxe" }

one(criteria)

Returns the sole matching reference; returns nil for no match; raises an error for multiple matches. Optional criteria default to {}.

local stone = betamoon.blocks:one { id = 1 }

Tool and armor registries filter searches to their respective categories. Their direct get / getRequired lookups use the item registry and do not apply the search category filter.

Resource references

Common reference properties

Inspectable override-capable properties are live reads of the effective value. Editing a Lua table field is not a supported way to edit underlying content; use overrides.

Property	Type	Meaning
id	integer	Numeric content ID.
damage	integer	Metadata/damage variant represented by a search result; zero on direct lookup.
name	string or nil	Internal Minecraft name.
key	string or nil	Same internal name exposed as a key.
displayName	string or nil	Translated display name.
owner	string	Owning BetaMoon script filename, or "minecraft" for untracked content.
isVanilla	boolean	True for untracked content; not proof that another Java mod did not register it.
isBetaMoon	boolean	True when BetaMoon tracks an owner.
exists	boolean	True when this reference was constructed; not a live existence probe.

Block reference properties

Property	Type	Meaning
texture	integer	Base terrain atlas index.
light	integer	Registered emitted light.
lightOpacity	integer	Registered light opacity.
hardness	number or nil	Stored hardness if inspectable.
resistance	number or nil	Stored resistance if inspectable; native storage may differ from declaration scaling.
stepSound	string	Effective step-sound name.
slipperiness	number	Effective movement slipperiness. Vanilla ice, for example, uses a higher value than ordinary blocks.
unbreakable	boolean	Whether the effective hardness marks the block as unbreakable.
fire	table	Effective { spread, burn } fire values. Both entries are integers.
fluid	fluid reference or nil	Present for registered flowing/still fluid blocks.
fluidRole	flowing, still, or nil	Explicit role in the paired fluid registration.

Item reference properties

Property	Type	Meaning
maxStackSize	integer	Stack limit.
maxDamage	integer	Maximum durability/damage value.
hasSubtypes	boolean	Whether metadata denotes subtypes.
icon	integer	Icon index for this damage value.
type	string	Item kind, such as item, food, pickaxe, or armor.
category	string	item, tool, or armor.
full3D	boolean	Whether the item uses the full-3D held-item transform.
efficiency	number or nil	Effective tool efficiency when the item exposes one.
damageVsEntity	integer or nil	Effective entity damage when the item exposes one.
fluid	fluid reference or nil	Present for a registered filled fluid bucket.

reference:override(definition)

Applies supported changes to the registered content and returns an override handle. See Overrides.

betamoon.stack(item, count, damage)

Creates a detached stack description. It does not spawn an item or modify an inventory.

Parameter	Type	Default
item	numeric ID or block/item reference	Required
count	integer	1
damage	integer	Reference damage, otherwise 0

Returns: { id, item, count, damage }; item holds the supplied ID or resolved reference. The consuming API validates the stack for its purpose.

local ingots = betamoon.stack(betamoon.items:getRequired(265), 4)

Stack input formats

Native recipes and tile inventory methods accept a numeric ID, a compatible reference, a named table { id = 265, count = 4, damage = 0 }, or a positional table { 265, 4, 0 }. Missing count/damage default to one/zero. Custom recipes use the stricter role-specific formats in Recipe types.

A live stack access object is not a detached stack description.

Example: Resource references.