API Assets

Assets

Lua API / Assets

Register reusable textures, sound clips, models, and animations in modInit() or modReload(). Use their references or exact namespaced keys in supported texture and sound fields. A single-file mod resolves defaults beneath betamoon/scripts; a packaged mod resolves them from the assets/ directory at its package root.

Register a texture

betamoon.assets.textures:add(definition) → texture reference

Registers a reusable PNG texture asset for block, item, model, armor, override, and container-GUI fields.

local slate = betamoon.assets.textures:add {
    key = "mymod:block/slate"
}

betamoon.blocks:add {
    id = 231, key = "mymod:block/slate", material = "rock",
    texture = slate
}

Field	Type	Meaning
key	string	Required lowercase namespace:path identifier, such as mymod:block/slate.
path	string?	Optional PNG path relative to betamoon/scripts for a single-file mod or the package's assets/ directory. Omit it to use <namespace>/textures/<key-path>.png.
animation	table?	Optional vertical frame-strip playback, shared by uses of this texture asset.

For a single-file mod this looks for betamoon/scripts/mymod/textures/block/slate.png. A directory package looks for <package>/assets/mymod/textures/block/slate.png, and a ZIP package looks for the entry assets/mymod/textures/block/slate.png. To keep a different layout, supply path = "art/slate.png"; a packaged default then lives at assets/art/slate.png. The pack override is bm_assets/art/slate.png. Do not include assets/ or bm_assets/ in path. The key remains mymod:block/slate in every layout.

Every registration needs a usable script default; a pack alone cannot provide it. Always provide the key without file extension, such as mymod:block/slate rather than mymod:block/slate.png.

Declare the texture before using it. Block texture/textures, item texture, armor modelTexture, texture overrides, and container GUI image fields accept texture references, registered texture keys, or relative PNG paths. Numeric atlas options keep their documented meanings. See Textures.

For a block and item sharing one reference, see Registered Texture. The Animated Texture lesson adds frame playback to the same pattern.

PNG files may contain up to 262,144 pixels and occupy up to 8 MiB. Block/item atlas images use the selected atlas cell size; model appearance textures, worn armor, and GUI images retain their dimensions. Animated PNGs use square frames stacked vertically; see Animated textures for timing and validation.

Register a sound clip

betamoon.assets.sounds:add(definition) → sound reference

key is required; path is optional. Without path, BetaMoon looks for both <namespace>/sounds/<key-path>.ogg and .wav beneath the mod's asset root. Exactly one must exist. If both exist, remove one or supply path; if neither exists, registration fails. The selected script file's extension also determines the pack override's extension. A pack cannot switch the format by providing the other extension. An explicit path must end in .ogg or .wav.

local click = betamoon.assets.sounds:add {
    key = "mymod:block/machine/click"
}

Clips support mono or stereo, with 8-bit or 16-bit decoded samples. Positional playback requires mono; stereo clips can play without a position. Encoded files are limited to 8 MiB and decoded samples to 32 MiB per clip. Use short clips for one-shot effects. See Sound events and playback.

Register models and animations

Use betamoon.assets.models:add { key, path? } for geometry and betamoon.assets.animations:add { key, path? } for clips. Without path, model defaults use <namespace>/models/<key-path>.json and animation defaults use <namespace>/animations/<key-path>.animation.json beneath the mod's asset root. See model asset registration and supported exports.

Look up an asset

Function	Result
betamoon.assets.textures:get(key)	Texture reference, or nil when absent.
betamoon.assets.textures:getRequired(key)	Texture reference; raises an error when absent.
betamoon.assets.sounds:get(key)	Sound reference, or nil when absent.
betamoon.assets.sounds:getRequired(key)	Sound reference; raises an error when absent.

Keys are exact and namespaced. Texture and sound registries have separate key spaces, so the same key can identify one texture and one sound. Duplicate declarations in one initialization and attempts to claim another script's key raise errors. Other scripts can use successfully initialized dependencies' assets; use script dependencies and modules when sharing content.

local slate = betamoon.assets.textures:getRequired("mymod:block/slate")

Inspect a reference

Texture and sound references expose these methods:

Method	Result
asset:getKey()	Exact namespaced key.
asset:getKind()	"textures", "sounds", "models", or "animations".
asset:getPath()	Resolved script-relative default path, or packaged path for a built-in model.
asset:getOverridePath()	Expected texture-pack override path, including bm_assets/: the resolved script path prefixed with bm_assets/ for registered script assets. Built-ins use their catalog paths.
asset:getSource()	Table with kind, name, and path for the currently usable content.

getSource().kind is "pack", "script", or "builtin"; name identifies the selected source and path is its selected entry or relative default path. Built-in models are listed in the Minecraft model catalog. After a failed refresh, this may describe the previous usable content. References identify keys across compatible reloads; looking up source/path information raises an error if the asset is no longer registered.

local source = slate:getSource()
betamoon.chat:send("Texture source: %s / %s", source.kind, source.path)
betamoon.chat:send("Pack override: %s", slate:getOverridePath())

Refresh and reload

betamoon.assets:refresh() requests a refresh at the next client tick. Use it after editing texture, sound, model, or animation files. Selecting a texture pack also refreshes assets. See texture-pack overrides for lookup paths and fallback behavior.

betamoon.assets:refresh()

An invalid override falls back to a usable script default and reports a warning. If neither replacement is usable, an already loaded asset keeps its previous content. Initial asset registration fails when no usable source exists.

Re-register assets and sound events during initialization. Reloadable scripts release their registrations on unload; retained scripts keep them. Existing retained block/item visuals can continue displaying their last usable textures. A failed script initialization does not publish its new asset registrations. See reload and compatibility.