Item Texture Configuration

Configure the dropped-in-world sprite for an item — sprite sheet, animation, and light mask.

Item textures control how an item looks when it exists as a physical object in the world — dropped on the ground or otherwise rendered as an entity. This is separate from the item’s inventory icon (there is no separate inventory icon config; the same sprite sheet is used, sliced to its first frame). The item must already be registered in Item Configuration — texture loading looks up the item’s ID by name and fails if it isn’t found.

File Location

Config file:

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

Texture images go in the same folder:

mods/<your-mod>/assets/textures/items/<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_item
    sprites:
      - name: default
        frame-count: 1
    frame-width: 32
    frame-height: 32

This registers the dropped-item sprite for my_item (an item that must already exist in item-config.yaml) from my_item.png.

Full Field Reference

textures:
  - name: my_item              # Required. Must match a name already registered in item-config.yaml
    override: Creation:coal    # Optional. Replace another mod's item texture (see below)
    light-mask: my_item_mask   # Optional. Light mask texture (see below)
    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 sequences
      - name: default          # Required. Animation name
        frame-count: 1         # 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: 1
            duration-ms: 100
    states:                    # Optional. Named static poses
      - name: idle
        sprite: default
        frame: first

Field	Required	Description
`name`	Yes	Must match a `name` already registered in `item-config.yaml`.
`override`	No	Full name of another mod’s item to replace (e.g. `Creation:coal`). See Overrides.
`light-mask`	No	Name of a separate PNG used as the light emission mask. See Light Masks.
`frame-width`	Yes	Width of a single frame in pixels.
`frame-height`	Yes	Height of a single frame in pixels.
`sprites`	Yes	List of named animation sequences. At least one required.
`sprites[].name`	Yes	Animation name.
`sprites[].frame-count`	Yes	How many frames this animation plays through.
`sprites[].frame-time-ms`	No	Milliseconds per frame for uniform timing. Default: `100`.
`sprites[].frame-durations-ms`	No	Per-frame timing override. See Per-Frame Timing.
`states`	No	Named static poses.
`states[].name`	Yes	State name.
`states[].sprite`	Yes	Which sprite this state uses.
`states[].frame`	Yes	`first`, `last`, or a zero-based frame index.

This is the same animation schema used by Mob Texture Configuration — see that page for the full sprite sheet layout diagram, per-frame timing formats, and YAML anchor/alias reuse pattern, all of which apply identically here.

Sprite Sheet Format

All sprites for an item share one sprite sheet image, laid out the same way as mob textures: columns are frames (left to right), rows are sprites (top to bottom, in declaration order). The image’s top-left frame-width × frame-height region (the first frame of the first sprite) is also what’s used to render the item in inventory slots and hotbars.

Per-Frame Timing

Same flat/batch frame-durations-ms format as Mob Texture Configuration. If the total entries (after expanding batches) don’t equal frame-count exactly, the override is ignored and frame-time-ms is used for all frames.

Light Masks

Same convention as mob textures: a same-size PNG placed alongside the main texture, white pixels emit full light and black pixels block it. If omitted, a fully opaque white mask is generated automatically. See Mob Texture Configuration — Light Masks.

Overrides

Your mod can replace the dropped-item sprite for an item from another mod without touching that mod’s files. Add override with the full mod-namespaced name of the item to replace:

textures:
  - name: fancy_coal
    override: Creation:coal
    sprites:
      - name: default
        frame-count: 1
    frame-width: 32
    frame-height: 32

The name field is still required (it locates your replacement PNG in your mod’s folder).
Your texture file must match the frame dimensions of the original item.
The override fully replaces the animation configuration of the original — redeclare all sprites and states you want to keep.

Complete Example

Based on the real shipped item textures:

textures:
  - name: coal
    sprites:
      - name: coal
        frame-count: 1
    frame-width: 32
    frame-height: 32
  - name: crafting_bench
    sprites:
      - name: crafting_bench
        frame-count: 1
    frame-width: 32
    frame-height: 32