Tree Texture Configuration

Configure textures for trees, the primary source of wood and other organic resources.

Trees are large world objects that serve as the primary source of wood and other organic resources. They are placed during world generation or by gameplay events, and can be chopped down by players. Their textures are declared in a YAML config file, one per mod.

File Location

Config file:

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

Texture images go in the same folder:

mods/<your-mod>/assets/textures/trees/<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_tree
    sprites:
      - name: my_tree
        frame-count: 1
    frame-width: 400
    frame-height: 500

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

Full Field Reference

textures:
  - name: my_tree                # Required. Registered as YourMod:my_tree
    override: Creation:oak_tree  # Optional. Replace another mod's registered tree (see below)
    light-mask: my_tree_mask     # Optional. Light mask texture (see below)
    frame-width: 400             # Required. Width of one frame in pixels
    frame-height: 500            # Required. Height of one frame in pixels
    sprites:                  # Required. One or more named animation sequences
      - name: my_tree            # Required. Animation/sprite 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: 3
            duration-ms: 80
          - count: 2
            duration-ms: 300
    states:                      # Optional. Named static poses
      - name: bare               # State name used by scripts
        sprite: my_tree          # Which sprite this state uses
        frame: first             # first, last, or a frame number (0-based)

Sprite Sheet Format

All sprites for a tree 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.

For most trees, there is one sprite with one frame, so the image is exactly frame-width × frame-height pixels.

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 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, 200]

Batch — a duration applied to several consecutive frames:

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

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.

Light Masks

A light mask controls how a tree 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: glowing_tree
    sprites:
      - name: glowing_tree
        frame-count: 1
    frame-width: 400
    frame-height: 500
    light-mask: glowing_tree_mask

Place glowing_tree_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 tree emits no special light).

Overrides

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

textures:
  - name: oak_tree
    override: Creation:oak_tree
    sprites:
      - name: oak_tree
        frame-count: 1
    frame-width: 312
    frame-height: 380

• 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 tree.
• 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

An oak tree with two seasonal sprites:

textures:
  - name: oak_tree
    sprites:
      - name: oak_tree
        frame-count: 1
      - name: oak_tree_bare
        frame-count: 1
    states:
      - name: leafy
        sprite: oak_tree
        frame: first
      - name: bare
        sprite: oak_tree_bare
        frame: first
    frame-width: 618
    frame-height: 677

Sprite sheet layout (618 px wide × 677 px tall frames, 1 column × 2 rows):

[ leafy tree ]   ← row 0: OAK TREE
[ bare tree  ]   ← row 1: OAK TREE BARE

Total image size: 618 × 1354 px.