Log inGet started
World

Beechwood Brook: A Temperate Forest to Walk, with Trees, Undergrowth and a Forest Builder

README.md

organicMaterials: Scale and Feather

24 organic and creature materials for the Swatchbook material library: leaves, pine needles, petals, mossy bark, mushroom, coral, shell and mother-of-pearl, bone, horn, scales, feathers, beetle shell, skin, fur and toon looks, each behind one name.

Version 1.0.7. Depends on materialLibraryKit 1.4.3 (Swatchbook), which installing this package brings with it. There is no setup code: once installed, every material is in the library's list, picker and swatch gallery on every player's machine.

Leaves, needles, petals and feathers are cut-out cards with real outlines that glow when the light is behind them. Mother-of-pearl and the inside of the sea shell shift through pink, green and blue as you move, the fish scales flash silver-gold, and the beetle shell slides from emerald through blue to violet. No material is metal: metallic is 0 on all 24, and the fish's silver and the beetle's colour come from a non-metallic layered film, as they do in nature. Every material belongs to one of three style families: realistic (17), stylised (the four skins) or toon (3). Skin is soft and lets warm light through at shadow edges.

Texture memory: 17.9 MB for all 24 (GPU, mipmaps included, each texture counted once), 25.9 MB with the 24 reference pictures the gallery shows. The largest material is barkMoss at 3.0 MB; no material samples more than 5 textures (the web limit is 9).

Install and use

Install organicMaterials from ZeroMind (search "organicMaterials" or "Scale and Feather"). It lands at /source/organicMaterials.package, and materialLibraryKit 1.4.3 comes with it under /source/deps/. Then, in any world, run this from a script or the console (execute):

local Materials = require("~materialLibraryKit.Materials")
local cube = entity.spawn("leafCube", { synced = true, components = { Model = { model = "cube" } } })
cube.localPosition = { 0, 0.5, 3 }
assert(Materials.apply(cube, "leafBroad"))       -- a broad leaf on every face, for every player
assert(Materials.apply(cube, "leafToon"))        -- the same cube for a cartoon world: only the name changes
for _, m in Materials.list({ collection = "organic", kind = "scales" }) do
    print(m.id, m.style, m.tileSize, m.textureKB)  -- scalesReptile, scalesFish, scalesToon
end
Materials.clear(cube)                             -- take it off again, for everyone
entity.despawn(cube.id)                           -- and the cube

Materials.apply(object, name) puts a material on any Model and shares the choice with every player; it returns ok, err. Materials.get(name).material is the material itself, for a Model of your own. Materials.list({ collection = "organic", ... }) filters by kind, style, tag or search, for example tag = "translucent", tag = "cut-out card", style = "toon" or search = "dragon".

Cards go on flat quads. A card is drawn once per face (UV 0..1) and is transparent outside its shape, so put it on the engine's plane mesh at its real size; a card's tileSize is its size in metres:

local leaf = entity.spawn("leaf", { components = { Model = { model = "@builtin::meshes.plane", material = "organicMaterials.materials.leafBroad" } } })
leaf.localScale = { 0.14, 1, 0.14 }                -- the broad-leaf card is 140 mm

The sea shell needs an open mesh. shell shows its ribbed outside on front faces and mother-of-pearl on back faces; the package's organicMaterials.meshes.scallop is a cupped scallop made for it (about 1 unit across: scale it to 0.08 to 0.12).

A still life. require("~organicMaterials.OrganicVignette").build({ position = { 0, 0, 7.6 } }) in a scene's build.luau stands this world's corner: a potted plant of leaf and flower cards, two shells and a feather on a little table, with a warm lamp behind the plant.

The gallery. To walk round every material, copy this world's scenes/main.scene, or stand the gallery in a scene of your own (spawn near the origin):

local g = entity.spawn("Gallery")
g.component.add("SwatchGallery", { view = "all", lighting = "studio" })
g.component.add("OrganicShowcase", {})

The materials

Every material is tagged category = organic, with its kind, its style (realistic, stylised or toon), tileSize (metres one repeat covers, or a card's size), roughness and metallic ranges (measured from its textures), textureKB (GPU memory, mipmaps included) and animated = false. Its tags add:

  • finish: glossy (median roughness under 0.3), satin (under 0.6) or rough;
  • metalness: non-metallic on every material (metallic 0 everywhere);
  • light: translucent (lets light through) or opaque;
  • form: cut-out card or tiled, and two-sided where both faces show;
  • texture cost: textures-tiny (under 128 KB), textures-light (under 1.5 MB), textures-medium (under 2.5 MB) or textures-heavy;
  • size: tile-<metres>m; animation: not-animated;
  • the shading it uses (diffuse transmission, subsurface, sheen, iridescent, structural colour, clearcoat, fibre highlights, anisotropic, two-layer shell, cel-shaded, backlit glow, rim light) and search words (species, creature, use).

Textures lists albedo / normal / mask sizes in pixels (the mask packs occlusion, roughness and metalness; - means none). Seam is Checks.seams' score at 4 × 4 and shimmer Checks.shimmer's score at 30 m (fails above 6), both measured on 2026-10-26 with materialLibraryKit 1.3.1 on the desktop engine.

NameMaterialKind, styleSizeRoughnessMetallicLets light throughTextures (memory)Seam / shimmer
Plants
leafBroadBroad leafleaf, realistic140 mm card0.43–0.530.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
leafNeedlePine needle sprigneedles, realistic200 mm card0.42–0.800.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
leafAutumnAutumn maple leafleaf, realistic120 mm card0.55–0.600.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
petalPinkFlower petalspetals, realistic80 mm card0.55–0.640.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
barkMossMossy barkbark, realistic1 m tile0.83–0.980.00no1024 / 1024 / 512 (3.0 MB)1.72 / 3.08
mushroomCapFly agaric capmushroom, realistic200 mm tile0.38–0.900.00yes512 / 512 / 512 (1.0 MB)1.04 / 1.29
Sea life
coralBrain coralcoral, realistic300 mm tile0.72–0.840.00yes512 / 512 / 512 (1.0 MB)0.31 / 1.41
shellSea shellshell, realistic100 mm tile0.12–0.750.00no512 / 512 / 512 (1.0 MB)0.97 / 1.23
motherOfPearlMother-of-pearlnacre, realistic80 mm tile0.10–0.160.00no512 / 512 / 256 (768 KB)1.73 / 4.09
Creature parts
boneBonebone, realistic200 mm tile0.57–0.690.00yes512 / 512 / 512 (1.0 MB)1.17 / 0.99
hornHornhorn, realistic250 mm tile0.36–0.490.00yes512 / 512 / 512 (1.0 MB)2.19 / 1.82
scalesReptileReptile scalesscales, realistic150 mm tile0.44–0.620.00no512 / 512 / 512 (1.0 MB)1.58 / 0.29
scalesFishFish scalesscales, realistic100 mm tile0.20–0.440.00no512 / 512 / 512 (1.0 MB)1.45 / 0.54
featherCardBarred featherfeather, realistic250 mm card0.42–0.680.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
chitinBeetleBeetle shellchitin, realistic50 mm tile0.16–0.350.00no512 / 512 / 256 (768 KB)0.50 / 0.20
Skin
skinLightLight skinskin, stylised250 mm tile0.53–0.580.00yes256 / 256 / 256 (256 KB)1.95 / 0.25
skinMediumMedium skinskin, stylised250 mm tile0.53–0.590.00yes256 / 256 / 256 (256 KB)0.37 / 0.12
skinDeepDeep skinskin, stylised250 mm tile0.53–0.590.00yes256 / 256 / 256 (256 KB)0.36 / 0.24
skinFantasyFantasy jade skinskin, stylised250 mm tile0.53–0.580.00yes256 / 256 / 256 (256 KB)1.68 / 0.12
Fur
furCardBrownBrown fur cardfur, realistic100 mm card0.450.00no512 / 512 / 256 (768 KB)0.79 / 0.00
furCardWhiteWhite fur cardfur, realistic100 mm card0.450.00yes512 / 512 / 256 (768 KB)0.00 / 0.00
Toon
leafToonToon leafleaf, toon140 mm card0.800.00yes256 / - / - (85 KB)0.00 / 0.00
scalesToonToon scalesscales, toon200 mm tile0.600.00no256 / - / - (85 KB)2.74 / 0.07
skinToonToon skinskin, toon250 mm tile0.700.00yes64 / - / - (5 KB)0.42 / 0.15

Texture memory

  • All 24 materials: 17.9 MB of GPU texture memory (18,351 KB), mipmaps included, each texture counted once: one at 3.0 MB (barkMoss), seven at 1.0 MB, nine at 768 KB, four skins at 256 KB, two toons at 85 KB and skinToon at 5 KB: 3,072 + 7,168 + 6,912 + 1,024 + 170 + 5 = 18,351 KB.
  • Reference pictures: 8.0 MB (24 at 512 px). They load only where the gallery hangs them.
  • Everything together: 25.9 MB, about a fifteenth of the library's 384 MiB budget for low-end devices.
  • Within the web limits: every material passes Checks.budget with no warnings. Each binds at most 5 sampled textures (the web limit is 9) and no storage buffers, nothing is over 1024 px, and every texture is UASTC (BC7 on desktop, ASTC on phones).
  • The mask is one texture in two slots: pbr materials bind their ORM mask to both occlusion_texture and roughness_metallic_texture. The library's Materials.measureTextures counts it per slot, so the catalog takes the second copy off; textureKB is the real figure.

How they were made

  • Reference pictures first. Every material has references/<id>, generated from the prompt in its catalog entry before the material was drawn. Each material was then compared with its picture side by side in its gallery bay under the library's Studio look, and fixed where they differed (the bark's moss cover, the nacre's colour bands, the fish's tint, the fur's density, the skins' palettes, and in 1.0.1 the beetle's green-blue-violet shift). The realistic materials' mean colour is matched to their picture's.
  • Baked procedurally in Luau by OrganicBaker and OrganicRecipes (require("~organicMaterials.OrganicRecipes").bakeAll() re-bakes all 24).
    • OrganicBaker is fabricsMaterials' FabricBaker (Warp and Weft, MIT), itself from Brick and Mortar, Bedrock and Heartwood. Every tiled map is periodic over one repeat, so it tiles by construction.
    • Cards are drawn as real shapes at real size: an ovate toothed beech leaf with pinnate veins, a five-lobed maple leaf with palmate veins, a Scots pine sprig of paired needles, a five-petal flower with stamens, a barred contour feather with chevron bars and down, and fur locks of hundreds of tapering strands in clumps.
    • Tiled surfaces: ridged bark plates with moss in the furrows, fly agaric warts on Poisson cells, brain-coral meanders, scallop ribs, wavy nacre layers, fibrous bone with pores, horn growth rings, overlapping keeled and cycloid scales, beetle elytra striae, and soft painted skin.
  • The engine's own lighting. Most materials are the engine's pbr shader with its own lobes: subsurface for skin, bone, horn, coral and the cap; clearcoat on the cap and lizard; sheen on moss and petals; the fibre lobe and anisotropy on fur. Four small shaders ship in the package:
    • organicCard (leaves, needles, petals, feather) shades the full PBR surface with the engine and adds diffuse transmission, so a thin card glows over its whole area when the sun, the sky or a lamp is behind it. The engine's subsurface lobe only lights up looking almost straight into the light.
    • organicShell (shell, motherOfPearl) gives nacre a film thickness that changes across the surface (read from the colour texture's alpha), so it shows pink, green and blue bands at once; the engine's material holds one thickness, one hue. On the sea shell, front faces are the ribbed outside and back faces the nacre inside.
    • organicFilm (scalesFish, chitinBeetle) models a fish's guanine crystals and a beetle's stacked chitin as what they are, non-metallic layered reflectors: a broadband part gives the fish its silver and an interference part colours both highlights and everything the surface mirrors, green face-on sliding through blue to violet at a slant, with the layer thickness varying across the surface. The engine's own thin-film lobe colours only direct highlights, which is why the beetle used to read as flat dark green under soft light.
    • toonOrganic (the toon set), adapted from Warp and Weft's toonFabric (MIT): cel bands, a rose-tinted shadow for skin, a rim band, and a flat backlit glow for the toon leaf.
  • Physically based. Colour carries no painted-in light; veins, grooves, pits and overlaps darken through the occlusion channel and the normal map. Metallic is 0 on every material, the fish and beetle included. Roughness follows the surface: nacre 0.10–0.16, beetle 0.16–0.35, horn 0.36–0.49, waxy leaves 0.43–0.6, bark 0.83–0.98. Normal maps are green-up, the convention the engine reads; the test suite proves the direction on a synthetic bump.
  • Real size (1 unit = 1 m): each repeat holds a whole number of scales, ribs, rings or rows at their real size (see Size), and each card is its subject's real length.

What was reused, and what was not

  • Used: the library's collection contract, gallery, picker, lighting looks and checks (materialLibraryKit 1.3.1); Warp and Weft's baker, catalog, showcase and toon shader (MIT); the engine's pbr lobes, plane mesh and lights.
  • Not used: the one-off leaf, bark, scale and skin materials in other games on ZeroMind. They are flat colours or untagged textures with no stated size and no cut-outs, built for one scene. Heartwood's oak bark has no moss.

Checked

On 2026-10-26, desktop engine, materialLibraryKit 1.3.1, for all 24:

  • Seamless tiled 4 × 4: every material passes Checks.seams (render and texture edges). The highest scores, scalesToon 2.74 and horn 2.19, pass on the library's rule that the edge is no stronger than the material's own ink lines and growth rings. Cards keep a transparent margin and a flat border colour, so they pass too.
  • No shimmer at 30 m: the worst is motherOfPearl at 4.09, against a limit of 6; every other material is under 3.1.
  • Web budget: Checks.budget reports no warnings for any material.

The test suite reruns the quick parts:

asset.resolve("organicMaterials.tests.organicMaterials", "testSuite"):run()

It covers the 24 names and every tag, the filters, the costs and budget, the physical values and normal direction, the cut-out shapes, seams and shimmer on one material per shader path (reptile scales, broad leaf, sea shell, toon scales), apply, swap and clear, the references and props, the picker, all 24 on one gallery ring, and this README. Each test runs inside the library's Sync.isolate(), so nothing it does reaches other players.

Multiplayer

  • Applied materials are shared. Materials.apply and the picker go through the library's shared channel: every player sees the material on any object every machine holds (a synced object, a scene's own objects such as the still life, the gallery's swatches), and players who join later get it too.
  • Lighting looks are shared. The gallery's toolbar switches them for everyone.
  • The gallery and its boards are local. Each machine builds the same swatches and hangs the same reference pictures; the still life is scene content, the same for everyone.

Known limits

Every limit here is tracked in an issue at github.com/OrigoZero/zero.

  • The gallery's frame rate (#20750). The 24-bay gallery is about 270 local entities, and the engine's per-frame upkeep of them dominates the frame in the desktop editor. The materials themselves cost nothing per frame.
  • Long waits (#19849). Some engine calls (a first bake, a first gallery build, a check sweep) can run for many seconds before they answer.
  • Not measured in a browser (#20946). An agent on the desktop engine cannot start a browser engine, so this release was prepared and checked on the desktop engine only; the web check is done separately.
  • Reloading the scene can save runtime models into it (#21023). Reloading this world's scene in the editor can write runtime-built entities into its saved file; the gallery's swatches are temporary and rebuilt each time.
  • A push can report one result and turn out another (#21025, #21207). A push can answer "timed out" or "queued" and still land, or the reverse.
  • A refused reused version number comes with a misleading remedy (#21206). ZeroMind accepts each version number once; fixes after 1.0.0 ship as the next patch version.
  • A fresh install needs the release published first (#19843). Install from a published release, not from a world mid-push.
  • Clearcoat uses the base surface's bumps (#21208). On chitinBeetle, mushroomCap and scalesReptile the clear coat follows the normal map instead of lying smooth over it.
  • Non-billboard text labels read from the front only (#21224). The gallery's plaques face the middle of the ring; from behind a bay they are not readable.
  • Self-lit surfaces show magenta in the debug views (#21225). The toon materials (toonOrganic lights itself) draw magenta in the capture tool's albedo, roughness and metallic passes; their final and normal views are normal. organicCard, organicShell and organicFilm hand the engine their surface and read correctly.

Design notes

How the package behaves by design; none of these is a defect.

  • One repeat per primitive face. The engine's cube, sphere and cylinder carry UVs 0..1 per face, so a tiled material shows at real size on them only when the object is its tileSize across. The gallery's floor tiles and walls lay their UVs out in metres. Cards (singleRepeat) are drawn once per face everywhere, so the gallery shows each card large on its tile and wall.
  • Fur lies along U, roots at U = 0, so its fibre highlights follow the tangent. Turn the quad to turn the fur.
  • Transmission comes from the sun, the sky and point and spot lights, through other cards' shadows from the sun.
  • Skins are stylised, chosen as palettes rather than matched to photographs: soft, a little translucent, not photoreal. The jade skin is a fantasy colour in the stylised family.

Version history

  • 1.0.7 (2026-11-03): the catalog's authoring function reaches materialLibraryKit by package name (~materialLibraryKit.Materials) instead of a root path, which named nothing in a world where the kit is installed under deps/ and kept such a world from publishing. Materials are unchanged.

  • 1.0.6 (2026-11-03): the 1.0.5 release went out with its package descriptor still at 1.0.4 on materialLibraryKit 1.4.2; 1.0.6 is the same content with the descriptor saying 1.0.6 on materialLibraryKit 1.4.3. Materials are unchanged.

  • 1.0.5 (2026-11-03): depends on materialLibraryKit 1.4.3, which measures texture memory for the package-relative texture names this collection uses since 1.0.3 (on 1.4.2 every texture measured 0 KB, so the web-budget test failed); the collection file and the install line state the right versions again. Materials are unchanged.

  • 1.0.4 (2026-11-02): depends on materialLibraryKit 1.4.2, the version the other collections (Heartwood, Bedrock) now bring, so it installs as a package beside them.

  • 1.0.3 (2026-11-02): every material names its textures and shader package-relatively (~.textures.X), so the collection also renders when installed as a library; republished on the current built-in library so it installs as a package again. Materials are unchanged.

  • 1.0.1 (2026-10-26): names, families and metal.

    • Renamed to the collection's intended names: needlePine → leafNeedle, petalFlower → petalPink, barkMossy → barkMoss, beetleShell → chitinBeetle, seaShell → shell, toonLeaf → leafToon, toonScales → scalesToon, toonSkin → skinToon. The old names no longer resolve; change them in scripts that used 1.0.0.
    • Style families: skinFantasy is now stylised (it was fantasy); every material is realistic, stylised or toon.
    • No metal: metallic is 0 on all 24. scalesFish and chitinBeetle move to the new organicFilm shader, which gives the fish its silver and the beetle its colour shift from a non-metallic layered film.
    • The beetle shell matches its reference: it read as flat dark green in the gallery, because the engine's thin-film lobe colours only direct highlights. With organicFilm it reflects green face-on and slides through blue to violet at a slant and across its patches.
    • Textures, sizes and every other material are unchanged; texture memory is still 17.9 MB.
  • 1.0.0 (2026-10-26): the 24 materials above, their reference pictures, the organicCard, organicShell and toonOrganic shaders, the scallop mesh, OrganicShowcase, OrganicVignette, this world's gallery scene with its backlit still life, and the test suite. Depends on materialLibraryKit 1.3.1.