# artsTD
**Arts TD** is a multiplayer tower defense where every race is a way of making art. This package is the game itself: the eight art races and their towers, the enemy roster and its medium prefixes, tower fusion into hybrids, the campaign maps and waves, saved progress and the shared session that keeps a room of friends on one map.
## What is in the game
- **8 art races**, each drawn by the look published for its medium (see "How the races look"): Watercolor, Ink, Pencil, Toon, Anime, Comic, Paper Cutout and Pixel, with **4 towers each** (32 race towers), every tower with 3 upgrade tiers.
- **The neutral Studio** with **4 towers** any race can build: Easel Bolt, Canvas Cannon, Lantern Watch and Turpentine Mister (slows).
- **Hybrids:** any two towers of different races fuse into a hybrid. There are 448 combinations across all 28 race pairs, 12 of them hand-made specials worth discovering.
- **Enemies** named "<medium> <enemy>" (Watercolor Goblin, Ink Knight) and hybrid enemies in two media at once (Watercolor Ink Goblin); every wave set has at least one hybrid.
- **6 campaign maps** with ramping waves, upgrades, selling, gold, lives, a next-wave preview, wins and losses with star ratings, and saved progress.
## How the races look
Every race's towers and enemies are drawn by mediumKit's published renderer: watercolor by watercolorBlocks, ink by inkBlocks, pencil by pencilBlocks, toon by toonBlocks, anime by animeBlocks, comic by comicBlocks, paper cutout by paperBlocks and starterBlocks, pixel by retroMaterials. Each look is gated to the objects in that medium, so the map keeps its own look. A hybrid tower shows both parents' models, each in its own medium.
Open **`scenes/gallery.scene`** (the Gallery of Media) and press Play to see all eight media and four hybrids at once, on towers and on a parade of over a hundred enemies.
## Choosing your art
Pressing **Paint** on the title opens the race picker every time: all eight races, the ones you have not unlocked shown locked, your current one marked. The **Your art** button at the top of the level select and of every battle (key **P**, or the gamepad's View button) opens it again at any time to switch. Each player picks for themselves, so two players on one account (two windows, a desktop and a tablet) can paint in different media in the same match. A player who joins late gets the room's map, towers, fused hybrids, gold and lives from the synced session.
## Frame budget: the target and what was measured
**Target: 60 fps on the desktop app, 30 fps on the web.** `artsTD.budget` holds it on every player's machine. Once a second it reads the frame time, and when frames run long it renders the scene and the art-medium looks at a lower resolution (down to 55% on desktop, 50% on the web), climbing back to full resolution when there is room. Enemies cast no shadow, the Gallery of Media moves half of its parade each frame, and mediumKit 1.0.3 spreads its watcher's checks evenly over frames.
**Where it was measured:** the Gallery of Media (16 tower models: the eight races' towers and four two-model hybrids; 112 walking enemies in all eight media and four hybrid pairs, all on one screen). Native desktop app, **development build**, window 2097x1409, on a shared machine that was also running the editor and agent tools. Wall time per frame on that machine (40 to 140 ms) mostly measures the other work on it. The numbers below are the engine's own CPU and GPU time, and the rate the engine reports it would hold with the machine to itself.
| Settings | Render scale | Engine CPU | GPU passes | Rate with the machine to itself |
|---|---|---|---|---|
| Desktop profile, before this pass (full resolution) | 100% | 21.6 ms | 51.4 ms | 27 fps (GPU bound) |
| Desktop profile, as shipped (governor on) | 55% | 19.6 ms | 20.1 ms | 51 fps (CPU bound) |
| Web profile (low quality looks, 30 fps target), run on the desktop app | 55% | 20.6 ms | 17.5 ms | 49 fps |
What this means, honestly:
- **Desktop, 60 fps: not reached on this machine.** The governor brings the GPU from 51 to 20 ms. The engine estimates 51 fps here and is limited by the CPU. Most of the remaining CPU time is the development build and the editor and agent tooling running beside the game (state snapshots, publish reminders), which a shipped build does not run. The gallery's own script is 0.5 ms. Whether a release build on a quiet machine holds 60 fps was **not measured**.
- **Web, 30 fps: not measured in a browser.** No browser engine was connected. The web profile run on the desktop app estimates 49 fps, above the target, but a browser's WebGPU and a weaker device are different, and nothing here measured them.
- **Tablet: not measured.** No tablet was connected.
- At full resolution most GPU time is the medium looks' full-screen passes (pencil about 15 ms, toon 5, ink 3, watercolor 1.5, the rest under 1 ms each), plus styleKit's object mask and culling (about 13 ms). They all scale with the pixel count, which is why the render scale is the lever.
## What was tested, and what was not
| | Status |
|---|---|
| Desktop app, keyboard and mouse, gamepad, touch (simulated input) | tested on this desktop in earlier passes |
| Window sizes from a sideways phone to an upright tablet (build menu 1 to 5% of the screen) | tested by resizing the desktop window |
| The level select: from the title (Paint), after picking or cancelling a race (keys Enter and Esc), from the pause menu and from the results screen | tested on this desktop, each route showing the parchment map with each map's best result |
| The fourth tower of every race: on sale, built, upgraded to tier 3, drawn as its own model | tested on this desktop |
| Gallery of Media framing (all 12 towers and the parade in one shot) and its legend leaving with the gallery | tested on this desktop |
| Two live fusions (parent A becomes the hybrid in place, parent B is removed, hybrid ready within 0.1 s on the host) | tested on one desktop client |
| Win, quit, restart, twice: race, palette, stars, maps won and best result per map kept; a worse win does not overwrite the best | tested on one desktop client |
| **The web build in a browser** (any input) | **not tested and not measured**: no browser engine was connected; "web profile" above is the low tier run on the desktop app |
| **A tablet** | **not tested and not measured**: no tablet was connected |
| **A second player seeing the same hybrid, and two players picking different races in one match** | **not tested with two clients**: the machine had too little free memory for a second game client. The hybrid lands in the synced session state every player reads, and each player's race is announced separately, but no second player was watched receiving them |
## Modules
| Part | Module |
|---|---|
| Races, colours, media, towers, enemy traits | `artsTD.races` |
| Race and hybrid towers on turretsKit + build menu | `artsTD.towers` |
| Enemies with generated models, prefixed kinds | `artsTD.enemies` |
| Fusing two towers into a hybrid (fusionKit) | `artsTD.hybrids`, `artsTD.fuse` |
| Campaign maps, waves, stars | `artsTD.maps` |
| Saved progress (saveKit) | `artsTD.progress` |
| Room state, players and their races, map switching, results | `artsTD.session`, `artsTD.Session` |
| Title, race picker, level select, "Your art" button | `artsTD.flow` |
| Painting towers and enemies in their media | `artsTD.painter` |
| Juice and sound on build, upgrade, combine and sell | `artsTD.feel` |
| The Gallery of Media | `artsTD.gallery` |
| Holding 60 fps (desktop) / 30 fps (web) by render resolution | `artsTD.budget` |
| Boot | `artsTD.game` |
| Map scenery | `artsTD.scenery` |
The scene `scenes/arts.scene` builds the battlefield with towerDefenseKit and spawns the synced `ArtsSession`; `scenes/gallery.scene` is the Gallery of Media.
# 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.