Wielded Item Texture Configuration

Configure sprites and animations for weapons and tools held by players and mobs.

Wielded items are the weapons and tools held by players and mobs during gameplay. Each wielded item can have one or more named sprites, each with its own sprite strip and optional animation timing.

File Location

Wielded item textures are declared in:

mods/<your-mod>/assets/textures/wielded-items/wielded-items.yaml

Texture images go in the same folder:

mods/<your-mod>/assets/textures/wielded-items/<item-name>.png

One PNG file per item, named after the item (e.g. my_sword.png). All sprites for that item are packed into the same file as vertical rows.

Minimal Example

textures:
  - name: my_sword
    sprites:
      - name: my_sword_jab
        frame-count: 1
    frame-width: 32
    frame-height: 32

This registers a wielded item named my_sword with a single static sprite loaded from my_sword.png. It will be referenced as YourMod:my_sword anywhere a wielded item name is expected.

Full Field Reference

textures:
  - name: my_sword              # Required. Registered as YourMod:my_sword
    frame-width: 32             # Required. Width of one frame in pixels
    frame-height: 32            # Required. Height of one frame in pixels
    sprites:                 # Required. One or more named animation states
      - name: my_sword_jab      # Required. Name of this sprite (animation state)
        frame-count: 4          # Required. Number of frames in the sprite strip
        frame-time-ms: 80       # Optional. Milliseconds per frame (default: 100)
        frame-durations-ms:     # Optional. Per-frame timing override (see below)
          - count: 2
            duration-ms: 50
          - count: 2
            duration-ms: 400
    wielded-item-data:          # Optional. Visual behavior settings
      texture-rotation-offset-degrees: 45.0   # Optional. Visual rotation offset in degrees

Top-level fields

Sprite fields

wielded-item-data fields

How Sprites Play

Which sprite (row) is shown is driven by two mechanisms — the sprite name matters only through them:

• IDLE is automatic. A sprite named exactly IDLE is played, and looped, as soon as the item is equipped — and again whenever a one-shot animation finishes. It is the only name the engine plays on its own. An item with no IDLE sprite just shows its first sprite’s first frame while held.
• Everything else is script-triggered. Any other sprite plays only when the item’s Lua script triggers it by name — for example a weapon’s server-on-primary-use hook calling entity:animate("SWING", false). The sprite name you declare must match the string the script passes; when the animation finishes, the item returns to its IDLE loop (or its static first frame).

So a name that nothing plays — e.g. a lone my_sword_jab sprite that no script triggers — simply serves as the item’s static held sprite; any string would behave identically. Reserve IDLE for the held-idle loop, and match your attack/use sprite names to whatever your item’s script sends.

Sprite Sheet Format

All sprites for an item live in a single PNG file. The image is a 2D grid:

• Columns = frames within a sprite, read left to right
• Rows = sprites, in declaration order (first sprite = top row)

[ var0 frame 0 ][ var0 frame 1 ][ var0 frame 2 ]   ← sprite 0 (top row)
[ var1 frame 0 ][ var1 frame 1 ][ var1 frame 2 ]   ← sprite 1
[ var2 frame 0 ][ var2 frame 1 ][ var2 frame 2 ]   ← sprite 2

• Total image width = frame-width × frames-per-row
• Total image height = frame-height × number-of-sprites

All rows must have the same number of columns. The column count is derived from the image width divided by frame-width. If two sprites have different frame counts, size the image to fit the one with the most frames and leave the unused columns in shorter sprites as transparent pixels.

For a single-sprite item with one frame, the image is exactly frame-width × frame-height.

Per-Frame Timing

By default, all frames 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: [50, 50, 400, 400]

Batch — a duration applied to several consecutive frames:

frame-durations-ms:
  - count: 2
    duration-ms: 50
  - count: 2
    duration-ms: 400

Both produce the same result: frames 0–1 display for 50 ms each, frames 2–3 display for 400 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.

Multiple Sprites

A wielded item can have several named sprites — for example, separate animations for different attack types or states. Each sprite is triggered independently by the engine or via the Lua API.

textures:
  - name: my_weapon
    frame-width: 32
    frame-height: 64
    sprites:
      - name: my_weapon_jab
        frame-count: 1
      - name: my_weapon_swing
        frame-count: 6
        frame-time-ms: 60
      - name: my_weapon_idle
        frame-count: 3
        frame-time-ms: 200
        frame-durations-ms:
          - count: 1
            duration-ms: 1000
          - count: 2
            duration-ms: 100

All three sprites live in a single file my_weapon.png, which is 6 × frame-width wide (sized to the longest sprite) and 3 × frame-height tall — one row per sprite, top to bottom in declaration order. The JAB and IDLE rows have fewer active frames; their unused rightmost columns are left transparent.

Overrides

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

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

• The name field is still required — it is used to locate your replacement PNG in your mod’s folder.
• Your override entry fully replaces the target’s registered texture, so redeclare every sprite you want to keep.

Complete Example

A sword with a static jab sprite and an animated swing with mixed frame timing:

textures:
  - name: my_sword
    frame-width: 32
    frame-height: 32
    sprites:
      - name: my_sword_jab
        frame-count: 1
      - name: my_sword_swing
        frame-count: 4
        frame-time-ms: 80
        frame-durations-ms:
          - count: 1
            duration-ms: 40
          - count: 2
            duration-ms: 80
          - count: 1
            duration-ms: 300
    wielded-item-data:
      texture-rotation-offset-degrees: 45.0

The texture file is my_sword.png — 4 × 32 = 128 pixels wide and 2 × 32 = 64 pixels tall. Row 0 (top) is the JAB sprite’s single frame padded to 4 columns wide; row 1 is the SWING sprite’s 4 frames. The swing animation has 4 frames: the first snaps on quickly (40 ms), the middle two advance at normal pace (80 ms each), and the last frame lingers at the end of the swing (300 ms) before the animation completes.