Log inGet started
Package

forestProps.package

This package holds more than this page lists. See all of its files in its world.

README.md

forestProps

61 kinds of temperate forest trees, plants, logs and rocks for any world, each one switched by a single component. Oak, beech, silver birch and maple from sapling to veteran, a dead snag, a broken tree and a fallen giant, plus ferns, shrubs, grasses, reeds, wildflowers, ivy, mosses, fungi, forest-floor litter, logs, stumps, boulders and pebbles. Every prop has near, middle and far levels of detail, and the same switches work on all of them: kind, age, season (spring, summer, autumn, winter), look (real, painted, toon), variant and detail.

Install and use: install forestProps from ZeroMind (it brings forestMaterials, the surfaces it is drawn with), then put a forestProps.ForestProp component on any entity and pick the prop. Load the PropGallery scene to see every prop side by side. To fill a whole forest with them by woodland rules, install forestKit, which brings forestProps with it.

entity.spawn("oak").component.add("forestProps.ForestProp", { kind = "oak", age = "veteran", season = "autumn" })

Baked, LOD'd props for a temperate deciduous (English / central-European) woodland: oak, beech, silver birch and maple trees at four ages, a standing dead snag, a snapped broken tree and a fallen veteran oak, plus ground cover (ferns, bushes, grass, reeds, flowers, herbs, ivy, moss, fungi, forest-floor litter, logs, stumps, rocks and pebbles): 61 kinds in all. Every mesh is generated once and baked into the package, so installing it costs no generation; one ForestProp component switches any prop by kind, age, season, look and variant. Materials come from the forestMaterials package (its dependency).

ForestProp

Put it on any entity; it builds child entities (one Model + MeshLod per part, swapping LOD0 -> LOD1 -> LOD2 by screen size) and a static collider, all local and unsaved, rebuilt from its synced fields: so every peer builds the same prop and a reload rebuilds it. Changing any field rebuilds.

FieldDefaultMeaning
kind"oak"any kind Props.kinds() lists (oak, beech, birch, maple, deadSnag, brokenTree, fallenGiant, and every ground kind below)
age"mature"trees: sapling, young, mature, veteran (ignored by kinds without ages)
season"summer"spring, summer, autumn, winter (deciduous trees are bare in winter)
look"real"real, painted, toon (toon trees use a clumped-blob crown)
variant1baked shape variant, 1..n (wraps)
seed0when non-zero, picks the variant and a yaw turn from the seed (for scattering)
detailautoauto swaps to the cheaper far versions as the prop shrinks on screen; near, mid or far pins one
collidetruebuild the catalog entry's static collider (tagged with attribute forestSurface when the entry names one)

Gallery

Load the PropGallery scene (or put a PropGallery component on any entity) to see every prop side by side, labelled with its settings: each tree type at every age and shape, every season in every look, near/mid/far/auto detail, dead wood, and every undergrowth, log, stump and rock kind in each shape, season and look.

Props API

local Props = require("~forestProps.Props")   -- "forestProps.Props" from outside a package
Props.kinds() -> { string }                   -- every kind, trees first
Props.kindsOf(category) -> { string }         -- "tree", "deadtree", "bush", "fern", ...
Props.info(kind) -> Entry?                    -- { kind, category, ages?, variants, radius, height, collider?, surface?, byAge? }
Props.parts(kind, { age?, season?, look?, variant?, lod? }) -> { { mesh, material } }
Props.normalize(kind, opts) -> opts           -- the defaults/clamps parts applies
Props.register(entry, partsFn)                -- how a catalog adds kinds (GroundCatalog does)

Props.parts only hands out baked meshes (read from the generated BakedTrees / BakedGround literal indexes), each with the forestMaterials material for that season and look. Trees: part 1 is bark, part 2 leaves (absent in winter). Tree entries add byAge[age] = { radius, height, trunk } (metres) for spacing and colliders per age.

Trees

KindAgesWhat it is
oaksapling, young, mature, veteranEnglish oak: decurrent trunk splitting into gnarled limbs; the veteran has a huge buttressed trunk, low wide-spreading limbs and broken limbs
beechsapling, young, mature, veteranEuropean beech: smooth grey straight leader trunk, tall dense dome, flat layered leaf sprays
birchsapling, young, mature, veteransilver birch: slender white trunk, narrow airy crown, weeping hanging twigs
maplesapling, young, mature, veteranfield maple / sycamore: short trunk splitting into ascending limbs, rounded crown
deadSnag-standing dead tree, silver deadwood, broken stub branches and a jagged top
brokenTree-thick trunk snapped low, splintered jagged top with rotten wood in the break
fallenGiant-a veteran oak lying on its side (+X), mossy bark, broken limbs, upturned root plate with soil at the origin

Three seeded variants each. Trunks and branches are tapered tubes (root flare with buttress lobes, collars at joins, bark UVs at a fixed world scale continued from parent to child); leaves are alpha-cut leaf-cluster cards on the twigs with normals bent outward from the crown centre and RGB darkened toward the crown core. Leaf-card vertex alpha is the wind weight (0 at the twig -> 1 at the card tip); bark is solid, alpha 1. Winter LOD2 uses a branches-only stand-in (barkw).

Triangle counts (max over the 3 variants; LOD0/1/2 summer, LOD2 winter, LOD0 toon):

TreeLOD0LOD1LOD2LOD2 winterLOD0 toon
oak sapling / young / mature / veteran1.4k / 5.0k / 11.5k / 19.5k0.3k / 1.5k / 3.5k / 5.9k174 / 368 / 483 / 530<= 6002.0k / 3.4k / 8.0k / 9.7k
beech1.3k / 5.0k / 11.5k / 19.5k0.3k / 1.5k / 3.6k / 5.9k164 / 414 / 562 / 600<= 6001.8k / 3.3k / 8.3k / 11.2k
birch1.4k / 4.3k / 11.5k / 17.3k0.3k / 1.1k / 3.4k / 3.8k180 / 378 / 574 / 592<= 6002.2k / 3.4k / 10.2k / 13.9k
maple1.2k / 5.0k / 11.5k / 19.5k0.3k / 1.5k / 3.5k / 5.9k164 / 334 / 395 / 482<= 6002.0k / 3.9k / 9.4k / 12.6k
deadSnag / brokenTree / fallenGiant1.3k / 0.5k / 2.3k456 / 296 / 72050 / 64 / 102--

Budgets (INTERFACES.md): mature LOD0 <= 12k, veteran <= 20k, LOD1 ~25-35% of LOD0, LOD2 <= 600.

Regenerating: edit TreeGen (species x age parameters live in its config table), then in a task run require("forestProps.TreeBake").bakeKind("oak") for each changed kind (or .bakeAll()), then .writeIndex() (regenerates BakedTrees) and .prune(). Bakes overwrite in place; nothing duplicates. tests/trees.testSuite checks every kind/age/season/look/variant/LOD resolves, winter is leafless, the budgets, and that ForestProp rebuilds.

Ground props

Fifty-four ground kinds, each with 3-4 seeded shape variants and three LODs, baked as meshes under meshes/ground/<kind>/ and registered by GroundCatalog through Props.register, so they switch exactly like trees: by kind, season, look (real, painted, toon, via forestMaterials), variant and lod.

CategoryKindsMade of
fernfernBracken, fernMale, fernHartsTongueone bent alpha card per frond in a radial clump (bracken arching flat, male fern a shuttlecock, hart's tongue wavy straps)
bushbramble, hazel, hollya stem skeleton (arching bramble canes, a coppiced hazel stool with twigs, a holly trunk with a spiral of branches) carrying leaf-sprig cards
grassgrassClump, grassLongbent blade-tuft cards leaning out of the clump
flowerbluebell, foxglove, woodAnemone, redCampion, buttercup, wildGarlic, daisya patch of plants, each two or three crossed whole-plant cards
mossmossCushiona lumpy, flat-bottomed cushion
fungusflyAgaric, toadstools, bracketFunguslathed stems, caps and gills; toadstools on a moss pad; banded bracket shelves on a mossy bark stub
loglogFresh, logMossy, logHollow, logRottendisplaced bark tubes with saw-cut ring faces or splintered broken ends, branch stubs, a hollow interior, a sagging rotten log with sloughed bark over soft wood, and a moss skin grown over the upper surfaces
stumpstumpCut, stumpBroken, stumpMossya flared stump with root buttresses: a ringed saw cut, a splintered crater, or a moss dome
rockboulder, mossyRock, streamStone, steppingStonenoise-displaced, faceted, flat-bottomed stone with moss on top; a group of wet rounded cobbles; a flat-topped stepping slab
bush (2nd wave)elder, hawthorn, dogRose, bilberryelder: arching grey stems with opposite shoots, pinnate leaf sprays, flat cream umbels (spring, summer) and hanging black-purple berry clusters on red rays (autumn), bare in winter; hawthorn: a short trunk into a dense zig-zag rounded crown of small lobed leaves, white May blossom (spring), dark red haws (autumn, winter); dog rose: long arching green-red canes, small leaflets, pale pink flowers (summer), scarlet hips (autumn, winter); bilberry: a knee-high mound of green stems, small oval leaves, blue-black berries (summer, autumn)
grass (2nd wave)grassTussocktufted hair-grass: a dense fountain of fine arching blades with tall pale flowering stems; straw-coloured in winter
reedrushClump, bulrushsoft rush: needle-thin upright dark green stems with brown side tufts, evergreen; bulrush: long strap leaves and tall stems with velvety brown sausage heads and a spike (water's edge)
flower (2nd wave)primrose, lesserCelandine, cowParsleyprimrose: rosettes of crinkled tongue leaves with pale yellow flowers (spring); lesser celandine: a low carpet of glossy round leaves with butter-yellow star flowers (spring); cow parsley: tall green stems, ferny base leaves and lacy white umbels
herbnettlePatcha stand of upright leafy nettle stems (three crossed cards each), spring to autumn, gone in winter
ivyivyGround (and ivyStump, a stump)evergreen ivy leaf mats on brown runners across the ground; ivyStump is an old cut or broken stump with vines spiralling up the bark and leaf mats hugging it (a stump: collider, walks as log)
moss (2nd wave)mossCarpet, mossRootsfeather-moss carpet: a wide thin undulating mat with an irregular edge, feathered with tiny golden-green fronds; a moss-covered root mound: a mossy hump with old roots running out and diving into the ground
fungus (2nd wave)honeyFungus, puffballa dense tuft of tawny ringed honey fungus; white pear-shaped puffballs sitting on a moss pad (both gone in winter)
litterbranchLitter, twigPile, leafLitterscattered fallen sticks and forked twigs (four variants); a heaped pile of brash; drifts of fallen oak and beech leaves with a few twigs, brown all year (autumn colours in autumn)
log (2nd wave)fallenBranch, logSplita fallen limb with side branches lying out and a snapped limb sticking up, mossy on top; a split half log, face up, often with its other half lying bark up beside it, sawn end-grain ends
stump (2nd wave)rootPlate, ivyStumpan upturned root plate (torn soil face, roots and rootlets, leafy mossy top) with its sawn trunk stub lying away along +X
rock (2nd wave)pebblePatchwet rounded pebbles on a patch of stream-bed grit, for stream banks

Seasons: ferns turn bronze in autumn; bracken and male fern lie collapsed and dead in winter (a baked winter form), hart's tongue stays green. Flowers bloom in spring and summer and return no parts in autumn and winter. Hazel and bramble yellow in autumn; hazel is bare in winter and bramble keeps a sparse set of leaves; holly is evergreen. Fly agaric and toadstools are absent in winter. Logs, stumps, rocks, moss and bracket fungi stay all year. Second wave: elder flowers in spring and summer and fruits in autumn, bare in winter; hawthorn blossoms in spring, carries haws in autumn and winter, bare in winter; dog rose flowers in summer, hips in autumn and winter, bare in winter; bilberry fruits in summer and autumn, bare green stems in winter; primrose and lesser celandine flower in spring only; nettles, honey fungus and puffballs are gone in winter; ivy, soft rush and the feather-moss fronds keep their summer green all year; leaf litter is dry brown all year and in autumn colours in autumn. Per-part rules live in GroundCatalog.PART_SEASONS (GC.showsPart) and evergreen material locks in GC.materialSeason.

No second-wave kind adds a texture: single flower heads and leaves are cropped out of the existing forestMaterials atlas cells with a card uv rect (GroundFlora.CROP: a wood anemone flower tinted pale yellow is the primrose, tinted pink the dog rose; a daisy head tinted butter-yellow is the celandine; the wild garlic umbel is the elder and cow parsley flower head), berries and hips are small balls on the wet stream-stone and fly-agaric surfaces, and tree leaf textures (maple for ivy, oak for hawthorn, birch for dog rose and bilberry) dress the new shrubs. Generators: GroundFlora (plants) and GroundLitter (litter, deadwood, pebbles), registered into GroundGen.SPECS.

Foliage cards carry vertex alpha 0 at the base rising to 1 at the tips (wind sway) and per-card tint in vertex RGB; solid parts carry alpha 1 (see Mesh contract). Logs, stumps, boulders and stones have colliders (logs and stumps walk as log, rocks as stone); plants have none. Budgets: ground cover LOD0 <= 600 triangles a clump, LOD1 <= 150, LOD2 empty (culled); bushes LOD0 <= 3000 with a card impostor at LOD2; logs, stumps and rocks LOD0 <= 3000, LOD1 <= 900, LOD2 <= 300.

local Props = require("~forestProps.Props")
-- a mossy log in autumn, painted look, second variant, near LOD
for _, part in Props.parts("logMossy", { season = "autumn", look = "painted", variant = 2, lod = 0 }) do
	local e = entity.spawn("logPart")
	e.component.add("Model", { model = part.mesh, material = part.material })
end
print(Props.info("steppingStone").collider.shape, Props.info("steppingStone").surface) --> box  stone

Regenerating: change a generator in GroundGen / GroundHard, then run require("~forestProps.GroundBake").run() inside a task (or .run({ kinds = { "boulder" } })); it rewrites the meshes and BakedGround, the literal-resolve table the catalog reads. The tests/groundProps.testSuite checks every kind/season/look/variant/LOD resolves, the seasonal rules and the budgets.

Mesh contract (every baked mesh)

  • Winding: front faces are counter-clockwise. The bake's finishing pass (Geo.orient, run by Geo.bake and GroundBake.finish) swaps two indices of any triangle whose face normal (b-a)x(c-a) points against the sum of its three vertex normals, so no baked mesh draws inside out whatever order a generator emitted its triangles in.
  • Vertex colour RGB is a tint the material multiplies its albedo by.
  • Vertex colour alpha is the wind-sway weight on foliage cards only (tree leaf / toon parts, TreeCatalog.FOLIAGE_PARTS; ground parts whose surface is in GroundCatalog.FOLIAGE: ferns, grass, flowers and the bramble / hazel / holly leaf sprigs): 0 rigid at the base, 1 full sway at the tips. Every other part (tree bark and barkw, dead wood and soil, bush stems, logs, stumps, rocks, stones, moss cushions, fungi) is SOLID and baked with alpha 1 (Geo.solid), so a material that multiplies vertex alpha into surface alpha (the engine's pbr) draws it opaque. Trunks and stems do not sway.
  • Atlas UVs: a ground part whose surface has an entry in forestMaterials' ATLAS table (ferns, shrub leaves, wildflowers, toadstool caps, bracket shelves) has its 0..1 card UVs remapped into that cell at bake time: u' = (col + u) / cols, v' = (row + v) / rows, row 0 the top row of the image.