Log inGet started
World

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

CallWhat 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?) -> booleanOpens or closes it, and returns whether it is open now.
Picker.isOpen() -> booleanWhether it is showing.
Picker.styles() -> { string }{ "grid", "list", "quick" }.
Picker.style() -> stringThe 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) -> unsubscribeCalls 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) -> booleanRoutes 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 and kind · style under 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 entity selection 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.
  • setTarget overrides 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.frameDriver system 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 an image widget. The image loader reads VFS paths directly, so the picker makes no computed asset.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.