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.

When several trees share the same spacing, footprint, hitbox, or breaking tool, you can factor that shape into a preset and give each entry a preset: key instead of repeating it — see Config Presets.

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.

Ceiling & wall attachment

By default a static object roots on the ground. The attach field lets an object spawned by an underground feature anchor to a cave ceiling or wall instead — the way hanging vines, dangling roots, ceiling moss, and stalactites grow:

trees:
  - name: hanging_vine
    attach: ceiling          # floor (default) | ceiling | wall
    spacing: { x: 3, y: 3 }
    max-size: { width: 1, height: 4 }
    spawn-chance: 0.4
    variations:
      - name: hanging_vine
        hitbox: { width: 1, height: 4 }

Notes:

• Feature-only. attach is honored solely by the underground-feature spawn path (a feature that lists the object in its static-object-spawns, see underground-feature-config.md). Objects placed on the surface or on sky islands always spawn on the floor. The feature must carve open space (a cave-generator) for a ceiling/wall to exist to attach to.
• Textures aren’t pre-flipped. A ceiling object is rendered upside-down from its authored texture, so draw it rooted at the bottom of the image exactly like a floor object; the engine flips it and hangs it from the ceiling.
• Clearance. A ceiling object only spawns where there is at least max-size.height of open air below the ceiling for it to hang into. A wall object only spawns in an open cell with solid rock on exactly one side.

Submerged (underwater) spawns

By default a surface object needs open air above the ground it spawns on. The submerged field lets an object instead root on the seabed — the terrain surface of an ocean or lake biome, which sits below the water the biome layers on top with fill-surface-blocks. This is how kelp and other underwater foliage grow on the shallow shelf:

trees:
  - name: kelp
    submerged: true             # root on a below-water-line seabed
    submerged-max-depth: 12     # only within 12 blocks of the water line (the shallows)
    spacing: { x: 4, y: 4 }
    max-size: { width: 1, height: 6 }
    spawn-chance: 0.5
    biomes: [ Creation:tropical_ocean ]
    variations:
      - name: kelp
        hitbox: { width: 1, height: 6 }

Notes:

• Surface path only. submerged is honored by the surface natural-spawn scan (the same one that places land trees). An ocean biome’s terrain surface is its seabed, so the object anchors there and grows up into the water. It has no effect on underground-feature or sky-island spawns.
• Needs a water line. The object spawns only where the biome declares fill-surface-blocks and the terrain top is below that fill-to-altitude. A biome with no water fill never spawns submerged objects, and a column whose surface is above the water line (a beach, an offshore islet) is skipped.
• Stay in the shallows. Set submerged-max-depth to keep the object near the surface — a good match for a kelp forest. Author the object no taller than the local water depth so it doesn’t spike out of the surface; the depth cap is your control for that. Omitting the cap allows any depth.
• Anchor is still floor. A submerged object roots at its base and grows upward like a normal floor object — author its texture rooted at the image bottom. attach and submerged are independent; a submerged object ignores attach.
• Sits on the seabed, not in it. A submerged object is placed one cell higher than a land object would be, so it rests on top of the seafloor surface rather than embedding its base row into the seabed block (which reads as “rooted” for a wide tree but “buried” for thin foliage).

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.

Last updated Aug 17, 2026