Swatchbook: Material Library, Picker and Calibration Kit
- ..
- .metadata296 B
- README.md5.5 KB
- package.yaml481 B
- starter.materialCollection
- tests
README.md
starterMaterials
The engine's own ready-made surfaces, tagged and registered into the materialLibraryKit library without copying them. Version 1.1.4.
Install it from ZeroMind (search "starterMaterials", or install the published
package 23d92c7c-345b-43bb-bb86-ab7c9d884ffa) and nothing else: the
materialLibraryKit core (1.4.1) comes with it, once, under /source/deps/, with
its calibration shelf, gallery, picker, lighting looks and checks. The 19
starter materials appear in Materials.list, the material picker and the swatch
gallery on every player's machine, with no code in your world. Scripts reach the
core by its package name, ~materialLibraryKit, wherever it was installed.
From any script or the console:
local Materials = require("~materialLibraryKit.Materials")
print(#Materials.list({ collection = "starter" })) --> 19
-- synced: the crate exists for every player, so every player sees its material
local crate = entity.spawn("crate", { synced = true, components = { Model = { model = "cube" } } })
crate.localPosition = { 0, 0.5, 3 }
assert(Materials.apply(crate, "gold")) -- every player sees it
When you are done with the crate, take it away again for every player with
Materials.clear(crate) and entity.despawn(crate.id).
The core brings two guides with it: "How to add materials to your game"
(addMaterialsToYourGame: installing collections, finding, applying and
swapping materials for every player, making your own collection) and "Dress
your game level with materials" (dressYourLevelWithMaterials: a small level
built and dressed from an empty world, then given a new look with one change).
Open them with man or the editor's Docs panel.
Version history
1.1.4 (current, 2026-10-31)
- Installs with the materialLibraryKit 1.4.1 core: after Stop in the editor, what the library reports (applied materials, the lighting look, the gallery exhibit) is back to what it was when play started, matching what the scene shows.
- The 19 materials, their ids and tags are unchanged.
1.1.3 (2026-10-31)
- A clean install: 1.1.2 named the engine's own parts it uses (the parallax and
checker shaders and materials) at the engine version it was built with, so
installing it also laid 8 private copies of those parts under
/source/deps/. 1.1.3 names them with no engine version, so an install brings this package and the materialLibraryKit core, and nothing else. - Installs with the materialLibraryKit 1.4.0 core, which ships the two guides above and lists one calibration shelf whatever other collections a world holds.
- The 19 materials, their ids and tags are unchanged.
1.1.2 (2026-10-21)
-
If you installed 1.1.2 before 18:00 UTC on 2026-10-21, install again: it was published several times that day while it was being finished.
-
Installs with the materialLibraryKit 1.3.0 core. Installing this package on its own brings the whole core with it, once.
-
Every test runs isolated from the live room (
Sync.isolate()/Sync.endIsolation()), so running the suite changes nothing other players see. 8 tests, passing on every run, among them a check that outside play a pick is on the model at once. -
The example spawns a shared crate, so every player really has it, and shows how to take it away again.
-
The version is stated the same way in every place (package settings and description, this README, the asset listing, the collection), and a test checks it.
-
The 19 materials are unchanged.
1.1.1 (2026-10-20)
- Installs with the materialLibraryKit 1.2.1 core.
1.1.0 (2026-10-20)
- Installs with the materialLibraryKit 1.2.0 core, which installs into a new world again.
- The README's example and the package's tests reach the core as
~materialLibraryKit, so they work where an install puts it (/source/deps/). 1.0.0 used@root::, which only finds the core at the top of a world.
1.0.0 (2026-10-18)
- First release: 19 engine materials tagged into the library, and a test suite
(
tests/starterMaterials.testSuite) that drives them through the list, apply, the picker, the gallery, the lighting looks and the checks.
To run the tests: tools.use("tests", "run", "starterMaterials").
What it registers
| id | material | category / kind | style |
|---|---|---|---|
| chrome | metal_chrome | metal / chrome | realistic |
| brushedMetal | metal_brushed | metal / steel | realistic |
| gold | gold | metal / gold | realistic |
| glass | glass | glass / clear glass | realistic |
| water | water (animated) | liquid / water | realistic |
| grass | grass | ground / grass | stylised |
| plasticRed, plasticWhite | plastic_red, plastic_white | plastic / glossy plastic | realistic |
| toonRed | cel_shaded | toon / cel shading | toon |
| neon, emissiveWhite | neon, emissive_white | emissive | scifi |
| animatedColour | animated_color (animated) | emissive / colour cycle | stylised |
| checkerRedBlue (animated), checkerWhite, litChecker, triplanarChecker | checkerboard, checkerboard_white, lit_checkerboard, triplanar_checker | pattern | stylised |
| bricksParallax, bricksFlat | parallax_cube, parallax_cube_flat | masonry / brick | realistic |
| defaultWhite | default | basic / matte | realistic |
The whole collection is one file, starter.materialCollection/collection.yaml:
it is also the worked example of a collection that only tags materials that
live elsewhere.