Log inGet started
Package

productionKit.package

README.md

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

PackageVersionWhat productionKit uses it forWhat its install brings
economyKit1.0.13coins, wallets that keep between sessions, and the bank: the one machine that decides every payment, which also runs every buildinginventoryKit, menusKit, navUiKit, saveKit
buildPlaceKit1.0.18placing 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 withgridKit, juiceKit, and the wood, stone, masonry and sci-fi material collections
saveKit1.3.0each 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:

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:

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

idnamewhat one cycle doesevery
farmFarmmakes 1 wheat2 s
lumberMillLumber Millmakes 1 wood2 s
mineMinemakes 1 ore3 s
sawmillSawmill2 wood → 1 plank3 s
smelterSmelter2 ore + 1 wood → 1 metal4 s
bakeryBakery2 wheat → 1 bread3 s
marketMarketsells 1 plank for 6 coins, else 1 metal for 15, else 1 bread for 42 s
houseHouseeats 1 bread, pays 5 coins rent6 s
warehouseWarehouseraises every limit by 100 (×1.5 a level)no cycle
barracksBarracksa 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
powerPlantPower Plantmakes 2 power2 s
researchLabResearch Lab3 power → 1 research5 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

FamilyChoicesSwitch with
Building kindthe twelve above, or your owna building's kind (scene line or the ProductionBuilding component's field)
Lookrustic (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 definesa building's look; Production.setLook(id, look)
Display above a buildingring (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), noneProduction.setup{ display = ... }, a building's display, Production.setDisplay(id or nil, style)
Big numbersshort (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 screencard (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.notesProduction.setup{ welcome = ... }, Production.setWelcomeScreen(style)
Queue panellist (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

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:

    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:

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

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.

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

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.