weatheredPlanks

# woodsMaterials: Heartwood 25 seamless, real-scale, physically based woods for the materialLibraryKit material library, from sawn oak to charred yakisugi, plus toon, hand-painted and pixel-art sets. Version 1.0.1. Once installed, the woods turn up in the library's list, picker and swatch gallery on every player's machine, with no setup code. The materialLibraryKit core (1.1.0) is a declared dependency of this package and comes with it: one install is all a world needs. ## Changelog - **1.0.1**: One install now brings the whole materialLibraryKit core (checked in a brand-new world), so the README no longer asks for a second install. The gallery opens with all 25 woods on one ring in a fresh world too (before, the extra calibration entries a fresh install lists could push four woods onto another page), and a reference board that goes missing is hung again within a second. The woods themselves are unchanged. - **1.0.0**: First release: 25 woods, their reference pictures, the gallery scene and the test suite. ## Install and use Install **woodsMaterials** from ZeroMind (search "woodsMaterials" or "Heartwood", or install the published package `348f7ef1-f2a6-4df5-9db0-6ecc38c6570d`). It lands at `/source/woodsMaterials.package`, and the materialLibraryKit core comes with it under `/source/deps/`. Nothing else to install. Scripts reach the core by its package name with `~`, wherever it was installed. Then, from any script: ```luau local Materials = require("~materialLibraryKit.Materials") local crate = entity.spawn("crate", { components = { Model = { model = "cube" } } }) crate.localPosition = { 0, 0.6, 3 } crate.localScale = { 1.2, 1.2, 1.2 } -- one repeat of oakPlanks is 1.2 m assert(Materials.apply(crate, "oakPlanks")) -- every player sees it -- swapping the wood changes only the name assert(Materials.apply(crate, "weatheredPlanks")) for _, m in Materials.list({ collection = "woods", kind = "bark" }) do print(m.id, m.style, m.tileSize, m.textureKB) end ``` `Materials.apply` returns `ok, err`; the `assert`s make a failed apply stop with its reason instead of leaving the crate grey. To walk round every wood, open the gallery scene that comes in the package. No code is needed: in the shell run `zero scene load woodsMaterials.WoodsGallery`, or set it as your world's start scene in `.world_settings` (`startup_scene = "woodsMaterials.WoodsGallery"`). Every wood stands in its own bay on all six sample shapes (a floor tile and a wall at real scale, and a cube, sphere, shader ball and cylinder standing side by side so none hides another), with its reference picture framed on the wall above them. The toolbar switches the lighting look for everyone, and **Materials** on the toolbar opens the picker. Each player arrives on a spot of their own, and the scene lifts their orbiting camera to 3 m so their avatar stays below the line of sight to the bays. To put the gallery in a scene of your own instead, add it in that scene's `build.luau`. `WoodsShowcase` opens it on the page of woods and hangs each wood's reference picture beside it: ```luau local g = entity.spawn("Gallery") g.component.add("SwatchGallery", {}) g.component.add("WoodsShowcase", {}) ``` The gallery stands around the origin, so put the player's spawn there. The world this package comes from, "Heartwood: The Woods Material Collection", opens straight into `WoodsGallery`, with the lighting looks (daylight, overcast, golden hour, moonlight, warm interior, studio) switchable live from the toolbar. ## The woods Every wood is tagged `category = wood`, with its `kind` (what kind of wood thing it is), its `style`, `tileSize` (metres covered by one texture repeat), roughness and metallic ranges, `textureKB` (GPU texture memory, mipmaps included), `animated = false`, and search words (species, finish, use). Filter on any of them, for example `Materials.list({ collection = "woods", tag = "oak" })`, `Materials.list({ kind = "bark" })` or `Materials.list({ collection = "woods", search = "weathered" })`. The library has six style families (`realistic`, `stylised`, `toon`, `pixel`, `scifi`, `fantasy`), so the hand-painted planks are style `stylised` and carry the tag `hand-painted`: `Materials.list({ tag = "hand-painted" })` finds them. Texture sizes are albedo / normal / mask in pixels (the mask packs ambient occlusion, roughness and metalness; `-` means the wood does not use that map). Seam and shimmer are the scores materialLibraryKit's `Checks.run` reported for each wood on 2026-10-20, on the desktop engine; how each score passes or fails is explained under "Checked". | Name | Wood | Kind | Style | Tile (m) | Roughness | Metallic | Textures (px) | Texture memory | Seam / shimmer | |---|---|---|---|---|---|---|---|---|---| | `oakBoard` | Oak board | board | realistic | 0.5 | 0.6–0.76 | 0 | 512 / 512 / 512 | 1.3 MB | 0.72 / 0.58 | | `pineBoard` | Pine board | board | realistic | 0.5 | 0.62–0.69 | 0 | 512 / 512 / 512 | 1.3 MB | 0.92 / 1.22 | | `walnutBoard` | Walnut board | board | realistic | 0.5 | 0.42–0.54 | 0 | 512 / 512 / 512 | 1.3 MB | 0.87 / 0.99 | | `birchBoard` | Birch board | board | realistic | 0.5 | 0.62–0.64 | 0 | 512 / 512 / 512 | 1.3 MB | 0.85 / 0.09 | | `cherryBoard` | Cherry board | board | realistic | 0.5 | 0.45–0.53 | 0 | 512 / 512 / 512 | 1.3 MB | 0.61 / 0.30 | | `mapleBoard` | Maple board | board | realistic | 0.5 | 0.51–0.57 | 0 | 512 / 512 / 512 | 1.3 MB | 1.42 / 0.16 | | `mahoganyBoard` | Mahogany board | board | realistic | 0.5 | 0.46–0.55 | 0 | 512 / 512 / 512 | 1.3 MB | 1.44 / 2.84 | | `oakPlanks` | Oak planks | planks | realistic | 1.2 | 0.52–0.66 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.15 / 0.66 | | `weatheredPlanks` | Weathered grey planks | planks | realistic | 1.2 | 0.74–0.9 | 0 | 1024 / 1024 / 512 | 3.3 MB | 3.60 / 2.21 | | `parquetHerringbone` | Parquet herringbone | parquet | realistic | 0.99 | 0.32–0.54 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.22 / 0.53 | | `plywood` | Plywood | plywood | realistic | 0.6 | 0.61–0.66 | 0 | 512 / 512 / 512 | 1.3 MB | 0.80 / 0.26 | | `paintedWoodChipped` | Painted wood (chipped) | painted | realistic | 1.2 | 0.52–0.77 | 0 | 1024 / 1024 / 512 | 3.3 MB | 0.78 / 1.26 | | `varnishedFloor` | Varnished floor | floor | realistic | 1.2 | 0.14–0.21 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.53 / 1.73 | | `endGrain` | End grain | end grain | realistic | 0.3 | 0.55–0.84 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.73 / 1.76 | | `oakBark` | Oak bark | bark | realistic | 1 | 0.83–0.95 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.15 / 4.28 | | `pineBark` | Pine bark | bark | realistic | 1 | 0.8–0.94 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.13 / 4.34 | | `birchBark` | Birch bark | bark | realistic | 1 | 0.64–0.87 | 0 | 1024 / 1024 / 512 | 3.3 MB | 1.32 / 0.68 | | `beechBark` | Beech bark | bark | realistic | 1 | 0.6–0.83 | 0 | 1024 / 1024 / 512 | 3.3 MB | 0.80 / 1.69 | | `driftwood` | Driftwood | driftwood | realistic | 0.6 | 0.73–0.9 | 0 | 512 / 512 / 512 | 1.3 MB | 1.18 / 0.43 | | `charredWood` | Charred wood (yakisugi) | charred | realistic | 0.5 | 0.58–0.95 | 0 | 512 / 512 / 512 | 1.3 MB | 1.10 / 0.47 | | `bamboo` | Bamboo | bamboo | realistic | 0.48 | 0.37–0.45 | 0 | 512 / 512 / 512 | 1.3 MB | 0.54 / 0.42 | | `toonPlanks` | Toon planks | planks | toon | 1 | 0.85 | 0 | 256 / - / - | 85 KB | 0.83 / 2.33 | | `toonLog` | Toon log | log | toon | 1 | 0.85 | 0 | 256 / - / - | 85 KB | 3.59 / 3.49 | | `handPaintedPlanks` | Hand-painted planks | planks | stylised | 2 | 0.85 | 0 | 512 / 512 / - | 683 KB | 4.57 / 3.71 | | `pixelPlanks` | Pixel-art planks | planks | pixel | 1 | 0.85 | 0 | 32 / - / - | 1 KB | 6.00 / 3.47 | ### Texture memory - **All 25 woods: 48.8 MB** of GPU texture memory, mipmaps included. Each wood's maps are its own, so this is the per-wood sum. - **Reference pictures: 8.3 MB** (25 at 512 px). They are only loaded where the gallery shows them. - **Everything together: 57.2 MB.** The largest wood is 3.3 MB; the 512 px woods are 1.3 MB; the toon woods 85 KB; the pixel-art planks 1 KB. - Every wood binds at most 5 sampled textures (the web limit is 9) and no storage buffers, and passes `Checks.budget`. - Textures are UASTC and transcode to BC7 on desktop and ASTC on mobile. ### On the web Checked against the browser engine's limits with materialLibraryKit's `Checks.budget` and `Checks.textureMemory` (2026-10-20): - **Total texture memory of the collection: 48.8 MB** for all 25 woods, plus 8.3 MB of reference pictures where the gallery shows them: 57.2 MB in all. That is about a seventh of the library's 384 MiB budget for low-end devices. - **Every wood passes the web budget with no warnings:** at most 5 textures sampled per draw (the browser limit is 9), no storage buffers, at most 3.3 MB per wood (the per-material limit is 24 MiB), nothing over 1024 px. - **All 89 textures are GPU-compressed** (UASTC, 20 at 1024 px, 66 at 512 px, 2 at 256 px, 1 at 32 px), so none needs a filtering mode a browser lacks. - The gallery page of woods is 25 bays and about 280 entities, about 1.5 times a full page of the core gallery (16 bays), which materialLibraryKit measured at 47–60 fps in a browser tab. **Run in a browser (2026-10-20).** The world was opened in a browser tab of the Zero editor and played; the editor measured that tab with materialLibraryKit's `Gallery.requestTour()`. This run was made before the six woods listed under "Second pass" below were redone; the redone woods use the same texture sizes except end grain, which grew from 1.3 to 3.3 MB. The tab's viewport was 840 × 632 at render scale 1, and its frame rates: | What the tab showed | Bays | Entities | fps | |---|---|---|---| | Empty floor (the tab's own ceiling) | 0 | 0 | 37.4 | | Page 1 (the core's calibration shelf) | 20 | 225 | 26.3 | | **Page 2, all 25 woods with their reference pictures** | 25 | 280 | **32.7** | | Close-up view | 1 | 28 | 40.0 | | Compare view | 2 | 23 | 38.5 | - The woods page ran at 32.7 fps against 37.4 fps on an empty floor, so the 25 woods with their references cost the tab about 13%. Left on the woods page without the tour, the tab reported 37–48 fps. - The tab ran the browser **editor**, whose own interface sets that 37 fps ceiling; the published player page carries no editor and runs faster (the core measured 47–60 fps there). - Every wood rendered in the browser: a wood applied from the desktop editor (charred wood on the oak board bay's sphere) reached the tab, whose report showed the material it wanted and the one on its model agreeing, and clearing it put the oak board back on both screens. ## How they were made - **Baked procedurally in Luau** (`WoodBaker`, `WoodRecipes`): 21 of the 25 woods. Every map is periodic over one repeat, so it tiles with no seam by construction, and is drawn at real scale (1 unit = 1 m). After baking, each texture is rolled so its wrap falls on its calmest row and column, which keeps a crack or a grain line from running exactly along the texture edge. - **Four woods from their own reference pictures.** Oak bark, pine bark, birch bark and driftwood did not read as their references when drawn procedurally, so each was synthesised from its reference picture by the engine's `pbr_gen` service (a seamless base colour, height and roughness) and brought in by `WoodRecipes.importScan`, which: - removes low-frequency light from the colour and lifts cavity darkness out of it (the ambient-occlusion channel carries it instead), so the colour map holds no painted-in light; - matches the average colour to the reference picture, channel by channel; - maps roughness into the wood's physical range and derives green-up normals and occlusion from the height. The baked textures in `textures/` are the masters for these four; their recipes refuse to re-bake and point at `importScan`. - **Real-world sizes.** - Species boards: two 25 cm boards per 0.5 m repeat, each cut around one cathedral. - Oak planks: 15 cm wide, 1.2 m long, 3 mm bevels, staggered butt joints. Weathered planks: 20 cm wide with 6 mm gaps and nail heads 9 mm across. Varnished strips: 12 cm. Painted planks: 15 cm. - Herringbone: oak blocks 7 x 35 cm at 45 degrees; the repeat is two herringbone periods, 0.99 m. - End grain: 5 cm butcher-block blocks in alternating light and dark wood, with 3.5 to 5.5 mm growth rings and a band of open pores along each ring. - Bark: a 1 m repeat; oak fissures a few centimetres apart, pine plates roughly 8 to 12 cm wide, birch diamond scars 2 to 8 cm across. - Driftwood: 0.6 m repeat of split, bleached grain. Charred wood: alligator blocks about 1.6 cm wide and 1.5 to 2.5 cm tall. Bamboo: 4 cm poles with nodes about 24 cm apart. - **Growth rings like a real board.** The grain is a tapered log's rings cut by the board's face, so flat-sawn faces show nested cathedral arches with near-straight sides and quarter-sawn mahogany shows straight stripes and a ribbon figure. - **Physically based.** - The colour maps carry no painted-in light or shadow; grooves, joints and furrows darken through the ambient-occlusion channel. Albedos were measured against each reference picture. - Wood is a dielectric: metallic is 0 everywhere. - Roughness follows the finish: the varnished floor 0.14–0.21 (the glossiest), lacquered parquet 0.32–0.54, oiled walnut, cherry and mahogany 0.42–0.57, raw boards 0.5–0.76, weathered wood and driftwood up to 0.9, bark and charred wood up to 0.95. - Normal maps use the green-up convention the engine reads, and raised grain, plank bevels and bark ridges face outward (checked in the core's normal pass). - **Grain runs one way.** In every wood the grain, the plank length, the bark fissures and the bamboo poles run along the texture's V (up the image). On the gallery's walls and the engine's cylinder that is vertical, so bark runs up a trunk and bamboo stands upright. - **Kept calm at a distance.** At full scan contrast, oak and pine bark shimmered at 30 m (scores of 14.2 and 7.1): seen edge-on from that far, their dark crevices repeat about every one and a half screen pixels. Their ridge-to-furrow colour contrast is therefore compressed (the depth stays in the normals and occlusion), which brings them to 4.28 and 4.34. These were the same in three runs on the desktop engine; on another machine the score of the earlier oak bark measured about 0.75 higher, which would still leave both under the limit of 6. - **Stylised woods.** The toon planks and toon log use a small cel shader shipped in the package (`toonWood`): the sun's light stepped into three flat bands with a lifted shadow, no specular and no metalness, over flat colour with bold ink lines. The hand-painted planks are a non-metallic PBR material with brush-stroke colour bands, lighter worn edges, dark painted seams and iron nail heads. The pixel-art planks are a 32 x 32 texture drawn with nearest filtering. - **Reference pictures.** Every wood has a reference picture (`references/<id>`), generated before its material and compared with it side by side: first as colour statistics, then as unlit albedo next to the picture, then lit in the gallery. The gallery hangs each picture on its wood's bay. - **Second pass.** Six woods were redone after they were seen in their bays against their references: oak, pine and birch bark and driftwood (from their reference pictures, above), the birch board (now a smooth, even cream with faint grain, where it had grey blotches) and end grain (doubled to 1024 px so its rings and pores read from a few metres, where it had looked like a plain checkerboard). The other 19 were left as they were. ## Checked Every wood passes all of the core's `Checks.run`: - **Diagnostic views:** final, albedo, roughness, metallic and normal on a sphere, a tile and a shader ball. - **Seams:** the wood is tiled 4 x 4 and rendered from above, and the average brightness jump across tile boundaries is compared with the jumps inside a tile. The **seam score** is boundary jump ÷ interior jump. The render passes when *any* of these holds: the boundary jump is at most 3 code values, or the score is at most 2, or the boundary jump is no bigger than 1.1 × the strongest edges inside a tile (their 98th percentile). Separately, every texture's opposite edges must match. So a score above 2 can still pass when the wood's own pattern has edges as strong as its tile boundary: the pixel-art planks (6.0) are hard pixel edges everywhere, and the hand-painted planks (4.57), toon log (3.59) and weathered planks (3.60) have bold strokes, ink lines and plank gaps inside each tile. All 25 pass. - **Shimmer:** near (about 1.5 m) and far (30 m, grazing) views; the **shimmer score** is how many code values the far view moves under a half-pixel camera shift. It fails above 6. The highest are pine bark (4.34) and oak bark (4.28). - **Texture memory** cross-checked against what the renderer holds, and the **web budget**. The package's test suite reruns all of them and also covers the 25 names, every tag, the styles, the filters, the costs, the physical ranges, the tile sizes, apply / swap / clear, the picker, the gallery with every sample shape unobstructed and its reference boards, the toon shader, the declared dependency and this README. It runs from any scene. The test runner despawns everything a test leaves behind, so the suite never rebuilds a gallery that is already standing; when none is (the engine's own runner, `tests.run`, unloads the open scene before a suite), it stands one up the way the package ships it (`SwatchGallery` with `WoodsShowcase`) and removes it again. To run it: ```luau asset.resolve("woodsMaterials", "testSuite"):run() ``` ## Multiplayer `Materials.apply` goes through the core's shared `materials` channel, so a wood one player puts on something shows on every player's machine, and players who join later get it too. Gallery swatches and reference boards are local to each machine and cost the network nothing. Lighting looks are shared the same way. ## Known limits - **Duplicate calibration entries in a fresh world.** The core's own published record still pulls its retired 1.0.0 version, so a fresh world lists the core's `calibration` collection twice and `Materials.problems()` reports the duplicates (17 in a brand-new world checked on 2026-10-20 with 1.0.1). The woods are not affected: none of their ids is shared, the woods report no problems, and the gallery still opens with all 25 woods on one ring of their own. This belongs to the materialLibraryKit core: its published record still depends on the retired 1.0.0 record (zero#19444). - **One repeat per primitive face.** The engine's cube, sphere and cylinder carry one texture repeat per face (UV 0..1), so a wood shows at real scale on them only when the object is sized to its `tileSize` (or a multiple, with the material's `uv_scale`). The gallery's floor tiles and walls lay their UVs out in metres, so they always show real scale. - **The install download is larger than the texture memory.** Each texture keeps its lossless PNG source beside its GPU data, because materialLibraryKit measures texture cost from the source image. The woods package is about 111 MB on disk (561 files); what the GPU holds is the 48.8 MB above. - **Oak and pine bark carry less colour contrast than their reference pictures.** It was compressed to pass the 30 m shimmer check (see "Kept calm at a distance"); their furrows read through the normal and occlusion maps. - **The four scanned woods can't be re-baked from code.** Their textures are the masters; regenerate from the reference picture and run `WoodRecipes.importScan` to redo one. - **The toon log is the log's side.** `toonLog` draws bark lines along the log; it does not paint growth rings on a cylinder's end caps. - **The species boards are glued panels.** Each 0.5 m repeat holds two 25 cm boards with a hairline joint, the way a tabletop or panel is made, so a single repeat never shows the inverted arches a periodic ring pattern would otherwise have. - **Toon woods have no diagnostic channels.** `toonWood` is a self-shading shader, so the core's albedo, roughness and metallic passes draw it magenta; its final and normal views are normal. - **Engine issues, as listed in materialLibraryKit's README:** - No `asset.materialCollection.*` namespace yet (gh#1889), so the woods are reached through `Materials.*`. - Name tags sometimes read `{PlayerName}` (gh#19201). - Two-player behaviour can't be tested inside one engine (gh#18688, gh#19114); shared woods were checked through the core's sync report on one peer, and live with a browser tab. - The engine's normal-map green convention is undocumented (gh#19414). These maps are green-up.