# coatedFinish Two-layer finish shader for the metallic and pearl car paints, the stylised candy paint, the carbon fibres and the diner vinyl of syntheticsMaterials. The base (tilted aluminium or mica flakes, painted flecks, or woven carbon tows) is lit with its own normal map; a smooth clear coat on top is lit with the surface's geometric normal (or follows the base, `coat_follows_base`), both through the engine's own PBR lighting (every light, shadows and the environment), and combined with the coat's Fresnel. The engine's `pbr` clearcoat shares the base's bumpy normal, which is why this exists. The mask packs occlusion, roughness, flake coverage and the sine of twice the fibre angle; the base colour's alpha carries the cosine, so each tow or forged chip has its own highlight direction. Base roughness widens with screen-space normal variation, so flakes and tows below a pixel average out instead of shimmering. **Glints** (`sparkle`, `sparkle_cells`, `sparkle_tilt`, `sparkle_cone`): a UV grid of cells each holding one randomly tilted flake (tilts spread as a gaussian with a wider tail); a flake flashes when it reflects the sun or a distant, point or spot light to the eye. Cells coarsen with distance and the glints fade once a pixel holds enough flakes that one always catches the light, so there is sparkle up close and none at 30 m. **Colour travel** (`flake_edge_color`, `flop`, `flop_power`, `flop_body`): the flakes' colour, and with `flop_body` the base coat's, moves from `flake_color` (face-on, near the sun's mirror direction) to `flake_edge_color` (away from it and toward grazing). `relief_fade` fades large regular relief by pixel footprint so it never moirés. The capture tool's albedo, roughness and metallic passes read the base layer.

# syntheticsMaterials: Polish and Polymer **31 real-scale synthetics and finishes for the Swatchbook material library, in three style families (realistic, stylised, toon): plastics, rubber, foam, vinyl, carbon fibre, car paint with a real clear coat, ceramic, porcelain, enamel, lacquer, kitchen worktops and laminates, each reached by one name.** **Version 1.0.3. Depends on materialLibraryKit 1.3.1** (Swatchbook), which installing this package brings with it. Nothing else is installed and there is no setup code: once installed, every material is in the library's list, picker and swatch gallery on every player's machine. **Download size:** the package is **894 files, 87.0 MB**, of which **61.1 MB are the 31 reference pictures** (kept at full 1024 px in the package; the engine loads them at 512 px), 16.3 MB the material textures (source files and previews) and 5.2 MB the 84 display-piece meshes. materialLibraryKit adds 139 files and 0.9 MB. (Measured on 2026-10-26 by summing the package's files; ZeroMind's installer reported 1,105 files for 1.0.0, as it also counts the files it writes for the dependency and its own records.) Once running, all 31 materials take 12.2 MB of GPU texture memory; see "Texture memory". ## Install and use Install **syntheticsMaterials** from ZeroMind (search "syntheticsMaterials" or "Polish and Polymer"). It lands at `/source/syntheticsMaterials.package`, with materialLibraryKit 1.3.1 under `/source/deps/`. Then, in a brand-new world, run this from a script or the console (`execute`): ```luau local Materials = require("~materialLibraryKit.Materials") local panel = entity.spawn("panel", { synced = true, components = { Model = { model = "sphere" } } }) panel.localPosition = { 0, 1, 3 } assert(Materials.apply(panel, "carPaintMetallic")) -- every player sees metallic blue assert(Materials.apply(panel, "carPaintPearl")) -- one word changes it to pearl assert(Materials.apply(panel, "stylisedCarPaint")) -- or to hand-painted paint for a stylised world assert(Materials.apply(panel, "toonCarPaint")) -- or to the toon paint for a cartoon world for _, m in Materials.list({ collection = "synthetics", kind = "car paint" }) do print(m.id, m.style, m.tileSize, m.textureKB) end Materials.clear(panel) -- take the paint off again, for everyone entity.despawn(panel.id) -- and the ball ``` `Materials.apply(object, name)` puts a material on any `Model` and shares the choice with every player; `Materials.get(name).material` is the material asset itself, for a `Model` of your own. `Materials.list({ collection = "synthetics", ... })` filters by `kind` (`plastic`, `rubber`, `foam`, `vinyl`, `carbon fibre`, `car paint`, `ceramic`, `porcelain`, `enamel`, `lacquer`, `quartz`, `granite`, `laminate`), `style` (`realistic`, `stylised`, `toon`), `tag` (`clearcoat`, `metal flake`, `sparkle`, `colour travel`, `anisotropic`, `textures-none`…) or `search`. To walk round every material, make your start scene the gallery (as this world's `scenes/main.scene` does), or stand it in a scene of your own (`build.luau`, spawn near the origin): ```luau local g = entity.spawn("Gallery") g.component.add("SwatchGallery", { view = "all", lighting = "studio" }) g.component.add("SyntheticShowcase", {}) -- all 31 on one ring, each with its reference picture require("~syntheticsMaterials.SyntheticExhibits").build() -- the car panels and the kitchen ``` ### Real size on the display pieces Textured materials repeat once per UV unit (the library's convention; `tileSize` says how many metres that is), so a piece shows real scale when its UVs run metres ÷ tileSize. The package ships those pieces as meshes baked for every tile size it uses: `meshes/carPanel_<mm>` (a 1.6 × 0.9 m doubly-curved body panel), `counter_<mm>` (1.2 × 0.03 × 0.62 m worktop), `door_<mm>` (0.6 × 0.72 m cupboard front), `mug_<mm>`, `pot_<mm>` and `mat_<mm>` (a 0.9 × 0.6 m floor mat). `SyntheticSurface` swaps a piece to the right one whenever any player applies another material: ```luau local door = entity.spawn("door", { synced = true, components = { Model = { model = "syntheticsMaterials.meshes.door_400", material = "syntheticsMaterials.materials.laminateWoodgrain" } } }) door.component.add("SyntheticSurface", { shape = "door", material = "laminateWoodgrain" }) ``` ## How the collection is set up The library finds materials through **material collections**: any `<name>.materialCollection/collection.yaml` in the world registers with materialLibraryKit when it loads, which is why installing the package is the whole setup. This package has one, `synthetics.materialCollection`, and it is written by code, never by hand: - **`SyntheticCatalog`** is the single definition of every material: one entry each, in `ENTRIES`. `SyntheticCatalog.build()` writes `materials/<id>.material/mat.yaml` for every entry and the collection's `collection.yaml` with the tags, the roughness and metal ranges it measures from the baked masks, and the texture memory it measures from the textures each material binds. `SyntheticCatalog.writeBoards()` writes the reference board each gallery bay hangs. - **`SyntheticRecipes`** holds one procedural recipe per textured material and bakes its maps into `textures/` through **`SyntheticBaker`**. `bakeAll()` re-bakes everything and calls `build()`. - **`references/<id>`** is the material's reference picture, and `boards/<id>` the unlit material that shows it in the gallery. ### What a new material has to provide To add a material that belongs to the collection (and passes its tests): 1. **A catalog entry** in `SyntheticCatalog.ENTRIES` with: `id` (the one name players and scripts use; camelCase, unique across the library), `name` (display name), `group`, `kind`, `style` (`realistic`, `stylised` or `toon`; the library also knows `pixel`, `scifi`, `fantasy`), `tileSize` (metres one texture repeat covers; `1` for untextured), `words` (search words), `description`, `res` (pixel sizes of the `albedo`, `normal` and `mask` maps it needs; `{}` for none), `props` (shader properties), `shader` (omit for the engine's `pbr`, or `C.SHADERS.coated` / `C.SHADERS.toon`), `metal` (the metallic range when it is not a constant), `sizes` (the real dimensions, in words) and `prompt` (what its reference picture shows). 2. **A reference picture first:** generate `references/<id>.png` from the entry's `prompt` before making the material, set its texture to at most 512 px, and compare the material against it in the gallery. 3. **A recipe** in `SyntheticRecipes` if it has textures. The recipe must be periodic over one repeat (the baker's generators are), put **no light in the colour** (pits and seams darken through the occlusion channel and the normal map), keep base colours inside 0.01–0.9, write heights in metres with raised = toward the viewer (the baker writes **green-up** normal maps), and pack the mask as R = occlusion, G = roughness, B = metallic (pbr) or flake coverage (coatedFinish). 4. **Run `SyntheticRecipes.bakeAll({ "<id>" })`** (it rebuilds the collection) and `SyntheticCatalog.writeBoards()`. Colours in `mat.yaml` must be flow lists (`[r, g, b, a]`), which `build()` writes; see "Design notes". 5. **Check it** with the library's `Checks.seams`, `Checks.shimmer` and `Checks.budget` (at most 9 textures and 1 buffer per material, no warnings), add its id to the test suite's `REQUIRED` list and its row to this README, and run the suite. Every entry ends up tagged `category = synthetic`, with its kind, style, `tile-<metres>m` (or `tile-uniform`), roughness and metal range, finish (`glossy` / `satin` / `rough`), metal word, texture weight (`textures-none` / `-tiny` / `-light` / `-medium`), the layers it uses, `not-animated` and its words. ## The materials Every material is tagged `category = synthetic`, with its `kind`, its `style`, `tileSize` (metres one repeat covers; `1` and `tile-uniform` for the untextured ones, which are the same everywhere), roughness and metallic ranges (measured from the baked masks), `textureKB` (GPU memory, mipmaps included), and `animated = false`. Its tags add the layers it uses (`clearcoat`, `two-layer`, `metal flake`, `sparkle`, `colour travel`, `anisotropic`, `sheen`, `subsurface`, `cel-shaded`, `reflection band`), a finish, a metal word, a texture weight, `tile-<metres>m`, `not-animated`, and search words. Textures lists albedo / normal / mask sizes in pixels (`-` means none). Seam is `Checks.seams`' score at 4 × 4, shimmer `Checks.shimmer`'s score at 30 m (fails above 6). Both measured on 2026-10-25 with materialLibraryKit 1.3.1 on the desktop engine; see "Checked". | Name | Material | Kind, style | Tile (m) | Real sizes | Roughness | Metal | Shader, layers | Textures (memory) | Seam / shimmer | |---|---|---|---|---|---|---|---|---|---| | **Plastics** | | | | | | | | | | | `plasticMatte` | Matte ABS plastic | plastic | 0.05 | spark-eroded texture, pits 0.05 to 0.2 mm; 50 mm repeat | .60 | .00 | pbr | - / 256 / - (85 KB) | 0.00 / 0.03 | | `plasticGloss` | Glossy red plastic | plastic | uniform | uniform (polished mould, no texture) | .10 | .00 | pbr | - / - / - (none) | 0.00 / 0.00 | | `plasticTextured` | Moulded grain plastic | plastic | 0.1 | moulded leather grain, pebbles 1 to 3 mm; 100 mm repeat | .51–.79 | .00 | pbr | - / 512 / 256 (427 KB) | 0.00 / 0.13 | | `plasticSoftTouch` | Soft-touch plastic | plastic | 0.02 | stipple 0.03 to 0.08 mm; 20 mm repeat | .68 | .00 | pbr: sheen | - / 256 / - (85 KB) | 0.00 / 0.00 | | **Rubber** | | | | | | | | | | | `rubberTyre` | Worn tyre rubber | rubber | 0.15 | abrasion streaks 5 to 40 mm along U, pits and cuts 0.5 to 3 mm; 150 mm repeat | .76–.93 | .00 | pbr | 256 / 512 / 256 (512 KB) | 1.59 / 0.20 | | `rubberStuddedFloor` | Studded rubber floor | rubber | 0.2 | studs 26 mm across, 2.5 mm high, 50 mm grid; 4 x 4 studs per repeat | .65–.88 | .00 | pbr | 256 / 512 / 256 (512 KB) | 0.17 / 2.19 | | **Foam** | | | | | | | | | | | `foamPolyurethane` | Open-cell foam | foam | 0.06 | open cells 0.6 to 1.2 mm; 60 mm repeat | .92 | .00 | pbr | 512 / 512 / 512 (1.0 MB) | 1.24 / 0.14 | | `foamEVA` | Closed-cell foam mat | foam | 0.1 | pebbled skin, pebbles 1.5 to 2 mm, pinholes 0.3 mm; 100 mm repeat | .72 | .00 | pbr | 256 / 512 / - (427 KB) | 0.41 / 0.12 | | **Vinyl** | | | | | | | | | | | `vinylFloor` | Vinyl sheet flooring | vinyl | 0.25 | chips 1 to 5 mm, emboss 0.3 to 1 mm; 250 mm repeat | .50 | .00 | pbr | 512 / 512 / - (683 KB) | 0.98 / 0.29 | | `vinylUpholstery` | Diner booth vinyl | vinyl | 0.24 | channels 120 mm wide padded 3.5 mm, stitched seams, stitches 5 mm; grain 0.3 to 1 mm; 240 mm repeat | .24–.36 | .00 | coatedFinish: clearcoat, two-layer | - / 512 / 256 (427 KB) | 0.00 / 1.67 | | **Carbon fibre** | | | | | | | | | | | `carbonTwill` | Carbon fibre twill | carbon fibre | 0.032 | 2/2 twill, 3K tows 2.0 mm wide; 16 x 16 tows per repeat | .30–.51 | .55 | coatedFinish: clearcoat, two-layer, anisotropic | 512 / 512 / 512 (1.0 MB) | 1.05 / 0.00 | | `carbonForged` | Forged carbon | carbon fibre | 0.15 | chopped chips 8 to 30 mm long, 3 to 10 mm wide; 150 mm repeat | .40–.49 | .40 | coatedFinish: clearcoat, two-layer, anisotropic | 512 / 512 / 512 (1.0 MB) | 1.44 / 1.69 | | **Car paint** | | | | | | | | | | | `carPaintSolid` | Solid gloss car paint | car paint | 0.05 | orange peel waves 2 to 6 mm; 50 mm repeat | .40 | .00 | pbr: clearcoat | - / 256 / - (85 KB) | 0.00 / 0.00 | | `carPaintMetallic` | Metallic flake car paint | car paint | 0.05 | aluminium flakes 0.2 to 0.5 mm, tilted up to 25 degrees; 50 mm repeat | .10–.42 | .00–1.00 | coatedFinish: clearcoat, two-layer, metal flake, sparkle | - / 512 / 512 (683 KB) | 1.03 / 0.21 | | `carPaintPearl` | Pearl tri-coat paint | car paint | 0.025 | mica flakes 0.1 to 0.25 mm (the metallic flake map at half size); 25 mm repeat | .10–.42 | .00–.85 | coatedFinish: clearcoat, two-layer, metal flake, sparkle, colour travel | - / 512 / 512 (683 KB) | 1.05 / 0.01 | | `carPaintMatte` | Matte wrap film | car paint | 0.05 | cast-film texture 0.05 to 0.2 mm; 50 mm repeat | .55 | .00 | pbr | - / 256 / - (85 KB) | 0.00 / 0.00 | | **Ceramic and finishes** | | | | | | | | | | | `ceramicGlazed` | Speckled stoneware glaze | ceramic | 0.12 | iron speckles 0.3 to 1.5 mm, glaze ripple 5 to 20 mm; 120 mm repeat | .45 | .00 | pbr: clearcoat | 512 / 256 / - (427 KB) | 1.01 / 0.35 | | `porcelainWhite` | White porcelain | porcelain | uniform | uniform (glazed, no texture) | .35 | .00 | pbr: clearcoat, subsurface | - / - / - (none) | 0.00 / 0.00 | | `enamelSteel` | Cobalt vitreous enamel | enamel | 0.2 | glass ripple 10 to 40 mm, pinholes 0.2 mm; 200 mm repeat | .30 | .00 | pbr: clearcoat | - / 256 / - (85 KB) | 0.00 / 0.37 | | `lacquerPiano` | Piano black lacquer | lacquer | uniform | uniform (polished level, no texture) | .25 | .00 | pbr: clearcoat | - / - / - (none) | 0.00 / 0.00 | | `lacquerRed` | Cinnabar red lacquer | lacquer | uniform | uniform (hand-rubbed, no texture) | .35 | .00 | pbr: clearcoat | - / - / - (none) | 0.00 / 0.00 | | **Kitchen surfaces** | | | | | | | | | | | `countertopQuartz` | Polished quartz countertop | quartz | 0.5 | quartz grains 0.5 to 4 mm; 500 mm repeat | .08 | .00 | pbr | 1024 / - / - (1.3 MB) | 1.14 / 0.12 | | `countertopGranitePolished` | Polished granite countertop | granite | 0.5 | crystals 2 to 8 mm; 500 mm repeat | .07 | .00 | pbr | 1024 / - / - (1.3 MB) | 1.15 / 2.66 | | `laminateWoodgrain` | Oak woodgrain laminate | laminate | 0.4 | grain lines 1 to 4 mm apart, pores 0.2 to 0.5 mm, ray flecks 3 to 15 mm; 400 mm repeat | .45 | .00 | pbr | 1024 / 512 / - (1.7 MB) | 1.01 / 0.14 | | `laminateSolid` | Plain matte laminate | laminate | 0.05 | suede emboss 0.05 to 0.3 mm; 50 mm repeat | .55 | .00 | pbr | - / 256 / - (85 KB) | 0.00 / 0.00 | | **Toon** | | | | | | | | | | | `toonPlastic` | Toon plastic | plastic, toon | uniform | uniform (flat colour) | .20 | .00 | toonFinish: cel-shaded | - / - / - (none) | 0.00 / 0.00 | | `toonCarPaint` | Toon car paint | car paint, toon | uniform | uniform (flat colour) | .10 | .00 | toonFinish: cel-shaded, reflection band | - / - / - (none) | 0.00 / 0.00 | | `toonCeramic` | Toon ceramic | ceramic, toon | uniform | uniform (flat colour) | .30 | .00 | toonFinish: cel-shaded | - / - / - (none) | 0.00 / 0.00 | | **Stylised** | | | | | | | | | | | `stylisedPlastic` | Stylised painted plastic | plastic, stylised | 0.25 | painted strokes 25 to 70 mm long; 250 mm repeat | .38 | .00 | pbr | 256 / - / - (85 KB) | 1.04 / 1.34 | | `stylisedCarPaint` | Stylised candy paint | car paint, stylised | 0.25 | painted strokes 30 to 80 mm, flecks 1 to 2.5 mm; 250 mm repeat | .19–.35 | .00–.70 | coatedFinish: clearcoat, two-layer, metal flake, sparkle | 256 / - / 256 (171 KB) | 1.50 / 2.08 | | `stylisedCeramic` | Stylised drip-glaze ceramic | ceramic, stylised | 0.2 | painted strokes 15 to 50 mm, one blue band per 200 mm repeat (along V) | .40 | .00 | pbr: clearcoat | 256 / - / - (85 KB) | 0.67 / 2.49 | **Earlier names.** Seventeen materials have had other names: seven were renamed in 1.0.1 and ten in 1.0.2 (see "Version history"). Every earlier name still works where a world stores it: each is a material asset (`syntheticsMaterials.materials.<earlier name>`) that draws exactly what the new one draws, and the ten renamed in 1.0.2 kept their asset ids, so a saved scene follows them to the new name by itself. The earlier names are not library entries, so nothing shows twice in the list, picker or gallery; `SyntheticCatalog.currentName(name)` turns any earlier name into the current one, and `SyntheticSurface` accepts either. | Earlier name | Name now | | Earlier name | Name now | |---|---|---|---|---| | `plasticGlossy` | `plasticGloss` | | `paintSolidGloss` | `carPaintSolid` | | `rubberStudded` | `rubberStuddedFloor` | | `paintMetallic` | `carPaintMetallic` | | `foamOpenCell` | `foamPolyurethane` | | `paintPearl` | `carPaintPearl` | | `foamClosedCellMat` | `foamEVA` | | `paintMatteWrap` | `carPaintMatte` | | `vinylSheetFloor` | `vinylFloor` | | `quartzCountertop` | `countertopQuartz` | | `vinylDinerBooth` | `vinylUpholstery` | | `graniteCountertop` | `countertopGranitePolished` | | `ceramicSpeckled` | `ceramicGlazed` | | `countertopGranite` | `countertopGranitePolished` | | `enamelCobalt` | `enamelSteel` | | `lacquerPianoBlack` | `lacquerPiano` | | `laminatePlain` | `laminateSolid` | | | | **What the two special car paints do:** - **`carPaintMetallic` sparkles.** Besides the flake map (which, averaged, gives the soft metallic sheen), `coatedFinish` adds real glints: every light that lights the surface (the sun, and distant, point and spot lights) can flash individual flakes whose tilt reflects it to your eye, so the panel shows separate bright sparkles around and away from the highlight, which move as you move. Far away, where a pixel holds many flakes, the glints fade into the sheen, so they never shimmer at 30 m. - **`carPaintPearl` shifts colour, gently.** Its flakes and body read **lavender-rose** where you look at it face-on and close to the light's mirror direction, and **mint green** away from the light's reflection and toward grazing angles. On a curved panel the shift runs across the surface, and walking round it moves the shift, but it is a pastel pearl, not a chameleon paint, and how strong it looks depends on where the light is: strongest in sun (Daylight, Golden Hour), weakest under Overcast. ### Texture memory - **All 31 materials: 12.2 MB** of GPU texture memory (12,445 KB, mipmaps included, every texture counted once): 41 textures, all UASTC (BC7 on desktop, ASTC on phones), none over 1024 px. Summing each material's own `textureKB` gives 13,141 KB, because `carPaintMetallic` and `carPaintPearl` share one 683 KB set of flake maps. - **Seven materials need no texture at all** (the glossy plastic, porcelain, both lacquers, the three toons). The stylised three use one or two 256 px maps (171 KB or less each). The largest is `laminateWoodgrain` at 1.7 MB. - **Reference pictures: 10.3 MB** of GPU memory (31 at 512 px). They load only where the gallery hangs them. - **Everything together: 22.5 MB**, about a seventeenth 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 limit is 9) and no storage buffers. - **The pbr mask is one texture in two slots** (`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. - **Meshes:** the 84 display-piece meshes are geometry, not texture; a scene loads only the ones its pieces wear. ## How they were made - **Reference pictures first.** Every material has `references/<id>`, generated from the prompt in its catalog entry before the material was made: a flat, evenly lit close-up at the material's real width for patterned surfaces, a studio product shot for finishes whose look is their reflections (paints, lacquers, porcelain), a hand-painted game-asset render for the stylised family, and a cel-shaded render for the toons. Each material was then compared with its picture side by side in the gallery, and up close on the car panels. Flat-shot surfaces have their mean colour matched to the picture (scaled by 0.75 for the light a photo holds; the quartz picture sits low, so it uses 1.15, the stoneware 0.9 and the dusty tyre 0.6). - **Baked procedurally in Luau** by `SyntheticBaker` and `SyntheticRecipes` (`require("~syntheticsMaterials.SyntheticRecipes").bakeAll()` re-bakes all 23 textured materials in about a minute). Every field covers one repeat and every generator is periodic, so the maps tile by construction: - carbon twill is a real 2/2 twill: which tow is on top at each crossing, crimped where it dives under, filament striations along each tow; forged carbon is pressed chips each with its own fibre direction; - flake paint is aluminium platelets 0.2–0.5 mm, each tilted up to 28° and written straight into the normal map (flakes are facets, not heights); - studs, foam cells, pebbled EVA skin, moulded leather grain, spark-eroded ABS, abraded tyre rubber, vinyl chips, channel-stitched upholstery, speckled glaze, quartz grains, granite crystals and rift-sawn oak with pores and ray flecks, all at their stated real sizes; - the stylised family is layered, periodic brush strokes, each one flat paint, over a soft underlay: teal for the plastic, candy orange with chunky gold flecks for the car paint, and cream with a drip band of blue glaze for the ceramic. - **Physically based, stylised included.** Colour carries no painted-in light; pits, pores and seams darken through the occlusion channel and the normal map. The stylised family is hand-painted in colour only, so the scene still lights and shades it under every lighting look. Normal maps are green-up, the convention the engine reads, and the test suite proves the direction on a synthetic bump. Base colours stay inside 0.01–0.9. Metal appears only where it physically is: the paint flakes and the conductive carbon fibre. - **A real clear coat.** The engine's `pbr` clearcoat shares the base's normal-mapped normal, so a flake or weave normal map would make the coat itself bumpy. `coatedFinish` (this package) lights the base and the coat separately with the engine's own PBR lighting (every light, shadows and the environment): the base with its flakes or tows, the coat level over it (or following the base, for the upholstery topcoat), combined by the coat's Fresnel. It also gives each carbon tow and forged chip its own highlight direction, adds the flake glints and the pearl's colour travel described above, widens base roughness with screen-space normal variation so sub-pixel flakes don't sparkle into noise, and can fade large regular relief by footprint so it never moirés. Solid paint, lacquer, porcelain, enamel and the glossy plastic have no normal map (or only a coat-wide orange peel), so the engine's own `pbr` clearcoat is exactly right for them. - **A small cel shader for the toons.** `toonFinish` is adapted from fabricsMaterials' `toonFabric` (MIT): cel bands, lifted shadows, a hard highlight disc, and for car paint the painted sky-and-ground reflection band. ### What was reused, and what was not - **Used:** the library's collection contract, gallery, picker, lighting looks and checks (materialLibraryKit 1.3.1); fabricsMaterials' baker (itself masonry's, stone's and wood's, MIT), catalog, showcase and drape-mesh pattern, and its toon shader; the engine's `pbr` shader with its clearcoat, anisotropy, sheen and subsurface lobes, and its PBR lighting inside `coatedFinish`. - **Not used:** the engine's `metal_chrome`, `glass`, `plastic_red` and `plastic_white` (plain uniform values; chrome and glass are not synthetics, and the plastics are a generic roughness 0.5 with no finish of their own). `pbr_layered` (coverage-masked wear over a base) was not needed: no material here is a wear layer. - **Not used:** published carbon, car paint, porcelain and enamel materials in other games. NIGHTGLIDE's carbon is 4096 px textures with a base colour above 1 and the coat sharing the weave's normal; the car paints and porcelains are flat values or generated maps with no stated scale, several with base colours above 1. ## Checked On 2026-10-25, desktop engine, materialLibraryKit 1.3.1, for **all 31** materials: - **Seamless tiled 4 × 4:** `Checks.seams` renders a 4 × 4-repeat plane and checks every texture's opposite edges. All 31 pass both. - **No shimmer or moiré at 30 m:** `Checks.shimmer` moves a grazing 30 m view by half a pixel and measures the change. All 31 are under the limit of 6. The worst are `countertopGranitePolished` 2.66, `stylisedCeramic` 2.49, `rubberStuddedFloor` 2.19 and `stylisedCarPaint` 2.08; the sparkling `carPaintMetallic` stays well inside the limit. - **Web budget:** `Checks.budget` passes with no warnings for every material. - **Against the references:** side by side in the gallery, and at arm's length and 3 m on the car panels under Studio and Daylight: the metallic shows separate sparkles across its sunlit area; the pearl reads lavender-rose near the light's reflection and mint away from it, greener from one side than the other. - **From the spawn:** every exhibit sign and label is projected through the spawn camera and checked against every gallery label: none covers a gallery label and none stands in front of an exhibit piece (the floor mat's label is a low placard beside it; the kitchen title stands in the gap between the runs). The panel labels sit high enough to clear your own avatar's head. Checked again in play with the real camera. - **Shared with every player:** in play, `Materials.apply` on a scene panel swaps metallic → pearl → twill → toon by one word through the library's shared channel, and `SyntheticSurface` follows with the right real-size mesh each time. The test suite reruns the quick parts in under a minute: ```luau asset.resolve("syntheticsMaterials.tests.syntheticsMaterials", "testSuite"):run() ``` It covers the 31 names and every tag, the filters (the three style families included), the costs and budget, the physical values and normal direction, seams and shimmer on one material per shader path (studded rubber, metallic paint, carbon twill, toon car paint), the library's diagnostic views on granite and metallic paint, apply / swap / clear, `SyntheticSurface`, the references, the picker, all 31 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, the gallery's swatches), and players who join later get it too. - **Display pieces follow.** `SyntheticSurface` makes the same mesh swap on every machine from the shared material. - **Lighting looks are shared.** The gallery's toolbar switches them for everyone. - **Gallery pieces are local.** Swatches and reference boards are built on each machine. ## Known limits Every limit here is an open engine issue; `gh#N` is issue N at github.com/OrigoZero/zero. - **The gallery runs at about 8 fps in a web browser (gh#20750).** Measured by the world's owner on 2026-10-25 with 1.0.1, playing this world's gallery start scene in a web browser: **about 8 fps** (median of five readings, 7.9–8.5). In the desktop editor the library's own `Gallery.tour()` measured 12.3 fps on this pack's page against 14.0 fps for the empty floor (2097 × 1409 viewport). The frame is dominated by the engine's `gather_and_send_deltas.settle_loans` working through the gallery's local swatch entities, which is the cost gh#20750 tracks; the materials themselves cost nothing per frame beyond their draws. - **1.0.2 was not re-measured in a browser (gh#20946).** An agent working in the desktop engine cannot start a browser engine to check the web build, so the figure above is 1.0.1's. 1.0.2 changes names, tags and sign positions only, not what the gallery draws. - **The test suite takes 35 to 45 seconds (gh#19849).** Most of it is the engine rendering the seam, shimmer and diagnostic-view checks; the call runs as a background task. - **The engine's own clear coat uses the base's normal (gh#21208).** On `@builtin::shaders.pbr` the clear coat is shaded with the base layer's normal-mapped normal, so a flake or weave normal map would make the coat bumpy too. That is why the flake paints, the carbon and the diner vinyl draw with this package's `coatedFinish`, which lights a level coat over its own base; materials you make on the engine's `pbr` over a flake normal map get the bumpy coat. - **Labels read from the front only (gh#21224).** The gallery's and the exhibits' 3D text is drawn on one side; walk behind a sign and its text is mirrored. Every label faces the spawn and the gallery ring's centre, where visitors stand. ### Design notes How the package behaves by design; none of these is a defect. - **Earlier names in library calls.** materialLibraryKit looks materials up by their current id and has no aliases, so `Materials.apply(object, "plasticGlossy")` and the picker know only the new names; a script written with an earlier name returns `false` until it says the new one (or wraps the name in `require("~syntheticsMaterials.SyntheticCatalog").currentName(...)`). Everything a world stores (material references on models, saved scenes, `SyntheticSurface` pieces) keeps working, as above. - **Colours are written as flow lists.** The engine's material loader reads a colour property only as a YAML flow list (`[r, g, b, a]`); written as a block list it is dropped and the shader default (white) drawn. `SyntheticCatalog.build()` always writes flow lists, so a hand edit should too. - **One repeat per primitive face.** The engine's cube, sphere and cylinder carry UVs 0..1 per face, so a textured material shows at real size on them only when the object is its `tileSize` across. The gallery's floor tiles and walls, the display-piece meshes, and any mesh with UVs laid in metres ÷ tileSize show real size. - **Fibre direction follows the UVs.** Carbon tows run along U and V, the tyre's abrasion along U, and the stylised ceramic's glaze band along V; turn the mesh's UVs to turn them. - **The two-layer and toon shaders.** `coatedFinish` hands its base layer to the engine, so the albedo, roughness and metallic passes read the paint's or carbon's base (the glints add only to the final picture). `toonFinish` lights itself, so those passes draw it magenta; its final and normal views are normal. - **The diner vinyl's channels fade with distance.** Its 120 mm padding is relief in the normal map; past about 11 mm of vinyl per pixel it fades to flat glossy red, so the long regular channels never moiré. ## Version history - **1.0.3 (2026-10-26):** text only: long dashes taken out of this README, the gallery scene's README and the world's description, and the release notes that 1.0.2 left unpublished are now in the world. No material, name, tag or sign changed. - **1.0.2 (2026-10-26):** ten clearer names (the earlier names keep working as material assets with the same asset ids, so saved scenes follow them; a script calling `Materials.apply` with an earlier name needs the new one): - `plasticGlossy` → `plasticGloss` - `rubberStudded` → `rubberStuddedFloor` - `foamClosedCellMat` → `foamEVA` - `vinylSheetFloor` → `vinylFloor` - `vinylDinerBooth` → `vinylUpholstery` - `ceramicSpeckled` → `ceramicGlazed` - `enamelCobalt` → `enamelSteel` - `lacquerPianoBlack` → `lacquerPiano` - `countertopGranite` → `countertopGranitePolished` - `laminatePlain` → `laminateSolid` Also: every material asset now carries its description and search tags (kind, style, finish, layers, colour, uses, texture weight, tile size) in its own `.metadata`, so ZeroMind search finds each one by what it is, not only the library; the diner vinyl (`vinylUpholstery`) is no longer tagged `metal flake`, which it never had; every exhibit sign and label is laid out under the gallery's own labels as seen from the spawn, none covering another or standing in front of an exhibit piece; the 17 earlier names (both rounds) resolve to their materials; this README's size figures and limits brought up to date. No material looks different. - **1.0.1 (2026-10-25):** the stylised family (`stylisedPlastic`, `stylisedCarPaint`, `stylisedCeramic`), making 31 materials in three style families; seven renames so every name starts with its kind: `paintSolidGloss` → `carPaintSolid`, `paintMetallic` → `carPaintMetallic`, `paintPearl` → `carPaintPearl`, `paintMatteWrap` → `carPaintMatte`, `foamOpenCell` → `foamPolyurethane`, `quartzCountertop` → `countertopQuartz`, `graniteCountertop` → `countertopGranite` (renamed again in 1.0.2); real flake sparkle on the metallic paint; a pearl whose colour moves with the light and the viewer; the kitchen's studded rubber floor mat and the `mat_<mm>` meshes; exhibits and signs laid out to read from the spawn; this README's collection guide, size and browser figures. - **1.0.0 (2026-10-25):** the first 28 materials, their reference pictures, `coatedFinish` and `toonFinish`, the display-piece meshes with `SyntheticSurface`, `SyntheticShowcase` and `SyntheticExhibits`, this world's gallery scene with the car panels and kitchen, and the test suite. Depends on materialLibraryKit 1.3.1.