Arts TD
README.md
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.
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.
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
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
wheelthe 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 = truerefuses 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 withentity.spawnSynced, owned by their machine) withSyncfields 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 customrememberstore 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; newPicker.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
layeroption,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.