api
The one module a game requires to put up a choose-your-race / faction / class / character screen. Games and the kit's own PickerHost and PickerGallery components call it.
pickerKit.api
The one module a game requires to put up a choose-your-race / faction / class / character screen. Games and the kit's own PickerHost and PickerGallery components call it.
Picker.open({ id, title, subtitle, choices, layout, theme, previewStyle, remember, mode, exclusive, allowCancel, confirmText, initial, preview, onPick, onConfirm, onCancel, ... }) opens a picker; close, isOpen, pickOf(player, id), picks(id), onPicked(fn), setLayout / layouts, setTheme / themes, setPreviewStyle / previewStyles, setChoices(id, choices) and VERSION are the rest of the surface.
The kit remembers each player's confirmed choice in the engine's per-player store: saved(id) reads it, current(id) gives this session's pick or the saved one, forget(id) clears it, and reopen(id, overrides) opens the picker again any time on the current choice, with locked choices shown locked. render(opts, w, h) draws a picker as a widget tree without opening it.
Picks are synced per player through pickerKit's seats, so pickOf answers on every machine. Input (select, confirm, back, navigate, stick, drag, handle) and build(w, h, safe, extras) are what the PickerHost component drives each frame.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2pickerKit.api: the one module a game uses. local Picker = require("pickerKit.api") Picker.open({ id = "race", title = "Choose your art", choices = {...}, layout = "cards", theme = "parchment", mode = "each", onConfirm = function(choiceId, player) ... end }) Call `open` on every machine (each player's game runs it); every machine draws its own screen for its own player, and picks travel between machines through each player's synced seat (`pickerKit.seats`). The kit spawns its own local host entity (PickerHost) that draws and reads input in play, so nothing has to be placed in a scene.
sounds( ) → any
play(kind: string, opts: any?) → void
| arg | type | description |
|---|---|---|
| kind | string | |
| opts | any? |
call(fn: any, ...: any) → void
| arg | type | description |
|---|---|---|
| fn | any | |
| ... | any |
normalize(list: { any }) → void
| arg | type | description |
|---|---|---|
| list | { any } |
indexOf(P: Picker, id: string?) → number
| arg | type | description |
|---|---|---|
| P | Picker | |
| id | string? |
choiceById(P: Picker, id: string?) → Choice
| arg | type | description |
|---|---|---|
| P | Picker | |
| id | string? |
playerOf(s: any) → any
| arg | type | description |
|---|---|---|
| s | any |
me( ) → any
message(P: Picker, text: string, kind: string?) → void
| arg | type | description |
|---|---|---|
| P | Picker | |
| text | string | |
| kind | string? |
hostComponent( ) → string
ensureHost( ) → void
setBlocked(on: boolean) → void
| arg | type | description |
|---|---|---|
| on | boolean |
syncBlocked( ) → void
inputBlocked( ) → boolean
Whether pickerKit is holding this player's gameplay controls (a picker is open).
engineStore(userId: string?) → any
| arg | type | description |
|---|---|---|
| userId | string? |
readSaved(pickerId: string, userId: string?) → string
| arg | type | description |
|---|---|---|
| pickerId | string | |
| userId | string? |
writeSaved(pickerId: string, choice: string?) → void
| arg | type | description |
|---|---|---|
| pickerId | string | |
| choice | string? |
useStore(id: string, opt: any) → void
| arg | type | description |
|---|---|---|
| id | string | |
| opt | any |
remembered(P: Picker) → string
| arg | type | description |
|---|---|---|
| P | Picker |
remember(P: Picker, choice: string) → void
| arg | type | description |
|---|---|---|
| P | Picker | |
| choice | string |
saved(pickerId: string, userId: string?) → string
The choice this player saved for a picker id (remembered from an earlier confirm, this session or a past one), or nil. `userId` reads another player's saved choice from the engine store.
| arg | type | description |
|---|---|---|
| pickerId | string | |
| userId | string? |
forget(pickerId: string) → void
Forget this player's saved choice for a picker id.
| arg | type | description |
|---|---|---|
| pickerId | string |
seatPicks(P: Picker) → void
| arg | type | description |
|---|---|---|
| P | Picker |
holderOf(P: Picker, choice: string) → any
in exclusive mode: who holds a choice (earliest pick wins, then lowest peer)
| arg | type | description |
|---|---|---|
| P | Picker | |
| choice | string |
hostSeat( ) → any
roomPick(id: string?) → void
Shared mode: the room's current pick for a picker (host decides, or the vote leads), and whether the room has confirmed it.
| arg | type | description |
|---|---|---|
| id | string? |
canDecide(P: Picker) → boolean
| arg | type | description |
|---|---|---|
| P | Picker |
prepare(P: Picker, id: string, opts: { [string]: any }) → void
set a picker up from its options (shared by open and render)
| arg | type | description |
|---|---|---|
| P | Picker | |
| id | string | |
| opts | { [string]: any } |
open(opts: { [string]: any }) → string
Open a picker screen. Returns its id. See the README for every option.
| arg | type | description |
|---|---|---|
| opts | { [string]: any } |
close(id: string?) → void
Close a picker (the top one when no id). Its picks stay readable with pickOf/picks.
| arg | type | description |
|---|---|---|
| id | string? |
isOpen(id: string?) → boolean
Whether a picker (or any, with no id) is open on this machine.
| arg | type | description |
|---|---|---|
| id | string? |
reopen(id: string, overrides: { [string]: any }?) → string
Open a picker again any time with the options it was last opened with, plus `overrides` (fresh `choices` after an unlock, say). It starts on this player's pick, else their saved choice, which is marked as their current choice; locked choices show locked. Returns the id, or nil when the picker was never opened and the overrides carry no choices.
| arg | type | description |
|---|---|---|
| id | string | |
| overrides | { [string]: any }? |
current(id: string) → string
This player's current choice for a picker: their pick this session, else the saved one, or nil.
| arg | type | description |
|---|---|---|
| id | string |
setChoices(id: string, choices: { any }) → void
Replace a picker's choices (after an unlock, say); the focus stays on the same choice id.
| arg | type | description |
|---|---|---|
| id | string | |
| choices | { any } |
choices(id: string?) → void
The choices a picker shows (normalized copies), or nil.
| arg | type | description |
|---|---|---|
| id | string? |
seatFor(player: any) → any
| arg | type | description |
|---|---|---|
| player | any |
pickOf(player: any?, id: string?) → string
A player's pick (nil = this machine's player; a userId string, a peer id, a players-registry player or a callback's player table). In shared mode, the room's pick.
| arg | type | description |
|---|---|---|
| player | any? | |
| id | string? |
isConfirmed(player: any?, id: string?) → boolean
Whether a player has confirmed their pick (same player forms as pickOf).
| arg | type | description |
|---|---|---|
| player | any? | |
| id | string? |
picks(id: string?) → void
Every present player's pick: `{ [userId] = choiceId }` (shared mode: everyone maps to the room's pick).
| arg | type | description |
|---|---|---|
| id | string? |
votes(id: string?) → void
Shared mode: each present player's own vote/suggestion `{ [userId] = choiceId }`.
| arg | type | description |
|---|---|---|
| id | string? |
players(id: string?) → void
The players choosing: `{ userId, peer, name, isLocal, host, pick, confirmed }` for a picker id.
| arg | type | description |
|---|---|---|
| id | string? |
onPicked(fn: (any, string?, string) → void
Listen for any player's pick changing, on every machine: fn(player, choiceId, pickerId). Returns a function that stops listening.
| arg | type | description |
|---|---|---|
| fn | (any, string?, string |
setLayout(name: string) → void
Switch every open picker (and the default) to a layout.
| arg | type | description |
|---|---|---|
| name | string |
layout( ) → string return layoutName end
layouts( ) → void
setTheme(name: string) → void
Switch every open picker (and the default) to a theme.
| arg | type | description |
|---|---|---|
| name | string |
theme( ) → string return themeName end
themes( ) → void
setPreviewStyle(style: any) → void
Switch every open picker (and the default) to a preview style: "none", "portrait", "stats", "banner", "showcase", one added with `pickerKit.previews.define`, or a function `fn(choiceId, box) -> widget`.
| arg | type | description |
|---|---|---|
| style | any |
previewStyle( ) → any return previewName end
previewStyles( ) → void
setLayer(n: number) → void
Set the default UI layer picker screens draw on (990); a picker's own `layer` option wins.
| arg | type | description |
|---|---|---|
| n | number |
layer( ) → number
The UI layer the top picker draws on.
catalogue( ) → any
`{ version, layouts, themes, previews }` with labels and descriptions.
_top( ) → Picker
focusTo(P: Picker, i: number, quiet: boolean?) → void
| arg | type | description |
|---|---|---|
| P | Picker | |
| i | number | |
| quiet | boolean? |
focus(i: number, quiet: boolean?) → void
Focus choice i of the top picker (as hover / stick / tap does).
| arg | type | description |
|---|---|---|
| i | number | |
| quiet | boolean? |
focused( ) → number
navigate(dir: string) → void
Move focus one step: "left", "right", "up", "down".
| arg | type | description |
|---|---|---|
| dir | string |
refuse(P: Picker, i: number, text: string) → void
| arg | type | description |
|---|---|---|
| P | Picker | |
| i | number | |
| text | string |
select(i: number?) → boolean
Try to pick choice i (default: the focused one). Locked or taken choices are refused with a shake. Picking the current pick again confirms it.
| arg | type | description |
|---|---|---|
| i | number? |
confirm( ) → boolean
Confirm the current pick (the confirm button / Enter on the picked choice).
back( ) → boolean
Back: un-ready a confirmed pick, else cancel when `allowCancel` is set.
stick(x: number, y: number) → void
Point the wheel with a stick or pointer direction (x right, y up).
| arg | type | description |
|---|---|---|
| x | number | |
| y | number |
drag(dx: number?) → void
Carousel/book swipe in progress: dx points dragged so far (nil ends it; a long swipe turns one step).
| arg | type | description |
|---|---|---|
| dx | number? |
handle(id: string, data: any?) → boolean
Handle a UI callback id from the picker screen. Returns true when it was the picker's.
| arg | type | description |
|---|---|---|
| id | string | |
| data | any? |
_tick(dt: number) → void
Run once a frame by the host: fires onPicked/onConfirm for other players' changes, resolves exclusive clashes, ends shared picks.
| arg | type | description |
|---|---|---|
| dt | number |
_isDirty( ) → boolean return dirty end
_markDirty( ) → void
_clean( ) → void
_attach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_detach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
modeLine(P: Picker, n: number) → string
| arg | type | description |
|---|---|---|
| P | Picker | |
| n | number |
build(w: number, h: number, safe: any?, extras: any?) → any
Build the top picker's widget tree for a canvas w×h (safe = { left, top, right, bottom }). extras: { prompt = fn(action, id), device, touch }.
| arg | type | description |
|---|---|---|
| w | number | |
| h | number | |
| safe | any? | |
| extras | any? |
render(opts: { [string]: any }, w: number, h: number, extras: any?) → any
Draw a picker screen as a widget tree WITHOUT opening it: no host, no input hold, no sounds, no callbacks (for thumbnails, docs, menus and tests). Takes the same options as `open`; `focus = i` picks the focused choice. It reads, never writes, the saved choice.
| arg | type | description |
|---|---|---|
| opts | { [string]: any } | |
| w | number | |
| h | number | |
| extras | any? |
buildFor(P: Picker, w: number, h: number, safe: any?, extras: any?) → any
| arg | type | description |
|---|---|---|
| P | Picker | |
| w | number | |
| h | number | |
| safe | any? | |
| extras | any? |
_reset( ) → void
Tests only: forget every picker, listener and pick on this machine.
_memoryOnly(on: boolean) → void
Tests only: keep saved choices in memory instead of the player's real store.
| arg | type | description |
|---|---|---|
| on | boolean |
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.