API Worldgen Trees

Trees

Lua API / World generation / Trees

Trees are reusable atomic features. They can use a vanilla-style adapter, bounded procedural geometry, or one of several authored local structures. Schedule the returned reference through an ordinary placement or place it directly from an authoritative callback.

betamoon.worldgen.trees:add(definition)

Compiles a tree and returns a feature reference. Keys normalize to namespace:tree/path; get returns a reference or nil, and getRequired raises an error when absent.

local silverwood = betamoon.worldgen.trees:add {
    key = "mymod:silverwood",
    trunk = {
        block = silverLog,
        height = { min = 6, max = 10 },
        radius = 1,
        bend = 0.12
    },
    branches = {
        start = 0.55,
        count = { min = 3, max = 7 },
        length = { min = 2, max = 4 },
        upwardBias = 0.35
    },
    canopy = {
        block = silverLeaves,
        shape = "clustered_sphere",
        radius = { min = 2, max = 4 },
        density = 0.82
    },
    ground = { 2, 3 },
    replace = { 0, 18 }
}

Procedural field definitions

Field	Default / range
key	Required stable tree key.
trunk.block	Required block.
trunk.metadata	0; accepts 0–15.
trunk.height	Required integer or range, 1–24.
trunk.radius	1; accepts 1–2.
trunk.bend	0; accepts 0–1.
branches.start	0.55; accepts 0.1–0.95 as the trunk-height fraction at which branching starts.
branches.count	Required when branches is supplied; integer/range 0–16.
branches.length	Required when branches is supplied; integer/range 1–12.
branches.upwardBias	0.25; accepts 0–1.
canopy.block	Required leaf block.
canopy.metadata	0; accepts 0–15.
canopy.shape	sphere; also layered_disk, cone, or clustered_sphere.
canopy.radius	Required integer/range 1–8.
canopy.density	1; accepts 0.05–1.
ground	Grass and dirt.
replace	Air and leaves.

Shape guide:

• sphere creates a rounded continuous crown;
• layered_disk creates stacked flat foliage layers like a classic small tree;
• cone narrows upward for spruce-like crowns;
• clustered_sphere creates several overlapping rounded foliage clusters.

BetaMoon plans the trunk, branches, and canopy together. If a required cell is blocked or another validation fails, the entire tree is rejected before any block changes.

Vanilla-style adapters

local paleTree = betamoon.worldgen.trees:add {
    key = "mymod:pale_tree",
    generator = "normal",
    trunk = paleLog,
    leaves = paleLeaves,
    trunkMetadata = 0,
    leavesMetadata = 0,
    ground = { 2, 3 }
}

generator is normal, big, or taiga. The adapter supplies bounded height, canopy, and branch defaults; optional trunk, leaves, and metadata fields replace its materials without changing global Minecraft blocks. ground and replace use the same defaults as procedural trees.

Structure-backed trees

local ancientTree = betamoon.worldgen.trees:add {
    key = "mymod:ancient_tree",
    templates = {
        { structure = "mymod:ancient_tree_a", weight = 3 },
        { structure = "mymod:ancient_tree_b", weight = 1 }
    },
    rotation = "random_horizontal",
    mirror = "none",
    ground = { enchantedSoil }
}

Structure-tree field definitions

Field	Default / behavior
templates	Required nonempty weighted list. Every structure must be a local structure reference or key.
weight	1; positive relative weight.
rotation	random_horizontal; accepts the ordinary local-structure rotations.
mirror	none; accepts the ordinary local-structure mirrors.
ground	Grass and dirt.

One template is selected per tree placement. An ore, patch, sequence, or other generic feature is rejected where a structure template is required. A direct placement's explicit rotation or mirror overrides these tree defaults.

References expose getKey() and all ordinary feature preview/place behavior.

Examples: simple tree placement and complete modular worldgen pack.