# buildPlaceKit
**A base-building kit for any multiplayer Zero world: press B, pick a piece, see a green or red ghost where you aim, turn it, click to place it.** Pieces cost money and give part of it back when you take them down, they snap to a grid, to any surface or to each other, and every player (and everyone who joins later) sees the same base.
Version **1.0.35** (`Build.VERSION`; this README, `package.yaml` and `Build.VERSION` move together).
**What you get:** 24 piece kinds in two styles (a rustic **Frontier** style in oak timber, dry stone and thatch, and a sci-fi **Outpost** style in hull panels with glowing trim), three snap modes, four ghost looks, three build menus, prices and refunds through economyKit's cheat-proof wallets, a thud, a camera kick and a dust puff on every placement (juiceKit and the kit's own sounds), keyboard and mouse, gamepad and touch controls, pieces kept between sessions, and 22 automated tests. One install brings gridKit, economyKit and juiceKit with it, and the wood, stone, masonry and sci-fi material collections the styles are drawn with.
## First example
1. Install **buildPlaceKit** into your world: search ZeroMind for "buildPlaceKit" and install it from the ZeroMind panel, or install the package id `710d96cd-5dfe-476c-aa76-f43ac60fdefc` (`zeromind.installAsset`). It takes a few seconds to a minute. On the current engine, install 1.0.17 or newer: older releases are refused (#22402, see Known limits).
2. In `scenes/main.scene/build.luau`, add this line inside `function content()`, before its `end`:
```lua
require("buildPlaceKit.api").BuildMode {}
```
3. Press Play and press **B**.
If, right after installing, no wallet shows in the top-left and every piece is refused with "Not enough Coins", close the world and open it again once (#22328, see Known limits). Stop and Play does not clear it; reopening does, and it does not come back.
A 60 × 60 m build zone sits around the scene's origin. A hotbar of pieces opens at the bottom of the screen and a glowing hologram of a foundation follows where you aim. Click to build it: 20 coins leave your wallet (top-left; every new wallet starts with 100), it lands with a thud and a puff of dust. Pick a Wall (scroll or number keys) and aim at the foundation's edge: the wall clicks onto it. Aim at the ground under your own feet and the ghost turns red (*Someone is standing there*); clicking there buzzes and builds nothing. (Aim a second foundation at the first instead and it clicks on beside it: piece-to-piece snapping is the default.) Press **X** and click a piece to take it down for half its price back. **B** or **Esc** puts build mode away.
economyKit, which the kit uses for wallets, also starts inventoryKit's bag for every player. When the kit sets economyKit up itself (as here), it turns the bag's strip, its Tab/I keys and its touch button off, and stands the rest of inventoryKit's keys down (G for its screen-style gallery, the number keys, E at a chest; the `buildPlaceKit.bagQuiet` input map), so a world that only wants building gets no bag and no bag keys. (This needs economyKit 1.0.13 or newer, which buildPlaceKit 1.0.14 and newer install: older economyKit releases loaded a second copy of inventoryKit, so the bag strip stayed on whatever the kit asked.) Pass `inventory = true` to `Build.setup` to keep the bag; with the bag on, build mode stands it and its keys down while it is open (so Tab, G and the number keys are the build kit's) and puts them back when build mode closes. The kit sets economyKit up again at the start of every Play, so the bank, the wallet and coins on the ground work on the second Play of a session as on the first.
If your own code calls economyKit or juiceKit too (coins on the ground, an effect of your own), install those two kits into your world as well: economyKit `d113a24e-3a87-40d2-a725-af49b56f629b`, juiceKit `eed55f6d-afaf-4767-83c5-539ef91e0dc5`. The install moves the copies buildPlaceKit brought up to your world's top level rather than adding second ones, so there is still one wallet and one bank. A kit that only came in as buildPlaceKit's dependency belongs to buildPlaceKit, and a game that requires it without installing it can find it unresolved once published. Today, on the current engine, those two installs are refused (#22402, see Known limits). Until economyKit and juiceKit are published again, your code can call the copies buildPlaceKit brought, which run in your world; install the two kits yourself once they install again, before you publish a game that relies on them.
## Guides
Two guides ship inside the package and open in the Docs panel, with `man`, or with the `guides` tool by their folder path:
- **How do I let players build walls, floors and roofs in my game?** What the kit gives you, how pieces, styles, snap modes, ghost looks, menus, prices and multiplayer fit together, and what to do first: `buildPlaceKit.package/how-to-let-players-build-walls-floors-and-roofs-in-your-game`.
- **Make a base building survival game, step by step.** From an empty world to a small multiplayer game where players earn coins and build themselves a shelter, with buildPlaceKit, economyKit, juiceKit and gridKit: `buildPlaceKit.package/make-a-base-building-survival-game-step-by-step-earn-coins-and-build-a-shelter`.
## Changing it with one setting
```lua
local Build = require("buildPlaceKit.api")
-- inside content():
Build.BuildMode {
style = "scifi", -- "rustic" (Frontier) | "scifi" (Outpost) | your own
ghost = "blueprint", -- "hologram" | "tint" | "wireframe" | "blueprint" | your own
menu = "catalogue", -- "hotbar" | "radial" | "catalogue"
snap = "grid", -- "grid" | "surface" | "socket"
size = { 40, 30, 40 }, -- the build area (x, height, z), centred on `position`
position = { 0, 0, 20 },
}
```
Every name also answers to its aliases (`"Outpost"`, `"wheel"`, `"outline"`, `"piece to piece"`, ...); an unknown name is an error that lists the valid ones. Several zones can sit side by side, each with its own settings; a player builds by the rules of the zone they aim into. Players can switch style (**T**), snap mode (**G**) and, where the world allows it, ghost look (**V**) themselves; a zone turns that off with `allowStyleSwitch = false` / `allowSnapSwitch = false`.
All `BuildMode` options: `label`, `style`, `ghost`, `menu`, `snap`, `size` (or `sizeX`, `sizeY`, `sizeZ`), `cell` (grid cell, default 3 m), `free` (no cost), `costScale`, `refund` (0-1, default 0.5), `removeAnyone` (default: only the builder takes a piece down), `pieces` (list of kinds allowed), `styles` (list of styles allowed), `allowStyleSwitch`, `allowSnapSwitch`, `maxSlope` (degrees, default 35), `showBounds` (mark the edges on the ground while building), `order` (which zone wins where two overlap), plus `name`, `position`, `yaw`.
Kit-wide defaults go in `Build.setup` from code that runs in play (a scene's `entrypoint.luau`):
```lua
local Build = require("buildPlaceKit.api")
function onLoad()
Build.setup({
style = "rustic", ghost = "hologram", menu = "hotbar", snap = "socket",
refund = 0.5, removeAnyone = false, persist = true,
startCoins = 500, -- what a new wallet starts with (economyKit currency "coins")
wallet = "corner", -- economyKit wallet display; economy = false leaves economyKit's setup to you
allowGhostSwitch = true, -- V cycles the ghost look
inventory = false, -- true keeps inventoryKit's bag (strip, Tab/I, touch button), which economyKit starts
})
end
```
## Languages
Every word a player reads (the build panel, the menus, the touch buttons, the hints, piece, style, look, menu and snap-mode names and descriptions, prices, and every refusal) comes in **English** and **Brazilian Portuguese**, the languages of economyKit and gridKit. Each player reads the kit in their own language (`i18n.pick` over the kit's languages), and refusals travel from the deciding machine as codes, so two players in different languages each read the reason in theirs.
To change a line or add a language, put a catalog in your world, `/locales/<tag>/buildplacekit.json`, with any of the kit's keys (`buildPlaceKit.lang` lists them all in `Lang.WORDS.en`):
```json
{ "place": "Build {{ piece }} for {{ cost }}", "piece_wall_name": "Palisade" }
```
or from code: `require("buildPlaceKit.lang").define("es", { place = "Colocar {{ piece }} {{ cost }}", ... })`. A piece, style or look you add yourself reads `piece_<id>_name` / `_desc` (`style_`, `ghost_`, `menu_`, `snap_`) the same way, and shows the name you gave it until a catalog names it.
## Controls
| | keyboard and mouse | gamepad | touch |
|---|---|---|---|
| build mode on / off | **B** | **Y** | **Build** button |
| place | left click | **RT** | tap the world to aim, then **Place** |
| rotate | **R** | **RB** | **Rotate** |
| pick a piece | wheel, **1-0**, **[ ]** | d-pad left / right | tap it in the menu |
| menu (catalogue, wheel, next hotbar page) | **Tab** or **Q** (hold for the wheel) | **LB** (hold for the wheel) | **Menu** |
| demolish (take down, part refund) | **X**, then click | d-pad down | **Demolish** |
| snap mode | **G** | d-pad up | **Snap** |
| style | **T** | in the catalogue | in the catalogue |
| ghost look | **V** (when allowed) | | |
| open doors, gates, chests | **E** | **X** | |
| close menu / leave build mode | **Esc** | **B** | **Exit** |
On a touch screen the kit reads where the engine draws its own buttons (Sprint, Interact, Jump, and any a game adds) every frame and keeps clear of them: its own buttons stand on top of that column, or beside it on a screen too short to stack them, and the piece strip and hotbar stop short of it. Checked on a wide touch screen (1920 × 1080), a phone held sideways (1688 × 780) and upright (780 × 1688).
A game that lays out its own HUD can put the Build button where it wants it: `Build.setTouchAnchor({ left = 294, top = 272 })` (screen points from the screen's left and top edges; or `Build.setup({ touchAnchor = { left, top } })`). It applies to the Build button while build mode is closed; `Build.setTouchAnchor(nil)` goes back to the kit's own placement. farmLifeKit uses it to keep Build clear of the engine's menu button on phones (1.0.24).
While the catalogue or the wheel is open, walking and the camera stand down (the `buildPlaceKit.buildBlock` input map) and the mouse is freed, so pointing at the menu never turns the view.
## Catalogue
`Build.catalogue()` returns every entry below as `{ kind, setting, id, name, description, tags }`; `Build.variants{ kind = "piece", category = "roof" }` filters it.
### Pieces (`Build.select("wall")`, or `pieces = { ... }` on a zone)
Sizes are in metres (width × height × depth). One cell is 3 m, one storey 3 m. Prices are coins in the Frontier style; the Outpost style costs 1.5 times as much.
| id | name | category | size | price | snaps onto |
|---|---|---|---|---|---|
| `foundation` | Foundation | foundation | 3 × 0.45 × 3 | 20 | the ground; other foundations' edges |
| `floor` | Floor | floor | 3 × 0.25 × 3 | 10 | the ground; slab edges; wall tops (upper storey) |
| `wall` | Wall | wall | 3 × 3 × 0.25 | 15 | slab edges; wall tops; beside walls |
| `wallWindow` | Window Wall | wall | 3 × 3 × 0.25 | 18 | as a wall |
| `wallDoorway` | Doorway Wall | wall | 3 × 3 × 0.25 | 16 | as a wall; takes a Door |
| `door` | Door | door | 1.3 × 2.3 × 0.12 | 12 | a doorway only; opens with Interact |
| `wallHalf` | Half Wall | wall | 3 × 1.5 × 0.25 | 8 | as a wall |
| `roofFlat` | Flat Roof | roof | 3 × 0.25 × 3 | 12 | wall tops; slab edges; walls stand on it |
| `roofSlope` | Sloped Roof | roof | 3 × 1.5 × 3 | 14 | wall tops (rising inward); another slope (peak or higher course); beside a slope |
| `roofCorner` | Roof Corner | roof | 3 × 1.5 × 3 | 14 | wall tops; beside slopes |
| `stairs` | Stairs | stairs | 2.4 × 3 × 3 | 20 | on a slab; out from a slab edge; the ground |
| `ramp` | Ramp | stairs | 3 × 1.5 × 3 | 15 | on a slab; out from a slab edge; the ground |
| `ladder` | Ladder | stairs | 0.7 × 3 × 0.15 | 6 | a wall face |
| `pillar` | Pillar | wall | 0.4 × 3 × 0.4 | 5 | slab corners; the ground |
| `fence` | Fence | defense | 3 × 1.1 × 0.12 | 6 | the ground; slab edges; beside fences |
| `gate` | Gate | defense | 3 × 1.4 × 0.15 | 14 | as a fence; opens with Interact |
| `barricade` | Barricade | defense | 3 × 1.4 × 1.2 | 10 | the ground; slabs; slab edges |
| `towerBase` | Tower Base | foundation | 3 × 3 × 3 | 40 | the ground; floors and walls click onto its deck |
| `campfire` | Campfire | utility | 1.3 × 0.9 × 1.3 | 8 | the ground; slabs; lit, flickering light |
| `chest` | Storage Chest | utility | 1.1 × 0.75 × 0.65 | 12 | the ground; slabs; lid opens with Interact |
| `torch` | Torch | utility | 0.3 × 1.7 × 0.3 | 3 | the ground; slabs; wall faces; lit |
| `workbench` | Workbench | utility | 2 × 0.95 × 0.9 | 18 | the ground; slabs |
| `bed` | Bed | utility | 1.1 × 0.7 × 2.1 | 16 | the ground; slabs |
| `banner` | Banner | utility | 1 × 3.2 × 0.2 | 7 | the ground; slabs |
### Styles (`style`)
| id | name | what it looks like | price |
|---|---|---|---|
| `rustic` | Frontier | oak-bark log frames, oak boards and planks, dry-stone footings, golden thatch, iron straps, warm firelight | × 1 |
| `scifi` | Outpost | gunmetal and light hull panels, deck plating, carbon, hazard stripes, cyan light strips and energy cores | × 1.5 |
### Ghost looks (`ghost`)
| id | also | what it looks like |
|---|---|---|
| `hologram` | holo, glow | a glowing see-through hologram with a bright rim that breathes (default) |
| `tint` | plain, transparent | the piece washed green or red, half see-through |
| `wireframe` | outline, lines, edges | edges only: clearly green where the piece fits, red where it does not |
| `blueprint` | plan, schematic | drafting blue, coloured edges and a grid on the ground |
Every look is green where the piece fits and red where it does not; a refused click also jolts the ghost sideways.
### Build menus (`menu`)
| id | also | what it is |
|---|---|---|
| `hotbar` | strip, bar | a strip of pieces along the bottom; number keys, scroll or tap; Tab pages through categories (default) |
| `radial` | wheel, pie | hold Tab / LB for a wheel of categories and pieces; point and release |
| `catalogue` | grid, shop, store | a full catalogue with pictures, prices, refunds, the style switch and your wallet |
### Snap modes (`snap`)
| id | also | how pieces land |
|---|---|---|
| `grid` | cells, tiles | slabs on cell centres, walls on cell edges (turned along the edge you aim nearest), posts and torches on corners, on whatever surface is under the cell (walls on a floor's edge stand on the floor); roofs rest on the wall tops around their cell; cells come from gridKit's square grid |
| `surface` | free, anywhere | exactly where you aim, on whatever is there: on open ground turned to face you in 15° steps, on a placed piece squared up with it; aimed right at a matching edge or wall top (within 0.7 m) it clicks on, so floors, walls and roofs still meet; torches and ladders aimed at a wall hang on it |
| `socket` | piece to piece, snap | onto the nearest matching socket of a placed piece within 1.8 m (default); with nothing near, ground pieces sit on the surface |
In every mode:
- **Torches and ladders hang where you aim on a wall:** a placed wall, or any solid surface of the world (a scene's wall, a rock face). A torch also stands on the ground or a floor.
- **Roofs follow the wall top you aim at.** Aimed at a wall top, or just past it so the aim lands on the ground behind, a roof rests on that wall top, over the floor side first (Rotate puts it on the other side). A roof never sits at floor level beside a floor.
- **Gentle slopes are fine.** Pieces stay level, so on a slope a piece dips into the ground at its low side; ground up to `maxSlope` (35° by default) takes any piece.
## Refusals
A red ghost names why, and a click there is refused with that reason and nothing is built or charged:
| code | text |
|---|---|
| `overlap` | Something is already built there |
| `player` | Someone is standing there |
| `floating` | Needs something to rest on |
| `slope` | The ground is too steep |
| `outside` | Outside the build area |
| `blocked` | Something is in the way (scenery that is not a piece, and not the ground or slope the piece stands on) |
| `needsSocket` | Needs a doorway to fit into (doors) |
| `cost` | Not enough Coins: you need 12 more |
| `tooFar` | Too far away |
| `notYours` | Someone else built this (taking down) |
## Events
```lua
local Build = require("buildPlaceKit.api")
local stop = Build.on("placed", function(e) print("built", e.kind, e.id) end)
Build.on("refused", function(e) print("refused", e.code, e.text) end)
Build.on("fx", function(e) print(e.what, e.kind, "by peer", e.peer) end) -- every change, on every machine
stop()
```
Events: `placed`, `refused`, `removed` (this player's requests), `pieceAdded`, `pieceRemoved` (any piece on this machine), `buildOpened`, `buildClosed`, `message`, `fx` (every placement, removal and door from the deciding machine), `restored`, `rejected`.
## Your own pieces, styles and ghost looks
```lua
local Build = require("buildPlaceKit.api")
-- a piece: size, price and how it snaps; its look is drawn by the style
Build.definePiece("well", {
name = "Well", category = "utility", size = { 2, 1.2, 2 }, cost = { coins = 25 },
description = "A stone well.",
})
-- a style: borrow the shapes of a flavor ("timber" or "panel") and give each surface role a material
Build.defineStyle("desert", {
name = "Desert", flavor = "timber", costScale = 1.2,
materials = {
plank = asset.resolve("masonryMaterials.materials.stucco", "material"),
roof = asset.resolve("masonryMaterials.materials.roofClayPantiles", "material"),
cloth = { color = { 0.85, 0.55, 0.2 }, rough = 0.9 },
},
})
-- a ghost look: build(ghost, parts, kind) spawns under ghost.root, color(ghost, valid) recolours
Build.defineGhost("sketch", {
name = "Sketch",
build = function(ghost, parts, kind) --[[ spawn entities under ghost.root ]] end,
color = function(ghost, valid) end,
})
```
Material roles: `frame`, `plank`, `floor`, `stone`, `roof`, `metal`, `accent`, `trim` (emissive), `glass`, `cloth`, `fire`. A role is a material handle (always write `asset.resolve("…", "material")` with a literal name: `zm push` refuses computed asset names) or a colour spec `{ color, rough, metal, glow, alpha }`. A role a style leaves out is borrowed from `rustic` (or `base = "<style>"`).
A piece kind's full shape, for snapping your own kinds to the built-in ones: `boxes` (what it blocks, `{ c = centre, s = size, pitch? }`), `support` (points that must rest on something), `sockets` (`{ tag, p, yaw }` it offers) and `plugs` (`{ tag, p, yaw }` it attaches with). Socket tags in use: `floorEdge`, `floorTop`, `floorCorner`, `wallTop`, `wallSide`, `wallFace`, `doorway`, `roofTop`, `roofSide`, `pillarTop`, `fenceSide`. See `buildPlaceKit.catalog`.
## Pieces the scene places
```lua
-- inside content(): a real piece (doors open, fires burn, players snap to it) that cannot be taken down
Build.piece { kind = "campfire", style = "rustic", position = { 4, 0, 6 }, yaw = 0 }
```
## Reference
`local Build = require("buildPlaceKit.api")`
- Scene: `BuildMode(opts)`, `piece(opts)`.
- Setup: `setup(opts)`, `definePiece`, `defineStyle`, `defineGhost`, `catalogue()`, `variants(filter)`.
- This player: `open()`, `close()`, `toggle()`, `isOpen()`, `select(kind)`, `setStyle`, `setSnap`, `setGhost`, `setMenu`, `state()`.
- Requests (answered by the deciding machine, `cb(res)` with `{ ok, code, text, id, costs, refund }`): `place(kind, style, position, yawDegrees, cb)`, `remove(pieceId, cb)`, `toggleOpen(pieceId, cb)`, `setLit(pieceId, on, cb)` (a fire or torch burns or goes cold: no flame, no light).
- Reading: `check(kind, position, yawDegrees)` → `ok, code, text`; `pieces()`; `stats()`; `clearSaved()`.
- Modules for advanced use: `buildPlaceKit.catalog` (data), `.snap` (where a piece goes), `.rules` (whether it fits), `.geom` (oriented boxes), `.art` (how pieces look), `.ghost`, `.menus`, `.fx`, `.sfx`, `.authority`, `.registry`.
- Components: **BuildMode** (a zone), **BuildPiece** (one placed piece; put there by the deciding machine or by `Build.piece`; its synced `lit` field is whether a fire or torch burns).
## How it stays fair in multiplayer
- **One machine decides.** The machine running economyKit's bank (the lowest peer in the room) decides every placement, removal and door. A player's machine only sends a request; the deciding machine checks it against its own copy of the world with the same rules the ghost uses, takes the price from the wallet through the bank, and only then builds the piece. Two players clicking the same spot in the same moment are decided one after the other, so the second gets "Something is already built there" and pays nothing.
- **Pieces are synced entities** the deciding machine owns, so every player sees them and a player who joins later receives them all. Each machine draws a piece's look and colliders itself from its kind and style, so a piece costs one small synced record on the wire.
- **No free pieces.** Money moves only through the bank (economyKit's rules apply: balances written by hand are put back). A piece entity some other machine spawns without asking is not vouched for by the deciding machine: it is refused and every machine hides it.
- **Wallets and the bank restart on every Play.** After Stop and Play the kit starts economyKit's bank and every player's wallet again (a player's coins are kept by economyKit), so the wallet shows, coins on the ground pay, and a second player who joins after the host restarted gets a ready wallet with their starting coins.
- **Kept between sessions.** The deciding machine writes each piece to the world's runtime data and puts them back at the start of every play session: after Stop and Play, after reopening the world, and beside any pieces the scene places itself (`persist = false` turns that off; `Build.clearSaved()` forgets them).
## Performance
Each piece is 4-14 instanced parts and 1-5 box colliders, built locally, with nothing per frame unless it burns or swings. Fires and torches share a light budget (the nearest 8 are lit; `require("buildPlaceKit.art").lightBudget(4)` for phones). The ghost is one set of parts recoloured in place. Overlap checks only compare pieces within a few metres.
## Tests
The `buildPlaceKit` suite (22 tests): Stop letting the next Play set economyKit up again, inventoryKit's keys standing down while its bag is off, saved pieces coming back on every Play (also on the second Play of one engine session, and beside the scene's own pieces), the first Tab paging the hotbar, building on a 12° slope (and a 48° rock refused), torches and ladders hanging on world walls, a torch on a built wall under a roof, a roof aimed past a wall top landing on the walls in all three modes, both languages complete, the catalogue, every kind drawn in every style, prices and refunds, grid cells/edges/corners, grid walls on a floor and a roof on the walls, surface placement and wall mounts, a surface-mode hut (free floor, walls clicking onto its edges, roof on the wall tops), placed pieces keeping their colliders, a piece-to-piece hut (walls on floor edges and at a corner, a second floor, a roof on a wall top and at the peak, a door in a doorway, stairs), every refusal, the deciding machine (one spot, one piece; only the builder takes it down; a forged piece refused), your own piece and style, and this README's first example. Run it in edit mode with `tools.use("tests", "run", { suite = "buildPlaceKit" })` (a suite is picked by its `.testSuite` asset name).
1.0.33: gamepad building works with a follow camera: the ghost stands ahead of the player along the view, far enough for the piece to clear them (the screen's centre was the player, so it sat at their feet); turning the camera with the right stick swings it round, and RT places even when the mouse was left over a panel. On touch screens the current-piece chip shares one layout with the build buttons and never sits under them: it stops short of them, or rises above them where the screen is narrow, and shows just the piece (the Pieces button opens the menu).
1.0.35: fires and torches can go out. `Build.setLit(pieceId, on)` asks the deciding machine to light a fire or torch piece or put it out, and the piece's synced `lit` field draws it cold when it is out: no flame, no light, nothing that reads as hot to heatSignatures. A survival game's fuel rules decide when (Castaway Isle's campfires kept their flames and light after running out of fuel).
1.0.34: installs load as one kit: every part of buildPlaceKit is published against this same release, so an installed copy no longer runs some of its parts at an older version beside the rest (a fresh install could register its build zones where the build menu never saw them, and say "Nothing to build here" everywhere).
1.0.32: a piece the game's `allow` rule refuses (asked ahead with no builder and no spot) looks locked in every build menu: dimmed, a padlock and the rule's reason ("School unlocks when your town becomes a Town") on catalogue cards, the detail pane and the radial centre, a padlock and "Locked" on hotbar slots and radial items; `menuState().locked` lists them. The key hints panel stands clear of the current-piece chip and the hotbar, so its last line is never under them. The test suite checks the kit's own pieces and categories, so another kit adding free art pieces or its own categories no longer fails it.
1.0.31: touch buttons (Build, Place, Rotate, Exit ...) work wherever the game view sits in the window. A tap was mapped to the UI by dividing by the pixel ratio alone, so in the editor (and any view not at the window's top-left) every tap missed; it now goes through `ui.fromViewport`, as the mouse-over-menu test does too.
1.0.30: a draw that fails (often because a module it needs is still loading on a cold start) is no longer cached, so the next draw of that piece tries again instead of showing the generic block until the kind is redefined.
1.0.29: a scene piece whose kind was still unknown when it loaded (it drew nothing and warned "unknown kind") is drawn once the game defines that kind; 1.0.28 only redrew pieces that had already drawn.
1.0.28: a piece whose kind a game defines (or redefines) after the scene's pieces loaded is redrawn with the new definition. Before, a scene that placed a game's own piece drew it as a generic block until the next load, because the parts cache never saw the later `definePiece`. `definePiece` now stamps each definition with a revision the parts cache keys on, and `Catalog.onDefine(fn)` tells every standing BuildPiece of that kind to redraw.
1.0.27: a game's own pieces bring their own art and rules. `definePiece(id, { draw = function(b, styleId) ... end })` draws the piece (ghost and placed piece) with the kit's part builder (`b.box`, `b.cyl`, `b.sphere`, `b.cone`, `b.logX`, `b.strut` ...) instead of a generic block; a part may carry `spec = { color, rough, metal, glow, alpha }` for a colour no surface role covers (water, leaves, flowers). `Build.setup({ allow = function(kind, style, builderKey, position) return ok, reason end })` lets a game refuse pieces the deciding machine would otherwise place (a building unlocked by a rank, a quest or a tech tree); a refusal arrives as `notAllowed` with the game's reason. Nothing changes for worlds that use neither.
1.0.26: built on economyKit 1.2.11. Before, the kit reached economyKit through single module copies of an older release that, outside their package, could not find each other, so build mode failed to load in a world on economyKit 1.2.11.
1.0.25: the art and language tests check the kit's own pieces only (`Catalog.BUILTIN_KIND_IDS`), so they pass in a world where another kit (productionKit, a game's `definePiece`) adds pieces with their own words and art. 1.0.24 adds `touchAnchor` / `Build.setTouchAnchor` for the touch Build button.
1.0.23 changes no code of its own: economyKit 1.1.4 is installed cleanly from ZeroMind underneath it. 1.0.21 and 1.0.22 were published from a hand-patched copy of economyKit, which landed economyKit's `economy` module at two releases side by side in a new world, and the odd copy failed to load.
1.0.22 changes no code of its own: it is built on the current engine library (@builtin 034765f). On the older one, a kit buildPlaceKit brings could not find `@builtin::modules.frameDriver`, so BuildMode failed to load in worlds on a current engine.
1.0.21 changes no code of its own: it is built on economyKit 1.1.4 (the bank comes up even after a failed load, and a game can name the bank's machine), with every installed kit byte-identical to a published release, so a fresh install resolves.
1.0.20 changes no code of its own: it is built on economyKit 1.1.3, so every economyKit reference it publishes names a released economyKit (1.0.19 named a Market Square commit whose economyKit no release holds, and kits that depend on buildPlaceKit failed to install with VERSION_NOT_FOUND).
1.0.19 changes no code of its own: it is built on economyKit 1.1.2 (and through it inventoryKit 1.0.10, pickupsKit 2.3.8 and saveKit 1.3.2), the current gridKit and @builtin a9870f6. The economyKit and pickupsKit that 1.0.18 brought named their own modules by `/source/...` and `@root::` paths that exist only in their home worlds, so a world that got buildPlaceKit as a dependency (under `deps/`) failed to load it.
Each release is also installed from ZeroMind into a brand new world, the way anyone installs it, and checked there. 1.0.15 changed only the deciding-machine test (its made-up players now take peer ids above every peer in the session, so a real player can never share one) 1.0.16 only these texts, 1.0.17 only how `package.yaml` writes its description (on one line, so the current engine installs it; #22402) and these texts, and 1.0.18 only the wording of that description (what the kit gives you and how to install it), so the play checks of 1.0.14 still hold: the four kits of the example guide installed, the world reopened once, the guide's code pasted, then a wallet of 30, a coin paying 5, no bag strip over the hotbar, **G** switching to Grid, and on the second Play the bank up, the wallet kept and coins paying. Earlier, the 1.0.9 release candidate was checked in depth: one install of the package (7,676 files in 7 s), this README's first example added word for word to `scenes/main.scene/build.luau`, the test suite passing 18 of 18 twice there (and twice in this world), and in play with real mouse aim and clicks: a floor, two walls and a roof built in each of the three snap modes (grid walls on two cell edges and the roof on their tops; piece-to-piece walls on the floor's edge sockets; surface walls clicking onto the edges of a floor turned to face the camera), a foundation aimed at the player's own feet shown red with *Someone is standing there* and its click refused, a 60-coin Outpost tower base with 40 in the wallet shown red with *Not enough Coins: you need 20 more*, refused and charging nothing, and every placed piece a synced entity owned by the deciding machine. The example guide's game was built in that world from its steps too. The 1.0.17 release candidate (1.0.17-rc1, the same files with only the version number different) was installed into a brand new world on the current engine in one step (7,676 files) and passed 22 of 22 twice there.
## Known limits
- **#19525: a Text3D label rasterised at `scale` 2 has the tops of its letters cut off.** The showcase's big headers (FRONTIER STYLE, OUTPOST STYLE, RAISE THE ROOF) showed it. The showcase now draws its signs at `scale = 1`, which shows whole letters; if you put up your own signs, do the same until the engine fixes it. The kit itself draws no Text3D labels.
- **#22121: a fresh install of economyKit can leave inventoryKit's parts failing to load** ("module 'inventoryKit.items' not found", or "module `~.items` ... has no root to resolve against"). It comes from the install of economyKit's own dependencies, not from this kit. In fresh worlds checked for earlier releases those lines stayed in the log for the whole session, and building, prices, refunds and coins all worked; if the kit's BuildMode or BuildPiece components say they are waiting for content, a scene reload (or reopening the world) brings them up.
- **Showcase signs are English.** The kit itself speaks English and Brazilian Portuguese; the signs and painted words of this showcase world are scenery and are not translated.
- **No structural collapse.** Taking down a wall leaves the roof on it standing; pieces do not fall.
- **Ladders do not carry you up by themselves.** The default character controller has no climb state: walk into a ladder and jump, or use stairs and ramps (they are walkable).
- **The storage chest opens and shuts but holds no items.** Pair it with inventoryKit (already installed with economyKit) if your game needs storage.
- **The deciding machine is a player's machine**, as with economyKit's bank: a player alone in a world is their own decider, so a modified client playing alone can build for free.
- **#14448**: two engines signed in to one account collide as one player, so a real two-player race for one spot could not be run by the author; it is covered by the tests (two requests through the deciding machine), and every placed piece was checked to be a synced entity the deciding machine owns. A second player on another account sees the same pieces.
- **#20750**: the web build's frame rate drops in busy scenes; keep large bases to a few hundred pieces and lower the light budget on phones.
- **#20946**: this kit was checked in the desktop engine; the browser build was not run by its author.
- **#21420**: an install with several dependencies can be slow: economyKit brings several kits and the styles bring four material collections. A fresh-world install of the package alone has taken 7 s; a first install on a slow connection can take about a minute.
- **#19849**: some ZeroMind calls (install, preview) can take a long time to answer.
- **#19258**: the ZeroMind search description can lag a release.
- **#22328: right after installing, the wallet can fail to start.** No wallet shows and build mode refuses every piece with "Not enough Coins: you need 20 more", and Stop and Play does not clear it. Close the world and open it again once after the install; everything then works and it does not come back. It shows most after installing several kits in a row, as the example guide does, and often follows a log line `package collision: 'economyKit' already registered at /zero/source/deps/...` while the install moves buildPlaceKit's copy of a kit to the world's top level.
- **#22402: on the current engine, a package whose `package.yaml` writes its description as a folded block is refused at install.** You see the install fail with "... is not installed, because it does not run: 1 installed asset(s) do not load as their type: ... package.yaml is not valid YAML: yaml: line 3: block-scalar indicators (chomping/indentation) are not supported", and the world keeps nothing of the install. buildPlaceKit 1.0.16 and older are refused this way; 1.0.17 writes its description on one line and installs. economyKit 1.0.13 and juiceKit 1.2.8 are still refused when you install them on their own, so the example guide's step of installing them by name fails today; they arrive and run inside buildPlaceKit's own install all the same, and gridKit installs as usual.
# buildPlaceKit.menus
Every on-screen part of build mode: the piece **hotbar** (category tabs, number keys, paging), the **radial wheel** (categories inside, pieces outside, centre readout), the **catalogue** (category tabs, piece cards with art, detail pane with price/refund/footprint, Frontier/Outpost style switch, snap-mode switch, wallet), plus the status panel (piece, style, snap, ghost, a green "Click to place" line with its price or the red reason), the demolish banner, control hints for keyboard/gamepad, message toasts that slide in and fade (refused ones shake red), big thumb buttons for touch (Build, Place, Rotate, Demolish, Menu, Snap, Exit) and the small "B Build" chip. Rustic pieces get warm amber panels and sci-fi pieces get cyan, following `state.style`.
The build controller calls `Menus.render(state, actions)` every frame. A screen is rebuilt only when what it shows changes. Clicks and finger taps call `actions.select/setCategory/setStyle/setSnap/closeMenus/page/place/rotate/toggleDemolish/toggleBuild/openMenu/cycleSnap`. `Menus.isPointerOverMenu(x, y)` tells whether a window point (device pixels) is on a menu, so a click on a menu does not also place a piece. `Menus.radialLayout(state)`, `Menus.radialPick(state)`, `Menus.radialIndexAt(n, ax, ay)` and `Menus.hotbarLayout(state)` let the controller map stick/keys to pieces. `Menus.hide()` and `Menus.unregister()` take everything down. `Menus._sampleState(menu, device)` builds a preview state, and `state.viewport = { width, height, safe }` lays the UI out as a phone would on a desktop screen. Piece pictures come from `buildPlaceKit.art` (`Art.icon`) when present, or from `Menus.setIconSource(fn)`, with a drawn category glyph as the fallback.
# townKit.icons
A picture of every town building (house plot, well, clinic, tavern, school, temple, watchtower, flower bed, tree grove, lamp post, park, fountain, gazebo, statue, clock tower, monument) and every productionKit building a town ladder unlocks (farm, lumber mill, bakery, market, sawmill, mine, smelter, warehouse), in the `rustic` and `scifi` looks. Each is a 256 px texture in `townKit.package/icons`, rendered from the building's own model.
`Town.install` hands them to buildPlaceKit's build menus through `Menus.setIconSource(Town.icon)`, so the catalogue cards, the build bar and the touch bar show the building instead of a category glyph. `Town.icon(kindId, look)` reads this table (`<look>_<kind with dots as underscores>`, falling back to the rustic picture); pieces of other kits keep buildPlaceKit's own pictures.
Every texture is named literally, one line each, so a published copy of townKit pins each picture. A world that adds a building of its own can add a texture and a line here, or leave it to buildPlaceKit's glyph.
# api
The one interface to buildPlaceKit: `local Build = require("buildPlaceKit.api")`. `Build.BuildMode{}` makes a build zone (one line gives a working build mode), `Build.piece{}` places scenery pieces, `Build.setup{}` sets kit-wide defaults and the economy, `Build.on` listens to events, `Build.definePiece` / `defineStyle` / `defineGhost` add content, `Build.catalogue()` / `variants()` list every piece, style, ghost look, menu and snap mode, and `place` / `remove` / `toggleOpen` / `check` drive the kit from code. Games call it from `build.luau` and from scripts that run in play.
# townKit.displays
What players read, as pure UI tree builders: six town status displays (banner, card, ledger, minimal, pixel, hologram) with barsKit happiness meters, five on-screen home moods (faces, hearts, thumbs, pixel emotes, sci-fi symbols) plus the roof-colour tint, the welcome-back screen, the rank-up celebration and the card for the home you stand by.
# townKit.ladders
The town ladders: medieval (Hamlet, Village, Town, City, Capital), scifi (Outpost to Capital World, with sci-fi names for every building) and cozyHamlet (a short, gentle climb). Each rank names the people and happiness it needs, an income bonus and what it unlocks; `unlockLadderFor` builds the matching unlockLadder ladder. Add your own with `define`.
# env
The live world as the placement rules read it on this machine: placed pieces near a point, a downward height probe that knows pieces from ground, a test for scenery in the way (ignoring pieces and players), every player's feet, and the build zones. `buildPlaceKit.controller` and `buildPlaceKit.authority` hand it to `buildPlaceKit.rules`; tests replace it with a flat stand-in.
# townKit.rules
Happiness rule sets, one setting each: relaxed, classic, strict and pure idle. A rule set weighs each need, sets the happiness people move in at and leave below, how fast they come and go, how much taxes hurt, what counts as covered, how long a home keeps a tier it can no longer support and how offline time is caught up. Also the five tax levels.
# townKit.starters
Ready-made places to grow a town: forestClearing, riversideMarket, hilltopTerraces and scifiColony. Each builds its ground and scenery inside a scene's content(), places the first well and house plot, and says its look, ladder, starting coins, build zone and spawn. Called by `Town.starter`; add your own with `define`.
# buildPlaceKit.art
What every piece kind looks like in every style. `Art.parts(kind, style)` returns the look as plain data (mesh, material role, placement in piece space, `moving` for door/gate/lid leaves, `fx` for flames), so ghosts and previews redraw it with their own materials.
`Art.spawn(parent, kind, style, opts)` builds it as temporary child entities, with boxes and logs on runtime meshes whose UVs are laid out in metres, so wood, stone and hull panels show at real-world size on any beam or panel.
Two flavors: `timber` (log posts, beams, plank infill, dry-stone footings, thatch) and `panel` (bevelled hull panels, deck plating, hazard stripes, glowing cyan trim).
`Art.setOpen` swings the door, gate and chest pivots, `Art.tick` flickers flames and lights, and `Art.lightBudget(n)` keeps only the n piece lights nearest the camera burning, so a base with fifty torches stays cheap.
`Art.icon(kind, style)` returns the 256 px menu picture rendered for each kind and style (`icons/<style>_<kind>.png`).
# townKit.catalog
What a town is made of, as data: the needs homes can be supplied with (water, health, fun, education, faith, safety, beauty, bread, jobs), the house tiers a plot climbs with their capacity, wealth and needs, the services and decorations with the rangeKit areas they cover, and the workers each productionKit building needs. `defineKind`, `defineTier` and `defineNeed` add your own.
# townKit.art
How every town building is drawn: draw functions for each house tier (plot, hut, cottage, townhouse, manor; landing pad to arcology in the sci-fi look) and each service and decoration, written against buildPlaceKit's part builder (box, cyl, sphere, cone, strut) with its surface roles plus colour specs for water, leaves, flowers, plaster and roof tiles. townKit.town registers them with buildPlaceKit; add your own with `Art.define(id, fn)` or a kind's `draw` field.
# Town
Runs a townKit town on every machine in play: the works on economyKit's bank machine, coverage sources, homes drawn by tier, the status display, moods over homes, the coverage overlay, the range preview while placing, welcome-back and rank-up screens. `Town.starter(...)` in a scene's `build.luau` places it; every field (starter, ladder, rules, status, mood, look, overlay, name) is one setting that swaps that part.
# townKit: city builder and idle town kit
**Grow a town from an empty plot in a forest clearing to a capital city, in any multiplayer Zero world.** Place house plots and settlers move in when the town is a nice place to live, build a hut, and improve it to a cottage, a townhouse and a manor as wells, clinics, taverns, schools, temples, parks, fountains and statues cover their street. Happy towns pay more taxes; production chains (farms → bakeries → markets) sell for coins; the town climbs from hamlet to village, town, city and capital, each rank unlocking new buildings; and when you come back tomorrow a welcome-back screen tells you what your town earned and how it grew while you were away.
Version **1.1.7** (`Town.VERSION`).
townKit holds only what is special about city builders. Everything else is an installed kit, one copy of each. Installing townKit brings them all; the versions are the ones this release was built and tested with (`tests/thrivingTown` in the Thriving Town world checks them).
| Kit | Version | What townKit uses it for |
|---|---|---|
| **rangeKit** | 1.0.1 | every service and decoration covers the homes within its range (circle, square, diamond …, with falloff); the area shows while you place a building, and **O** shows any need's coverage over the whole town |
| **productionKit** | 1.4.0 | farms, lumber mills, bakeries, markets, warehouses …: production chains that sell for coins, the bread homes eat, offline catch-up for production, big idle numbers |
| **buildPlaceKit** | 1.0.34 | placing every building with a green/red ghost (press **B**), prices, refunds, pieces kept between sessions; its `draw` and `allow` hooks draw town buildings and lock them until the rank that unlocks them |
| **economyKit** | 1.2.11 | coins, wallets and the bank: the one machine that runs the town (arrives with productionKit) |
| **saveKit** | 1.3.10 | each player's last visit, for their own welcome-back screen (arrives with economyKit) |
| **unlockLadder** | 1.0.0 | runs the town's ranks: each rank is a step whose goal is "this many people at this happiness" and whose reward unlocks buildings and house tiers; its progress is kept in the shared town record, so every player sees one rank |
| **barsKit** | 1.4.6 | the happiness meters in every status display |
| **scoreKit** | 1.4.8 | a bonus on the leaderboard each time the town ranks up |
| **gridKit** | 1.0.13 | grid snapping under buildPlaceKit (arrives with buildPlaceKit) |
The showcase world adds the scenery and the look, which a town of your own can swap for anything:
| Kit | Version | Used for |
|---|---|---|
| **clearedForest** | 1.0.0 | the forest ringing the clearing, kept clear where the town grows |
| **forestKit** | 0.3.1 | the forest's trees, atmosphere and footsteps (arrives with clearedForest) |
| **worldClockKit** | 1.6.8 | the shared day and night clock |
| **styleKit** | 1.8.3 | the stackable art-style look |
| **toonBlocks** | 1.4.5 | the warm look's blocks (soft wrap light, warm fill, pencil line, vignette, grain) |
## Quick start (about five minutes)
1. **Install townKit** from ZeroMind into your world (ZeroMind panel → search "townKit" → Install, or `zero zeromind installAsset cf997c56-c911-4498-95e5-93e7b5733140`). It brings every kit above, about sixty parts in all, in about two minutes. Let it finish (the ZeroMind panel stops showing kits arriving) before step 3, so the scene is built with everything in place.
2. **Make an empty scene** to grow the town in: `zero scene create --startup main empty` (or New Scene → Empty in the editor).
3. **Put one line in it.** Replace everything in `scenes/main.scene/build.luau` with:
```lua
function content()
require("townKit.town").scene("forestClearing", { status = "ledger", mood = "faces", rules = "classic", welcome = "ledger" })
end
```
Then turn the scene's player on: `zero scene player spawns` (or Scene → Player → Spawns in the editor). The empty template starts as a scene nobody plays, and without this step Play shows nothing; with the town already in the scene, it keeps the town's own player and spawn and adds nothing.
`Town.scene` builds the starter town (the clearing, the forest around it, a first well, hut and flower bed), the sun and sky, and a player standing at the town's edge facing it. If the build ran while kits were still arriving, the town adds its build zone itself when you press Play (the log says so); save `build.luau` again to keep it in the scene. Already have a scene with its own light, sky and player? Use `Town.starter(...)` with the same options instead, take any ground of your own out from under the town, and put your spawn at the `spawn` it returns.
4. **Press Play**, then press **B** to build. Pick the **House Plot** and place it a few steps from the well, inside the well's ring (press **O** to see how far water reaches), then put a **Flower Bed** beside it. Settlers move in within seconds; stand beside a home to see its card (people, happiness and what it needs next). **=**/**−** change taxes.
Gamepad: the left stick walks (and moves the build cursor), **Y** builds, **RT** places, **B** closes, the d-pad left/right changes taxes, **d-pad up** upgrades the home you stand by, **View** shows coverage. Touch: the **Build** button and the buttons on the town banner.
## One setting each
| Family | Choices |
|---|---|
| Starter town (plot, layout, climate) | `forestClearing` (sunny beech clearing), `riversideMarket` (river and bridge, misty mornings), `hilltopTerraces` (stone terraces, autumn), `winterHollow` (snowy birch hollow by a frozen pond), `desertOasis` (spring-fed pool on a hot plain), `scifiColony` (landing deck, alien dust storms) |
| Town ladder | `short` (Hamlet → Town → Capital), `standard` / `medieval` (Hamlet → Village → Town → City → Capital), `long` (eight ranks up to Capital), `scifi` (Outpost → … → Capital World), `cozyHamlet` (four small ranks) |
| Happiness rules, gentle to demanding | `relaxed` (also `gentle`), `classic`, `strict`, `demanding`, and `idle` (nobody ever leaves) |
| Town info display | `ledger` (storybook parchment), `card` (clean modern), `cartoon`, `pixel`, `minimal`, `banner` (carved wood), `hologram` |
| How a home feels | `faces`, `colourRings` (a ring on the ground), `icons` (floating icon of what it misses most), `chimneySmoke` (white, grey or dark smoke), `hearts`, `thumbs`, `roofColour`, `pixelEmotes`, `scifiSymbols` |
| Welcome-back screen (productionKit's) | `ledger` (parchment report with a seal), `card`, `toast`, `chest` (treasure chest), `report` (report card with grades) |
| Coverage overlay | any rangeKit look: `heatTiles`, `rings`, `chalk`, `glow`, `pixel`, `hologram`, `runes`, `wash` |
Change them on the `townKit.Town` component, in `Town.starter(id, opts)`, or live with `Town.setStatus`, `Town.setMood`, `Town.setRules`, `Town.setOverlay`.
## Buildings
Homes: **House Plot** → Hut (3 people) → Cottage (6, needs water) → Townhouse (12, water, health, bread) → Manor (20, water, health, fun, education, faith, bread). Services: **Well** (water), **Clinic** (health), **Tavern** (fun), **School** (education), **Temple** (faith), **Watchtower** (safety). Decorations (beauty): **Flower Bed**, **Tree Grove**, **Lamp Post**, **Park**, **Fountain**, **Gazebo**, **Statue**, **Clock Tower**, **Grand Monument**. Every one is drawn in a rustic and a sci-fi look.
## Multiplayer, saving, offline
The town runs on its owner's machine. Each machine announces its account, whether the world lets it save, and the town owner it knows (the account that first saved the town); every machine then picks the same one to run the town, the bank, the buildings and the saved pieces: the owner's, else one that can save, else the room's host. Only the owner's machine writes the saved town, so a friend who can play but not edit builds and grows the same town through the owner's machine and never overwrites it. The running machine also sends the town to every machine, so everyone in the room (and anyone who joins late) sees the same homes, people, happiness and rank, even before their own copy of the world's saved data has arrived. The town is still there after the world restarts. When the works starts after nobody played, it catches the town up (up to the rule set's offline cap) and every member is paid what the town earned. Coins earned while you were away always reach your wallet: if it is not ready the moment you arrive, the town keeps them owed and pays them a moment later. The welcome-back screen shows after an absence of a minute or more, or whenever the town earned something for you while you were gone (20 seconds or more). It is one of productionKit's welcome-back screens (the `welcome` setting picks which), showing everything together: the time away, every coin earned (taxes and market sales), the goods made, and lines for the town (population and happiness before and after, homes that grew, a new rank, the share that came from taxes), compared with your own last visit (kept in your saveKit profile). Your time away is measured by the town's works from the last moment it saw you until your machine says hello.
## Guides
- `how-to-make-a-city-builder-or-idle-town-game`: how to make a city builder or idle town game with townKit.
- `example-add-a-new-building-and-a-new-upgrade-tier`: a worked example: a Bakery Stall service and a Mansion tier.
# townKit.sim
The town's rules as pure functions, shared by the works and the tests: each home's happiness from the coverage around it, bread, jobs and taxes; people moving in and out; homes climbing and losing tiers; workers and staffing; taxes; the town's rank; and catching up offline time to a cap.
# townKit.works
The one machine that runs the town (economyKit's bank machine): steps townKit.sim twice a second against the real homes, coverage, bread and jobs, pays taxes through economyKit (absent members are paid when they return), writes the town to the world's shared runtime data for every player and late joiner, catches up offline time on start and answers players' requests (hello, taxes, rename).
# view (productionKit)
What one machine sees of the works: `local View = require("productionKit.view")`. Every machine keeps a View of the town and building records it has read from the world's shared runtime data and when each arrived. `View.apply` takes a record as it arrives (from the store's change feed, a poll, or the works on that very machine) and returns what changed as events (made, status, jobDone, stockChanged); `View.poll` reads everything at once (a late joiner's first look); `View.building` moves a working building's progress on smoothly from when its record arrived, so every machine shows the same bar without a write per frame. Pure Luau with no engine state, so the tests run several machines side by side; `productionKit.production` keeps this machine's one.
# productionKit.text
Every word productionKit shows a player goes through this module, which reads it from the engine's translation catalogs (`i18n`) in the player's language, with the English as a fallback so a missing key never shows as a raw key.
The kit's own modules call it (catalog names, number words and rates, refusals, prompts, screens and displays). A game rarely needs it directly, but can use it the same way for text of its own:
```lua
local Text = require("productionKit.text")
Text.t("productionkit.reasons.missing", { resource = "Wood", need = "2" }, "Not enough {{ resource }}: you need {{ need }} more")
Text.key("lumberMill") -- "lumber_mill": a catalog-safe key part from an id
Text.townName("main") -- "Millbrook": the name a player reads for a town id
Text.revision() -- moves when the language or a catalog changes; include it in cache keys
Text.onChange(function(locale) ... end)
```
- `Text.t(key, values?, fallback)`: the text in the player's language with `{{ name }}` values filled in.
- `Text.live(key, values?, fallback)`: the same as a live value for a widget, which redraws by itself when the language changes.
- `Text.fill(s, values)`: fills `{{ name }}` placeholders in any string.
- `Text.townName(id)`: the name a player reads for a town id, never the id itself. A catalog key `productionkit_ui.town.names.<id>` in your world comes first, then the name the game gave the town (`setup{ townNames = { main = "Riverside" } }`), then the kit's own: `main` reads "Millbrook" (`productionkit_ui.town.default`), a player's own town (per-player towns) reads "Your Town" (`productionkit_ui.town.own`), and any other id is spelled out in words (`north_farm` reads "North Farm").
- `Text.NS` (`"productionkit"`) and `Text.UI` (`"productionkit_ui"`): the kit's two catalog namespaces, in `productionKit.package/locales/en/`.
To translate the kit, add `locales/<language>/productionkit.json` and `productionkit_ui.json` to your world with the same keys; to change one word, state its key in your world's `locales/en/` catalog.
# numbers (productionKit)
Big numbers the way idle and tycoon games write them. `local N = require("productionKit.numbers")`, then `N.format(1234567)` is `"1.2M"`, `N.rate(3.5)` is `"+3.5/s"` and `N.duration(7980)` is `"2h 13m"`. Five styles, switched by one setting (`N.setStyle("letters")` or `Production.setup{ numbers = "letters" }`): `short` (1.2K, 3.4M, 5.6B, 7.8T, 9.1Qa ... up to 1e303), `letters` (K, M, B, T, then aa, ab ... zz), `scientific` (1.23e15), `engineering` (12.3e15) and `words` (1.2 million). Pure Luau, no engine state, used by every productionKit display and screen.
# ProductionBuilding (productionKit)
One production building placed by a scene. `Production.building{ kind = "sawmill", look = "rustic", position = { 0, 0, 10 } }` in a scene's `build.luau` puts it on an entity, or add it to any entity by hand. Fields: `buildingId` (what its progress is kept under; keep it stable), `kind` (farm, lumberMill, mine, sawmill, smelter, bakery, market, house, warehouse, barracks, powerPlant, researchLab, or your own), `look` (rustic or scifi), `display` (ring, badge, float, minimal, none), `town`, `label`, `height`. Every machine registers it with productionKit, which draws its look and the display above it; the works' machine runs it. Changing `kind`, `look` or `display` is the only change needed to switch it.
# ProductionHost (productionKit)
productionKit's driver on one machine. The kit spawns it on a temporary local entity the first time a game uses it in play; never place it by hand. Each frame it runs the kit (follows economyKit's bank to pick the machine that runs the works, passes requests and answers, runs the buildings there), draws every building's look, animation and the display above it, turns buildPlaceKit pieces of production kinds into working buildings, draws the town's stock bar, the "[E] Training queue / [U] Upgrade" prompt near a building, the production queue panel and the welcome-back screen, and reads E, U and Escape through `productionKit.productionMap`. Needs no sibling components.
# sim (productionKit)
The rules of production as pure data in and data out: `local Sim = require("productionKit.sim")`. `Sim.step(works, dt)` advances every building (recipes that start by taking inputs and stop as "starved" when they cannot, or "full" when the town has no room for the output; queues that finish jobs in order; storage that raises limits) and returns what happened; `Sim.catchUp` runs a long stretch for offline earnings and sums it up; `Sim.enqueue` / `Sim.cancel` move a queue's goods; `Sim.cap`, `Sim.rates`, `Sim.cycleTime` read limits and speeds. Touches nothing in the engine, so the works, the tests and a game's own previews all run the same rules.
# productionKit.art
The 3D art for productionKit's twelve building kinds (farm, lumber mill, mine, sawmill, smelter, bakery, market, house, warehouse, barracks, power plant, research lab), each in a rustic timber look and a sci-fi industrial look, with moving parts that run only while the building works: windmill sails, water wheels, saw blades, drill heads, a spinning fusion ring, radar dishes, robot arms, conveyors, cranes, flickering forge and oven fires, glowing cores and chimney smoke or steam that rises, grows and fades.
It draws through buildPlaceKit's renderer: `Art.install()` hooks `buildPlaceKit.art.parts` and `.material`, so the piece kind `productionKit.<kind>` (the static body) is drawn by BuildPiece like any build piece, and `productionKit.<kind>#<group>` draws a moving group. Roles named `pk.*` are this module's own materials (golden wheat, grow lights, awning cloth, bricks, clay tiles, reactor glow).
Called by productionKit's building component and host: `Art.spawn(entity, kind, look, opts)` returns a handle (`opts.static = false` when BuildPiece already drew the body, `opts.size` for a kind with no art of its own, which gets a generic workshop), `Art.tick(handle, dt, t, working)` animates it, `Art.despawn(handle)` removes it, and `Art.roofHeight(kind)` says where a display floats. `Art.parts(kind, look, group)` and `Art.partCounts(look)` return the plain part data. A look other than rustic or scifi is drawn with the shapes of its buildPlaceKit style's flavor and that style's materials.
# production (productionKit)
The one interface a game uses: `local Production = require("productionKit.production")`. It sets the kit up (`setup`), places buildings in a scene (`building{ kind, look, position }`), reads stock, limits, rates and buildings as every machine sees them, gives each town the readable name players see (`townName`, set with `setup{ townNames = ... }`), sends queue, cancel, upgrade and pause requests to the works and reports the answers as events (`on`), switches a building's kind, look or display and the kit's number style, welcome-back screen and queue panel with one call each, registers every kind as a buildPlaceKit piece, formats big numbers and rates, and chooses which machine runs the works (the one running economyKit's bank). See the package README for every call.
# range (rangeKit)
The one interface a game uses: `local Range = require("rangeKit.range")`. It registers range sources (an aura, a coverage area, a supply range) in channels, answers deterministic queries about them (strength at a point combined by the channel's stack rule, the sources reaching a point strongest first, one source's cover, grid cells in range), defines custom shapes, falloffs, looks and channels, and draws local placement previews and channel or source overlays in eight looks through the `rangeOverlay` shader. Game code, the `RangeSource` component and UIs call it; see the package README for every call.