treadmillNeon

# animBoard The reference-picture board of animatedMaterials' gallery: draws its picture exactly as it is, with no light or shadow on it, and reports the picture as the surface's colour (roughness 1, no metal) to the engine's colour, roughness, metal and normal views, so a board reads as its picture there too instead of magenta. After retroMaterials' retroBoard (MIT).

# animatedMaterials: Flux and Flicker **Animated and special surfaces for the Swatchbook material library (materialLibraryKit): flowing water and lava, conveyor belts and treadmills that travel at a stated speed in metres per second, wind-blown cloth, pulsing lights, dissolves, holograms, spreading frost, drying wet surfaces, a spreading burn and world-aligned rock, ground, masonry and metal; every live setting is changed per object with one call that every player sees.** Version 1.0.16. Depends on materialLibraryKit 1.3.4 (Swatchbook) and nothing else; installing this package brings the library along and no other collection. A fresh install also writes six of the engine's own shader parts into the new world under `deps/` (`pbr`, `unlit`, `pbr_shading`, `shadows`, `shadow_bias`, `engine_bindings`): the package's shaders include the engine's PBR shading module and some materials draw with its `pbr` and `unlit` shaders, and the engine pins every built-in asset content names at the version it was built against, so the materials look the same in every world whatever engine library that world is on. Once installed, all 28 materials are in the library's list, picker and swatch gallery on every player's machine, with no setup code. ## Install, then flowing lava and a dissolving crate Install **animatedMaterials** from ZeroMind (search "animatedMaterials" or "Flux and Flicker"). Then, in an empty world, from the console or any script: ```luau local Materials = require("~materialLibraryKit.Materials") local Live = require("~animatedMaterials.Live") -- flowing lava on a 4 m plane; synced, so every player has the plane and sees the lava local lava = entity.spawn("lavaPool", { synced = true, components = { Model = { model = "plane" } } }) lava.localScale = { 4, 1, 4 } lava.localPosition = { 0, 0.02, 0 } -- 2 cm up, clear of the ground it would flicker through assert(Materials.apply(lava, "lavaCrusted")) assert(Live.set(lava, "flowSpeed", 0.3)) -- metres per second, this plane only assert(Live.set(lava, "flowDirection", 90)) -- degrees on the surface: now it runs along +V -- the dissolve on a crate, driven from 0 (whole) to 1 (gone) over 3 s of game time local crate = entity.spawn("crate", { synced = true, components = { Model = { model = "cube" } } }) crate.localPosition = { 3, 0.5, 0 } assert(Materials.apply(crate, "dissolveEmber")) assert(Live.set(crate, "amount", 0)) assert(Live.set(crate, "amount", 1, { over = 3 })) ``` `Materials.apply` and `Live.set` return `ok, err`; the `assert` stops with the reason instead of leaving a grey or still object. Swap the look by changing one word: `"lavaToon"`, `"dissolveArcane"`, `"dissolveDigital"`. `Live.get(crate, "amount")` reads what an object shows now, `Live.settings("lavaCrusted")` lists what a material takes with its ranges, `Live.reset(crate)` puts its settings back to the material's defaults, and `Materials.clear(crate)` then `entity.despawn(crate.id)` takes it away again. ## One way to change any animated material: `Live` Every animated or special material has its live settings (listed below), and they are all changed the same way: | Call | Does | |---|---| | `Live.set(object, setting, value, opts?)` | Sets one setting of one object, clamped to its range, for every player. `opts.over = seconds` eases to it on the game's clock; `opts.localOnly = true` keeps it on this machine. Returns `ok, err` (an unknown setting is refused with the list the material takes). | | `Live.get(object, setting)` | The value the object shows now (its own, else the material's default); nil for an object that wears no material of this collection, and while the material library has not loaded yet. | | `Live.all(object)` | Every setting of the object, `{ [name] = value }`. | | `Live.reset(object, setting?)` | Back to the material's default, one setting or all, for every player. | | `Live.settings(materialId)` | `{ name, min, max, default, unit, description }` for each setting. | | `Live.onChanged(fn)` | `fn(object, setting, record)` whenever a setting changes here or arrives from another player. Returns an unsubscribe function. | - **Per object.** A setting is written as the object's own named values (`am.<setting>`), which the material binds in its `values:` block, so twenty crates wearing one material each show their own amount, and an object never given a setting shows the material's default. A setting on a parent reaches the meshes under it. - **Every player, late joiners too.** Settings go through materialLibraryKit's `Sync` (newest write wins), keyed the way `Materials.apply` keys objects: a shared (`synced`) entity, the scene's own entities and the gallery's swatches. A player who joins later is sent the room's state and their objects take it. - **No jumps.** Changing a speed or a direction never makes the surface jump: each setter also states where the surface stood at that moment on the shared clock, and a ramp (`over`) integrates the motion as the speed or direction changes. - **The game's own clock.** Every material moves by `AnimClock`: in play it advances with gameplay time, so `engine.timeScale` slows it and a pause freezes it; in edit mode it runs on real time, so the surfaces move while you author. A machine that joins asks the room for the clock and takes it before it ever speaks for the room; one machine per mode (edit or play), the lowest peer id among those already keeping the time, restates it every 5 s, and a small drift is eased in rather than jumped, so a stripe or a wave stands in the same place on every screen. Only the newest copy of `AnimClock` on a machine answers, so an edited module that reloaded on every machine never sends its old, stopped clock. A setting made on a machine in the instant before its clock takes the room's time (a script that runs as a player joins, or as the module reloads) is moved onto the room's time when it does, so its ramp still runs its full length. Ramps (`over`) run on the same clock: they slow, pause and finish together everywhere. ## Texture memory **6 MB for all 28 materials** (GPU memory, mipmaps included; UASTC, which the engine turns into BC7 on desktop and ASTC on phones). 22 of the 28 are procedural and bind no texture at all. The six that do (`wetPaving`, `wetAsphalt`, `worldRock`, `worldGround`, `worldMasonry`, `worldMetal`) bind 3 textures each at 512 px (albedo, normal, and a mask packing ambient occlusion, roughness, height and metal), 1 MB per material. **The 28 reference pictures** the gallery hangs add 9.3 MB (512 px each, 341 KB), **15.3 MB with them**. Every material passes the library's web check (`Checks.budget`): at most 3 sampled textures (the web limit is 9), no storage buffer (the limit is 1), nothing over 512 px. ## The materials Every material is tagged `animatedMaterials`, its category (`animated` for the ones that move by themselves, `special` for the amount-driven and world-aligned ones), what kind it is, `family-<family>`, `animated` with what moves or `not-animated`, `live-settings` with each setting and its range (`live-flowSpeed 0..3 m/s`) or `no-live-settings`, its tile size (`tile-<metres>m`, the metres one repeat covers, 1 unit = 1 m), how it is mapped (`mapping-uv`, `mapping-object` for the belts and effects, `mapping-world` with `world-aligned` and `triplanar`), its style (`style-realistic`, `style-toon`, `style-scifi`, `style-fantasy`), `emissive` and `self-lit` where it glows, how many textures it binds and their cost (`0-textures`, `textures-none`; `3-textures`, `textures-medium`), `seamless`, `metallic` or `non-metallic`, and search words. The library keeps its tags in lower case. Each kind comes in at least two looks, so a world swaps the look by changing one name. The live settings are changed with `Live.set` on one object (above). A setting marked m/s, Hz or lines/s is a speed: the surface travels at it and never jumps when it changes. Tile is the real size of one repeat; the belts and the effects map in metres along the object's own axes, the world-aligned set by world position. | Material | Name | Kind | Category | Style | Tile | Live settings (range, default) | Textures (memory) | |---|---|---|---|---|---|---|---| | `riverClear` | Clear mountain river | river | animated | realistic | 2 m | `flowSpeed` 0..3 m/s (0.8), `flowDirection` 0..360 deg (0) | none (0 KB) | | `riverMurky` | Murky lowland river | river | animated | realistic | 2 m | `flowSpeed` 0..3 m/s (0.6), `flowDirection` 0..360 deg (0) | none (0 KB) | | `waterToon` | Toon water | river | animated | toon | 2 m | `flowSpeed` 0..3 m/s (0.8), `flowDirection` 0..360 deg (0) | none (0 KB) | | `lavaCrusted` | Crusted flowing lava | lava | animated | realistic | 2 m | `flowSpeed` 0..0.5 m/s (0.12), `flowDirection` 0..360 deg (0), `glow` 0..4 x (1) | none (0 KB) | | `lavaToon` | Toon lava | lava | animated | toon | 2 m | `flowSpeed` 0..0.5 m/s (0.12), `flowDirection` 0..360 deg (0), `glow` 0..4 x (1) | none (0 KB) | | `beltRubber` | Rubber conveyor belt | conveyor belt | animated | realistic | 1 m | `beltSpeed` -5..5 m/s (0.5) | none (0 KB) | | `beltSlats` | Steel slat conveyor | conveyor belt | animated | realistic | 0.15 m | `beltSpeed` -5..5 m/s (0.5) | none (0 KB) | | `treadmill` | Treadmill belt | treadmill | animated | realistic | 1.4 m | `beltSpeed` -5..5 m/s (2.5) | none (0 KB) | | `treadmillNeon` | Sci-fi glow treadmill | treadmill | animated | scifi | 0.5 m | `beltSpeed` -5..5 m/s (1.5) | none (0 KB) | | `flagCotton` | Printed cotton flag | flag | animated | realistic | 1.5 m | `windStrength` 0..25 m/s (8), `windDirection` 0..360 deg (0) | none (0 KB) | | `bannerCanvas` | Heavy canvas banner | banner | animated | realistic | 2 m | `windStrength` 0..25 m/s (8), `windDirection` 0..360 deg (0) | none (0 KB) | | `pulseBreath` | Breathing light panel | light panel | animated | scifi | 1 m | `pulseRate` 0..4 Hz (0.25), `glow` 0..30 x (6) | none (0 KB) | | `pulseAlarm` | Alarm strobe lens | alarm light | animated | realistic | 0.6 m | `pulseRate` 0..4 Hz (2), `glow` 0..30 x (9) | none (0 KB) | | `dissolveEmber` | Ember dissolve (wooden crate) | dissolve | special | realistic | 1 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (7), `edgeWidth` 0.005..0.2 m (0.03) | none (0 KB) | | `dissolveArcane` | Arcane dissolve (carved stone) | dissolve | special | fantasy | 1 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (7), `edgeWidth` 0.005..0.2 m (0.06) | none (0 KB) | | `dissolveDigital` | Digital dissolve (sci-fi panel) | dissolve | special | scifi | 0.5 m | `amount` 0..1 (0.45), `edgeGlow` 0..20 x (10), `edgeWidth` 0.005..0.2 m (0.07) | none (0 KB) | | `holoBlue` | Blue hologram | hologram | animated | scifi | 1 m | `flicker` 0..1 (0.25), `glitch` 0..1 (0.15), `glow` 0..8 x (1.3), `scanSpeed` -20..20 lines/s (12) | none (0 KB) | | `holoGlitchRed` | Glitching red hologram | hologram | animated | scifi | 1 m | `flicker` 0..1 (0.75), `glitch` 0..1 (0.8), `glow` 0..8 x (1), `scanSpeed` -20..20 lines/s (9) | none (0 KB) | | `frostWindow` | Frosting window glass | frost | special | realistic | 1 m | `amount` 0..1 (0.5) | none (0 KB) | | `frostToon` | Toon frost creep | frost | special | toon | 1 m | `amount` 0..1 (0.5) | none (0 KB) | | `wetPaving` | Wet flagstone paving | wet paving | special | realistic | 2 m | `wetness` 0..1 (0.7) | 3 (1024 KB) | | `wetAsphalt` | Wet road asphalt | wet asphalt | special | realistic | 3 m | `wetness` 0..1 (0.7) | 3 (1024 KB) | | `burnWood` | Burning wooden planks | burn | special | realistic | 1 m | `amount` 0..1 (0.5), `emberGlow` 0..10 x (4) | none (0 KB) | | `burnToon` | Toon burning planks | burn | special | toon | 1 m | `amount` 0..1 (0.5), `emberGlow` 0..10 x (3) | none (0 KB) | | `worldRock` | World-aligned cliff rock | rock | special | realistic | 4 m | none (world-aligned, still) | 3 (1024 KB) | | `worldGround` | World-aligned forest floor | ground | special | realistic | 2 m | none (world-aligned, still) | 3 (1024 KB) | | `worldMasonry` | World-aligned brick | brick | special | realistic | 0.9 m | none (world-aligned, still) | 3 (1024 KB) | | `worldMetal` | World-aligned chipped painted metal | painted metal | special | realistic | 1 m | none (world-aligned, still) | 3 (1024 KB) | - `riverClear`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, rippling, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, water, stream, creek, brook, clear, mountain, pebbles, shallow, transparent, caustics, nature - `riverMurky`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, rippling, drifting scum, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, water, murky, muddy, silty, swamp, lowland, canal, brown, green, scum, foam, nature - `waterToon`: animatedmaterials, animated, river, family-water, flowing, travels in m/s, sparkling, live-settings, live-flowspeed 0..3 m/s, live-flowdirection 0..360 deg, tile-2m, mapping-uv, style-toon, toon, 0-textures, textures-none, seamless, non-metallic, water, cartoon, cel shaded, stylised, sea, teal, blue, foam, sparkle - `lavaCrusted`: animatedmaterials, animated, lava, family-lava, flowing, travels in m/s, glowing, crust tearing, live-settings, live-flowspeed 0..0.5 m/s, live-flowdirection 0..360 deg, live-glow 0..4 x, tile-2m, mapping-uv, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, magma, molten, volcano, volcanic, fire, crust, basalt, hot - `lavaToon`: animatedmaterials, animated, lava, family-lava, flowing, travels in m/s, glowing, live-settings, live-flowspeed 0..0.5 m/s, live-flowdirection 0..360 deg, live-glow 0..4 x, tile-2m, mapping-uv, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, cartoon, cel shaded, stylised, magma, volcano, fire, orange - `beltRubber`: animatedmaterials, animated, conveyor belt, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-1m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, conveyor, belt, rubber, factory, warehouse, industrial, black, moving surface - `beltSlats`: animatedmaterials, animated, conveyor belt, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-0.15m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, metallic, conveyor, slats, steel, metal, chain conveyor, factory, airport, baggage, moving surface - `treadmill`: animatedmaterials, animated, treadmill, family-belt, scrolling, travels in m/s, live-settings, live-beltspeed -5..5 m/s, tile-1.4m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, running machine, gym, fitness, belt, black, moving surface - `treadmillNeon`: animatedmaterials, animated, treadmill, family-belt, scrolling, travels in m/s, glowing, live-settings, live-beltspeed -5..5 m/s, tile-0.5m, mapping-object, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, moving walkway, travelator, sci-fi, neon, cyan, glow, spaceship, conveyor, moving surface - `flagCotton`: animatedmaterials, animated, flag, family-cloth, fluttering, waving in the wind, vertex animation, live-settings, live-windstrength 0..25 m/s, live-winddirection 0..360 deg, tile-1.5m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, cotton, fabric, cloth, wind, waving, banner, printed, pole, teal, orange, star - `bannerCanvas`: animatedmaterials, animated, banner, family-cloth, billowing, swaying in the wind, vertex animation, live-settings, live-windstrength 0..25 m/s, live-winddirection 0..360 deg, tile-2m, mapping-uv, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, canvas, sail, sailcloth, heavy fabric, cloth, wind, medieval, tent, stitched, hem - `pulseBreath`: animatedmaterials, animated, light panel, family-pulse, pulsing, breathing, glowing, live-settings, live-pulserate 0..4 hz, live-glow 0..30 x, tile-1m, mapping-uv, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, pulse, sleep light, glow, standby, led, frosted, acrylic, sci-fi, wall light, indicator - `pulseAlarm`: animatedmaterials, animated, alarm light, family-pulse, flashing, strobing, glowing, live-settings, live-pulserate 0..4 hz, live-glow 0..30 x, tile-0.6m, mapping-uv, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, alarm, strobe, warning light, beacon, siren, red, flash, emergency, lens, industrial, lockdown - `dissolveEmber`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, flickering embers, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-1m, mapping-object, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, burn away, disintegrate, ember, fire, crate, wood, destroy, vanish, char - `dissolveArcane`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, pulsing runes, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-1m, mapping-object, style-fantasy, fantasy, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, arcane, magic, spell, runes, stone, teleport, vanish, disintegrate, violet, cyan - `dissolveDigital`: animatedmaterials, special, dissolve, family-dissolve, animated, driven by amount, dissolves away, flickering voxels, live-settings, live-amount 0..1, live-edgeglow 0..20 x, live-edgewidth 0.005..0.2 m, tile-0.5m, mapping-object, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, metallic, digital, de-rez, voxel, pixel, hologram, teleport, sci-fi, cyan, glitch, disintegrate - `holoBlue`: animatedmaterials, animated, hologram, family-hologram, scanlines climbing, flickering, glitching, live-settings, live-flicker 0..1, live-glitch 0..1, live-glow 0..8 x, live-scanspeed -20..20 lines/s, tile-1m, mapping-world, world-aligned, triplanar, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, holo, projection, sci-fi, blue, cyan, scanlines, transparent, additive, glow, ghost, futuristic - `holoGlitchRed`: animatedmaterials, animated, hologram, family-hologram, glitching, flickering hard, scanlines climbing, colour split, live-settings, live-flicker 0..1, live-glitch 0..1, live-glow 0..8 x, live-scanspeed -20..20 lines/s, tile-1m, mapping-world, world-aligned, triplanar, style-scifi, scifi, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, glitch, corrupted, red, error, warning, sci-fi, scanlines, chromatic aberration, transparent, additive, cyberpunk, hacked - `frostWindow`: animatedmaterials, special, frost, family-frost, not-animated, live-settings, live-amount 0..1, tile-1m, mapping-object, style-realistic, realistic, 0-textures, textures-none, seamless, non-metallic, ice, window, glass, winter, frozen, cold, crystals, freeze, transparent - `frostToon`: animatedmaterials, special, frost, family-frost, animated, driven by amount, frost sweeps diagonally across, twinkling sparkles, live-settings, live-amount 0..1, tile-1m, mapping-object, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, ice, freeze, cartoon, stylised, winter, cold, snow, sparkle, frozen - `wetPaving`: animatedmaterials, special, wet paving, family-wet, not-animated, live-settings, live-wetness 0..1, tile-2m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, wet, rain, puddle, puddles, flagstone, paving, stone, street, courtyard, drying, damp, glossy - `wetAsphalt`: animatedmaterials, special, wet asphalt, family-wet, not-animated, live-settings, live-wetness 0..1, tile-3m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, wet, rain, puddle, puddles, asphalt, road, tarmac, street, drying, damp, glossy, reflective - `burnWood`: animatedmaterials, special, burn, family-burn, animated, driven by amount, spreading burn, flickering embers, live-settings, live-amount 0..1, live-emberglow 0..10 x, tile-1m, mapping-object, style-realistic, realistic, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, fire, scorch, char, charred, wood, planks, ember, smoulder, destruction - `burnToon`: animatedmaterials, special, burn, family-burn, animated, driven by amount, spreading burn, live-settings, live-amount 0..1, live-emberglow 0..10 x, tile-1m, mapping-object, style-toon, toon, emissive, self-lit, 0-textures, textures-none, seamless, non-metallic, fire, scorch, char, cartoon, cel, wood, planks, ember - `worldRock`: animatedmaterials, special, rock, family-world, not-animated, no-live-settings, tile-4m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, cliff, stone, boulder, mountain, blockout - `worldGround`: animatedmaterials, special, ground, family-world, not-animated, no-live-settings, tile-2m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, forest floor, dirt, pine needles, soil, terrain, blockout - `worldMasonry`: animatedmaterials, special, brick, family-world, not-animated, no-live-settings, tile-0.9m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, non-metallic, world aligned, world space, no uv, masonry, wall, running bond, red brick, building, blockout - `worldMetal`: animatedmaterials, special, painted metal, family-world, not-animated, no-live-settings, tile-1m, mapping-world, world-aligned, triplanar, style-realistic, realistic, 3-textures, textures-medium, seamless, metallic, world aligned, world space, no uv, metal, chipped paint, green, steel, industrial, machine, blockout ## Pairing a conveyor with a moving surface The belt materials (`beltRubber`, `beltSlats`, `treadmill`, `treadmillNeon`) map by metres along the object's own axes and travel along the object's own **+x**, the frame a collider's `surfaceVelocity` is stated in. Add the package's `Conveyor` component to the belt and it gives the collider `surfaceVelocity = (beltSpeed, 0, 0)` every time the belt's live speed changes, so a crate resting on it moves exactly with the stripes: ```luau local Materials = require("~materialLibraryKit.Materials") local Live = require("~animatedMaterials.Live") local belt = entity.spawn("belt", { synced = true, components = { Model = { model = "cube" } } }) belt.localPosition = { 0, 0.6, 0 } belt.localScale = { 5, 0.12, 0.9 } -- runs along its own x; turn it to aim it belt.component.add("BoxCollider", { friction = 1 }) belt.component.add("Conveyor", {}) assert(Materials.apply(belt, "beltRubber")) assert(Live.set(belt, "beltSpeed", 1.2)) -- m/s: the stripes and the crate both move at 1.2 local crate = entity.spawn("crate", { synced = true, components = { Model = { model = "cube" } } }) crate.localPosition = { -2, 1.2, 0 } crate.localScale = { 0.5, 0.5, 0.5 } crate.component.add("BoxCollider", { friction = 1 }) crate.component.add("Physics", { kind = "dynamic", mass = 20 }) ``` Physics runs in play, so the crate rides in play; the stripes move in edit mode too. A negative speed runs the belt backwards. Without the component, state the same yourself: `collider.surfaceVelocity = { Live.get(belt, "beltSpeed"), 0, 0 }`. An engine whose colliders have no `surfaceVelocity` field refuses that write (the web build has shipped without it: "Component<BoxCollider> has no declared field 'surfaceVelocity'"). The `Conveyor` then says so once in the log and carries what rests on the belt itself: the belt's collider is made frictionless while it carries (its own friction comes back when the component is removed), and at every physics step (once a frame on an engine without a physics step hook) each dynamic body whose middle stands over the belt is handed the belt's speed along it, plus a pull that closes any distance it has fallen behind, on the shared game clock. It finds the bodies by an overlap query and by the belt's contacts, and reads the belt's box from its oriented bounds, else its collider's size, else its scale. Measured on the desktop with that mode forced (`_forceCarry`), crates rode 0.499, 0.499, 2.496 and 1.497 m/s on belts at 0.5, 0.5, 2.5 and 1.5 m/s, and within about 1.3% at 1.2, -0.8, 3.0 and 2.0 m/s; the demo yard's crate rode its 0.5 m/s belt at 0.499 (step hook) and 0.504 (once a frame); with the collider's own `surfaceVelocity`, within 0.7%. `conveyor:_mode()` says which way a belt moves its load (`"surface"` or `"carry"`), and `conveyor:_carryStats()` what carrying found (the hook, the bodies near the belt and riding it, the last error a physics call gave). ## The gallery and the demo yard This world opens on the library's swatch gallery, showing this collection alone on a stand in front of the spawn: all 28 bays on four curved rows, each row higher than the one before so its floor shows over the plaques in front, the amount-driven and world-aligned ones in the two front rows under the SPECIAL banner and the moving ones in the two back rows under ANIMATED. Players arrive on a 4 m deck facing the stand, and the camera tilts 6.5 degrees up from there, so one look shows every bay with its name and facts (checked from the play camera at 16:9 with a 60 degree vertical view). Each bay shows its material on a sphere, a cube, a shader ball and a cylinder, a floor tile and a wall at real size (the belts and world-aligned materials map in metres themselves), its reference picture in a dark frame, and a label on one shared grid that reads from the deck: the name, then three short rows (what it is; style and tile size; whether it moves by itself, by an amount or not at all, and how many textures it binds), each set about 0.38 m tall. The live settings and texture memory are in the picker and this README. The cloth bays also fly a small flag on a pole, and the lava bays stand a soft orange light. Everything moves, in edit mode too. The toolbar switches the library's six lighting looks for everyone (Daylight, Overcast, Golden hour, Moonlight, Warm interior, Studio), and **Materials** opens the picker. Behind the deck, one turn away and down a ramp, stands the demo yard, built on every machine by the `AnimYard` component (local pieces, nothing saved into the scene file): on the left a lava channel between world-aligned rock banks, a rubber conveyor carrying a metal crate (the `Conveyor` component moves it with the stripes, in play), a cotton flag on a 4 m pole and a blue hologram sign over a pedestal; on the right a crate dissolving out and back in, a window frosting over and clearing, and a wet paving patch drying and soaked again. The cycles run on the shared clock through `Live`, so every player sees the same moment. Players come from the scene's player prototype, each on their own spot along the deck. The library's ring is still there as `layout = "ring"` (the default), for a scene that wants it. In a scene of your own, in its `content()`: ```luau local AnimGallery = require("~animatedMaterials.AnimGallery") entity.spawn("Gallery").component.add("AnimShowcase", { driveGallery = true, lighting = "daylight", layout = "stand" }) for _, s in AnimGallery.standYardSpots() do -- the yard's two halves, behind the deck, facing it local yard = entity.spawn("AnimYard_" .. s.part) yard.localPosition = s.position yard.localRotation = { 0, math.sin(math.rad(s.yaw) / 2), 0, math.cos(math.rad(s.yaw) / 2) } yard.component.add("AnimYard", { part = s.part }) end -- stand each arriving player on the deck: AnimGallery.standSpot(i) gives the i-th spot and its yaw ``` ## How they were made - **Reference pictures first.** Every material has `references/<id>`, a picture generated from the prompt in its entry before its shader was written. Each material was then compared beside its picture in its gallery bay under the Daylight look and the dark Moonlight look, by reviewers who wrote down what each bay showed, and changed where they differed (the review notes are in this world's `design/review`). - **One definition.** `AnimEntries` gathers the families under `families/`; `AnimCatalog.build()` writes every `mat.yaml` (shader, properties, textures and the `values:` block binding each live property to `am.<setting>`) and the collection with its tags and measured texture memory; `AnimCatalog.writeBoards()` writes the reference boards. - **Searched and reused.** The library core (materialLibraryKit 1.3.1) and its gallery, picker, lighting looks and checks; the startup asset type and catalog pattern of retroMaterials and toonMaterials (MIT); the gallery dressing forked from retroMaterials' RetroShowcase (MIT); Rune and Ember's `fantasyLava` shader forked as `animLava` (MIT); Hull and Hologram's `scifiHolo` forked as `animHolo` (MIT); the world-aligned and wet surfaces' textures forked from stoneMaterials, groundMaterials, masonryMaterials and metalsMaterials (MIT), repacked at 512 px. Looking Glass's water, the engine's `water_material`, `triplanar`, `animated_color` and `foliage` were read for ideas; none of them is a dependency, and no other package comes along with an install. - **Shaders.** `animWater`, `animLava`, `animBelt`, `animCloth`, `animPulse`, `animHolo`, `animDissolve`, `animBurn`, `animFrost`, `animWet`, `animWorld`, plus `animBoard` for the reference boards and the shared WGSL module `animCommon` (periodic noise, Voronoi, object-metre mapping). Every procedural field is periodic over one repeat, so it tiles with no seam. ## Tests ```luau asset.resolve("animatedMaterials.tests.animatedMaterials", "testSuite"):run() ``` Eight short tests, each wait a frame or two (the ramp test waits on the shared clock for half a second, at most 5 s on a slow machine); the whole run takes under a minute on a quiet desktop engine, longer while other work loads it: every material in the library and fully tagged; a live setting changes one object only (clamped, an unknown setting refused, reset); a speed or direction change never makes the surface jump; a ramp runs on the shared clock; a setting from another player (as a late joiner's snapshot arrives) lands on the object; the shared clock moves in edit mode and drives every material; the `Conveyor` gives its collider the belt's speed; every material inside the web limits. Each runs inside the library's `Sync.isolate()`, so nothing reaches other players; probes stand far from the gallery and are removed. The library's slower render checks run as tools: `zero materialChecks run <id>`. ## Multiplayer Applied materials and the lighting look go through the library's `Sync`; live settings through the same `Sync` on their own channel; the clock through two small messages (a joiner asks; the machine keeping the room's time in that mode answers and restates it every 5 s). Every player sees the same settings on the same objects, a player who joins late included. The gallery's swatches and the yard's pieces are local and built the same on every machine under the same names, so a setting made on one of them reaches every player too. A ramp costs one message, not one per frame. `Live` also answers the library's room report: `require("~materialLibraryKit.Sync").askRoom()` returns, for every player, the section `animatedMaterials` with what that player's objects actually show (each setting it holds, whether the object is built there, and the values read back off it), so another player's screen can be checked from yours. Checked with two players: a setting made before the second player joined, a lava pool's speed and direction, and a dissolve ramp all read the same on both, the ramp at the same point of the shared clock. ## Gallery frame rate - **Desktop engine:** about 72 fps in play (frames drawn over 10 s), in the desktop editor on this release with the whole 28-bay stand (460 local pieces) and the demo yard (40) standing and moving, measured by the author. - **Web (browser):** about 29 fps, the median over 60 s in play at the arrival point by the stand, in Chrome on the owner's desktop, with all 28 bays and both halves of the yard up, measured by the world's owner on 1.0.9. The cost is the engine's per-frame upkeep of the gallery's many objects in the browser ([#20750](https://github.com/OrigoZero/zero/issues/20750)). Materials on ordinary scene objects in your own world do not carry the gallery's cost. ## How it works - **Cloth mesh.** Free flutter needs a finely divided mesh whose vertex colour marks the free part; the package ships one (`animatedMaterials.meshes.flagCloth`, 1.5 x 1 m). On a cube or a sphere the shape holds and the wind moves only the shading. - **Long-running speeds.** Flow and belt offsets are kept in metres in 32-bit floats; after many hours at full speed a step can reach a few millimetres a frame. A `Live.set` of the same speed restates the offset close to zero. - **World-aligned and amount-driven tiling.** The world-aligned set maps by world position (an object moved slides under its pattern); the dissolve, frost and burn patterns are sized by the object, so they scale with it. ## Known limits Engine issues are listed by their number at github.com/OrigoZero/zero. - **Gallery frame rate on the web ([#20750](https://github.com/OrigoZero/zero/issues/20750)).** About 29 fps in the browser (the owner's measurement on 1.0.9), against about 72 on the desktop. The gallery is about 460 local pieces (plus the yard's 40) with 28 procedural shaders, and the engine's per-frame upkeep of that many objects is what costs the frame there. In your own world, with the materials on ordinary scene objects, that does not apply. - **Checked in the browser by the owner, not the author ([#20946](https://github.com/OrigoZero/zero/issues/20946)).** The author cannot start a browser engine; this release was prepared and checked on the desktop engine, and the web frame rate and the web boot were checked by the world's owner on 1.0.9. - **The library's material checks tools in the browser ([#7789](https://github.com/OrigoZero/zero/issues/7789)).** In the browser, the material library's `materialChecks` tools log "module '.shared' not found" as they load: each tool loads its helper with a relative `require(".shared")` that the web build does not resolve. Those tools are part of materialLibraryKit (Swatchbook), not of this package, so this package cannot fix them; the materials, the gallery, `Live` and the library's `Checks` module are not affected, and the tools work on the desktop engine. - **Reloading the scene can save runtime things ([#21023](https://github.com/OrigoZero/zero/issues/21023)).** The gallery's swatches and the yard's pieces are temporary and rebuilt each time; check the scene file before committing after a reload. - **A push can report a timeout and still land ([#21025](https://github.com/OrigoZero/zero/issues/21025)).** Check the world's commits before pushing again. - **Flat labels read from the front only ([#21224](https://github.com/OrigoZero/zero/issues/21224)).** The gallery's plaques face the deck, and the yard's signs face the deck from below it, so each reads correctly from where visitors stand; walked round to the back, a label reads mirrored. - **A copy of a shared object does not report itself as shared ([#21477](https://github.com/OrigoZero/zero/issues/21477)).** On a machine that holds another machine's copy of a `synced` object, the engine answers `e.synced()` false, so the material library's `Materials.keyOf` names that object by its name path there and by its id on the machine that spawned it. What you see: every screen shows the right value either way. Before 1.0.9 a setting made from one machine could read back with `Live.get` as the material's default on another; `Live` now reads both keys and takes the newest, so it reads back the same on every machine. Give shared objects unique names, since the name path is what a copy is known by. - **A 3D text label keeps its old text ([#7781](https://github.com/OrigoZero/zero/issues/7781)).** `AnimShowcase` never rewrites a label: when an entry changes (a new tile size, a new setting) it removes the bay's labels and spawns them again with the new text. Do the same with labels of your own. - **Plaques blank for a moment after a test run ([#15118](https://github.com/OrigoZero/zero/issues/15118)).** The renderer reset at the end of a run destroys every 3D text label's picture; the gallery remakes its own within a few seconds. - **A test run in a live world can remove objects the world's own scripts made ([#21495](https://github.com/OrigoZero/zero/issues/21495)).** The test suite's own probes are temporary, stand far away and are removed, but the engine's test runner can take other objects that scripts spawned. The gallery and the yard rebuild themselves: in this world, with the yard's pieces removed it stood again within 6 s, and with half the gallery's pieces removed all 28 bays stood again within 15 s; after a whole suite run here both were still standing. Objects your own scripts spawned may not come back, so run the suite in a world nobody is playing. - **A test run can release what the yard draws with ([#21873](https://github.com/OrigoZero/zero/issues/21873)).** The renderer reset at the end of a run can release the meshes and materials the demo yard made for itself (its poles, frames and plain boxes) while its objects stay, so for a moment the yard draws only the pieces that wear package materials. The yard checks every second whether what it draws with is still there and, when something is gone, builds itself again; the gallery stand rebuilds its own the same way. - **Labels in the debug views ([#21451](https://github.com/OrigoZero/zero/issues/21451)).** The engine's own 3D text draws magenta in the albedo, roughness and metallic capture views; keep the plaques out of frame when judging a material in those views. - **Wind-blown cloth in a render feature pass ([#21428](https://github.com/OrigoZero/zero/issues/21428)).** The cloth moves its vertices in the material's clip-space hook, by each flag's own wind values. A render feature that redraws the scene's meshes in its own geometry pass (an outline, a custom depth or mask pass) moves the vertices the same way whatever value the material holds, so in that pass a flag does not follow its own wind strength and direction. - **A gallery board's picture can drop out ([#21868](https://github.com/OrigoZero/zero/issues/21868)).** Each bay's reference board shows its picture through the board material, and the engine can release that picture while the board still wears it; the board then draws plain white, and which board it hits varies (seen on the clear river one while the dissolve, burn and masonry boards showed fine). It stays white until the gallery is built again (reload the world, or switch the gallery's view). The materials themselves, their previews in the picker and list, and objects in your own world are not affected. - **Shader previews ([#21617](https://github.com/OrigoZero/zero/issues/21617), [#21618](https://github.com/OrigoZero/zero/issues/21618)).** The engine's preview pictures fail for shaders that include the package's own shader module (`animCommon`), so some shaders show no preview; the shaders compile and draw. The materials' own previews (the pictures the library's picker and list show) are rendered files and always show. The gallery's reference boards are another matter: see #21868 above. ## Version history - **1.0.16 (2026-10-30):** release of this round's work: late joiners and play see the newest setting on every object (1.0.12), the demo yard rebuilds itself after a test run (1.0.13), materialLibraryKit 1.3.4 with no long dashes and the current engine library (1.0.14), a README that says what a fresh install writes (1.0.15). The package description says what it is and how to install and use it. Materials, settings, tags and tests are unchanged. - **1.0.15 (2026-10-30):** README only: it says plainly what a fresh install writes (the package, materialLibraryKit and six pinned engine shader parts under `deps/`) and why. Checked by a fresh install of 1.0.14 into a new empty world on the current engine library, which also carried no long dashes. Materials, settings, tags and tests are unchanged. - **1.0.14 (2026-10-30):** depends on materialLibraryKit 1.3.4, the kit's release with no long dashes in any text file, so a fresh install carries none. The world is on the current built-in library. Materials, settings, tags and tests are unchanged. - **1.0.13 (2026-10-30):** the demo yard builds itself again when a test run's renderer reset releases the meshes and materials it made ([#21873](https://github.com/OrigoZero/zero/issues/21873)): it used to rebuild only when its objects went missing, so after a run it could stand there drawing nothing but the flag. Materials, settings, tags and tests are unchanged. - **1.0.12 (2026-10-30):** a player who joins late, and a machine entering play, sees the newest setting on every object. One object can hold its settings under its id and under its name path (set from the machine that spawned it and from one holding its copy), and a late joiner's snapshot or the replay on entering play wrote whichever record came last, so belts, flags, holograms and pulses could fall back to old values; `Live` now writes the newest of them, whichever key arrives. The collection's version agrees with the package's. Known limits drop the closed #21492, and the shader preview entry points at #21868 above it. Materials, settings, tags and tests are unchanged. - **1.0.11 (2026-10-30):** README only. Known limits name [#21868](https://github.com/OrigoZero/zero/issues/21868), a gallery board's reference picture dropping out to plain white, and the shader preview entry says what the materials' own previews and the gallery boards really show. The world's cover shows the stand and the demo yard together. Materials, settings, tags and tests are unchanged. - **1.0.10 (2026-10-30):** the browser frame rate is the owner's new measurement, about 29 fps (median over 60 s in Chrome at the stand), in place of the 1.0.6 figure. The `Conveyor` asks its collider whether it declares `surfaceVelocity` before writing it, so a browser engine without the field no longer logs "BoxCollider has no declared field surfaceVelocity"; it carries the load itself there as before. Materials, settings, tags and tests are unchanged. - **1.0.9 (2026-10-30):** `Live.get` and `Live.all` read a setting back the same on every machine: a setting made from a machine holding a copy of a shared object was stored under the object's name path rather than its id ([#21477](https://github.com/OrigoZero/zero/issues/21477)), so other machines showed it but read the default; `Live` now reads both and takes the newest. Checked with three windows, a late joiner included, both ways. The README splits how-it-works notes from the known limits, cites #21617 and #21618 for shader previews, and says that an install also pins six engine shader parts. Stays on materialLibraryKit 1.3.1: the library's 1.3.3 is in its world's history but not yet its published version, so a fresh install could not get it. Materials, settings, tags and tests are unchanged. - **1.0.8 (2026-10-28):** the first example's lava plane stands 2 cm above the ground, so in an empty world it shows whole instead of flickering through the ground (checked at a 2 cm lift on a ground at height 0: a clean crust with glowing cracks). The demo yard's signs are turned to read from the deck, where they read mirrored before. The known limits cite [#7789](https://github.com/OrigoZero/zero/issues/7789) for the library's material checks tools in the browser and add a second engine reading a setting back as the default ([#21477](https://github.com/OrigoZero/zero/issues/21477)). The world's listing describes the stand and the yard behind the deck. Materials, settings, tags, tests and texture memory are unchanged. - **1.0.7 (2026-10-28):** the whole gallery in one look from the spawn. The world's gallery stood its 28 bays on the library's ring round the spawn, so a visitor saw about 7 of them and had to turn round for the rest; `AnimShowcase` now takes `layout = "stand"` (the library's ring stays the default), which moves every bay onto four curved, stepped rows in front of a 4 m deck the visitors arrive on (`AnimGallery.STAND`, `stand`, `standSpot`, `standYardSpots`), with the demo yard behind the deck, one turn away. The plaques carry the name and three short rows instead of four long ones, so every row is set about 0.38 m tall instead of about 0.27 m; the two longest names wrap to three smaller lines. The README gives the owner's browser frame rate on 1.0.6 and says this release is not yet measured in a browser, points the long waits and the tests at [#21492](https://github.com/OrigoZero/zero/issues/21492) (it cited a different issue), and says plainly that the library's material checks tools log "module '.shared' not found" in the browser and that this package cannot fix them. 1.0.6 was already published, so this round ships as 1.0.7. Materials, settings, tags, tests and texture memory are unchanged. - **1.0.6 (2026-10-28):** a ramp started as a machine joins keeps its length. A setting made in the instant before a machine's clock took the room's time was stamped on the machine's own clock, so when the clock then jumped to the room's (hundreds of seconds on), a ramp such as the README's 3 s dissolve read finished at once. `AnimClock` now tells `Live` how far it moved when it takes the room's time (`AnimClock.onSettle`), and `Live` moves the settings it stamped before then by that much and sends them out again. Checked with a simulated room 500 s ahead: the dissolve read 0.495 at 1.5 s and 1.0 at 3.5 s. Materials, settings, tags and texture memory are unchanged. - **1.0.5 (2026-10-28):** the yard's crate rides in the browser, and a late joiner's clock holds steady. The `Conveyor`'s carrying fallback took a body's pivot for its middle, and the demo yard's crate has its pivot at its base, below the belt's top face, so it was never counted as riding and stood still while the stripes moved; it now tests each body's middle (its bounds' centre), finds bodies by the belt's contacts as well as an overlap query, reads the belt's box from its collider or scale where oriented bounds are missing, carries once a frame where there is no physics step hook, starts a body put back at the start of the belt afresh, and reports what it found (`_carryStats`). `AnimClock`: an edited module reloads on every machine, and the message handlers the older copies had registered still answered a joiner with their own stopped clocks, while more than one machine could restate its clock, so a late joiner's clock jumped between readings hundreds of seconds apart (and the yard's cycles with it). Now only the newest copy on a machine speaks or listens, a joiner takes the room's clock before it ever speaks for the room, one machine per mode keeps the time, and a small drift is eased in. Materials, settings, tags and texture memory are unchanged. - **1.0.4 (2026-10-28):** the belts carry their load in the browser and the web boot is quiet. The web build's colliders have no `surfaceVelocity` field, so the `Conveyor`'s write was refused and it logged "has no declared field 'surfaceVelocity'" hundreds of times a minute while the crates stood still; it now says so once and carries what rests on the belt itself, keeping pace with the stripes (measured within 1.3% of the belt's speed with that mode forced on the desktop). `AnimClock` asked for the material library with a `require` before the library had registered, which logged "names no package" at boot even inside `pcall`; every place that waits for the library now asks `asset.resolve` first and requires it only once it is there. The README gives the owner's web frame rate measured on 1.0.3 (about 27 fps). Materials, settings, tags and texture memory are unchanged; the conveyor test accepts either way of moving the load. - **1.0.3 (2026-10-28):** works when the web build starts this package before the material library. In the browser the gallery dressing (`AnimShowcase`) and the yard (`AnimYard`) failed at boot with "no package named materialLibraryKit exists", and `Live` started without its shared channel and never tried again, so the `Conveyor` repeated "attempt to index nil with 'entries'" every frame. All three now bind the library when it is there and start the moment it is; until then `Live.get` answers nil and `Live.set` and `Live.reset` return false with the reason. The scene places each arriving player once the library is there. `Live` answers the library's room report (`Sync.askRoom`, section `animatedMaterials`), which checked two players side by side. The README gives the owner's web frame rate. Materials, settings, tags, tests and texture memory are unchanged. - **1.0.2 (2026-10-28):** fixes after a side-by-side review of every bay beside its reference picture in Daylight and Moonlight. `lavaToon` takes its crust highlight from a real dome lit by the scene instead of a lighter colour painted into the crust, so the lava glows only by its own emission; `dissolveArcane` glows violet-blue to cyan like its picture; `frostWindow` grows thinner, finer fern crystals over a crisp, granular frost edge on darker glass instead of soft blotches. `Live`: a ramp on `flowDirection` now curves the flow smoothly (the travelled path is the integral of the velocity), where before the surface swung sideways while the direction turned. The README's known limits cite the issue that describes each one. Settings, tags, tests and texture memory are unchanged. - **1.0.1 (2026-10-28):** first public release. The gallery holds its ring: when the library rebuilt its own "all" view while the materials were still registering (as a world loads, or after switching worlds), `AnimShowcase` took that for a player's choice and left the library's 3-page layout standing; it now steps back only when someone picks another kind of exhibit, and takes the "all" view back with this collection's 28-bay ring. Materials, settings, tags, tests and texture memory are unchanged from 1.0.0. - **1.0.0 (2026-10-28):** the release candidate, proven by a fresh install in a scratch world and never made public: 28 animated and special materials in 11 families, their reference pictures, the shaders (`animWater`, `animLava`, `animBelt`, `animCloth`, `animPulse`, `animHolo`, `animDissolve`, `animBurn`, `animFrost`, `animWet`, `animWorld`, `animBoard` and the shared `animCommon` module), `Live`, `AnimClock`, the `Conveyor` component, the flag mesh, the gallery dressing (`AnimShowcase`, `AnimGallery`), the demo yard (`AnimYard`), the eight tests and this showcase world.