Asset Texture Packs

Override script assets with texture packs

Assets / Texture-pack overrides

Place BetaMoon override files beneath bm_assets/ at the root of the texture-pack ZIP. The selected pack supplies overrides; files it does not replace use the script's defaults. Selecting Default restores those defaults.

Registered assets

When a script registers an asset with only a key, its conventional file path determines both the script default and the pack override:

bm_assets/<namespace>/<category>/<key-path>.<extension>

Supported categories are textures, sounds, models, and animations. For a key-only sound, the script must contain exactly one matching .ogg or .wav file; preserve that format in the pack. Use asset:getOverridePath() to obtain the exact expected path.

Registered asset	Override entry
Texture mymod:block/slate	bm_assets/mymod/textures/block/slate.png
Sound mymod:block/machine/click with OGG default	bm_assets/mymod/sounds/block/machine/click.ogg
Sound mymod:block/machine/alarm with WAV default	bm_assets/mymod/sounds/block/machine/alarm.wav
Model mymod:item/robot	bm_assets/mymod/models/item/robot.json
Built-in model minecraft:block/torch	bm_assets/minecraft/models/block/torch.json
Built-in normal GUI button	bm_assets/betamoon/textures/gui/controls/button/normal.png
Animation mymod:item/robot	bm_assets/mymod/animations/item/robot.animation.json

If a script supplies path when registering an asset, that path determines the override instead. For { key = "mymod:block/machine", path = "animated_machine/machine.json" }, a loose script uses betamoon/scripts/animated_machine/machine.json, while a packaged mod uses <package>/assets/animated_machine/machine.json. Put the pack model at bm_assets/animated_machine/machine.json. The key still identifies the asset in Lua. This applies to textures, sounds, models, and animations; the path's case and directories are preserved. Several keys using the same path share one pack entry.

Built-in Minecraft models keep their catalog paths and use the same Bedrock geometry JSON format for bundled files and replacements.

Direct file paths

For an unregistered texture, sound, model, or animation path, BetaMoon reads the default relative to betamoon/scripts or the owning package's assets/ directory. Prefix that exact logical path with bm_assets/ for its override:

Script path	Override entry
dummy.png	bm_assets/dummy.png
textures/slate.png	bm_assets/textures/slate.png
mymod/Textures/Guard.PNG	bm_assets/mymod/Textures/Guard.PNG
mymod/sounds/click.ogg	bm_assets/mymod/sounds/click.ogg

Direct paths preserve case and directory structure, with backslashes normalized to slashes. ZIP entries are case-sensitive. Use lowercase names for portability. Paths must stay relative and cannot contain .., absolute locations, or empty directory segments.

Example pack layout

MyPack.zip
  pack.png
  pack.txt
  bm_assets/
    dummy.png
    mymod/
      textures/block/slate.png
      sounds/block/machine/click.ogg

Overrides follow the same supported file types and size limits as asset registration. Keep texture layout and proportions appropriate for the block, item, armor, or GUI using the image. For animated textures, the pack PNG must be a valid vertical frame strip. Playback settings remain in Lua; a malformed strip falls back to the script default. Block/item frames scale to the selected atlas cell size.

Refresh and troubleshoot

After changing files in the selected ZIP, call betamoon.assets:refresh() from a script callback. The request runs on the next client tick. Re-selecting a pack also refreshes content.

If an override cannot be read or decoded, BetaMoon reports the asset and pack entry and tries the script default. If both replacement sources are unusable, an already loaded asset retains its previous content. Check warnings in the Scripts screen or launcher console, and inspect asset:getSource() to see the source actually in use.

Install BetaMoon's Java agent as described in the installation guide so custom textures load and refresh correctly. Packs supply textures, sounds, models, and numeric animation clips; they do not replace scripts or gameplay definitions.

Model/animation replacements must preserve the bundled names and material requirements used by scripts. Incompatible combinations fall back together. See model compatibility and supported export formats.