Log inGet started
Package

townKit.package

This package holds more than this page lists. See all of its files in its world.

README.md

townKit: city builder and idle town kit

Grow a town from an empty plot in a forest clearing to a capital city, in any multiplayer Zero world. Place house plots and settlers move in when the town is a nice place to live, build a hut, and improve it to a cottage, a townhouse and a manor as wells, clinics, taverns, schools, temples, parks, fountains and statues cover their street. Happy towns pay more taxes; production chains (farms → bakeries → markets) sell for coins; the town climbs from hamlet to village, town, city and capital, each rank unlocking new buildings; and when you come back tomorrow a welcome-back screen tells you what your town earned and how it grew while you were away.

Version 1.1.7 (Town.VERSION).

townKit holds only what is special about city builders. Everything else is an installed kit, one copy of each. Installing townKit brings them all; the versions are the ones this release was built and tested with (tests/thrivingTown in the Thriving Town world checks them).

KitVersionWhat townKit uses it for
rangeKit1.0.1every service and decoration covers the homes within its range (circle, square, diamond …, with falloff); the area shows while you place a building, and O shows any need's coverage over the whole town
productionKit1.4.0farms, lumber mills, bakeries, markets, warehouses …: production chains that sell for coins, the bread homes eat, offline catch-up for production, big idle numbers
buildPlaceKit1.0.34placing every building with a green/red ghost (press B), prices, refunds, pieces kept between sessions; its draw and allow hooks draw town buildings and lock them until the rank that unlocks them
economyKit1.2.11coins, wallets and the bank: the one machine that runs the town (arrives with productionKit)
saveKit1.3.10each player's last visit, for their own welcome-back screen (arrives with economyKit)
unlockLadder1.0.0runs the town's ranks: each rank is a step whose goal is "this many people at this happiness" and whose reward unlocks buildings and house tiers; its progress is kept in the shared town record, so every player sees one rank
barsKit1.4.6the happiness meters in every status display
scoreKit1.4.8a bonus on the leaderboard each time the town ranks up
gridKit1.0.13grid snapping under buildPlaceKit (arrives with buildPlaceKit)

The showcase world adds the scenery and the look, which a town of your own can swap for anything:

KitVersionUsed for
clearedForest1.0.0the forest ringing the clearing, kept clear where the town grows
forestKit0.3.1the forest's trees, atmosphere and footsteps (arrives with clearedForest)
worldClockKit1.6.8the shared day and night clock
styleKit1.8.3the stackable art-style look
toonBlocks1.4.5the warm look's blocks (soft wrap light, warm fill, pencil line, vignette, grain)

Quick start (about five minutes)

  1. Install townKit from ZeroMind into your world (ZeroMind panel → search "townKit" → Install, or zero zeromind installAsset cf997c56-c911-4498-95e5-93e7b5733140). It brings every kit above, about sixty parts in all, in about two minutes. Let it finish (the ZeroMind panel stops showing kits arriving) before step 3, so the scene is built with everything in place.
  2. Make an empty scene to grow the town in: zero scene create --startup main empty (or New Scene → Empty in the editor).
  3. Put one line in it. Replace everything in scenes/main.scene/build.luau with:
function content()
    require("townKit.town").scene("forestClearing", { status = "ledger", mood = "faces", rules = "classic", welcome = "ledger" })
end

Then turn the scene's player on: zero scene player spawns (or Scene → Player → Spawns in the editor). The empty template starts as a scene nobody plays, and without this step Play shows nothing; with the town already in the scene, it keeps the town's own player and spawn and adds nothing.

Town.scene builds the starter town (the clearing, the forest around it, a first well, hut and flower bed), the sun and sky, and a player standing at the town's edge facing it. If the build ran while kits were still arriving, the town adds its build zone itself when you press Play (the log says so); save build.luau again to keep it in the scene. Already have a scene with its own light, sky and player? Use Town.starter(...) with the same options instead, take any ground of your own out from under the town, and put your spawn at the spawn it returns.

  1. Press Play, then press B to build. Pick the House Plot and place it a few steps from the well, inside the well's ring (press O to see how far water reaches), then put a Flower Bed beside it. Settlers move in within seconds; stand beside a home to see its card (people, happiness and what it needs next). =/− change taxes.

Gamepad: the left stick walks (and moves the build cursor), Y builds, RT places, B closes, the d-pad left/right changes taxes, d-pad up upgrades the home you stand by, View shows coverage. Touch: the Build button and the buttons on the town banner.

One setting each

FamilyChoices
Starter town (plot, layout, climate)forestClearing (sunny beech clearing), riversideMarket (river and bridge, misty mornings), hilltopTerraces (stone terraces, autumn), winterHollow (snowy birch hollow by a frozen pond), desertOasis (spring-fed pool on a hot plain), scifiColony (landing deck, alien dust storms)
Town laddershort (Hamlet → Town → Capital), standard / medieval (Hamlet → Village → Town → City → Capital), long (eight ranks up to Capital), scifi (Outpost → … → Capital World), cozyHamlet (four small ranks)
Happiness rules, gentle to demandingrelaxed (also gentle), classic, strict, demanding, and idle (nobody ever leaves)
Town info displayledger (storybook parchment), card (clean modern), cartoon, pixel, minimal, banner (carved wood), hologram
How a home feelsfaces, colourRings (a ring on the ground), icons (floating icon of what it misses most), chimneySmoke (white, grey or dark smoke), hearts, thumbs, roofColour, pixelEmotes, scifiSymbols
Welcome-back screen (productionKit's)ledger (parchment report with a seal), card, toast, chest (treasure chest), report (report card with grades)
Coverage overlayany rangeKit look: heatTiles, rings, chalk, glow, pixel, hologram, runes, wash

Change them on the townKit.Town component, in Town.starter(id, opts), or live with Town.setStatus, Town.setMood, Town.setRules, Town.setOverlay.

Buildings

Homes: House Plot → Hut (3 people) → Cottage (6, needs water) → Townhouse (12, water, health, bread) → Manor (20, water, health, fun, education, faith, bread). Services: Well (water), Clinic (health), Tavern (fun), School (education), Temple (faith), Watchtower (safety). Decorations (beauty): Flower Bed, Tree Grove, Lamp Post, Park, Fountain, Gazebo, Statue, Clock Tower, Grand Monument. Every one is drawn in a rustic and a sci-fi look.

Multiplayer, saving, offline

The town runs on its owner's machine. Each machine announces its account, whether the world lets it save, and the town owner it knows (the account that first saved the town); every machine then picks the same one to run the town, the bank, the buildings and the saved pieces: the owner's, else one that can save, else the room's host. Only the owner's machine writes the saved town, so a friend who can play but not edit builds and grows the same town through the owner's machine and never overwrites it. The running machine also sends the town to every machine, so everyone in the room (and anyone who joins late) sees the same homes, people, happiness and rank, even before their own copy of the world's saved data has arrived. The town is still there after the world restarts. When the works starts after nobody played, it catches the town up (up to the rule set's offline cap) and every member is paid what the town earned. Coins earned while you were away always reach your wallet: if it is not ready the moment you arrive, the town keeps them owed and pays them a moment later. The welcome-back screen shows after an absence of a minute or more, or whenever the town earned something for you while you were gone (20 seconds or more). It is one of productionKit's welcome-back screens (the welcome setting picks which), showing everything together: the time away, every coin earned (taxes and market sales), the goods made, and lines for the town (population and happiness before and after, homes that grew, a new rank, the share that came from taxes), compared with your own last visit (kept in your saveKit profile). Your time away is measured by the town's works from the last moment it saw you until your machine says hello.

Guides

  • how-to-make-a-city-builder-or-idle-town-game: how to make a city builder or idle town game with townKit.
  • example-add-a-new-building-and-a-new-upgrade-tier: a worked example: a Bakery Stall service and a Mansion tier.