# pickerKit: choose your race, faction, class or character
A finished **"choose your side" screen** for any Zero game: races, factions, classes, heroes, starters, loadouts, art styles. Locked choices stay visible (greyed, silhouetted, with a padlock, the reason and progress toward the unlock) and refuse with a shake and a sound. One setting picks the **layout**, another the **theme**, a third the **preview style**, and every layout works with every theme. The kit **remembers** each player's choice between sessions. It plays with **mouse, keyboard, gamepad and touch**, shows the right button prompts, fits **phones and tablets**, and is **multiplayer**: every player picks their own (and sees everyone else's pick and ready state), or the room makes one pick together.
**Install:** search ZeroMind for `pickerKit` and install it (`zero zeromind installAsset <pickerKit package guid>`), or `tools.use("zeromind", "installAsset", "<guid>")`. menusKit (UI sounds) and controlsKit (input reading and button prompts) come with it. Nothing has to be placed in a scene: the kit spawns its own local host the first time a picker opens in play.
```luau
local Picker = require("pickerKit.api")
Picker.open({
id = "race", title = "Choose your art", subtitle = "Each style paints its own towers",
choices = {
{ id = "ink", name = "Ink", title = "Masters of the Stroke", color = { r = 40, g = 40, b = 58 }, icon = "✒",
blurb = "One decisive line, no second chances.", stats = { { label = "Power", value = 0.85 }, { label = "Range", value = 0.8 } } },
{ id = "pixel", name = "Pixel", color = "#3d3f78", icon = "▦", blurb = "Chunky, fast and relentless.",
locked = true, lockText = "Win map 3 to unlock", progress = 0.66 },
},
layout = "cards", theme = "parchment", mode = "each", confirmText = "Paint!",
onConfirm = function(choiceId, player) startGameAs(choiceId) end,
})
```
Call `open` on **every machine** (each player's game runs it, e.g. from the scene's `onLoad` / `localPlayerReady`). Each machine draws the screen for its own player; picks travel between machines by themselves.
Try it: the world *Choose Your Side* opens on `scenes/gallery`, a showroom where a bar cycles every layout, theme, sample set, multiplayer mode, preview style and backdrop (keys L / T / C / M / P / B). Drop `pickerKit.PickerGallery` on any entity to get the same showroom in your own world.
## Layouts (`layout`)
| Name | What it looks like | Moves with |
|---|---|---|
| `cards` | Big cards in a row: art, name, title, blurb, stat bars, lock strip. Pages with arrows and dots when they do not all fit; one large card on a phone. | ←/→ |
| `portraitGrid` | Fighting-game roster: a grid of portrait tiles with name plates and a blinking 1P cursor, beside a large detail panel (stacked on a phone). | ←/→/↑/↓ |
| `bannerHall` | Tall hanging banners on a gilded rod; the focused standard unfurls with emblem, story and stats while the others sway. | ←/→ |
| `carousel` | A turning carousel: the centre card large and lit, neighbours scaled, skewed and dimmed; drag/swipe to turn; a wide story-and-stats panel under it. | ←/→, swipe |
| `wheel` | A radial wheel of emblems with a highlighted wedge and needle; point the stick (or the mouse) at a choice; the hub and a side panel show the details. | stick angle, ←/→ |
| `book` | An open codex: art and name on the left page, chronicle and stats on the right, one bookmark tab per choice; pages flip; single page on a phone. | ←/→, tabs, swipe |
`Picker.layouts()` lists them; `require("pickerKit.layouts").define(name, { label, desc, nav = "row"|"grid"|"ring"|"pages", draw = fn(ctx, x, y, w, h) -> nodes })` adds your own (build it from `pickerKit.parts`).
## Themes (`theme`)
| Name | Look | Fonts |
|---|---|---|
| `parchment` | aged map paper, ink washes, ruled border | EB Garamond |
| `neon` | synthwave grid and horizon sun, glowing outlines on night glass | Anton / JetBrains Mono |
| `storybook` | pastel sky, clouds and doodled stars, rounded frames | Gelasio |
| `minimal` | clean light surfaces, thin lines, one accent | Bricolage Grotesque / Arimo |
| `royal` | velvet and gilt, heraldic diamond pattern, gold frames | EB Garamond / PT Serif |
| `pixel` | starfield and grass blocks, hard drop shadows, segmented stat bars | JetBrains Mono |
| `paint` | painterly canvas with loose colour washes in the choices' own colours | Bricolage Grotesque / Gelasio |
`Picker.themes()` lists them; `require("pickerKit.themes").define(name, { base = "minimal", ink = "#...", accent = "#...", ... })` adds your own. Each theme also picks the menusKit UI sounds (move, pick, confirm, refuse) and the controlsKit prompt style.
## Preview styles (`previewStyle`)
A preview panel beside the layout shows the focused choice large. Pick one with `previewStyle` on `Picker.open` (or `Picker.setPreviewStyle(name)` for every picker); it works with every layout and theme. On a wide screen the panel is a column at the right, on a tall phone a band across the top, and on a short phone it steps aside so the layout keeps its room.
| Style | What it shows |
|---|---|
| `none` (default) | no panel: the layout uses the whole stage |
| `portrait` | a big round emblem or portrait, the choice's two colour swatches, its name, title and blurb |
| `stats` | large stat bars with their values (0 to 100), an overall rating in five pips, tags and the blurb |
| `banner` | a tall painted banner on a gilded rod in the choice's colours, with its emblem, name and motto; it unfurls as the focus moves |
| `showcase` | a turntable: in play a camera renders the choice's 3D model (`model`, `material`, `modelScale` on the choice, else a gem tinted in its colour) slowly turning on a pedestal into the panel; in edit mode, tests and `Picker.render` it shows the art floating on a turning halo |
| `fn(choiceId, box) -> widget` | your own panel; `box` is `{ width, height, locked, saved, choice, theme }` |
Every style shows a locked choice silhouetted with its padlock, reason and progress, and marks the player's current (saved) choice. `require("pickerKit.previews").define(name, { label, desc, draw = fn(ctx, choice, x, y, w, h) -> nodes })` adds your own named style. The older `preview = fn(choiceId|nil)` hook still fires as the focus moves, so a model in your own 3D scene can follow along.
## Remembering the choice
The kit remembers each player's choice by itself (`remember = true` by default). When a player confirms, the choice is saved in the engine's persistent per-player store (`runtime_data`, under `pickerKit/<picker id>`), so it survives leaving and coming back, and in multiplayer every player keeps their own. Opening that picker again starts on the saved choice and marks it CURRENT; locked choices still show locked.
```luau
local race = Picker.saved("race") -- the saved choice id, or nil
if race == nil then
Picker.open({ id = "race", title = "Choose your art", choices = races, onConfirm = startAs })
else
startAs(race)
end
-- later, from a "Change race" button: same options, fresh lock states
Picker.reopen("race", { choices = racesWithCurrentUnlocks(), allowCancel = true })
```
`Picker.current(id)` is this session's pick, else the saved one. `Picker.saved(id, userId)` reads another player's saved choice. `Picker.forget(id)` clears it. `remember = false` turns saving off; a `{ get, set }` table stores through your own save system instead.
## Choice fields
| Field | Meaning |
|---|---|
| `id` | string, what `onPick` / `pickOf` answer |
| `name`, `title?` | the name and a subtitle line |
| `blurb` | a sentence or two |
| `color` | `{ r, g, b }` (0..1 or 0..255) or `"#rrggbb"`; drives the card art, borders, bars and banner |
| `accent?` | a second colour |
| `icon?` | an inline SVG string (`"<svg ...>"`), a texture reference (or `{ texture = ref }`), or a glyph/emoji text; the name's initial when missing |
| `portrait?` / `portraitFn?` | a texture reference shown as the art, or `fn(choiceId, { width, height, locked, focused }) -> widget` for any widget you like |
| `stats?` | `{ { label = "Power", value = 0..1 }, ... }` |
| `tags?` | `{ "slow", "area" }`, shown as chips in detail panels |
| `locked`, `lockText`, `progress?` | locked choices show silhouetted with a padlock, the reason and a progress bar (0..1); picking one is refused with a shake and a sound |
| `new` | a pulsing NEW badge |
| `model?`, `material?`, `modelScale?` | the `showcase` preview's 3D model (an `asset.ref(..., "mesh")`), its material and scale |
## Options of `Picker.open`
`id` (default `"default"`), `title`, `subtitle`, `choices`, `layout`, `theme`, `mode` (`"each"` or `"shared"`), `decider` (`"host"` or `"vote"`, shared mode), `exclusive` (no two players the same choice, each mode), `allowCancel` (Esc/B/Back closes and calls `onCancel`), `confirmText`, `closeOnConfirm` (default true), `waitForAll` (each mode: stay open showing "Waiting… 2/3" until every present player confirmed, then `onAllConfirmed(picks)` and close), `initial` (choice id to start on), `remember` (default `true`: each confirmed pick is saved for this player in the engine's persistent store and the picker starts on it next time, see Remembering; `false` saves nothing; or your own store `{ get = fn(key), set = fn(key, value) }`, e.g. saveKit's `{ get = Save.get, set = Save.set }`, saved under `pickerKit.<id>`), `previewStyle` (`"none"` (default), `"portrait"`, `"stats"`, `"banner"`, `"showcase"`, or `fn(choiceId, box) -> widget`; see Preview styles), `sounds` (default true), `blockInput` (default true: the player's gameplay controls stand down while the picker is open), `backdrop` (`"full"`, `"dim"` to let a 3D scene show through, `"none"`), `insets` (`{ top, left, right, bottom }` points to keep clear for your HUD), `layer` (UI layer, default 990; see Layering), `preview = fn(choiceId|nil)` (called with the focused choice as it changes, and nil on close; use it to show a model in-world behind the UI), `onPick(choiceId, player)`, `onConfirm(choiceId, player)`, `onCancel()`, `onAllConfirmed(picks)`.
## API
```luau
Picker.open(opts) -> id
Picker.reopen(id, overrides?) -> id? -- open again any time with the last options (plus overrides): starts on the saved choice, locked ones locked
Picker.saved(id, userId?) -> choiceId? -- the remembered choice (this player, or another player's)
Picker.current(id) -> choiceId? -- this session's pick, else the saved one
Picker.forget(id) -- clear the remembered choice
Picker.render(opts, w, h, extras?) -> widget tree -- draw a picker without opening it (thumbnails, docs, menus); no host, input, sound or callbacks
Picker.setPreviewStyle(style) / Picker.previewStyle() / Picker.previewStyles()
Picker.close(id?) -- the top picker when no id; picks stay readable
Picker.isOpen(id?) -> boolean
Picker.pickOf(player?, id?) -> choiceId? -- synced, any machine; player = nil (me), userId, peer id, a players-registry player or a callback player
Picker.isConfirmed(player?, id?) -> boolean
Picker.picks(id?) -> { [userId] = choiceId }
Picker.players(id?) -> { { userId, peer, name, isLocal, host, pick, confirmed } }
Picker.onPicked(fn(player, choiceId, id)) -> stop() -- every machine, every player's change
Picker.roomPick(id?) -> choiceId?, confirmed -- shared mode
Picker.votes(id?) -> { [userId] = choiceId } -- shared mode
Picker.setLayout(name) / Picker.layout() / Picker.layouts()
Picker.setTheme(name) / Picker.theme() / Picker.themes()
Picker.catalogue() -> { version, layouts, themes, previews }
Picker.setChoices(id, choices) -- after an unlock: the focus stays on the same id
Picker.choices(id?)
Picker.inputBlocked() -> boolean
Picker.setLayer(n) / Picker.layer() -- default UI layer for picker screens (990)
Picker.VERSION
-- driving it from code (what the host does with input): focus(i), navigate(dir), select(i?), confirm(), back(), stick(x, y), handle(callbackId)
```
A callback `player` is `{ userId, peer, name, isLocal, host }`. `onPick` and `onConfirm` fire on the machine of the player who picked (in shared mode `onConfirm` fires on every machine when the room's pick is confirmed, with the deciding player); `onPicked` fires on every machine for every player.
## Input
- **Mouse**: hovering a card focuses it, clicking picks it, clicking the picked card again (or the confirm button) confirms. Arrows at the sides page.
- **Keyboard**: arrows / WASD move, Enter picks (Enter on the pick confirms), Space confirms, Backspace / Escape backs (un-readies, or cancels with `allowCancel`), Q / E step.
- **Gamepad**: d-pad / left stick move, A picks and confirms, Y confirms, B backs, bumpers step. On the `wheel` the stick points straight at a choice.
- **Touch**: tap to pick, tap again or the big button to confirm; swipe the carousel and the book.
- Button prompts (controlsKit) show for the device in hand and hide on touch. While a picker is open, the player's gameplay controls stand down (`blockInput`).
## Multiplayer
- **`mode = "each"`**: every player picks their own. Every screen shows small avatars on the choices ("Alice picked Ink" in the detail panels), a players strip with each pick and a ✓ when ready, and "2/3 ready". `exclusive = true` refuses a choice another player already holds ("Alice already picked Ink"); two players picking the same one at the same moment are settled by who picked first (session clock), the other is told and freed.
- **`mode = "shared"`**: one pick for the room. `decider = "host"` (default): the room host's pick is the room's pick and only the host confirms; everyone else's pick shows as a suggestion. `decider = "vote"`: the most-picked choice leads, and the room confirms when every present player has confirmed.
- How it syncs: each player gets one synced seat entity (`pickerKit.PickerSeat`, spawned with `entity.spawnSynced`, owned by their machine) with `Sync` fields for name, user id, host and picks per picker id. Late joiners receive every seat in the room snapshot, so they see the current picks at once. A machine only writes its own seat.
## What is inside
`api` (the surface above), `layouts`, `themes`, `previews` (the preview styles), `parts` (the widgets layouts are drawn from), `seats` (sync), `samples` (eight art races, eight fantasy factions, six arena heroes, with SVG emblems), `PickerHost` (local host: drawing and input), `PickerSeat` (synced per-player picks), `PickerGallery` (the showroom), `pickerInputBlock` (the input map held while open), `pickerKitTests` (tests), and two guides: *How to add a choose your race, faction or class screen with locked choices* and *Example: a hero select screen for a small arena game from an empty world*.
## Layering
A picker is modal, so it draws at UI layer **990** by default: above menusKit (950), campaignKit screens (960), the gallery bar (970) and ordinary HUDs, below toasts and system overlays (1000+). `layer = n` on `Picker.open` (or `Picker.setLayer(n)` for every picker) moves it; a screen on the same layer as another one may lose the tie and draw under it.
## Known limits
- Text fitting is estimated (the engine has no text-measuring call at tree-build time), so a very long name shrinks to fit rather than wrapping; blurbs are clipped to the room their panel has.
- Hover focus uses the pointer the UI publishes each frame; in a touch-only session hover is off and taps pick directly.
- Seats of players who left stay in the room (the engine hands a leaver's entities to another peer) but are ignored: only present peers count.
- Remembering uses the engine's per-player store (`runtime_data`), which needs a signed-in player; an anonymous session keeps the choice for that session only. A custom `remember` store is read and written only for this machine's player.
- The web build was not checked by the author (an agent in the engine cannot start a browser engine).
## Versions
- **1.0.4**: the api module README says what the module provides, who calls it and how remembering and synced picks work. No code change.
- **1.0.3**: built-in preview styles (`previewStyle` = `portrait`, `stats`, `banner`, `showcase`, or your own function), shown in the gallery (Preview pill, key P); the kit remembers each player's choice in the engine's per-player store by default (`remember = true`) and marks it CURRENT on reopen; new `Picker.saved`, `Picker.current`, `Picker.forget`, `Picker.reopen`, `Picker.render`, `Picker.setPreviewStyle`; round emblems no longer vanish on large art (the banner hall's open banner); the wheel no longer fails in a narrow stage; 27 tests.
- **1.0.2**: hovering an edge card no longer scrolls another card under a still mouse (paged cards and banner hall keep their window while the focus is inside it; the carousel turns on click, not hover); carousel side cards and the banner hall's rod stay inside the screen at tablet and phone sizes; the host no longer errors when the pointer read has no position; the test suite (17 tests) and both guides ship in the package.
- **1.0.1**: pickers draw at UI layer 990 by default (they lost a tie with campaignKit's level select at 960); new `layer` option, `Picker.setLayer` / `Picker.layer`. On a pad the picker now follows the engine's own UI pad focus (d-pad / stick move it between cards, south presses) and claims Back (east, Escape, Android back) to un-ready or cancel.
- **1.0.0**: first release: six layouts, seven themes, locked/NEW/progress, each and shared modes with exclusive picks and voting, mouse/keyboard/gamepad/touch, phone and tablet layouts, preview hook, input blocking, gallery, tests and two guides.