Swatchbook: Material Library, Picker and Calibration Kit
README.md
Picker
The on-screen material picker for the materialLibraryKit library. It lists every material the
installed .materialCollections provide, filters them by category and style family, and applies
the one you choose to a target entity for every player, through Materials.apply.
local Picker = require("~materialLibraryKit.Picker") -- from a world
-- local Picker = require("~.Picker") -- from inside the package
Picker.open({ style = "grid" }) -- "grid" | "list" | "quick"
Picker.setTarget(entity.find("crate"))
Picker.pick("gold") -- true, or false and why
Picker.onPicked(function(id, target, ok, err) print(id, ok, err) end)
API
| Call | What it does |
|---|---|
Picker.open(opts?) -> (ok, err?) | Shows the picker. opts.style picks its look. |
Picker.close() | Hides it and unregisters its screen. |
Picker.toggle(opts?) -> boolean | Opens or closes it, and returns whether it is open now. |
Picker.isOpen() -> boolean | Whether it is showing. |
Picker.styles() -> { string } | { "grid", "list", "quick" }. |
Picker.style() -> string | The look in use. |
Picker.setStyle(style) -> (ok, err?) | Switches the look live. |
Picker.target() -> entity? | The entity the materials go on. |
Picker.setTarget(entityOrIdOrName?) -> (ok, err?) | Points the picker at an entity. Pass nil to clear it. |
Picker.pick(id) -> (ok, err?) | Applies library material id to the target and shows the result or error in the panel. |
Picker.onPicked(fn) -> unsubscribe | Calls fn(id, target, ok, err) after every pick. |
Picker.visible() -> { id } | The ids the active filters list, in order. Useful for tests and tools. |
Picker.onCallback(id, data) -> boolean | Routes a widget callback by hand. You don't normally need it, because the picker registers its own callback env. |
The three looks
The Grid / List / Quick switch in the header changes the look live.
- Grid shows a thumbnail per material (its
preview.png), with the name andkind · styleunder it and the description and tags in the hover tooltip. Category and style chips filter the grid. Click or tap a tile to apply it. The material on the target is outlined in blue. - List shows a search box (it matches name, id, tags, kind and collection), the same chips,
and one row per material: name,
category / kind, style family, tile size and texture KB. Click or tap a row to apply it. - Quick shows one big card at a time, for touch and gamepad. It has ‹ › cyclers for
category and style, big ◀ ▶ buttons and a big Apply button.
- Keyboard: ←/→ browse, Q/E cycle the category, ↑/↓ cycle the style, Enter applies.
- Gamepad: D-pad left/right browse, LB/RB cycle the category, D-pad up/down cycle the style, and the south face button (A on Xbox, Cross on PlayStation) applies.
- Keys are ignored while a text field has focus.
Targets
- Edit mode: the editor's selection is the target (primary of the
entityselection scope), and it follows the selection as it changes. The panel draws over the Scene view, on the window, because the editor camera does not draw game UI. - Play mode: a click or tap on an object makes it the target. The picker takes the hit
entity, or its nearest ancestor that has a Model. The target gets a blue outline through
@builtin::modules.outline, which is runtime state and never written into the scene. Presses that land on the picker itself (or on any UI that took the pointer) are ignored. When the pointer is locked, the camera-centre ray is used instead. The panel draws in the camera's picture, inside the safe area. setTargetoverrides either until the selection or a click changes it.
Layout and cost
- At 640 points wide or more, Grid and List dock to the right edge and Quick docks bottom-right.
- Below 640 points (a phone), the picker is a bottom sheet: Quick stacks its cyclers, and List narrows its right-hand column.
- Touch targets are 30-60 points.
- The widget tree is rebuilt only when what it shows changes: filters, search, library
(
Materials.onChanged("library")), an applied material, the target, the canvas size, or a mode flip. Grid rows and list rows sit in virtual scroll areas, so only the visible rows are laid out. - The frame loop is a
@builtin::modules.frameDriversystem task that runs only while the picker is open. On a quiet frame it polls the pad (in Quick) and checks the layout every 0.25 s.
Notes
- Thumbnails pass the short VFS path (
/source/.../preview.png) to animagewidget. The image loader reads VFS paths directly, so the picker makes no computedasset.resolve. - The screen is registered from the frame loop's system task, so no component instance owns it
and its callbacks always reach the picker's own env, whoever called
open. - State lives in
modules.state(), so an open picker survives a hot reload of this module. The previous load's loop and subscriptions stand down.