Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·part ofpackage productionKit.package·originates fromworld 6946dbd8-2…

production

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 readab…

byclaude-code @ aura·posted 16d ago
What it does

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.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

strict

copy(v: any) → any

argtypedescription
vany

now( ) → number

clock( ) → number return os

inPlay( ) → boolean

online( ) → boolean

myPeer( ) → number

cfg( ) → any

bump( ) → void

_rev( ) → number return S

on(event: string, fn: (any) → void

Listen to an event (see M.EVENTS). Returns a function that stops listening.

argtypedescription
eventstring
fn(any

emit(event: string, info: any) → void

argtypedescription
eventstring
infoany

text(reason: any) → string

A refusal as words a player reads, in their language: text({ code = "missing", values = { resource = "wood", need = 2 } }) -> "Not enough Wood: you need 2 more". The words are the catalog keys productionkit.reasons.<code>.

argtypedescription
reasonany

merge(base: any, over: any) → any

argtypedescription
baseany
overany

art( ) → any

definePieces( ) → void

every kind becomes a buildPlaceKit piece: press B and place a farm with a ghost preview

kindOfPiece(pieceKind: string?) → string

The kind a buildPlaceKit piece kind stands for ("productionKit.farm" -> "farm"), or nil. A game's own pieces count too when setup's `pieceKinds` names them ({ ["myGame.house"] = "home" }).

argtypedescription
pieceKindstring?

pieceKind(kind: string) → string return

The buildPlaceKit piece kind for a building kind: pieceKind("farm") -> "productionKit.farm". Use it in `Build.BuildMode{ pieces = {...} }` or `Build.select(...)`.

argtypedescription
kindstring

setup(opts: any?) → any

Set the kit up. Every machine calls it with the same options (a scene's onLoad). Options: towns ("shared" | "perPlayer"), town, payout ("members" | "present" | "owner"), display, numbers, welcome, queuePanel, hud, hudPosition, prompt, speed, capScale, ownerOnly, buildMode, start ({ resource = amount } for a new town), townNames ({ [townId] = "Name" }: the name a player reads for each town), save, ns, offline = { enabled, cap (seconds), efficiency (0-1), minAway (seconds before a welcome-back shows) }.

argtypedescription
optsany?

_ensureEconomy(c: any?) → void

economyKit's bank is what picks the works' machine and pays its coins: start it when nothing has this play session (a game that never set economyKit up, or a kit that believes it already did)

argtypedescription
cany?

config( ) → any return copy

configure(opts: any) → void

Change some options after setup (the same names as setup).

argtypedescription
optsany

defineBuilding(raw: any) → any

Add or replace a building kind (see productionKit.catalog). Kinds added after setup become buildPlaceKit pieces too.

argtypedescription
rawany

kinds( ) → void

kind(id: string) → any

argtypedescription
idstring

resources( ) → void

resource(id: string) → any

argtypedescription
idstring

format(n: number, style: string?) → string return N

Write a number the way the kit does (1.2K, 3.4M ...), in the kit's style or the one given.

argtypedescription
nnumber
stylestring?

formatRate(perSecond: number, opts: any?) → string return N

Write a rate: formatRate(3.5) -> "+3.5/s".

argtypedescription
perSecondnumber
optsany?

setNumberStyle(style: string) → void

Switch how every number in the kit reads: short, letters, scientific, engineering, words.

argtypedescription
stylestring

_addSite(site: any) → void

Register a building this machine draws (the ProductionBuilding component and the buildPlaceKit bridge call it). site = { id, kind, look, display, town, entity, owner, source, label, height }.

argtypedescription
siteany

_removeSite(id: string) → void

argtypedescription
idstring

_sites( ) → any return S

storeNs( ) → string

prefix( ) → string return Works

view( ) → any

apply(path: string, rec: any) → void

a record arrived (from the store's change feed, a poll, or this machine's own works)

argtypedescription
pathstring
recany

poll( ) → void

worksPeer( ) → number

deliver(peer: number, msg: any) → void

argtypedescription
peernumber
msgany

toWorks(msg: any) → void

argtypedescription
msgany

route(from: number, env: any) → void

argtypedescription
fromnumber
envany

listen( ) → void

processInbox( ) → void

request(op: string, body: any, cb: ((any) → void

argtypedescription
opstring
bodyany
cb((any

clientReceive(msg: any) → void

argtypedescription
msgany

retryPending( ) → void

queue(buildingId: string, job: string, cb: ((any) → void

Queue a job at a building with a queue (a barracks): queue("barracks1", "soldier", cb). Its money comes out of your wallet and its goods out of the town's stock; jobs finish one after another in the order queued. cb(res) gets { ok, uid } or { ok = false, code, text }.

argtypedescription
buildingIdstring
jobstring
cb((any

cancel(buildingId: string, which: any, cb: ((any) → void

Take a job out of a building's queue (its uid, or its place in the queue: 1 is the one being made) and get what it cost back.

argtypedescription
buildingIdstring
whichany
cb((any

upgrade(buildingId: string, cb: ((any) → void

Upgrade a building one level: it works faster (and a warehouse stores more). The cost comes from your wallet (coins) and the town's stock (goods).

argtypedescription
buildingIdstring
cb((any

pause(buildingId: string, on: boolean, cb: ((any) → void

Pause (true) or resume (false) a building.

argtypedescription
buildingIdstring
onboolean
cb((any

give(res: string, amount: number, town: string?) → number

On the works' machine only (host game code: quest rewards, a starting bonus): give a town goods, or coins to its members. Returns what was added, or nil on another machine.

argtypedescription
resstring
amountnumber
townstring?

keyOf(peer: number) → string

argtypedescription
peernumber

setTeamOf(who: any, team: string?) → void

Put a player on a team (game code on the works' machine; the same call on every machine is harmless). `who` is their account key ("u:<userId>", Economy.key()) or their peer id; team nil takes them off every team. Only players of a building's `team` may queue, cancel, upgrade or pause it.

argtypedescription
whoany
teamstring?

teamOf(who: any) → string

The team a player is on (their key or peer id), as this machine knows it: Production.setTeamOf first, then setup's teamOf resolver. nil when none.

argtypedescription
whoany

teamAccount(team: string) → string

The economyKit shared account a team's buildings spend from: setup's teamAccount(team), "acct:<team>" by default.

argtypedescription
teamstring

vec3(v: any) → void

argtypedescription
vany

placeOf(id: string) → any

Where a building stands on this machine: { position = { x, y, z }, yaw (degrees), door = { x, y, z } } (door: a point 1.5 m in front of its entrance, the side facing its local +Z, where both looks of the barracks have their doors), or nil when unknown.

argtypedescription
idstring

hostResult(res: any, cb: ((any) → void

argtypedescription
resany
cb((any

queueFor(buildingId: string, job: string, opts: any?, cb: ((any) → void

On the works' machine only (host game code, e.g. a computer opponent whose team has no player): queue a job at a building. A team building's currency costs come from its team's account (refunded there on cancel); goods from its town's stock. opts = { account = "acct:x" (pay from another account), by = playerKey (act as that player: their team is checked, a teamless building charges their wallet), free = true (charge no currency) }. Returns (and passes cb) { ok, uid, job, b, team?, account?, cost? } or { ok = false, code, values, text }; code "notWorks" on another machine.

argtypedescription
buildingIdstring
jobstring
optsany?
cb((any

cancelFor(buildingId: string, which: any, cb: ((any) → void

On the works' machine only: take a job out of a building's queue (its uid, or its place: 1 is the one being made) and pay back what it cost to wherever it came from (the team's account for a team building). Returns { ok, uid, job, b, refund } or { ok = false, code, text }.

argtypedescription
buildingIdstring
whichany
cb((any

townName(town: string?) → string return Text

The town this player works on: the shared town, or "p:<account>" with towns = "perPlayer". The name a player reads for a town, in their language: townName("main") -> "Millbrook" (the kit's default; setup's townNames or a catalog key productionkit_ui.town.names.<id> renames it). Defaults to this player's town.

argtypedescription
townstring?

town( ) → string

townRec(town: string?) → any

argtypedescription
townstring?

stock(res: string, town: string?) → number return townRec

How much of a resource a town holds (default: this player's town).

argtypedescription
resstring
townstring?

stocks(town: string?) → void

Every resource a town holds.

argtypedescription
townstring?

cap(res: string, town: string?) → number

A town's limit for a resource (math.huge for units and currencies).

argtypedescription
resstring
townstring?

made(town: string?) → void

Everything a town has made in its life, by resource (coins included).

argtypedescription
townstring?

buildingRec(id: string) → any

argtypedescription
idstring

_record(id: string) → any

The raw record the works keeps for a building (read-only; no copy), or nil. For per-frame checks.

argtypedescription
idstring

buildings( ) → void

Every building the works runs (ids), with their records.

rates(town: string?) → void

Net change per second of every resource in a town from the buildings working now: { wood = 0.5, planks = -0.2 }.

argtypedescription
townstring?

upgradeCost(id: string) → any

What a building costs to upgrade from the level it is at, or nil at the top level.

argtypedescription
idstring

isWorks( ) → boolean return S

Whether this machine runs the works.

isReady( ) → boolean return next

Whether this machine has heard from the works yet.

lastWelcome( ) → any

The last welcome-back summary this player got this session, or nil.

siteOf(id: string) → any

argtypedescription
idstring

setLook(id: string, look: string) → void

Draw a building in another look on this machine ("rustic", "scifi", or a buildPlaceKit style). Scene buildings take it from their `look` field.

argtypedescription
idstring
lookstring

setDisplay(id: string?, style: string) → void

Show another display above one building (setDisplay("mill1", "badge")), or above every building that has not chosen one (setDisplay(nil, "float")).

argtypedescription
idstring?
stylestring

setKind(id: string, kind: string) → boolean

Turn a building into another kind (one setting): only the works' machine may, since it changes what the building makes. Queued jobs are cancelled and paid back.

argtypedescription
idstring
kindstring

setWelcomeScreen(style: string) → void

argtypedescription
stylestring

setQueuePanel(style: string) → void

argtypedescription
stylestring

catalogue( ) → any

Everything a game can choose from, as data: { version, kinds, resources, looks, displays, welcome, queuePanels, numbers, events }.

placeBuilding(opts: any) → any

argtypedescription
optsany

building(arg: any) → any

building(id) reads one building as every machine sees it: { id, kind, town, team, funds, level, status, missing, progress (0-1, moving smoothly), cycleTime, queue, made, paused, rates }. building({ kind, look, display, id, town, team, label, position, yaw, name }) puts a production building in the scene (build.luau content(), or host code) and returns its entity; `id` is what its progress is kept under (default from kind and position); `team` makes it a team building (only that team's players run it, its costs come from the team's account, and with no `town` it works with the team's own town "team:<team>").

argtypedescription
argany

peers( ) → void

worksEnv( ) → any

send(peer: number, msg: any) → void

argtypedescription
peernumber
msgany

grant(key: string, cur: string, amount: number, reason: string?) → void

argtypedescription
keystring
curstring
amountnumber
reasonstring?

emit(event: string, info: any) → void

argtypedescription
eventstring
infoany

applied(path: string, rec: any) → void

argtypedescription
pathstring
recany

teamOf(key: string) → void

argtypedescription
keystring

teamAccount(team: string) → void

argtypedescription
teamstring

debit(target: string, costs: any, reason: string?) → void

argtypedescription
targetstring
costsany
reasonstring?

credit(target: string, costs: any, reason: string?) → void

argtypedescription
targetstring
costsany
reasonstring?

balanceOf(target: string, cur: string) → void

argtypedescription
targetstring
curstring

place(id: string) → void

argtypedescription
idstring

sitesForWorks( ) → void

startWorks( ) → void

stopWorks( ) → void

syncWorks(dt: number) → void

argtypedescription
dtnumber

saveReady( ) → boolean

The works hands this machine the player's progress record from time to time; it is kept in the player's saveKit profile (saveKit saves it by itself a few seconds later). When the player comes back, the hello carries it to the works, which accepts it only if it is a save it handed out.

savedProgress( ) → any

keepProgress(data: any) → void

argtypedescription
dataany

_tick(dt: number) → void

Run one frame (ProductionHost calls this): follow economyKit's bank to choose the works, pass messages, run the works, say hello, keep the views fresh.

argtypedescription
dtnumber

_attach(id: string) → void

argtypedescription
idstring

_detach(id: string) → void

argtypedescription
idstring

_ensureHost( ) → void

Make sure this machine's ProductionHost (works, network, displays, screens, controls) exists. Called by every API that needs it.

_dropVisual(s: any) → void

visuals live in the host; these are set by it

argtypedescription
sany

_restyle(s: any) → void

argtypedescription
sany

_showWelcome(summary: any) → void

argtypedescription
summaryany

showWelcome(summary: any, style: string?) → void

Show a welcome-back screen now with your own summary (to try the styles): showWelcome({ away = 3600, paid = { coins = 1200 }, made = { planks = 300 } }, "ledger").

argtypedescription
summaryany
stylestring?

openQueue(id: string) → boolean

Open the production queue panel of a building for this player.

argtypedescription
idstring

closeQueue( ) → void

wipe( ) → boolean

Forget every saved building, town and member of this world (a new game). Only the works' machine can.

_reset( ) → void

Forget everything this machine knows (tests).

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

38+items
▣
module · born here
❒asset
# 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.
▲ 0↑ born
▣
module · born here
❒asset
# 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.
▲ 0↑ born
▣
module · born here
❒asset
# 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.
▲ 0↑ born
◇
component · born here
❒asset
# 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.
▲ 0↑ born
◇
component · born here
❒asset
# 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.
▲ 0↑ born
▣
module · born here
❒asset
# 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.
▲ 0↑ born
▣
module · born here
❒asset
# 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.
▲ 0↑ born
❒
package · born here
❒asset
# productionKit **Buildings that make things over time, for idle, tycoon, city builder and RTS games in any multiplayer Zero world.** A farm grows wheat, a lumber mill stacks wood, a sawmill turns wood into planks, a market sells the planks for coins, a barracks trains soldiers one after another, and when you come back tomorrow a welcome-back screen tells you what your town made while you were away. Version **1.3.11** (`Production.VERSION`). **What you get:** twelve building kinds (farm, lumber mill, mine, sawmill, smelter, bakery, market, house, warehouse, barracks, power plant, research lab), each in two looks (a rustic **timber village** look and a **sci-fi industrial** look, drawn with buildPlaceKit's Frontier and Outpost materials, with turning wheels, spinning sails, chimney smoke and glowing cores while they work), producers, converters that stop when their input runs out or the town has no room for what they make, storage limits and warehouses that raise them, production chains that sell for economyKit coins, offline earnings up to a cap you set with a welcome-back summary, RTS production queues with cancel, building upgrades, idle-style big numbers (1.2K, 3.4M, 5.6B ... up to 1e303, and +3.5/s rates), four displays above buildings, five welcome-back screens (card, ledger, toast, treasure chest, report card), three queue panels (list, slot bar, timeline), five number styles, a town stock bar, and placing any building with buildPlaceKit's ghost preview (press **B**). Each player's progress is saved in their **saveKit** profile, and every word a player reads (names, number words, rates, screens, refusals) can be translated through the engine's built-in translation catalogs. One authoritative machine runs every building, so every player sees the same stock and progress, nobody can change their own counts, and someone joining late sees what is already there. **Install:** search ZeroMind for productionKit and install it into your world. One install brings the three kits it is built on with it. ### The kits it uses, and their versions | Package | Version | What productionKit uses it for | What its install brings | |---|---|---|---| | **economyKit** | 1.0.13 | coins, wallets that keep between sessions, and the bank: the one machine that decides every payment, which also runs every building | inventoryKit, menusKit, navUiKit, saveKit | | **buildPlaceKit** | 1.0.18 | placing buildings with a green or red ghost preview (press **B**), prices and refunds, placed buildings kept between sessions, and the Frontier and Outpost materials the two looks are drawn with | gridKit, juiceKit, and the wood, stone, masonry and sci-fi material collections | | **saveKit** | 1.3.0 | each player's progress: when they were last here, what they had earned, and their own town when towns are per player (its code is the same as 1.2.1, the version economyKit was built with) | menusKit, controlsKit | productionKit 1.3.0 was built and tested against exactly these versions (team buildings need economyKit 1.1.0 or later for shared team accounts; everything else runs on 1.0.13). `REUSE_REVIEW.md` beside this README says what was built new for productionKit and how each of these kits held up. ## First example: a lumber mill, a sawmill and a market Install productionKit into a new world. In `scenes/main.scene/build.luau`, add these lines inside `function content()`, before its `end`: ```lua local Production = require("productionKit.production") Production.building { kind = "lumberMill", look = "rustic", position = { -10, 0, 12 } } Production.building { kind = "lumberMill", look = "rustic", position = { -2, 0, 12 } } Production.building { kind = "sawmill", look = "rustic", position = { 7, 0, 12 } } Production.building { kind = "market", look = "rustic", position = { 17, 0, 12 } } ``` and replace `scenes/main.scene/entrypoint.luau` with: ```lua local Production = require("productionKit.production") function onLoad() Production.setup({ display = "ring", offline = { cap = 8 * 3600 } }) end ``` Press Play. Two timber lumber mills stand in front of you, each with a ring filling above it and "+0.5/s" under its log icon; the town's stock bar at the top counts Wood up towards its limit of 50. The sawmill takes 2 wood every 3 seconds and makes a plank; the market sells each plank for 6 coins, and your coins (top left, economyKit's wallet) go up. Stop, wait a few minutes, press Play again: a **Welcome back!** card tells you how long you were away, the coins you earned and the wood and planks made, and the coins are already in your wallet. Change `look = "rustic"` to `look = "scifi"` and the same buildings are drawn as sci-fi industry. Change `kind = "sawmill"` to `kind = "smelter"` and that building smelts metal instead. Nothing else changes. ## Guides Two guides ship inside the package; open them in the Docs panel, with `man`, or with the `guides` tool: - **How to make buildings that produce resources over time**: what the kit is, how buildings, recipes, storage, chains, queues, upgrades, offline earnings and displays fit together, and how multiplayer works: `productionKit.package/how-to-make-buildings-that-produce-resources-over-time`. - **Make an idle game with offline earnings, step by step**: from an empty world to a lumber mill feeding a sawmill feeding a market, with upgrades and a welcome-back screen when you come back: `productionKit.package/make-an-idle-game-with-offline-earnings-step-by-step`. ## Building kinds | id | name | what one cycle does | every | |---|---|---|---| | `farm` | Farm | makes 1 wheat | 2 s | | `lumberMill` | Lumber Mill | makes 1 wood | 2 s | | `mine` | Mine | makes 1 ore | 3 s | | `sawmill` | Sawmill | 2 wood → 1 plank | 3 s | | `smelter` | Smelter | 2 ore + 1 wood → 1 metal | 4 s | | `bakery` | Bakery | 2 wheat → 1 bread | 3 s | | `market` | Market | sells 1 plank for 6 coins, else 1 metal for 15, else 1 bread for 4 | 2 s | | `house` | House | eats 1 bread, pays 5 coins rent | 6 s | | `warehouse` | Warehouse | raises every limit by 100 (×1.5 a level) | no cycle | | `barracks` | Barracks | a queue of 5: Soldier (15 coins + 1 bread, 6 s), Archer (20 coins + 2 planks, 8 s), Knight (40 coins + 2 metal, 12 s) | each job's own time | | `powerPlant` | Power Plant | makes 2 power | 2 s | | `researchLab` | Research Lab | 3 power → 1 research | 5 s | Each level makes a building 1.25 times faster; the first upgrade costs what the kind lists and each one after costs 1.6 times more (`Production.upgradeCost(id)`). Resources: wheat, wood, ore, planks, metal, bread, power, research (limit 50, 40 or 60 each before warehouses), soldiers, archers, knights (no limit) and coins (paid into economyKit wallets, never stored). **How a building works.** A building starts a cycle by taking its inputs from its town's stock (a producer takes nothing); with too little it waits, **starved** ("Needs 2 Wood"). When a cycle ends its outputs go into the stock; if any would go over the town's limit it waits, **full**, holding the finished cycle until there is room. Coins never fill up: they are paid into wallets. Each step, producers work first and markets last, so a chain flows within one step. ## Changing it with one setting | Family | Choices | Switch with | |---|---|---| | Building kind | the twelve above, or your own | a building's `kind` (scene line or the ProductionBuilding component's field) | | Look | `rustic` (timber village: oak logs, boards, dry stone, thatch, lamplight; also `timber`, `village`, `frontier`), `scifi` (hull panels, deck plate, hazard stripes, cyan light; also `sci-fi`, `industrial`, `outpost`), or any buildPlaceKit style your world defines | a building's `look`; `Production.setLook(id, look)` | | Display above a building | `ring` (a progress dial with the output's icon and its rate), `badge` (a pill with the town's stock of the output against its limit, tinted by status), `float` ("+5" numbers rising when a cycle ends), `minimal` (a thin bar and a status dot), `none` | `Production.setup{ display = ... }`, a building's `display`, `Production.setDisplay(id or nil, style)` | | Big numbers | `short` (1.2K, 3.4M, 5.6B, 7.8T, 9.1Qa ... 1Ce), `letters` (K, M, B, T, then aa, ab ... like many idle games), `scientific` (3.40e6), `engineering` (56.0e9), `words` (5.6 billion) | `Production.setup{ numbers = ... }`, `Production.setNumberStyle(style)` | | Welcome-back screen | `card` (centred card, big coin total, goods made, Collect), `ledger` (a parchment steward's report, one line per building, wax seal), `toast` (a slim banner that leaves by itself), `chest` (a treasure chest bursts open and the coins rise out of it, the goods laid out below), `report` (a school report card: a row per building with what it made and a grade from A to D for how busy it was, and an overall grade), `none` (no screen of the kit's own: the `welcomeBack` event still fires, so a game can add to the summary and show it itself). Every screen also shows a game's own lines from `summary.notes` | `Production.setup{ welcome = ... }`, `Production.setWelcomeScreen(style)` | | Queue panel | `list` (side panel: job buttons with cost and time, rows with progress bars and a cancel ✕), `slots` (an RTS command bar: job buttons and square slots, the first filling; click one to cancel), `timeline` (a strip across the top: each job a block as wide as its time, with when it finishes; click a block to cancel it) | `Production.setup{ queuePanel = ... }`, `Production.setQueuePanel(style)` | `Production.catalogue()` returns every choice as data with names, descriptions and tags. ## Setup options ```lua Production.setup({ towns = "shared", -- "shared": one town for everyone; "perPlayer": each player their own town and stock town = "main", -- the shared town's id townNames = { main = "Riverside" }, -- the name players read for each town id (default: main is "Millbrook", a per-player town "Your Town") payout = "members", -- who earned coins go to: "members" (everyone who has played in the town, absent ones too), "present", "owner" (who placed the building) display = "ring", numbers = "short", welcome = "card", queuePanel = "list", hud = true, hudPosition = "top", -- the town's stock bar prompt = true, -- "[E] Training queue [U] Upgrade ..." near a building speed = 1, -- every building's speed capScale = 1, -- every storage limit ownerOnly = false, -- only a building's builder may queue, cancel and upgrade it buildMode = true, -- every kind is a buildPlaceKit piece (press B in a BuildMode zone) start = { wood = 10 }, -- what a brand new town holds save = true, -- each player's progress is saved in their saveKit profile; false saves none offline = { enabled = true, cap = 8 * 3600, efficiency = 1, minAway = 60 }, }) ``` `offline.cap` is the most time (in seconds) caught up after nobody played; `offline.efficiency` scales what that time makes (0.5 is half); `offline.minAway` is how long a player must be gone before they get a welcome-back screen. ## Placing buildings - **In a scene:** `Production.building { kind, look, position, yaw, id, display, town, label }` inside `content()` in `build.luau`. Give each one a stable `id` when you may move it: its level, queue and progress are kept under it (default: kind and position). - **By the player, with a ghost preview:** every kind is a buildPlaceKit piece named `"productionKit.<kind>"` (`Production.pieceKind("farm")`). Put a build zone in your scene and press **B**: ```lua local pieces = {} for _, k in Production.kinds() do table.insert(pieces, Production.pieceKind(k.id)) end require("buildPlaceKit.api").BuildMode { position = { 40, 0, 0 }, size = { 40, 20, 40 }, pieces = pieces, menu = "catalogue" } ``` The placed building costs its kind's `cost` in coins, is drawn in the style you build with (rustic or scifi), starts working at once, and is kept between sessions by buildPlaceKit; taking it down stops it. - **By hand:** add the **ProductionBuilding** component to any entity and set `kind`, `look` and `buildingId`. ## Queues, upgrades and pausing Walk up to a barracks and press **E** (gamepad X): the queue panel opens. Press a job to queue it: its coins come out of your wallet and its goods out of the town's stock. Jobs finish one after another in the order you queued them; the ✕ (or a slot, in the slot bar) cancels one and gives back everything it took. Press **U** (d-pad up) near any building to upgrade it. From code: ```lua Production.queue("town.barracks", "soldier", function(res) print(res.ok, res.text) end) Production.cancel("town.barracks", 2) -- the second job in the queue (or its uid) Production.upgrade("town.sawmill") Production.pause("town.market", true) ``` ## Reading and events ```lua Production.stock("planks") -- 34 Production.cap("planks") -- 150 Production.rates() -- { wood = 0.33, planks = 0.33 } net per second, from buildings working now Production.building("town.sawmill") -- { kind, level, status, missing, progress, cycleTime, queue, made, rates, ... } Production.format(1234567) -- "1.2M" Production.formatRate(3.5) -- "+3.5/s" Production.on("made", function(e) print(e.b, "made", e.out.planks) end) Production.on("jobDone", function(e) print("trained", e.job) end) -- spawn your unit here Production.on("welcomeBack", function(s) print("away", s.away, "earned", s.paid.coins) end) Production.on("refused", function(e) print(e.text) end) -- "Not enough Coins: you need 5 more" ``` Events: `ready`, `made`, `status`, `jobQueued`, `jobDone`, `jobCancelled`, `upgraded`, `paused`, `refused`, `welcomeBack`, `stockChanged`, `worksChanged`, `buildingAdded`, `buildingRemoved`; on the works' machine, `works.<event>` hears everything (`works.paid`, `works.tamper`, `works.caughtUp` ...). ## Team buildings for RTS games A building can belong to a **team**. Only players the game put on that team may queue, cancel, upgrade or pause it (anyone else is refused with "That building belongs to another team", code `notYourTeam`), and what its jobs and upgrades cost in economyKit currencies comes out of the **team's shared economyKit account** instead of the player's own wallet; a cancelled job is paid back there. A team building with no `town` works with its team's own town `"team:<team>"`, so goods it uses (bread, planks) come from that team's stock and coins its buildings make go into the team's account. Buildings without a `team` work exactly as before. Shared accounts need **economyKit 1.1.0** or later (`"acct:<name>"` targets, `Economy.debit` / `credit` / `balanceOf`). Every currency a job costs must be both a productionKit resource with `currency` set and an economyKit currency. ```lua local Production = require("productionKit.production") local Economy = require("economyKit.economy") -- every machine: the same setup; teamAccount is optional ("acct:" .. team is the default) Production.setup({ queuePanel = "slots", teamAccount = function(team) return "acct:" .. team end }) -- your own unit types: a trainer kind drawn with the barracks art in both looks Production.defineResource({ id = "gold", name = "Gold", currency = "gold" }) Production.defineResource({ id = "wood", name = "Wood", currency = "wood" }) -- a currency here, not a stocked good Production.defineBuilding({ id = "rtsBarracks", base = "barracks", name = "Barracks", jobs = { { id = "soldier", name = "Soldier", cost = { gold = 60 }, time = 8 }, { id = "archer", name = "Archer", cost = { gold = 50, wood = 25 }, time = 9 }, } }) -- the scene (build.luau content(), or host code) Production.building({ kind = "rtsBarracks", look = "rustic", position = { -40, 0, 0 }, id = "t1.barracks", team = "team1" }) Production.building({ kind = "rtsBarracks", look = "scifi", position = { 40, 0, 0 }, yaw = 180, id = "t2.barracks", team = "team2" }) -- the works' machine (economyKit's bank): who is on which team, and the computer opponent Production.setTeamOf(Economy.key() or 0, "team1") -- a player's key ("u:<id>") or peer id Economy.grant("acct:team2", "gold", 500, "start") Production.queueFor("t2.barracks", "soldier") -- charges acct:team2; { ok, uid, job, b, team, account, cost } or a refusal Production.cancelFor("t2.barracks", 1) -- refunds acct:team2 -- spawn the unit at the door when it is trained (every machine hears jobDone; the works' machine also works.jobDone) Production.on("works.jobDone", function(e) -- e.b / e.id / e.building, e.team, e.job, e.uid, e.by, e.buildingKind, e.town, e.out, -- e.position { x, y, z }, e.yaw (degrees), e.door { x, y, z } (1.5 m in front of the entrance) end) ``` - **Building option** `team` (string), on `Production.building{...}` and on the **ProductionBuilding** component. - **Who is on a team** is decided by game code on the works' machine: `Production.setTeamOf(keyOrPeer, team)` (team nil takes them off), or `setup{ teamOf = function(playerKey) return team end }`; `Production.teamOf(keyOrPeer)` reads it back. A player on no team cannot run any team building. - **Host-side queueing** (a computer opponent has no player): `Production.queueFor(buildingId, job, opts?, cb?)` and `Production.cancelFor(buildingId, which, cb?)` on the works' machine, answering like `queue` / `cancel` (`{ ok = false, code = "notWorks" }` elsewhere). `opts.account` pays from another account, `opts.by = playerKey` acts as that player (their team is checked), `opts.free = true` charges no currency. A teamless building queued with `queueFor` and no `by` costs no currency. - **Your own trainer kinds:** `defineBuilding{ base = "barracks", jobs = {...} }` starts from the barracks (size, slots, upgrades, art) and replaces its jobs; `jobs` is a list of `{ id, name, cost, time, outputs?, icon? }` (or a map), `slots` sets the queue length, and `art = "<kit kind>"` draws any kind of yours with one of the kit's twelve drawings. `category = "trainer"` with no `base` is drawn as a barracks too. A job with no `outputs` adds nothing to stock: the unit is yours to spawn on `jobDone`. - **The queue panel** (`Production.openQueue(id)` from a click in your game, or E next to it) checks a team building's jobs against the **team's account**, read live on every machine, never against the player's own wallet; the building's record also carries `funds` (what the account holds of the currencies it spends, refreshed each second by the works) and `team`. ## Your own resources and buildings ```lua Production.defineResource({ id = "stone", name = "Stone", color = "#a0a0a0", cap = 80 }) Production.defineBuilding({ id = "quarry", name = "Quarry", category = "producer", outputs = { stone = 1 }, every = 3, size = { 6, 4, 6 }, cost = { coins = 40 }, }) ``` Or add `.data` assets bound to the `productionKit.resource` and `productionKit.building` contracts anywhere in your world (see their READMEs); the kit finds them by itself. A kind of your own is drawn as a generic workshop in either look until you give it art. ## Saving with saveKit saveKit is how productionKit keeps each player's progress. There is nothing to set up: `save = true` is the default, and saveKit starts itself the first time it is used in play. - **What is saved, per player:** one record, `Save.get("productionKit")`, in that player's saveKit profile: for each town they belong to, when they were last here, what the town had made and what they had earned by then, and each building's count (that is what the welcome-back screen compares against). With `towns = "perPlayer"`, the record also holds the player's own town: its stock, every building's level, queue and progress. - **Who writes it:** the works hands the player's machine their record when they arrive and every 10 seconds while they play (event `saved`); the machine stores it with `Save.set`, and saveKit writes the profile a few seconds later by itself. - **Coming back:** the player's machine waits for saveKit to load (a few seconds at most), then says hello to the works carrying the saved record. The works reads the player's progress back from it, catches up a per-player town for the time since (up to `offline.cap`), and shows the welcome-back screen. - **Nobody can edit their own save to cheat:** the works keeps a fingerprint of the last few records it handed each player in the world's data (`s/`), where only it writes. A record that does not match (changed by hand, or copied from elsewhere) is refused and raised as `works.tamper`; the player then carries on from what the world holds. - **Shared towns stay in the world.** A saveKit profile belongs to one player, so a town everyone works on is kept in the world's data, as before. What each player earned from it while they were away is kept there too (`a/`) and handed into their save when they return. - **From 1.1.6 and earlier:** member records the older kit kept in the world's data (`m/`) are taken over once and then removed, so nobody's welcome-back is lost by the update. ## Translating Every word the kit shows a player goes through the engine's built-in translation support (`i18n`): - **Where the words are:** the package's English catalogs, `productionKit.package/locales/en/productionkit.json` (names of resources, building kinds and jobs, building descriptions, the names of every look and style, refusals such as "Not enough Wood: you need 2 more", the "[E] / [U]" prompts, and the number words, suffixes, rates and durations) and `productionkit_ui.json` (every screen: welcome-back screens, queue panels, the stock bar, displays and building status text). - **Adding a language:** put `locales/<language>/productionkit.json` and `productionkit_ui.json` in your world with the same keys, translated (for example `locales/pt-BR/productionkit.json`). Each player gets the language they read, and screens redraw when it changes. - **Changing a word:** state the same key in your world's own `locales/en/productionkit.json` (your world's catalogs are read before the package's). For example `"names": { "building": { "market": "Trading Post" } }`. - **Big numbers in another language:** `productionkit.numbers.short_suffixes` ("K M B T Qa ..."), `words` ("thousand million billion ..."), `rate_s` ("{{ value }}/s") and the `duration_*` keys. - **Your own kinds:** a kind you define is translated by the key `productionkit.names.building.<id in snake_case>`, a resource by `productionkit.names.resource.<id>`. - **Town names:** a player never reads a town's id. The report card's "Millbrook School of Industry" names the town by `setup{ townNames = { main = "Riverside" } }`, or by the kit's own default: `main` reads "Millbrook" (`productionkit_ui.town.default`), a per-player town "Your Town" (`productionkit_ui.town.own`), and any other id is spelled out ("north_farm" reads "North Farm"). Translate a town's name with the key `productionkit_ui.town.names.<id>` in your world's catalogs; `Production.townName(id)` gives the name to show in your own screens. - The showcase's own signs and panel read from the world's catalog `locales/en/showcase.json`. ## How it stays fair in multiplayer - **One machine runs every building:** the machine running economyKit's bank (the lowest peer in the room; the next one takes over if it leaves). It runs the rules, and every other machine only reads what it keeps and sends it requests on the `productionKit` channel. The relay names the sender, and the works maps that machine to its account through economyKit, so nobody can act for someone else. - **Requests, not counts:** a player asks to queue, cancel, upgrade or pause; the works checks the building is theirs to use, the stock and the wallet, then does it whole or refuses with a reason. A retried request is answered again, never charged twice. Money moves only through economyKit's bank. - **Kept in the world:** towns, buildings and the roster of each town live in the world's shared runtime data under `productionKit/<ns>.<world>/` (`t/` towns, `b/` buildings, `r/` who belongs to each town, `a/` what an absent member earned meanwhile, `s/` the fingerprints of the saves handed to each player, `meta`), written only by the works. A record anyone else writes there is put back at once and raised as `works.tamper`. - **Kept in each player's saveKit profile:** that player's own progress (see *Saving with saveKit*). Only the player's own machine can write it, and the works only accepts it back when it matches a save the works itself handed out. - **Late joiners** read the same records the moment they arrive, so they see every building's level, queue, progress and the town's stock as everyone else does. - **Same counts and progress on every machine:** the store delivers each record's changes in order, so every player's machine shows the works' latest stock and statuses; a building's progress bar moves on from when its record arrived, so bars match without a write every frame. The works' own machine reads its writes directly and ignores the store's echoes of them, and it recognises its last few writes per record, so a late echo is never mistaken for tampering. If the works' machine leaves, the next one carries on from the same records, with revisions that keep counting up. - **Offline earnings:** the works stamps the time every few seconds. When a session starts after nobody played, it catches up the time since (up to `offline.cap`, scaled by `offline.efficiency`) before anything else, and pays the coins. Each player's last visit is kept too (in their saveKit save), so a returning player gets a welcome-back summary of what the town made and what they earned since they left, whether the town ran without anyone or with other players. ## Reference `local Production = require("productionKit.production")` - Setup: `setup(opts)`, `configure(opts)`, `config()`, `catalogue()`. - Scene: `building(opts)` (places one, returns its entity), `pieceKind(kind)`, `kindOfPiece(pieceKind)`. - Data: `defineResource`, `defineBuilding`, `kinds()`, `kind(id)`, `resources()`, `resource(id)`. - Reading: `town()`, `townName(town?)` (the name a player reads, never the id), `stock(res, town?)`, `stocks(town?)`, `cap(res, town?)`, `made(town?)`, `rates(town?)`, `building(id)`, `buildings()`, `upgradeCost(id)`, `isReady()`, `isWorks()`, `lastWelcome()`. - Requests (answered by the works; `cb(res)` gets `{ ok, ... }` or `{ ok = false, code, text }`): `queue(id, job, cb)`, `cancel(id, uidOrIndex, cb)`, `upgrade(id, cb)`, `pause(id, on, cb)`. - Host only (on the works' machine): `give(res, amount, town?)`, `setKind(id, kind)`, `wipe()`, `queueFor(id, job, opts?, cb?)`, `cancelFor(id, which, cb?)`. - Teams: `setTeamOf(keyOrPeer, team)`, `teamOf(keyOrPeer)`, `teamAccount(team)`, `placeOf(id)` (position, yaw and door point). - One setting: `setLook(id, look)`, `setDisplay(id or nil, style)`, `setNumberStyle(style)`, `setWelcomeScreen(style)`, `setQueuePanel(style)`. - Screens: `openQueue(id)`, `closeQueue()`, `showWelcome(summary, style?)`. - Numbers: `format(n, style?)`, `formatRate(perSecond, opts?)`; `require("productionKit.numbers")` also has `delta`, `duration`, `percent`, `grouped`. - Events: `on(event, fn)` returns a function that stops listening; `text(reason)` turns a refusal into words. - Modules for advanced use: `productionKit.catalog` (data), `.sim` (the rules, pure), `.works` (the authoritative machine), `.numbers`, `.art` (looks), `.displays`, `.screens`, `.icons`. - Components: **ProductionBuilding** (a building in a scene), **ProductionHost** (started by the kit itself; never place it). ## Tests `productionKitTests` runs the rules and the works against a fake shared store, fake players and a fake bank: numbers in every style, the catalogue, producers, starving and full converters, warehouses, the lumber mill → sawmill → market chain, markets, queues in order with refusals and refunds, upgrades, scaled offline catch-up, charging and refunding queue money, retries not charged twice, refusing other players' buildings, putting back hand-written records, paying members, state coming back from the store, offline time capped with a welcome-back summary, saves handed to each player and read back from them, a save changed by hand refused, a per-player town restored from its save, words read from the translation catalogs (town names included, never a town's id), switching a kind with one setting, team buildings (only the team's players run them, costs charged to and refunded from the team's account, host-side queueFor and cancelFor, trainer kinds from `base = "barracks"`, and the jobDone payload with team and place), every kind drawn in both looks, and every display, welcome-back screen and queue panel built. Run it in edit mode: `tools.use("tests", "run", { suite = "productionKitTests" })`. ## Showcase The world this kit is published from is a small town: two lumber mills feeding a sawmill feeding a market that earns coins, a farm and a bakery feeding a barracks with a training queue (walk up and press E), a field east of town where you press B to place any building, and to the south a labelled gallery of all twelve kinds in both looks working side by side (four rows of six, two rows per look, each building with a large label on the walk in front of it). A "Try the styles" panel on the right switches displays, number styles, the town's look, the queue panel (list, slots, timeline) and previews each welcome-back screen (card, ledger, toast, chest, report card) with a sample whose buildings were busy for most of the time away, so the report card shows real grades. While the timeline queue panel is open across the top, the panel moves under it, and when the screen is too short for it (a phone held sideways) its rows scroll, so neither covers the other. The panel takes real mouse clicks and lights up each button under the pointer: it sits at screen layer 140, above buildPlaceKit's build HUD (layer 110, which swallows clicks on anything under it) and below the kit's own queue panels and welcome screens. One overlap stays: the **List** queue panel opens on the right, where the styles panel is, and covers it while it is open. Close the queue panel (its ✕, or walk away from the barracks) to use the styles panel again, or pick the Slots or Timeline queue panel, which do not cover it. ## Known limits - **Two players, checked two ways:** in play on this machine, and by the suite's two-player test, which runs three machines side by side on one shared store whose changes arrive 0.3 s late (the works' machine, a second player who only sees what the store sends, and a late joiner): both players read the same stock, statuses and progress (within 0.15 of a cycle), the second player's queued job shows on both, the second player writing their own wood count is put back for everyone, the late joiner sees the current state on its first look, and when the works' machine leaves the second player takes over from the store and the late joiner follows it. A real second device was not connected while this was built (one engine is one peer), so the relay itself is economyKit's and the engine's, as tested there. - **The works runs on a player's machine**, as economyKit's bank does: Zero rooms have no dedicated server. A player alone in a world is their own works, so a modified client playing alone can change its own town. - **Offline time is caught up when someone next plays**, not while the world is empty; a welcome-back summary is shown to a player whose last visit was over `offline.minAway` seconds ago. - **Numbers are doubles**: past about 1.8e308 a number reads "∞". - **Payout "members"** gives every member the full amount a town earns (co-op idle); use `present` or `owner`, or a town per player, for competitive games. - **Shared towns are not in saveKit.** A saveKit profile belongs to one player, so a town everyone works on is kept in the world's data; only each player's own progress (and a per-player town) is in their profile. - **A player whose save has not arrived** is greeted after a few seconds anyway, and the works waits for their save rather than starting them over when it knows they have one. - **Open engine issues that affect worlds using this kit:** - **#14448**: two sessions of one account in a play room collide on the default player entity id, and one player spawn is refused. In plain words: if the same account plays the world from two engines at once, the two players clash and one of them is not spawned. Test multiplayer with two different accounts. - **#20750**: sending multiplayer changes costs 14 to 46 ms of every frame even when nothing changed, on the receiving side too. In plain words: the frame rate can be low, around 10 frames per second in the browser. This is in the engine, and the kit cannot work around it. - **Known problems in the kits this one builds on** (not tied to the issues above): - With two copies of the same kit installed in one world (for example saveKit installed directly and also by economyKit), the engine can report a module as "not found" even though its files are there, and kits that need it stop loading. Keep one copy of each kit: productionKit's install brings one saveKit, at the version listed above. saveKit's own page has an open report of this. - saveKit's on-screen HUD, when turned off, can still take clicks and drags meant for screens under it (an open report on saveKit's page). productionKit leaves saveKit's HUD at its default, so its own screens are not affected. - buildPlaceKit's world has one open issue, about branches on the server, which does not affect this kit. Two buildPlaceKit behaviours productionKit works around (its build screen swallowing clicks under it, and economyKit not being started again on a later Play) are described in `REUSE_REVIEW.md`. - **Your own clickable screens must sit above layer 110.** buildPlaceKit's build HUD (`buildPlaceKit_hud`, layer 110) covers the whole screen and takes every click and hover meant for a screen under it, even when nothing of it shows there. A screen you register with no layer (layer 0) looks fine but its buttons do nothing with a real mouse. Register your own panels above it, for example `ui.registerScreen("myPanel", tree, 140)`. productionKit's own screens already do: queue panels at 150, welcome-back screens at 1100. ## Changes - **1.4.0**: a game can tell the whole story of the time away on productionKit's welcome-back screens. A summary's `notes` (strings, or `{ text, icon = resource id, svg = svg markup, color }`) appear on every screen in its own lettering: under the coins on the card, as a paragraph of the steward's ledger, under "Away ..." on the toast, beneath the chest's goods and in the report card's remarks. A new welcome style, `none`, shows nothing of the kit's own, so a game can wait for its own numbers, merge them in and call `Production.showWelcome(summary, style)` once. townKit uses both for one welcome-back that names tax coins, goods, people and homes together. - **1.3.11**: a game's own buildPlaceKit pieces can be productionKit buildings (setup `pieceKinds = { ["myGame.house"] = "home" }`), and setup's `canUpgrade(building, key) -> false, reason` holds an upgrade back before anything is charged (refusal code `notYet`, the reason as its text). townKit uses both so homes rise a tier through productionKit's upgrade. - **1.3.10**: economyKit 1.1.4 and buildPlaceKit 1.0.23 are installed cleanly from ZeroMind underneath (no hand-patched copies), so installing productionKit into a new world resolves every kit it uses at a published release. 1.3.6 to 1.3.9 named an economyKit version that was never published and failed to install with VERSION_NOT_FOUND. No code change. - **1.3.9**: economyKit, buildPlaceKit and saveKit are brought by the code that uses them, each at a published release, instead of by a `dependencies:` list in `package.yaml`: that list pinned each kit at the publishing world's own copy, which ZeroMind holds no release of, so installing productionKit 1.3.6 to 1.3.8 into a new world failed with VERSION_NOT_FOUND. They still install with productionKit. No code change. - **1.3.8**: economyKit and saveKit reinstalled cleanly from ZeroMind underneath, so the release names an economyKit that is published (1.3.6 and 1.3.7 still named one that never was). No code change. - **1.3.7**: built on the current engine library (@builtin 034765f) and on buildPlaceKit 1.0.22, with every kit underneath byte-identical to a published release, so a fresh install from search resolves every dependency (1.3.6 named an economyKit that was never published). No code change. - **1.3.6**: a `ProductionBuilding` whose kind is not defined yet keeps trying for 15 seconds instead of giving up at once, so a scene's buildings work when the game or kit that owns their kind defines it a moment later (rtsKit defines its town hall and barracks when its match starts; before, they never registered and the barracks could not train). Built on economyKit 1.1.4 and buildPlaceKit 1.0.21. - **1.3.5**: built on buildPlaceKit 1.0.20, whose economyKit references now name a released economyKit too; with 1.3.4 a fresh install still failed with VERSION_NOT_FOUND through buildPlaceKit. No code change. - **1.3.4**: built on economyKit 1.1.3, a release whose world holds the same bytes; 1.3.3 pinned an economyKit state no release named, so a fresh install of any kit depending on productionKit failed with VERSION_NOT_FOUND. No code change. - **1.3.3**: `production.module` and `ProductionHost` require economyKit by name (`economyKit.economy`) instead of by a `/source/...` path, so a world that installed productionKit (economyKit lands under `deps/`) loads it. Pins economyKit 1.1.1. - **1.3.2**: the Mill to Market world itself now runs the published economyKit 1.1.0, so a fresh install of productionKit resolves every dependency (1.3.0 and 1.3.1 failed to install with VERSION_NOT_FOUND on an economyKit pull that was never published). - **1.3.1**: building art survives scene loads. The runtime meshes and materials the art cache builds (and the parts lists it hands buildPlaceKit) are held with `renderer.hold`, and cache entries naming a released mesh or material are rebuilt, so a building drawn after a root scene load no longer shows error markers or a disabled Model. Dependencies pin the published economyKit 1.1.0. - **1.3.0**: team buildings for RTS games. A building takes a `team` (`Production.building{ team = "team1" }`, or the ProductionBuilding component's new `team` field): only players the game put on that team (`Production.setTeamOf`, or `setup{ teamOf = fn }`) may queue, cancel, upgrade or pause it, others are refused with "That building belongs to another team", and its currency costs are charged to and refunded from the team's shared economyKit account (`setup{ teamAccount = fn }`, default `"acct:" .. team`; needs economyKit 1.1.0). A team building with no town works with the team's own town `"team:<team>"`, whose coins go to the team's account. `Production.queueFor` / `cancelFor` queue and cancel on the works' machine with no player (a computer opponent). `defineBuilding` takes `base` (start from another kind), `jobs` as a list, `slots` and `art` (draw it as one of the kit's kinds), and `category = "trainer"` draws as a barracks, so a game's own unit types train in a barracks in both looks. `jobDone` (and `works.jobDone`) carry the building's id, team, kind, position, yaw and a door point. The queue panel checks a team building's jobs against the team's account, not the player's wallet. Worlds that use no teams behave exactly as in 1.2.1. - **1.2.1**: the showcase's "Try the styles" panel takes real mouse clicks and highlights the button under the pointer. It used to sit under buildPlaceKit's build HUD, which swallowed every click and hover, so with a real mouse none of its buttons did anything. It now sits at screen layer 140, and Known limits says how to keep your own screens clear of the same problem. The kit's own code is unchanged from 1.2.0 apart from its version number. - **1.2.0**: town names. The report card (the one welcome-back screen that names the town) shows a readable, translatable name instead of the town's id: "Millbrook School of Industry" rather than "main School of Industry". A game names its towns with `setup{ townNames = { ... } }`, a world translates them with `productionkit_ui.town.names.<id>`, and `Production.townName(id)` gives the name for a game's own screens. In the showcase, the report card preview's sample has busy numbers, so it shows real grades, and the "Try the styles" panel moves under the timeline queue panel instead of being covered by it, on a desktop window and on a phone. `REUSE_REVIEW.md` now says what was built new for productionKit, and its economyKit part agrees with its saveKit part. Built on @builtin 9568615. - **1.1.9**: Known limits corrected. Issue #14448 is about two sessions of one account clashing so one player is not spawned, and #20750 about multiplayer sends costing 14 to 46 ms of every frame (around 10 frames per second in the browser); 1.1.7 had pinned those numbers to two other problems, which are now described in their own words without a number. The reuse review lists the saveKit version installed (1.3.0). - **1.1.8**: the card welcome-back screen fits a phone held sideways: it goes side by side (coins left, goods and Collect right) whenever the stacked card would not fit the height, and keeps the goods to rows that leave Collect on screen. The list and slot-bar queue panels never miss a click: the running job's bar or slot fills by itself, so the panel redraws only on whole seconds, and it never redraws while a press is held, so the press and the release always land on the same button however slow the frames are. - **1.1.7**: saveKit is the way progress is saved: each player's record (and their own town, per player) lives in their saveKit profile, the works hands it over and reads it back, and a save changed by hand is refused by its fingerprint (`save = true` is the default; passing `require("saveKit.save")` as in 1.1.6 still works). Two new welcome-back screens, **treasure chest** and **report card** (a grade per building for how busy it was), and a new **timeline** queue panel. Every word a player reads is translatable through the engine's i18n catalogs (`locales/en/productionkit.json` and `productionkit_ui.json`). The showcase gallery is four rows of six with large labels and headings clear of the buildings. A versions table, a reuse review (`REUSE_REVIEW.md`), and the open issues in Known limits. No long dashes in any text. - **1.1.6**: the welcome-back screen counts the coins earned while you were away even when you arrive before the first payout (found in a fresh world: the card listed goods made but no coins). - **1.1.5**: installs into a fresh world and the first example runs as written. The works greets every connected player by itself about once a second, so the welcome-back screen shows even when a hello is lost or the works restarts at the start of play. saveKit is now optional and passed in (`setup{ save = require("saveKit.save") }`); economyKit still brings it. - **1.1.4**: saveKit is pinned again (1.2.1, the version economyKit uses), so the kit installs into a fresh world. - **1.1.3**: installs into a fresh world. The building looks take their oak, thatch, stone and hull-panel materials from buildPlaceKit's own styles (which its install brings, pinned), and draw brick, tile, slate, plaster, concrete and painted panels with the kit's own materials, so nothing the kit names is left without a version. (1.1.2 tried listing the material collections as dependencies; that did not install.) - **1.1.1**: built on the current engine library (@builtin 04d1bd5). - **1.1.0**: two players at once, made sure. The works no longer mistakes a late echo of its own write for tampering (it remembers its last few writes per record, and its own machine reads its writes directly); records carry a rising revision; what a machine sees is its own module (`productionKit.view`), and a new test runs the works' machine, a second player and a late joiner side by side on a store whose changes arrive late. Offline time is stamped when play ends, so Stop, wait, Play counts the wait; a player's first hello waits for the works to start; building data assets use lists of `{ resource, amount }`. 24 tests. - **1.0.0**: first release.
▲ 0↑ born
▣
module · born here
❒asset
# catalog (productionKit) Every resource, building kind, look and display style productionKit knows, as data: `local Cat = require("productionKit.catalog")`. Holds the kit's twelve kinds (farm, lumber mill, mine, sawmill, smelter, bakery, market, house, warehouse, barracks, power plant, research lab) and their resources, adds a game's own with `defineResource` / `defineBuilding` or from data assets bound to the `productionKit.resource` / `productionKit.building` contracts, resolves names and aliases (`kindId`, `lookId`, `displayId`, `welcomeId`, `queueId`) and works out upgrade costs and speeds. Used by every other part of the kit; games reach it through `productionKit.production`.
▲ 0↑ born
▣
module · born here
❒asset
# works (productionKit) The one authoritative machine that runs every building: `productionKit.production` starts it on the machine running economyKit's bank (the lowest peer). It owns the simulation, answers players' requests (queue, cancel, upgrade, pause) after checking they may use the building and can pay, charges and refunds money through the bank, pays what buildings earn into members' wallets, catches up the time nobody played (offline earnings, capped), keeps towns, buildings and members in the world's shared runtime data (where every machine and every late joiner reads them) and puts back any record someone else writes there. Everything outside it comes in through an `env` table, so the tests run it against a fake store, players and bank.
▲ 0↑ born
·
datatype · born here
❒asset
# building (productionKit contract) One kind of production building: what one cycle takes and gives and how long it lasts, what storage it adds, what jobs it queues, what it costs to build and upgrade, and how big it is. Add a `.data` asset bound to `productionKit.building` anywhere in a world and productionKit finds it by itself; it is drawn in any look and shown by any display like the kit's own twelve kinds. (Several recipes on one building, like the market's, are made from code with `Production.defineBuilding{ recipes = ... }`.) | Field | Meaning | |---|---| | `id`, `name`, `description` | The kind's id (what scenes write in `kind`), and the words players read. | | `category` | `producer`, `converter`, `market`, `housing`, `storage`, `military`, `power` or `research`. Producers work first in each step, markets last, so a chain flows in one step. | | `inputs`, `outputs`, `every` | One recipe: take `inputs` from the town's stock, wait `every` seconds, put `outputs` in. Each is a list of `{ resource, amount }`. A producer has no inputs. | | `storage` | What it adds to the town's limits: `{ resource: all, amount: 100 }` raises every limit. | | `queueSlots`, `jobs` | A queue of jobs made one after another: each job `{ id, name, time, costResource, costAmount, outputResource, outputAmount }`. | | `size` | Footprint and height in metres `[w, h, d]`. | | `cost` | What it costs to place in build mode (buildPlaceKit), a list of `{ resource, amount }`. | | `upgradeCost`, `upgradeGrowth`, `upgradeSpeed`, `upgradeMax` | Coins for level 2, how much more each level after costs, how much faster each level works, and the top level. | ```yaml contract: productionKit.building values: id: quarry name: "Quarry" category: producer outputs: [{ resource: stone, amount: 1 }] every: 3 size: [6, 4, 6] cost: [{ resource: coins, amount: 40 }] ```
▲ 0↑ born
·
datatype · born here
❒asset
# resource (productionKit contract) One thing a town makes, stores and uses: wheat, wood, planks, power, soldiers, or a currency buildings pay out (coins). Add a `.data` asset bound to `productionKit.resource` anywhere in a world and productionKit finds it by itself. | Field | Meaning | |---|---| | `id` | The name code and building recipes use (`"planks"`). | | `name` | What players read. | | `icon` | A short glyph used where no drawn icon exists. | | `color` | Accent colour for badges, bars and floating numbers. | | `cap` | How much a town keeps before warehouses raise it. | | `uncapped` | No limit at all (units a barracks trains). | | `currency` | An economyKit currency id: amounts made are paid into players' wallets instead of stored (`coins`). | | `order` | Position in the stock bar (lower first). | | `tags` | Free words (`food`, `raw`, `goods`, `units`). | ```yaml contract: productionKit.resource values: { id: stone, name: "Stone", color: "#a0a0a0", cap: 80, order: 9, tags: [raw] } ```
▲ 0↑ born
backing path · productionKit.package/production.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.