Log inGet started
Package

townsfolkKit.package

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

README.md

townsfolkKit

Fill any town, village, farm or market with people who live out their day. Each townsperson has a role and a daily schedule written by the hour as plain text (6:00 open the stall, 12:00 eat at the tea house, 18:00 home) on the world's shared day and night clock, so every player sees the same person doing the same thing at the same time. You place activity spots (a bench, a market stall, a shrine, a well, a paddy row and 11 more kinds) and people walk there and visibly do it: sit, haggle, sweep, pray, carry sacks, tend rice, drink tea, queue, draw water, fish, juggle, beg, stand watch. Groups (a family, a line of porters, a procession of pilgrims) walk and stop together, and a player can walk along hidden inside one. When something goes wrong (a loud noise, a body in the street, an alarm, a drawn weapon) people react by temperament: they gawk and point, run away and cower, run to the nearest watchman to report it, or hide indoors, and afterwards they settle back into their day. Generated bodies come in three looks (realistic, painted, toon) and the whole crowd switches with one setting. Crowd level of detail keeps 40 people smooth; people go home at night without piling up or leaking. Multiplayer from the start.

Version 1.2.8 (TF.VERSION). The version in this README, package.yaml and TF.VERSION move together.

Built on installed kits, not rewritten: navKit (walking, paths, avoidance, crowd networking), aiKit (its noise bus, so every gunshot or thrown bottle another kit makes startles townsfolk, and its guards can be reported to), worldClockKit (the shared hour), soundstage (voices and market chatter), interactKit (house doors) and humanBodyKit (the generated bodies, a separate package from this world). One install brings them all.

Quick start

This works as written in a brand-new world.

1. Install townsfolkKit.package into /source (search ZeroMind for "townsfolkKit", or "fill my town with people who follow a daily schedule"). Its dependencies come with it.

2. Add to scenes/main.scene/build.luau. At the very end of function content(), just before its end (the new-world scene already has the ground, the light and the player). A world made some other way (with zeromind.create, say) may have no scenes/main.scene yet: make the same starter scene first with tools.use("scene", "create", "main", "player", { startup = true }) (in the shell: zero scene create main player), which gives ground, light and the default player.

	-- the shared clock: a whole day in 6 minutes, starting at 7 in the morning
	entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 6, startHour = 7 })

	-- the ground people walk on (baked when play starts)
	entity.spawn("NavMap").component.add("navKit.NavMap", { kind = "grid", size = { x = 40, y = 6, z = 40 } })

	-- a little square: a stall, a bench, a well, a shrine, somewhere to chat, a yard, a playground, a watch post
	local function spot(name, kind, x, z, yaw)
		local e = entity.spawn(name, { position = { x, 0, z }, rotation = { 0, math.sin((yaw or 0) / 2), 0, math.cos((yaw or 0) / 2) } })
		e.component.add("townsfolkKit.ActivitySpot", { kind = kind })
	end
	spot("Stall", "stall", 6, 6, math.pi)
	spot("Customer", "shop", 6, 4.6)
	spot("Bench", "bench", -6, 6)
	spot("Well", "well", 0, 10)
	spot("Shrine", "pray", -8, -6)
	spot("Gossip", "chat", 3, -6)
	spot("TeaSeat", "teahouse", -3, 12)
	spot("Yard", "sweep", 10, -6)
	spot("Playground", "play", -2, -10)
	spot("WatchPost", "watch", 0, -16)

	-- two homes to go to at dusk (doorsteps facing the square)
	entity.spawn("HomeA", { position = { 12, 0, -4 } }).component.add("townsfolkKit.Home", {})
	entity.spawn("HomeB", { position = { -12, 0, 2 } }).component.add("townsfolkKit.Home", {})

	-- six townsfolk, and the look of the whole crowd in one field
	entity.spawnSynced("Town").component.add("townsfolkKit.Town", {
		look = "painted", count = 6, roles = "merchant, elder, servant, monk, child, watchman",
	})

3. Press play. Six people appear where their day has them at 7:00: the elder prays at the shrine, the merchant opens the stall and calls to passers-by, the servant draws water at the well and then sweeps the yard (and later goes shopping and haggles at the stall), the monk prays and then sweeps, the child fetches water and then plays, the watchman stands at his post. At noon they eat at the tea house; at dusk they walk home and vanish inside, and at dawn they come out again. Change look = "painted" to "toon" or "realistic" and the whole crowd changes.

Now cause some trouble from the scene's entrypoint.luau (or the console while playing):

local TF = require("townsfolkKit.api")
TF.noise({ 0, 0, 6 }, 30)                 -- a bang: the timid flee, the nosy come to look
TF.knockOut("Townsfolk 02")              -- a body: people find it and run to the watchman
TF.on("reported", function(e) print(e.name .. " told " .. e.guardName .. " about a " .. e.kind) end)

What you get

piecewhat it is
townsfolkKit.apithe one interface: local TF = require("townsfolkKit.api")
Townsperson componenta person: role, temperament, look, schedule, home, group, outfit, seed, hat, colors (put it on a synced entity)
ActivitySpot componenta place people go to and do something: kind and its slots
Home componenta doorstep people go in at night and to hide; names an optional interactKit door
TownGroup componentpeople who walk and stop together; players can walk inside
Town componentone per scene: the whole crowd's look, LOD distances, an optional crowd to spawn
TownChatter componentmarket chatter that swells and fades with the crowd around it
townsfolkKit test suitethe catalog, schedules, spots, queues, stimuli and groups
two guidesthe how-to and a step-by-step example level (below)

Roles

Every role is one setting (role = "fisher"), with its own outfit, pace, temperament and day.

idoutfit and mannerdefault temperamentdefault day
farmhandstraw hat, rolled sleevescalmwell 5:30, paddy 6:00, tea house 11:30, paddy 12:30, chat 17:30, home 18:30
porterheadcloth, sash, quickcalmgate queue 5:30, carry sacks 6:00, tea house 12:00, carry 13:00, bench 18:00, home 19:00
merchantrich robe, capnosystall 6:00, tea house 12:00, stall 13:00, home 18:00
monkrobe and hood, slowcalmpray 5:00, sweep 8:00, pray 11:00, beg 12:30, pray 15:00, home 18:30
pilgrimtravel cloak, stafftimidgate queue 6:00, pray 7:00, well 10:00, tea house 11:00, pray 13:00, shop 16:00, home 18:00
childsmall, fasttimidwell 7:00, play 8:00, tea house 12:00, play 13:00, watch the show 16:00, home 17:30
elderstooped, slowcalmpray 7:00, bench 9:00, tea house 12:00, chat 14:00, bench 16:00, home 17:30
servantapron, headscarfinformerwell 5:30, sweep 6:30, shop 9:00, sweep 11:00, shop 14:00, carry 16:00, home 19:00
fisherwide hat, rodnosyfish 5:00, stall 10:00, tea house 12:00, fish 13:30, chat 17:30, home 19:00
entertainerbright clothesnosychat 8:00, perform 10:00, tea house 12:30, perform 14:00, tea house 18:00, home 20:00
beggarrags, bowlinformerbeg 6:00, well 11:30, beg 12:30, bench 17:00, home 19:30
watchmanhelmet, spear(watch: investigates)watch post 6:00, tea house 12:00, watch 12:45, home 20:00
soldierlacquered cuirass, flat war hat, spear(watch: investigates; a guard reports go to)watch 5:30, patrol the post 9:00, tea house 12:00, watch 12:45, patrol 16:00, home 20:00
samurairetainer: wide sleeves, split skirt, shoulder vest, sword sheathed at the left hip; stands guard empty-handed(watch: investigates; a guard)guard 6:00, stroll the inner court 9:00, guard 10:30, tea house 12:00, stroll 13:00, guard 14:30, home 19:30
cookapron, rolled sleeves, headwrap; carries jarscalmwell 5:30, stall:kitchen 6:00, carry 10:00, stall:kitchen 11:00, tea house 14:00, stall:kitchen 15:00, home 20:00
teaServantfitted robe, broad sash, hair bun; serves standing with a tray and bows at tea house seats, carries traysinformersweep 6:00, serve at the tea house 7:30, carry trays 11:00, tea house 12:00, sweep 15:00, tea house 16:00, home 21:00

Hats and liveries

Two optional synced Townsperson fields dress a person beyond their role (both are one-line text, so a player who joins late gets them whole; TF.addPerson(e, { ... }) takes them too):

fieldformatempty
hata humanBodyKit hat part: hat_straw, hat_turban, hat_headwrap, hat_hood, hat_skullcap, hat_fez, hat_helmet, hat_jingasa (flat lacquered war hat), or none for bareheadedthe seed picks from the outfit's hats
colorsslot=#rrggbb entries split by ; (or ,), e.g. main=#2b3a67;second=#d9c9a3;accent=#b03a2e. Slots: main, second, accent, hat, leather, dkleather, metal, strawthe seed picks from the role's palette

The seed still varies each face, skin, hair, height and build, so a crew of porters in one livery reads as a crew of different people:

for i = 1, 6 do
	local e = entity.spawnSynced("Porter " .. i, { position = { i, 0, 0 } })
	TF.addPerson(e, { role = "porter", seed = i, hat = "hat_skullcap", colors = "main=#2b3a67;second=#d9c9a3;accent=#b03a2e" })
end

A bad hat name or colour string is warned about and the person is dressed from their seed instead. Changing either field re-dresses the person on every screen.

Schedules

A schedule is text, one change per line (or ; between them). The time comes first (6, 6:30, 6am, 6:30 pm); the words after it name the activity, the last named one winning, so you write it the way you would say it:

p.component.add("townsfolkKit.Townsperson", { role = "merchant", schedule = [[
5:30 draw water at the well
6:00 open the stall
12:00 eat at the tea house
13:00 back to the stall
17:00 pray at the shrine
18:00 go home
]] })

Activities are the 16 spot kinds (by their words: "tea house", "eat", "lunch" and "drink" all mean teahouse; "gate", "queue" and "line" mean queue...), home ("sleep", "go home") and wander ("stroll"). End a line with kind:tag to pick spots with that tag: 6:00 open stall:fruit. TF.parseSchedule(text) answers the entries and any line it could not read; a Townsperson reports a bad line in its errors. The hour is worldClockKit's shared clock (with no WorldClock in the scene the clock still runs from its defaults).

What happens at each entry: the person picks a free slot at a spot of that kind (their favourite first, so a merchant keeps their stall; an owner on a spot reserves it), walks there and does it until the next entry. Queue kinds (queue, well) are joined at the back and shuffle forward; at the front the person does the thing, then strolls until their next entry. With no free spot they stroll nearby and try again.

In multiplayer, write a schedule on one line ("6:00 open the stall; 12:00 eat at the tea house; 18:00 go home"): a synced text field written over several lines reaches a player who joins late without its later lines (engine issue #25558). The kit rewrites a multi-line schedule as one line on the peer that runs the person, so both forms work, but one line depends on nothing.

Activity spots

kindwhat people dopropslots
benchsit and watch the street2
stallmind a market stall, call out, haggle with customers1
shopbrowse a stall's goods and haggle (place in front of a stall)basket2
sweepsweep back and forth over a yard (radius)broom1
praykneel and pray, bowing now and thenbeads3
carrycarry sacks to the drop-off (toOffset or to) and backsack2
paddybent over, planting and weeding along a row (radius)2
teahousesit at a table, sip tea, eatcup1
queuewait in line at a gate (order 1 = front)bundle1
welldraw water hand over hand; others queue behindjar1
fishfish at the water's edgerod1
performjuggle and dance; strollers stop to watch and clapballs1
begsit by the road holding out a bowlbowl1
watchstand watch with a spear (where reports are run to)spear1
chatstand in a little circle and gossip4
playchildren run and skip about (radius)4

A person at a spot faces the spot's forward (-Z): turn the entity to turn them. Fields: kind, slots (0 = the kind's own), tag, order (queues), owner, radius (roaming kinds), toOffset / to (carry), label, active. From code: TF.addSpot({ x, y, z }, "well", { yaw = 0, order = 1 }).

Reactions and temperaments

Four stimuli, each made from any peer:

stimulushowreaches
loud noiseTF.noise(pos, metres or "explosion"), or any aiKit noise of 9 m and up (gunshots, bottles, explosions from other kits)its loudness
body in the streetTF.knockOut(person) (they fall and lie there) or TF.addBody(entity or pos)13 m, in sight
alarmTF.alarm(pos)40 m
weapon drawnTF.weaponDrawn(entity, true) while it is out (any entity: a player's avatar, a townsperson, a guard), false to sheathe; each draw is news again to people who saw the last one12 m, in sight

Each person meets each stimulus once, by their temperament (one setting, temperament = "timid", swappable at any time):

temperamentnoisebodyalarmweapon
calmglances overgoes to lookwalks briskly awaywalks briskly away
nosygoes to look, pointsgoes to look, pointsgoes to lookruns away
timidruns away, cowersruns away, cowershides indoorshides indoors
informerruns to the watchruns to the watchruns to the watchruns to the watch

Watchmen, soldiers and samurai (every role with guard = true in the catalog) investigate: they walk briskly to the place, look about, and see to a body (it gets up dazed and goes home for a while). People who report run to the nearest watchman, or to an aiKit guard (preset guard, nightwatch or sentry, or team guards), point the way, and the guard is sent there (AI.alert). A stronger stimulus interrupts a weaker reaction; afterwards everyone settles back into their schedule (settled event). Fleeing people scream, reporters shout for the watch, gawkers gasp, near the camera.

A knocked-out person comes round by themselves after downSeconds (150) if no watchman finds them.

Groups

entity.spawn("Pilgrims").component.add("townsfolkKit.TownGroup", { kind = "procession" })
-- each member: group = "Pilgrims" on their Townsperson (the first by name leads, or set `leader`)
kindformationwhen it stops
familyloose cluster around the leaderchat
friendsloose clusterchat
porterssingle file, each carrying a sackstand
processiontwo by two, slowpray

The leader follows their schedule at the group's pace (a procession walks at 0.7 of the leader's own pace, a family at 0.9); the others keep the formation, walk with the leader from one activity to the next, stop with them, do the group's pose, and go home with them. A player can walk inside a group: step in among the members while they walk and keep up. The formation opens up around a player inside it. When two groups pass close by, a player counts as inside the one whose nearest member is closest. Ask from any peer:

local g = TF.groupOf(player)        -- the TownGroup entity a player walks inside, or nil
if TF.isInGroup(player) then ... end
TF.on("playerJoinedGroup", function(e) print("hidden among " .. e.group) end)   -- the local player

A stealth game uses this to let the player blend in: guards ignore a player for whom TF.isInGroup is true.

Looks

Every body is generated by humanBodyKit in three looks, realistic, painted and toon. Switch the whole crowd with one change, the Town's look field (synced, so every player switches), or TF.setLook("toon"); one person with their own look field or TF.setLook(person, "toon").

Level of detail and performance

The measured cost of each tier is in Performance below.

tierbody (by distance to this screen's camera, within a budget)simulation (by distance to the nearest player, on the peer running the person)
near / fullevery part animated every frame, within lodNear (22 m), the nearest maxFull (6) people only4 decisions a second, navKit pathing with steering round others, reacts to everything, within simNear (35 m)
midfewer parts, animated at 10 Hz, to lodFar (50 m), the next maxMid (12) people only1 decision a second, walks its schedule without steering round others, still reacts, to simFar (80 m)
farone merged shape, no animation: everyone past the distances or the budgeta decision every 4 s, trips are timed instead of walked (they appear at the spot after the walk would take), no reactions
hiddenindoorsindoors: paused, hidden

The budget is what keeps a packed market cheap: however many people stand within 22 m, only the 6 nearest the camera are fully animated and the next 12 run at 10 Hz. Bodies are re-ranked once a second, so nobody flickers between tiers. Change it with TF.configure({ maxFull = 10, maxMid = 16 }) on a fast machine, or lower it for the web.

Multiplayer

  • The host runs the people. The peer that owns a townsperson's synced entity (or the room host while nobody owns it) decides what they do and writes their state fields (activity, pose, prop, facing, mood, indoors); positions travel in navKit's crowd line. Every peer builds the same body from the synced role, seed and look, and poses it from the same fields, so everyone sees the same person doing the same thing.
  • The same hour everywhere. Schedules read worldClockKit's shared clock.
  • Trouble from anyone. TF.noise, TF.alarm, TF.addBody, TF.knockOut and TF.weaponDrawn work from any peer: stimuli go to every peer on townsfolkKit:stim, commands for a person to the peer running them on townsfolkKit:cmd.
  • Players come from the scene's player setup. Reactions, LOD and groups read every player's avatar from layers.active.players.
  • Late joiners receive the spawned crowd as synced entities and draw them at once.

Events

TF.on(name, fn); on the peer running the person unless noted.

eventpayload
activityperson, name, activity, text, hour: a schedule entry began
arrivedperson, name, activity, spot
home, leftHomeperson, name, home
reactedperson, name, kind, response, position, stimulus
reportedperson, name, guard, guardName, kind, position, stimulus
settledperson, name, after
knockedOut, revived, bodyClearedperson, name, by / how
stimulus, stimulusEndedevery peer: id, kind, position, radius, by
playerJoinedGroup, playerLeftGroupevery peer, the local player: group, player
lookevery peer: look
crowdSpawnedthe host: count

API reference (local TF = require("townsfolkKit.api"))

callwhat it does
TF.addPerson(e, opts?)make a (synced) entity a townsperson; opts are Townsperson fields
TF.addSpot(entityOrPos, kind, opts?)place an activity spot (yaw, name, ActivitySpot fields)
TF.addHome(entityOrPos, opts?)place a home's doorstep (yaw, name, door, capacity)
TF.addGroup(name, opts?)a group (kind, members = list of entities or names, leader)
TF.state(person)name, role, temperament, activity, pose, prop, mood, indoors, spot, lod, scheduled, position, down
TF.people(), TF.census(), TF.near(pos, r)every townsperson; how many doing each activity; who is near a point
TF.setRole, TF.setTemperament, TF.setSchedule, TF.setLook(person, look)change one person
TF.setLook(look)the whole crowd's look
TF.noise(pos, loudness?, opts?), TF.alarm(pos, opts?)a loud noise (aiKit hears it too), the town alarm
TF.addBody(at, opts?), TF.knockOut(person, by?), TF.revive(person), TF.isDown(person)bodies
TF.weaponDrawn(entity, on, opts?)a drawn weapon, while it is out
TF.stimuli(), TF.removeStimulus(id)the shared stimulus list
TF.guards()the watchmen, soldiers, samurai and aiKit guards reports go to
TF.groupOf(player), TF.isInGroup(player), TF.groupMembers(group)groups
TF.hour(), TF.parseSchedule(text), TF.scheduleOf(person), TF.formatHour(h)schedules
TF.roles(), TF.spotKinds(), TF.temperaments(), TF.looks(), TF.role(id), TF.spotKind(id), TF.temperament(id), TF.find(q), TF.catalog()the catalog (find({ kind = "spot", tag = "work" }))
TF.on(name, fn), TF.eventCounts()events
TF.stats()people, sim ms, body ms, LOD counts, stimuli, spots, homes, entity count, deferred (people whose decision waited a frame for the think budget)
TF.configure(opts)simNear, simFar, runSpeed, downSeconds, shakenSeconds, lodNear, lodFar, maxFull, maxMid, look

Constants: TF.VERSION, TF.ROLES, TF.SPOTS, TF.TEMPERAMENTS, TF.STIMULI, TF.LOOKS, TF.LODS, TF.GROUP_KINDS, TF.EVENTS, component names TF.PERSON, TF.SPOT, TF.HOME, TF.GROUP, TF.TOWN, TF.CHATTER.

Guides

Two guides ship inside the package:

  • How to fill my town with people who follow a daily schedule and react to noises (townsfolkKit.package/how-to-fill-my-town-with-people-who-follow-a-daily-schedule): every part of the kit, step by step.
  • Build a village market a thief has to slip through (townsfolkKit.package/build-a-village-market-a-thief-has-to-slip-through): an example level built with the kit from an empty world.

Open one with zero guides read <path> in the shell, the guides tool, or the Docs panel.

Tests

tools.use("tests", "run", { suite = "townsfolkKit" }).

Performance

Measured on 2026-11-17 in Mirage Wells (the showcase: 40 townsfolk in a 400 m desert), in play, in the Zero desktop app (dev build, Luau codegen on, 1920x1080; @builtin c8c4c7e until 09:50 UTC, dc6645f after) on a shared Linux machine. That machine's load swung hard while measuring, from every frame on performance cores to every frame on efficiency cores with a third of each frame spent waiting for a core, so each number below says what the machine was doing. Read script time and engine CPU time first (they move least with the load) and frame rates second. In play, the showcase's F3 readout and TF.stats() show the same numbers live on your own machine, a browser tab included.

Before and after (townsfolkKit 1.0.5 + humanBodyKit 1.1.0 + navKit 1.4.5, then townsfolkKit 1.2.6 + humanBodyKit 1.2.2 + navKit 1.5.5 + aiKit 1.3.18)

The "before" kit reported itself as 1.0.5 (TF.VERSION, and the README's version line), though its package.yaml already said 1.1.0; the two were brought together in 1.2.0. 1.2.1 fixes 1.2.0 on navKit older than 1.5.2, where reading navKit's new visualXYZ raised on every body every frame; the kit decides once from NK.VERSION. 1.2.2 and 1.2.3 changed only this section. 1.2.4 hears aiKit's noises the moment they happen (AI.onNoise, aiKit 1.3.18) and depends on the released navKit 1.5.3 and aiKit 1.3.18. 1.2.5 keeps each person's navKit agent instead of looking it up on every think, reads group members' positions without new tables, makes each activity-spot slot's claim key once, and sends events without throwaway tables; with navKit 1.5.4 a standing agent costs almost nothing to draw. 1.2.6 poses a body that casts no shadow only while it can be on screen, makes far meshes only for bodies in view, and depends on navKit 1.5.5 (no transform writes for standing agents). 1.2.7 depends on interactKit 1.6.7 (it was 1.6.3), controlsKit 1.4.7, aiKit 1.3.19, navKit 1.5.6, worldClockKit and @builtin current, so a world installing townsfolkKit beside a kit that pins interactKit 1.6.7 (concealKit, disguiseKit) gets one whole interactKit copy instead of two releases on one path. 1.2.8 depends on humanBodyKit 1.2.3, whose body shader is built on the current engine library, so an install no longer places an older engine shadow module and engine_bindings beside the current ones.

per frame, Mirage Wells, 40 townsfolkbeforeafter
townsfolk scripts (all 40 Townsperson updates)4.1 ms0.8-2.7 ms
navKit agents (all 40 NavAgent updates)3.3 ms1.5-3.0 ms
garbage the townsfolk make101 KB17 KB
kit timers, p50 / p95 (thinking, bodies, posing)1.4 / 7.1, 2.1 / 11.2, 0.9 / 7.4 ms0.4 / 1.0, 0.9 / 3.2, 0.5 / 1.2 ms
frames where the kits took over 33 mssome every minute (worst 156-211 ms)none in 40 s of steady play; none over 20 ms
the engine's sky field rebuilt in the background26 times in one session, about 60 s of work eachonce, when play starts (the engine does this for every scene load)
median frame / fps88 ms, 10.9 fps (94% of frames on efficiency cores, 20% waiting for a core)22.6 ms, 38 fps over 40 s; 26.5 ms, 32 fps on efficiency cores only

What made the difference, biggest first:

  1. Bodies no longer count as level geometry. Every Model humanBodyKit made was mobility = "auto", which the engine resolves to static for anything not moved by physics or an animation component. Bodies move by script, so the engine kept seeing the level change and re-baked its sky-visibility field in a background task: that was most of the "background tasks waking up" and the 150-750 ms hitches. humanBodyKit 1.2.0 makes every body Model movable.
  2. No body is built in one frame. A far body coming close makes its 20-odd parts a few a frame (HB.BUILD_MS, 3 ms a frame across all bodies) and stays drawn by its merged far mesh until they are ready; at most two bodies a frame turn far (fartherPerFrame). Building every part at once cost 75-107 ms on this machine.
  3. Posing writes in bulk. Each posed body sends its 15 joints in one batched write from a typed buffer, and every body root goes out in one batched write a frame, instead of a property write and a new table per joint and per root.
  4. Far meshes are kept. A far body keeps the merged mesh of each pose it has shown (and frees old ones a few frames after letting them go), so walking past the same people does not rebuild their meshes; a body built with its props makes its far mesh once.
  5. Nothing is checked every frame that changes less often, and noises arrive as they happen. Whether a player walks inside a group (5 times a second), the network session (twice a second), a person's schedule text (once a second); aiKit's noises reach the townsfolk through AI.onNoise the moment one lands (until 1.2.3 they asked aiKit for its noise list ten times a second); a person skips looking for trouble while nothing is happening; spot lists and player positions are kept between frames; no per-frame tables in thinking, drawing or groups.
  6. navKit 1.5.2 and 1.5.3 write an agent's pivot only when it moves, answer visualXYZ() without a table, and let a path's straightening pause within the planning budget like the search does.
  7. The showcase's own script. Mirage Wells' day script built its whole HUD again four times a second (and every frame during a chase or while you hold E), and its F3 readout asked TF.stats() every frame even while hidden. The HUD is now built only when something it shows changes, and the readout registers its line once, changes the text in place and reads the kits' own timers. The day script went from 2.4-3.6 ms and 60-104 KB of garbage a frame, the heaviest script in the scene, to about 1 ms with no measurable garbage.

Where a townsperson's time went before

Measured before any of this (townsfolkKit 1.0.5, 2026-11-17 03:05 UTC, 94% of frames on efficiency cores, about 20% of each frame waiting for a core). A 6-second call-stack sample at 1 kHz of the 40 townspeople, inclusive time:

parttime in 6 swhat it was doing
Townsperson.update, all of it598 mseverything below
body view (bodyview)410 msdrawing the 40 bodies
of it, level of detail switching (HB.setLOD)161 msmaking a body's 20-odd parts in one frame (_materialize, 68 ms) and a new merged far mesh at every pose change (_buildFar, 74 ms)
of it, posing (HB.update)114 msa property write and a new table per joint (_apply, 78 ms)
thinking (sim.tick)155 msdecisions (think, 73 ms) and groups (60 ms, asking every member's position every frame)
path finding and walking (NavAgent.update)518 msnavKit's crowd tick 337 ms (path planning 125, stepping agents 153) and drawing each agent's pivot (applyVisual, 131)

Per frame that was townsfolk scripts 4.1 ms and navKit 3.3 ms, with 101 KB of garbage. Background tasks: about 8 coroutines resumed each frame, none of them the kits' own (the engine's input tick, its renderer clean-up, the scene loader, saveKit now and then; the kits' own were door-close delays, a couple a minute). The costly one was the engine's sky-visibility rebuild, which the bodies set off (point 1): 26 rebuilds of about 60 s each in one session, 4-70 ms a frame. Now one sky task and the editor's own tasks resume, and the sky field is built once when play starts.

Every role, activity, temperament, look, outfit, group, reaction and the night watch behave as before; the kit's tests (15) and humanBodyKit's (33, four of them new for this release) pass, and a two-player check after the change saw the same 40 people doing the same things on both screens (activities, a knock-out, a firecracker, a drawn blade, the night watch at midnight, the whole crowd's look switched by the room host).

How much of the frame is the crowd, and what stands between it and 60 fps

Back to back in the same session at market hours (12:40 in the game, 2026-11-17 about 10:35 UTC, 85-100% of frames on efficiency cores, 28-34% of each frame waiting for a core), with the 40 townsfolk switched off and on again. The engine's own CPU time per frame (its thread clock, which leaves out the waiting):

engine CPU p50 / meanframe p50fps runhost-bound fps (the machine to itself)
no townsfolk14.3 / 16.0 ms20.4 ms3953
all 40 townsfolk, townsfolkKit 1.2.4 + navKit 1.5.320.4 / 22.5 ms25.4 ms3146

Measured again for 1.2.5 + navKit 1.5.4 (2026-11-17 about 11:00 UTC, 13:00-14:00 in the game, every frame on efficiency cores, 14-20% of each frame waiting for a core), crowd off and on back to back:

engine CPU p50 / meanframe p50fps runhost-bound fps
no townsfolk12.2 / 13.1 ms17.3 ms5576
all 40 townsfolk18.3 / 19.1 ms20.3 ms4552

What 1.2.5 and navKit 1.5.4 changed, from 8-second call-stack samples at market hours: navKit's per-agent updates fell from 609 to 387 sampled ms (the visual step of a standing agent no longer shows) on a busier machine, the townsfolk's from 507 to 464, and the navKit agent lookups each think made went away. The memory burst on the hour is gone: in the three windows right after 13:00, when all 40 pick a new activity, the townsfolk made 0-1.3 KB of garbage a frame, against 122-137 KB with 1.2.4 (most of it was a fresh string per activity-spot slot checked, plus event tables nobody read). The F3 readout no longer moves memory: shown and hidden for 12 s each, twice, the engine's memory changed by -2.4 to +7.7 MB while it showed and -2.0 to +1.3 MB while hidden, with the Luau heap falling while it showed.

Measured again for 1.2.6 + navKit 1.5.5 (2026-11-17 about 12:30 UTC, 13:00-14:00 in the game, 91% of frames on efficiency cores, 12-18% of each frame waiting for a core), crowd on and off twice, back to back:

engine CPU p50 / meanframe p50fps runhost-bound fps
no townsfolk12.4 / 13.0 ms, 13.1 / 13.8 ms16.7, 17.4 ms53, 5277, 73
all 40 townsfolk18.3 / 19.7 ms, 18.9 / 19.9 ms20.4, 20.7 ms42, 4351, 50

Then three one-minute runs with all 40 at market hours, the way the person who asked for 60 fps measured (they read 32, 40 and 48 fps with 1.2.5): 42.5, 37.7 and 37.1 fps (frame p50 19.9, 21.9, 22.6 ms). Earlier the same day, on a quiet stretch (77% of frames on performance cores, 3% waiting), 85 seconds with all 40 ran at a 16.2 ms median frame, 59-62 fps, with the crowd adding about 1.6 ms of engine time (10.6 against 9.0 ms); that was 1.2.5 with navKit 1.5.4.

What 1.2.6 and navKit 1.5.5 changed. A body that casts no shadow at its detail and stands outside the camera's view (tested against the frustum the renderer culls with, padded well past the body) is no longer posed until it comes into view, a far body off screen does not make a new merged mesh until someone can see it, and a mid body walking out of range off screen turns far once it is back in view; the pose is worked out from time, so a body shows the right shape the moment it appears. navKit no longer writes a transform for an agent that has not moved or turned since its last write. Merged far meshes made: 6-16 a minute at market hours. The crowd's steady cost moved by less than the machine's noise.

60 fps was not reached on this machine, and the crowd is what stands in the way here. Without a single townsperson the scene fits a 60 fps frame (12-13 ms of engine time, 52-55 fps run and 73-77 fps with the machine to itself, the rest being the editor's own camera and panels, which a published play session does not have); all 40 townsfolk add about 6 ms of engine time a frame at market hours on this loaded machine and about 1.6 ms on a quiet stretch. Of those 6 ms the kits' scripts are about 2.5-3.5 ms (navKit stepping and steering 40 agents, thinking, posing the 6 full bodies every frame and the visible mid ones ten times a second) and the rest is the engine moving and drawing what they produce: about 400 body parts and the posed joints' transforms. What would take the crowd under the 60 fps line on this machine without changing what anyone sees is mostly engine work (cheaper posing of many joints, which the engine's animation work is about) rather than more kit work. On a slower machine, the budget (maxFull, maxMid) changes how many people are fully animated, which is visible up close. Earlier measurements put the crowd at 1.5-3 ms; those were at a quieter hour on performance cores.

The crowd's slow frames. Under heavy load (91% of frames on efficiency cores), the three minutes had 4, 0 and 0 crowd frames over 33 ms. Every one caught with navKit 1.5.5's timers (stepMaxMs, planFrameMs) was a stall of 70-190 ms inside one agent's step or one path plan, in code that does no long work: over 1,040 real townsfolk routes measured one by one, a path search never ran more than 0.1 ms without a pause point, and a call-stack sample showed no stack holding a long stall. They come from the engine's thread being stopped while the machine is overloaded (the same frames show waiting for a core), not from the kits. On a quiet stretch, 90 seconds had no crowd frame over 20 ms (crowd p50 2.3, p99 under 10 ms). The body spikes (14-17 ms) were frames that made a merged far mesh; since 1.2.6 those are made only for bodies in view.

What a person costs

Measured in Mirage Wells by forcing all 40 people into each tier in turn (TF.configure and the Town's distances), two runs minutes apart; the range is the machine's load.

tierbody (drawing and posing)thinkingnavKit walking
full (every part, every frame)0.07-0.14 ms a personabout 0.02 ms a person0.04-0.11 ms a person while near or mid
mid (10 Hz, small parts hidden)0.03-0.05 msabout 0.02 msas above
far (one merged mesh)0.017-0.024 msabout 0.02 msas above
far from every player (trips timed, not walked)as their body tierunder 0.01 ms0.02 ms or less
hidden (indoors)under 0.01 mspausednone

With the default budget (6 full, 12 mid, the rest far) 40 people cost about 2-3 ms of bodies, 0.8-1.1 ms of thinking and 1.5-2 ms of navKit a frame.

Desktop and web

Desktop app (Zero desktop app, dev build, Linux, 24 cores, shared and heavily loaded): the tables above. With townsfolkKit 1.2.6 and navKit 1.5.5, three one-minute runs at market hours ran at 37-43 fps with the crowd's script at 3.0-3.4 ms a frame at the median; 59-62 fps on a quiet stretch.

In a web browser (townsfolkKit 1.2.5, measured by the person who asked for 30 fps, 40 townsfolk at noon, one minute): about 20-23 fps. The crowd's scripts took about 3 ms a frame there, its worst frame was 31 ms, and no frame of the crowd's went over 33 ms. 30 fps was not reached, and the kit is not what holds it back: the crowd is about 3 ms of a 43-50 ms browser frame. Two things outside the kit set the browser's limit:

  • The browser build stepped the world from a timer at about 21 steps a second (engine issue #19874), which caps the frame rate there near 21 whatever the scene costs.
  • Luau runs slower in the browser than in the desktop app (engine issue #26683), so every script in the scene, the kits' included, costs more there.

The kits cannot lift either limit. What they can do for a browser, they do: bounded work a frame (HB.BUILD_MS, fartherPerFrame), posing only what is seen, no per-frame garbage. Once the engine issues are fixed, open the world in a browser, play, press F3, and the line shows the same numbers as on the desktop.

Tablet: not measured. No tablet was available for this release, so there is no tablet reading yet.

On a slower machine or a phone, keep to 15-25 townsfolk and a smaller budget: TF.configure({ maxFull = 4, maxMid = 6, lodNear = 15, lodFar = 35 }), with the showcase's shadow settings and a DynamicResolution component.

Tuning: TF.stats() reports simMs, bodyMs, the people at each tier and the entity count; require("navKit.api").stats() reports navKit's tickMs, how many paths it plans, and since navKit 1.5.5 what each part of its last tick took (planFrameMs, stepMs, stepMaxMs, gridMs); require("humanBodyKit.api").stats() the bodies, how many are still making their parts (building), and HB.SHADOW_LODS which tiers cast shadows. TF.configure also takes fartherPerFrame (bodies turning far a frame) and humanBodyKit's HB.BUILD_MS (part making a frame).

Large towns: bounded work a frame (1.0.5)

A big town (townKit's castleTown: 124 activity spots, a 160 x 160 m navKit grid, 18 townsfolk) used to stall for seconds at a time and trip the engine's 10 s hang watchdog inside Townsperson. Two things fed it: navKit (1.4.5 and older) searched the whole map whenever a spot could not be reached, and a person who failed to reach a spot gave up after 6 s, waited 5 s and claimed the same spot again (their favourite, or the nearest), so the whole-map search came back about every 11 s for ever. Since 1.0.5:

  • Thinking is budgeted. People due to decide something are served longest-waiting first, until TF.configure-able thinkBudgetMs (2 ms) is spent or maxThinksPerFrame (8) have thought; the rest think next frame (TF.stats().deferred counts them).
  • An unreachable spot is let go. A person who cannot reach a slot keeps away from it for avoidSeconds (120 s; it stops being their favourite), and waits longer before each further try: retrySeconds (5 s), doubling up to retryMaxSeconds (60 s).
  • Changing count in play works. Lower it and the highest-numbered townsfolk are removed (claims released, agents stopped), three a frame; raise it and the missing ones are spawned.
  • navKit 1.5.0. Path searches are capped at 10,000 nodes and spread over frames, so even an unreachable target costs a few milliseconds a frame.

Measured in a scratch world (townKit castleTown toon, seed 7, NavMap 160 x 10 x 160, 18 townsfolk, no player so everyone is at full detail), desktop editor:

worst frameframes of 80 ms or more (steady state)p99 frame
townsfolkKit 1.0.4 + navKit 1.4.52,735 ms (navKit search, up to 3.3 s per update)20 in 53 s, p90 3.5 s43 ms
townsfolkKit 1.0.4 + navKit 1.5.0169 ms31 in 45 s107 ms
townsfolkKit 1.0.5 + navKit 1.5.0136 ms15 in 40 s59 ms

With 1.0.5 the crowd's own decisions took at most 7.2 ms in a frame and navKit's whole tick at most 21 ms (its longest search slice 0.65 ms). Setting count from 18 to 0 removed everyone within 6 s with no frame over 108 ms, and setting it back to 6 brought six people back. The frames still over 80 ms come from drawing (body posing, the toon ink pass) and garbage collection, not from planning.

Known limits

  • A schedule written over several lines is lost for a player who joins late (engine issue #25558: a synced text field written over several lines reaches a late joiner without its later lines). townsfolkKit works round it: the peer that runs a person rewrites a multi-line schedule as one line split by ; as soon as play starts, so what a late joiner receives is whole. Write schedules on one line ("0:00 stand watch; 7:00 home; 17:00 stand watch") and nothing depends on that rewrite; the showcase's night watchmen do.
  • Two windows on one account are one player (engine issue OrigoZero/zero#14448, also listed by navKit): a two-player test with two accounts was not run. For 1.2.0 the check was run with two peers on one account (the editor's own client and a helper client, peers 44 and 46 in one play room): both saw the same 40 people with the same roles, activities, moods and homes, the same reactions to a firecracker, a knock-out and a drawn blade triggered from the peer that does not run the people, the same night watch at midnight, and the whole crowd's look switched by the room host.
  • TF.setLook(look) for the whole crowd works only on the peer that owns the Town (the room host by default). Called on another peer it changes that peer's copy of the Town's look field, which the network does not carry, so nobody's crowd switches. Switch the crowd's look from the host, or set the Town's look field in the scene. Found during the 1.2.0 two-player check; it predates 1.2.0.
  • The editor's frame rate is not a player's. The numbers above include the editor's own panels; a published play session draws less.
  • Groups are formation followers, not a crowd solver. In very tight streets a follower can lag behind its slot and catch up at the next stop.