forestMaterials
Every surface of an English or central-European woodland behind one name, in three looks and four seasons, while shipping only the 13 materials the installed collections lack.** `ForestMaterials.get("leafOak", { season = "autumn", look = "toon" })` answers a material you put stra…
forestMaterials: Beechwood Brook forest surfaces
Every surface of an English or central-European woodland behind one name, in three looks and four seasons, while shipping only the 13 materials the installed collections lack. ForestMaterials.get("leafOak", { season = "autumn", look = "toon" }) answers a material you put straight on a Model or an instanced draw.
Install and use: install forestMaterials from ZeroMind (it brings the material collections it borrows bark, stone, ground, moss and water from), then require("forestMaterials.ForestMaterials") and ask for a surface by name, a season and a look, as in the first example below. It gives 42 named forest surfaces: oak, beech, birch and maple leaves, ferns, shrubs, wildflowers, long grass, fungi, bark, logs, stream stone and stream bed, each in the real, painted and toon looks and all four seasons. forestProps and forestKit draw with it, so installing either of those brings it too.
Version 2.0.5: the opening says what the package gives and how to install and use it. 2.0.4 (2.0.3 republished with the current engine library). 2.0.3: The painted and toon leaves draw again (the stylised shader takes its leaf tiling as a pair), and the tests find the package wherever it is installed. 2.0.2: Tree leaf textures repeat across each card, so leaves show at real size near and far. Terra Firma (groundMaterials 1.0.6) and Scale and Feather (organicMaterials 1.0.4) are now installed packages, like Heartwood and Bedrock, so a fresh world needs no libraries for them.
First example
local FM = require("forestMaterials.ForestMaterials") -- inside the package: require("~.ForestMaterials")
local card = entity.spawn("oakCard", { temporary = true, components = { Model = {
model = "@builtin::meshes.plane",
material = FM.get("leafOak", { season = "autumn" }), -- russet oak leaves, built at runtime from leafOak
} } })
card.localPosition = { 0, 1, 3 }
card.localRotation = { 90, 0, 0 } -- stand the plane up; the twig is at the bottom centre
card.localScale = { 0.6, 1, 0.6 }
print(FM.source("leafOak", { season = "autumn" })) -- runtime:forestMaterials:leafOak|autumn|real
print(FM.source("barkOak")) -- installed:woodsMaterials.materials.oakBark
print(FM.leafless("leafOak", "winter")) -- true: draw no canopy in winter
What the package ships, and what it borrows
The package holds 13 base materials (summer, real look):
| Material | What it is | Shader |
|---|---|---|
barkMaple | grey-brown flaky sycamore and field maple bark, 0.6 m tile | forestSolid |
woodRotten | crumbly red-brown cubical rot inside a fallen log, 0.4 m | forestSolid |
stoneStream | wet, water-worn dark stream stone, clear coat, 0.5 m | forestSolid |
groundStreamBed | wet stream-bed pebbles and grit, clear coat, 1 m | forestSolid |
fungi | atlas: toadstool cap and banded bracket fungus | forestSolid |
leafOak, leafBeech, leafBirch, leafMaple | leaf spray cards, four seasons each | forestFoliage |
grassBlades | long grass tuft card, four seasons | forestFoliage |
ferns | atlas: bracken, male fern, hart's-tongue, four seasons | forestFoliage |
shrubs | atlas: bramble, hazel, holly sprigs, four seasons | forestFoliage |
wildflowers | atlas: bluebell, foxglove, wood anemone, red campion, buttercup, wild garlic, daisy | forestFoliage |
Everything else is the collection's own material, used as installed:
| Surfaces | Comes from |
|---|---|
barkOak, barkBeech, barkBirch, barkDead, woodCutEnd | Heartwood oakBark, beechBark, birchBark, driftwood, endGrain (toon: toonLog) |
woodMossy, fungusFlyAgaric, fungusStem | Scale and Feather barkMoss, mushroomCap, bone |
stoneBoulder, stoneMossy | Bedrock cliffRock, mossyStone (toon: toonRock) |
groundForestFloor, groundLeafLitter, groundMoss, mossClump, groundPath, groundMud, groundGrass | Terra Firma forestFloor, leafLitter, moss, dirt, wetMud, shortGrass (painted handPaintedGrass, toon toonDirt / toonGrass) |
water | Flux and Flicker riverClear (painted and toon waterToon) |
A surface that should look different is improved in its collection, not copied here.
API
FM.get(surface, { season?, look? }) -> material, never nil: a material asset for the summer real look of a package surface or any collection surface, otherwise a runtime material. Unknown look ->real, season ->summer.FM.surfaces() -> { string }the 42 surface names.FM.group(surface)->bark | wood | leaf | undergrowth | flower | small | stone | ground | water.FM.baseOf(surface)-> the base material a package surface draws with (fernMale->ferns).FM.leafless(surface, season) -> boolean: deciduous leaves andhazelin winter; every flower in autumn and winter. Props then draw no part with that surface.FM.source(surface, opts)says where the answer came from (own:,runtime:,installed:);FM.refresh()drops the cache.FM.ATLAS[surface] = { atlas, col, row, cols, rows }: where an atlased card sits. A mesh drawn with an atlas surface has its UVs remapped into that cell (u' = (col + u) / cols,v' = (row + v) / rows, row 0 at the top); forestProps does this when it bakes.
Every asset FM can answer with or build from is resolved from a string literal in the generated ForestMaterialsTable, so components and scenes that call it stay publishable.
Looks and seasons
- real: tiles on
forestSolid(opaque PBR with clear coat; ignores vertex alpha). Cards onforestFoliage: alpha-cut at 0.45, two-sided, light passes through a leaf with the sun behind it, and the card sways in the engine's wind, weighted by vertex colour alpha (0 rigid at the base, 1 full sway at the tips); vertex RGB tints the albedo. - painted and toon: built at runtime on
forestStylisedfrom the same textures, for every surface, own or collection (no extra texture memory). Painted: softened colour in gently stepped tones, wrapped light with cool shadows. Toon: hard colour bands, two flat light bands, a pale rim. - seasons: recoloured albedos of the summer cards (spring fresh lime; autumn oak russet, beech copper, birch gold, maple red-orange, bracken bronze, hazel yellow, bramble red-purple; winter dry brown and straw), swapped in at runtime. Flowers bloom in spring and summer only.
Texture memory
52 textures, 40.9 MB of GPU memory for everything, all seasons included (UASTC/BC7, 1 byte a texel, mipmaps included). ForestMaterialsBuild.textureMemory() recounts it.
What's in the package
ForestMaterials.modulethe resolver and runtime looks;ForestMaterialsTable.moduleits generated literal table.forest.materialCollection: the 13 base materials in materialLibraryKit's list and picker.forestFoliage.shader,forestStylised.shader,forestSolid.shader;materials/(13),textures/(52).CardBaker.module(authoring): keys a plant picture painted on a flat key colour into a clean alpha cut-out, makes seasonal recolours and a normal map.ForestMaterialsBuild.module(authoring):writeAtlases(),writeMaterials(),writeTable(),writeCollection(),tidy(),textureMemory(). The atlases are now the shipped source of the atlased cards.tests/forestMaterials.testSuite.
Depends on
Installed packages: Heartwood (woodsMaterials), Bedrock (stoneMaterials), Terra Firma (groundMaterials 1.0.6), Scale and Feather (organicMaterials 1.0.4). Library: Flux and Flicker (animatedMaterials), for the water.
Scoped to this part · feeds back into the world's score.