API Models and Animations

Model and animation assets

Lua API / Models and animations

Register models and animations

Export files using the supported formats. The Blockbench workflow covers authoring and export.

Function	Result
betamoon.assets.models:add { key, path? }	Model reference. Optional path ends in .json; otherwise use <namespace>/models/<key-path>.json.
betamoon.assets.animations:add { key, path? }	Animation reference. Optional path ends in .animation.json; otherwise use <namespace>/animations/<key-path>.animation.json.

Register in modInit or modReload, before consumers. Keys are exact lowercase namespace:path identifiers. The two registries have separate key spaces. Each registration requires a usable bundled default. Ownership, duplicate handling, and reference inspection follow the asset API.

BetaMoon also supplies built-in Beta 1.7.3 block models under minecraft:block/.... Look them up with get or use their keys directly in appearance.model; they need no registration. Built-ins and texture-pack model replacements use the same supported Bedrock geometry JSON format.

local model = betamoon.assets.models:add {
    key = "mymod:item/robot"
}
local animation = betamoon.assets.animations:add {
    key = "mymod:item/robot"
}

For a single-file mod, these defaults belong at betamoon/scripts/mymod/models/robot.json and betamoon/scripts/mymod/animations/robot.animation.json. In a packaged mod, put the same relative paths beneath the package's assets/ directory. Supply path for another layout; the pack then looks at that same logical path beneath bm_assets/.

Model and animation lookup

Function	Result
betamoon.assets.models:get(key)	Model reference or nil.
betamoon.assets.models:getRequired(key)	Model reference; error when absent.
betamoon.assets.animations:get(key)	Animation reference or nil.
betamoon.assets.animations:getRequired(key)	Animation reference; error when absent.

Model and animation references

Both references expose getKey, getKind, getPath, getOverridePath, and getSource. getKind() returns "models" or "animations" respectively. Use betamoon.assets:refresh() after editing files.

animation:getClips() returns a new table indexed by exact exported clip name. Each entry contains duration in seconds and loop, one of "once", "loop", or "hold".

model:createPose() returns an independent rest pose. Explicit poses retain their geometry version after asset refresh; create a new pose to use updated geometry. Block/item appearances automatically use updated compatible geometry. Explicit poses are useful for inspecting parts, sampling clips, and reading socket transforms.

The Desk Lamp model item example registers a model and inspects one named part.

Pose operations

Method	Behavior
pose:hasPart(part)	Returns whether the named part exists.
pose:setPosition(part, xyz)	Replaces local translation offset relative to rest.
pose:setRotation(part, xyz)	Replaces local rotation delta relative to rest.
pose:setScale(part, xyz)	Replaces nonnegative local scale factors; identity is {x=1,y=1,z=1}.
pose:translate(part, xyz)	Adds to current local translation.
pose:rotate(part, xyz)	Composes additional rotation around the current local axes.
pose:scale(part, xyz)	Multiplies current scale factors.
pose:getPosition(part)	Returns a copied {x,y,z} offset.
pose:getRotation(part)	Returns an equivalent {x,y,z} Euler delta in degrees; angles can wrap.
pose:getScale(part)	Returns copied {x,y,z} factors.
pose:reset(part?)	Restores one part to rest; omit the argument to reset all parts. Resetting a part does not reset its children.
pose:getSocket(name)	Returns {position={x,y,z}, rotation={x,y,z}} for the named exported locator, after parent poses.

Vectors require all three finite coordinates within ±1,000,000. Positions use model units, with 16 units per block, +Y up, and forward -Z. Rotations use degrees and apply local X, then Y, then Z. Parents affect their descendants. Socket results exclude appearance/display transforms and do not change gameplay hitboxes. Missing required parts/locators raise errors.

local pose = model:createPose()
pose:setRotation("head", { x = 0, y = 25, z = 0 })
local headRotation = pose:getRotation("head")
pose:reset("head")

Sample and blend clips

pose:applyAnimation(animation, clip, seconds, weight?, parts?)

• animation: animation reference, registered key, or relative clip path. In onPose, register it beforehand so playback needs no file loading.
• clip: exact exported clip name.
• seconds: finite, nonnegative sample time.
• weight: 0–1, default 1.
• parts: optional dense list of up to 128 exact part names, restricting the affected parts.

Only channels present in the clip are blended. Calls apply in order. Looping clips wrap their time; hold clips keep their last values. A one-shot clip contributes nothing after its duration. Reset an explicit pose before evaluating a new frame. An appearance's onPose receives an already reset pose with its automatic clip applied.

local pose = model:createPose()
pose:reset()
pose:applyAnimation(animation, "animation.robot.idle", 0.5)
pose:applyAnimation(animation, "animation.robot.wave", 0.5, 0.4, { "head" })
pose:rotate("head", { x = 0, y = 10, z = 0 })

This example requires both named clips and the head part. setRotation replaces the clip's rotation channel; rotate adds to it. No clips are required for procedural Lua poses.