Tree Configuration

Register breakable static objects that spawn naturally during world generation.

Trees are breakable static objects that spawn naturally during world generation. This is the catalog file that registers them.

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

tree-config: tree-config.yaml

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/tree-config.yaml

The file is a single list of tree entries. Each entry represents one tree type (a natural-spawn group) and contains one or more named variations — the actual placeable objects. Mechanical fields (hitbox, tool-break-types, power-required, time-to-break-ms, drop-table) can be declared once at the tree level and every variation inherits them, so variations that differ only in appearance need nothing but a name:

trees:
  - name: my_oak
    spacing:
      x: 20
      y: 20
    max-size:
      width: 10
      height: 15
    spawn-chance: 1.0
    hitbox:
      width: 10.0
      height: 10.0
    tool-break-types: axe
    drop-table:
      drops:
        - item: oak_log
          min-amount: 4
          max-amount: 25
          chance: 1.0
    variations:
      - name: my_oak
      - name: my_oak_2

Both variations here share the tree-level hitbox, tool and drop-table; they differ only in which texture the world picks for them. A variation can still override any inherited field by declaring its own (see Field Inheritance).

Names — the tree entry’s name, each variation’s name, and item references like the item: in a drop — are automatically prefixed with your mod name unless you write a colon yourself. Write bare names (oak_log) for your own content; only add a prefix (OtherMod:their_item) to reference another mod.

Minimal Example

trees:
  - name: my_oak
    spacing:
      x: 20
      y: 20
    max-size:
      width: 10
      height: 15
    spawn-chance: 1.0
    hitbox:
      width: 10.0
      height: 10.0
    variations:
      - name: my_oak

Fields

A tree entry with no valid variations is skipped entirely (logged as an error) — at least one variation must parse successfully.

Choosing where a tree spawns

A tree spawns in a biome when the two are linked, and either side can declare the link:

# From the tree's side, in tree-config.yaml — works across mods.
trees:
  - name: glow_tree
    biomes:
      - Creation:forest        # another mod's biome
      - my_own_biome           # bare name = your own mod

# From the biome's side, in your biome file — only for biomes you own.
static-object-spawns:
  - glow_tree

The two are additive, not alternatives: a biome’s static-object-spawns and every tree naming that biome all feed one pool, so adding your tree to Creation:forest never displaces the trees Creation already spawns there. Declare the link once, from whichever side you own — writing it on both is harmless but redundant.

biomes is the only way to put a tree in a biome another mod owns, since the biome-side list would mean editing that mod’s files. It works the same way an ore’s biomes always has. Names follow the usual rule: bare means your own mod, OtherMod:name reaches across. If your mod adds to another mod’s biome, declare that mod as a dependency — that’s what guarantees its biomes load before your trees register.

Not for sky islands. An island’s static objects come from the sky island feature, not from its biome, so a tree naming a sky-island biome can’t be placed. The server logs a warning at load telling you to move it to the feature’s static-object-spawns instead.

A tree with no biomes and named by no biome never spawns naturally — it can still be placed by a structure or from Lua.

Worldgen placement, not runtime spawning. A tree’s spacing and spawn-chance are worldgen placement fields — decided deterministically when a chunk generates, and shared verbatim with structures and sky-island features. This is a different system from a mob’s runtime spawn-rules block (see Natural Spawning); the two look nothing alike because they answer different questions. Use this spacing-plus-spawn-chance vocabulary for anything placed at worldgen.

Variations

Each entry in variations is a distinct placeable object (e.g. a tree with two trunk styles both counted as the same “type” for spawning purposes):

A variation with an invalid name or hitbox — or with no hitbox when the tree defines no tree-level default — is skipped on its own; the rest of the tree’s variations still load.

Variations are otherwise chosen uniformly (each equally likely) unless you set weight. Setting equal weights on every variation is identical to leaving them all unset.

Typos fail the entry. Any field name on a tree entry or a variation that the engine doesn’t recognize is a load-time error naming the bad key (Unknown field '…' — entry skipped (check for a typo)); an unknown key on the tree skips the whole tree, one on a variation skips just that variation. This is the same rule every catalog file follows — see Unknown Fields.

Field Inheritance

hitbox, tool-break-types, power-required, time-to-break-ms and drop-table may be set on the tree entry itself as defaults. Each variation inherits the tree-level value unless it declares its own, which fully replaces the inherited one (drop-tables are not merged). This keeps variations that differ only in appearance down to a single name line while still letting an individual variation carry, say, a rarer drop-table or a tougher break time:

trees:
  - name: my_oak
    spacing:
      x: 20
      y: 20
    max-size:
      width: 10
      height: 15
    spawn-chance: 1.0
    hitbox: { width: 10.0, height: 10.0 }
    tool-break-types: axe
    drop-table:
      drops:
        - item: oak_log
          min-amount: 4
          max-amount: 25
    variations:
      - name: my_oak          # inherits hitbox, tool-break-types and drop-table
      - name: ancient_oak      # same hitbox/tool, but its own richer drop-table
        drop-table:
          drops:
            - item: oak_log
              min-amount: 20
              max-amount: 40
            - item: golden_acorn
              chance: 0.05

particles follows the same tree-level-default / per-variation-override rule (see below); the only field that is never inheritable is name.

Per-Variation Particles

A variation’s own particles block fully replaces the tree-level one for that variation — it isn’t merged. This lets, e.g., a wind-blown variation of a tree emit leaves on a different cadence than its sibling variations while still counting as the same tree type:

trees:
  - name: cherry_tree
    spacing:
      x: 20
      y: 20
    max-size:
      width: 10
      height: 15
    spawn-chance: 1.0
    hitbox: { width: 10.0, height: 10.0 }
    tool-break-types: axe
    drop-table:
      drops:
        - item: cherry_log
          min-amount: 4
          max-amount: 25
    particles:
      - emit-random:
          - name: cherry_leaf
            chance: 0.1
            cooldown-ms: 5000
            lifetime-ms: 10000
            x-offset-min: -8.0
            x-offset-max: 8.0
            y-offset-min: 8.0
            y-offset-max: 9.0
    variations:
      - name: cherry_tree          # inherits everything, including the tree-level leaf particles
      - name: cherry_tree_2         # same hitbox/tool/drop-table, but its own faster particle cadence
        particles:
          - emit-random:
              - name: cherry_leaf
                chance: 0.2
                cooldown-ms: 3000
                lifetime-ms: 10000
                x-offset-min: -9.0
                x-offset-max: 9.0
                y-offset-min: 10.0
                y-offset-max: 11.0

Here cherry_tree_2 inherits the tree-level hitbox, tool and drop-table but overrides the particle block, shedding leaves twice as often (chance: 0.2 vs 0.1) and faster (cooldown-ms: 3000 vs 5000) than plain cherry_tree, even though both are variations of the same tree type. This mirrors the shipped Creation cherry tree.