Mob Texture Configuration

Configure textures for mobs — wandering animals, hostile enemies, bosses, and custom creatures.

Mobs are creatures and enemies that move through the world: wandering animals, hostile enemies, bosses, and any custom mob added by a mod. Their textures are declared in a YAML config file, one per mod.

File Location

Config file:

mods/<your-mod>/assets/textures/mobs/mobs.yaml

Texture images go in the same folder:

mods/<your-mod>/assets/textures/mobs/<name>.png

The file name must match the name field exactly (case-sensitive), with spaces kept as spaces in the file name.

Minimal Example

textures:
  - name: my_creature
    sprites:
      - name: idle
        frame-count: 1
    frame-width: 32
    frame-height: 32

This registers a mob named my_creature from my_creature.png. It will be referred to as YourMod:my_creature anywhere a mob name is expected.

Full Field Reference

textures:
  - name: my_creature          # Required. Registered as YourMod:my_creature
    override: Creation:glorbo  # Optional. Replace another mod's registered mob (see below)
    light-mask: my_creature_mask  # Optional. Light mask texture (see below)
    frame-width: 32            # Required. Width of one frame in pixels
    frame-height: 64           # Required. Height of one frame in pixels
    sprites:                # Required. One or more named animation sequences
      - name: walking          # Required. Animation name
        frame-count: 8         # Required. Number of frames in this animation
        frame-time-ms: 100     # Optional. Milliseconds per frame (default: 100)
        frame-durations-ms:    # Optional. Per-frame timing override (see below)
          - count: 6
            duration-ms: 80
          - count: 2
            duration-ms: 300
      - name: idle
        frame-count: 4
        frame-time-ms: 200
    states:                    # Optional. Named static poses
      - name: idle             # State name used by scripts
        sprite: idle           # Which sprite this state uses
        frame: first           # first, last, or a frame number (0-based)

Sprite Sheet Format

All sprites for a mob share one sprite sheet image. The image is a grid:

• Columns — frames, read left to right. Total image width = frame-width × column count.
• Rows — sprites, stacked top to bottom. Total image height = frame-height × sprite count.

The first sprite declared in the YAML corresponds to the top row; the second to the row below it, and so on.

[ var 0, frame 0 ][ var 0, frame 1 ] …   ← row 0 (first sprite)
[ var 1, frame 0 ][ var 1, frame 1 ] …   ← row 1 (second sprite)

All rows must have the same number of columns. If a sprite uses fewer frames than the column count, fill the unused columns with transparent/empty pixels.

Per-Frame Timing

By default all frames in an animation display for the same duration (frame-time-ms). To give individual frames different hold times, add frame-durations-ms to the sprite.

Two entry formats are supported and can be mixed freely:

Flat — one value per frame:

frame-durations-ms: [80, 80, 120, 120, 200]

Batch — a duration applied to several consecutive frames:

frame-durations-ms:
  - count: 3
    duration-ms: 80
  - count: 2
    duration-ms: 200

Both produce the same result: frames 0–2 last 80 ms each, frames 3–4 last 200 ms each.

Note: The total number of entries (after expanding batches) must equal frame-count exactly. If the counts do not match, frame-durations-ms is ignored and frame-time-ms is used for all frames instead.

States

States let scripts snap a mob to a specific visual pose without playing an animation. Use frame: first for the first frame, frame: last for the last frame, or a zero-based number for any specific frame.

states:
  - name: idle
    sprite: idle
    frame: first

Light Masks

A light mask controls how a mob interacts with the lighting system. It must be a PNG the same size as the full sprite sheet. White pixels (255, 255, 255) emit full light; black pixels (0, 0, 0) block light entirely.

  - name: the_creature
    sprites:
      - name: the_creature
        frame-count: 1
    frame-width: 128
    frame-height: 128
    light-mask: the_creature_mask

Place the_creature_mask.png in the same folder as the main texture. If no light-mask is specified, a fully opaque white mask is generated automatically (the mob emits no special light).

Reusing Configuration with YAML Anchors

Mobs that share animation sets, states, or timing (e.g. several similar creatures with the same WALK/IDLE cycle) don’t need to duplicate that YAML by hand. Standard YAML anchors (&name) and aliases (*name) let you define a block once and reuse it anywhere in the same file — the parser resolves the alias to a full copy of the anchored block before the mob config is read, so no special loader support is needed.

Anchor whichever block is actually shared — a single sprite list, a states block, or anything else — and leave the rest of the entry free to differ:

textures:
  - name: pumpkling
    sprites: &basic_walk_cycle
      - name: idle
        frame-count: 4
        frame-time-ms: 100
      - name: walk
        frame-count: 6
        frame-time-ms: 100
    frame-width: 73
    frame-height: 68
  - name: wickermourn
    sprites: *basic_walk_cycle   # identical animation set, reused
    frame-width: 226                # its own frame size
    frame-height: 132

Note: An alias is a full substitution, not a merge — *basic_walk_cycle copies the entire anchored block as-is. You cannot reuse a block and then tweak just one field inside it; anchor only the smallest block that is genuinely identical across entries, and declare anything that varies outside of it.

Overrides

Your mod can replace the texture used for any mob from another mod without changing that mod’s files. Add override with the full mod-namespaced name of the mob to replace:

textures:
  - name: glorbo
    override: Creation:glorbo
    sprites:
      - name: glorbo
        frame-count: 1
    frame-width: 32
    frame-height: 32

• The name field is still required (it is used to locate your replacement PNG in your mod’s folder).
• Your texture file must match the frame dimensions of the original mob.
• Your override entry fully replaces the animation configuration of the original, so you must redeclare all sprites, states, and timing you want to keep.

Complete Example

A creature with two animation sprites and an idle state:

textures:
  - name: pumpkling
    sprites:
      - name: walking
        frame-count: 10
        frame-time-ms: 100
        frame-durations-ms:
          - count: 8
            duration-ms: 500
          - count: 2
            duration-ms: 20000
      - name: idle
        frame-count: 10
        frame-time-ms: 200
        frame-durations-ms:
          - count: 5
            duration-ms: 150
          - count: 5
            duration-ms: 300
    states:
      - name: idle
        sprite: idle
        frame: first
    frame-width: 32
    frame-height: 64

Sprite sheet layout (32 px wide × 64 px tall frames, 10 columns × 2 rows):

[ W0 ][ W1 ][ W2 ][ W3 ][ W4 ][ W5 ][ W6 ][ W7 ][ W8 ][ W9 ]   ← row 0: WALKING
[ I0 ][ I1 ][ I2 ][ I3 ][ I4 ][ I5 ][ I6 ][ I7 ][ I8 ][ I9 ]   ← row 1: IDLE

Total image size: 320 × 128 px.