API Textures

Textures

Lua API / Textures

On this page

• Resource paths
• Animated textures
• Block texture
• Block textures
• Item icon
• Item texture
• Model appearance textures
• Armor model textures
• GUI images

Resource paths

Custom textures are PNG files relative to betamoon/scripts for a single-file mod or relative to a packaged mod assets/ directory. Keep required asset subdirectories when installing a mod. Texture fields also accept registered texture assets or their exact namespaced keys. Direct paths and registered assets use their logical mod-relative file path beneath bm_assets/ for texture-pack overrides.

Animated textures

An animated PNG is a vertical strip of square frames: a 16-pixel-wide image with three frames is 16×48 pixels. Declare playback on a reusable texture asset, then use its reference wherever a BetaMoon texture field accepts an asset:

local ember = betamoon.assets.textures:add {
    key = "mymod:effects/ember",
    path = "effects/ember_frames.png",
    animation = { frameTicks = 2 }
}

-- The same reference works in block and item texture fields, fluid still/flowing
-- textures, model materials, armor model textures, and GUI image fields.

For a direct file path or a different speed at one use, put the same description in the texture field:

texture = {
    asset = "effects/ember_frames.png",
    animation = { frameTicks = 3 }
}

asset accepts a texture reference, exact namespaced key, or relative PNG path. An inline animation replaces the asset's playback settings for that use; animation = false shows the first frame. A descriptor with no animation uses the asset's declared playback or remains static. Plain texture strings and references retain their existing behavior.

Animation field	Meaning
layout	"vertical"; the default and currently supported layout.
frameTicks	Integer 1–1200, default 1. Two ticks per frame gives 10 frames per second at the usual 20 client ticks per second.
sequence	Optional dense list of one-based frame numbers, at most 256 entries. The default plays frames in image order. Repeating a number holds that frame longer. Playback loops.
clock	"client" (default) continues in menus and while paused; "unpaused" stops while the game is paused.

The first frame appears immediately; the next appears after frameTicks eligible ticks. Every use of the same asset and playback settings shows the same frame. Texture animation changes pixels, not block metadata, model pose, or fluid flow. Model textures can animate while their block model remains statically rendered. Playback phase cannot be set per individual block or item instance.

The PNG must have width W and height W × N, with 1–256 frames. A one-frame strip displays as a static image. Files are limited to 8 MiB and 262,144 decoded pixels. Invalid dimensions, sequence indices, or pack overrides produce an error or warning; an invalid override falls back to the script's valid default. Block/item frames scale individually to the current atlas cell size. Model, armor, and GUI frames retain their dimensions; GUI layout uses one frame's dimensions. Numeric atlas indices keep their original meaning and cannot be animated by this descriptor.

Block texture

texture accepts an integer atlas index, texture asset reference/key, or PNG path and sets the base texture.

texture = "textures/slate.png"

Block textures

textures maps face names to atlas indices, texture asset references/keys, or PNG paths. Assignments are applied from broad to specific: all, sides/side, top, bottom, north, south, west, east, front, back.

Key	Meaning
all	All six faces.
sides / side	Four horizontal faces; sides takes precedence when both exist.
top, bottom	Up and down.
north, south, west, east	Physical horizontal faces.
front, back	Static aliases for south and north, respectively.

textures = { all = 1, top = 2, north = "textures/front.png" }

Use metadata render variants to select oriented textures.

Item icon

icon = { x = column, y = row } uses zero-based atlas coordinates. Both fields are required; index is x + y × 16.

icon = { x = 7, y = 3 }

Item texture

texture = "path.png" supplies the inventory/held item image instead of a native icon. Item declarations accept a texture reference, registered texture key, or PNG path here; item overrides also accept atlas indices. Block/item images are scaled to 16×16.

Model appearance textures

appearance.texture and material texture fields accept texture references, keys, or PNG paths and retain the image's dimensions. See model material fields for slots, UV transforms, and blending.

Armor model textures

modelTexture accepts a texture reference/key or PNG path and supplies a worn armor layer, separate from texture. Conventional item images are 16×16 and worn layers 64×32. See Armor.

GUI images

Container GUI background and element images accept texture references/keys or PNG paths and use their own pixel dimensions. See Container GUIs.

Examples: Custom textures and Animated texture.