Living Lanes: Townsfolk Crowds with Daily Routines and Reactions Kit
- ..
- .metadata149 B
- ActivitySpot.component
- Home.component
- README.md43.3 KB
- Town.component
- TownChatter.component
- TownGroup.component
- Townsperson.component
- api.module
- audio
- bodyview.module
- build-a-village-market-a-thief-has-to-slip-through.guide
- bus.module
- catalog.module
- groups.module
- how-to-fill-my-town-with-people-who-follow-a-daily-schedule.guide
- net.module
- package.yaml1.9 KB
- reactions.module
- reuse-review.md5.5 KB
- schedule.module
- sim.module
- townsfolkKit.testSuite
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
| piece | what it is |
|---|---|
townsfolkKit.api | the one interface: local TF = require("townsfolkKit.api") |
Townsperson component | a person: role, temperament, look, schedule, home, group, outfit, seed, hat, colors (put it on a synced entity) |
ActivitySpot component | a place people go to and do something: kind and its slots |
Home component | a doorstep people go in at night and to hide; names an optional interactKit door |
TownGroup component | people who walk and stop together; players can walk inside |
Town component | one per scene: the whole crowd's look, LOD distances, an optional crowd to spawn |
TownChatter component | market chatter that swells and fades with the crowd around it |
townsfolkKit test suite | the catalog, schedules, spots, queues, stimuli and groups |
| two guides | the 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.
| id | outfit and manner | default temperament | default day |
|---|---|---|---|
farmhand | straw hat, rolled sleeves | calm | well 5:30, paddy 6:00, tea house 11:30, paddy 12:30, chat 17:30, home 18:30 |
porter | headcloth, sash, quick | calm | gate queue 5:30, carry sacks 6:00, tea house 12:00, carry 13:00, bench 18:00, home 19:00 |
merchant | rich robe, cap | nosy | stall 6:00, tea house 12:00, stall 13:00, home 18:00 |
monk | robe and hood, slow | calm | pray 5:00, sweep 8:00, pray 11:00, beg 12:30, pray 15:00, home 18:30 |
pilgrim | travel cloak, staff | timid | gate queue 6:00, pray 7:00, well 10:00, tea house 11:00, pray 13:00, shop 16:00, home 18:00 |
child | small, fast | timid | well 7:00, play 8:00, tea house 12:00, play 13:00, watch the show 16:00, home 17:30 |
elder | stooped, slow | calm | pray 7:00, bench 9:00, tea house 12:00, chat 14:00, bench 16:00, home 17:30 |
servant | apron, headscarf | informer | well 5:30, sweep 6:30, shop 9:00, sweep 11:00, shop 14:00, carry 16:00, home 19:00 |
fisher | wide hat, rod | nosy | fish 5:00, stall 10:00, tea house 12:00, fish 13:30, chat 17:30, home 19:00 |
entertainer | bright clothes | nosy | chat 8:00, perform 10:00, tea house 12:30, perform 14:00, tea house 18:00, home 20:00 |
beggar | rags, bowl | informer | beg 6:00, well 11:30, beg 12:30, bench 17:00, home 19:30 |
watchman | helmet, spear | (watch: investigates) | watch post 6:00, tea house 12:00, watch 12:45, home 20:00 |
soldier | lacquered 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 |
samurai | retainer: 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 |
cook | apron, rolled sleeves, headwrap; carries jars | calm | well 5:30, stall:kitchen 6:00, carry 10:00, stall:kitchen 11:00, tea house 14:00, stall:kitchen 15:00, home 20:00 |
teaServant | fitted robe, broad sash, hair bun; serves standing with a tray and bows at tea house seats, carries trays | informer | sweep 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):
| field | format | empty |
|---|---|---|
hat | a 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 bareheaded | the seed picks from the outfit's hats |
colors | slot=#rrggbb entries split by ; (or ,), e.g. main=#2b3a67;second=#d9c9a3;accent=#b03a2e. Slots: main, second, accent, hat, leather, dkleather, metal, straw | the 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
| kind | what people do | prop | slots |
|---|---|---|---|
bench | sit and watch the street | 2 | |
stall | mind a market stall, call out, haggle with customers | 1 | |
shop | browse a stall's goods and haggle (place in front of a stall) | basket | 2 |
sweep | sweep back and forth over a yard (radius) | broom | 1 |
pray | kneel and pray, bowing now and then | beads | 3 |
carry | carry sacks to the drop-off (toOffset or to) and back | sack | 2 |
paddy | bent over, planting and weeding along a row (radius) | 2 | |
teahouse | sit at a table, sip tea, eat | cup | 1 |
queue | wait in line at a gate (order 1 = front) | bundle | 1 |
well | draw water hand over hand; others queue behind | jar | 1 |
fish | fish at the water's edge | rod | 1 |
perform | juggle and dance; strollers stop to watch and clap | balls | 1 |
beg | sit by the road holding out a bowl | bowl | 1 |
watch | stand watch with a spear (where reports are run to) | spear | 1 |
chat | stand in a little circle and gossip | 4 | |
play | children 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:
| stimulus | how | reaches |
|---|---|---|
| loud noise | TF.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 street | TF.knockOut(person) (they fall and lie there) or TF.addBody(entity or pos) | 13 m, in sight |
| alarm | TF.alarm(pos) | 40 m |
| weapon drawn | TF.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 one | 12 m, in sight |
Each person meets each stimulus once, by their temperament (one setting, temperament = "timid", swappable at any time):
| temperament | noise | body | alarm | weapon |
|---|---|---|---|---|
calm | glances over | goes to look | walks briskly away | walks briskly away |
nosy | goes to look, points | goes to look, points | goes to look | runs away |
timid | runs away, cowers | runs away, cowers | hides indoors | hides indoors |
informer | runs to the watch | runs to the watch | runs to the watch | runs 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`)
| kind | formation | when it stops |
|---|---|---|
family | loose cluster around the leader | chat |
friends | loose cluster | chat |
porters | single file, each carrying a sack | stand |
procession | two by two, slow | pray |
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.
| tier | body (by distance to this screen's camera, within a budget) | simulation (by distance to the nearest player, on the peer running the person) |
|---|---|---|
| near / full | every part animated every frame, within lodNear (22 m), the nearest maxFull (6) people only | 4 decisions a second, navKit pathing with steering round others, reacts to everything, within simNear (35 m) |
| mid | fewer parts, animated at 10 Hz, to lodFar (50 m), the next maxMid (12) people only | 1 decision a second, walks its schedule without steering round others, still reacts, to simFar (80 m) |
| far | one merged shape, no animation: everyone past the distances or the budget | a decision every 4 s, trips are timed instead of walked (they appear at the spot after the walk would take), no reactions |
| hidden | indoors | indoors: 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.knockOutandTF.weaponDrawnwork from any peer: stimuli go to every peer ontownsfolkKit:stim, commands for a person to the peer running them ontownsfolkKit: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.
| event | payload |
|---|---|
activity | person, name, activity, text, hour: a schedule entry began |
arrived | person, name, activity, spot |
home, leftHome | person, name, home |
reacted | person, name, kind, response, position, stimulus |
reported | person, name, guard, guardName, kind, position, stimulus |
settled | person, name, after |
knockedOut, revived, bodyCleared | person, name, by / how |
stimulus, stimulusEnded | every peer: id, kind, position, radius, by |
playerJoinedGroup, playerLeftGroup | every peer, the local player: group, player |
look | every peer: look |
crowdSpawned | the host: count |
API reference (local TF = require("townsfolkKit.api"))
| call | what 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 townsfolk | before | after |
|---|---|---|
townsfolk scripts (all 40 Townsperson updates) | 4.1 ms | 0.8-2.7 ms |
navKit agents (all 40 NavAgent updates) | 3.3 ms | 1.5-3.0 ms |
| garbage the townsfolk make | 101 KB | 17 KB |
| kit timers, p50 / p95 (thinking, bodies, posing) | 1.4 / 7.1, 2.1 / 11.2, 0.9 / 7.4 ms | 0.4 / 1.0, 0.9 / 3.2, 0.5 / 1.2 ms |
| frames where the kits took over 33 ms | some 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 background | 26 times in one session, about 60 s of work each | once, when play starts (the engine does this for every scene load) |
| median frame / fps | 88 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:
- 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 Modelmovable. - 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. - 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.
- 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.
- 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.onNoisethe 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. - 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. - 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:
| part | time in 6 s | what it was doing |
|---|---|---|
Townsperson.update, all of it | 598 ms | everything below |
body view (bodyview) | 410 ms | drawing the 40 bodies |
of it, level of detail switching (HB.setLOD) | 161 ms | making 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 ms | a property write and a new table per joint (_apply, 78 ms) |
thinking (sim.tick) | 155 ms | decisions (think, 73 ms) and groups (60 ms, asking every member's position every frame) |
path finding and walking (NavAgent.update) | 518 ms | navKit'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 / mean | frame p50 | fps run | host-bound fps (the machine to itself) | |
|---|---|---|---|---|
| no townsfolk | 14.3 / 16.0 ms | 20.4 ms | 39 | 53 |
| all 40 townsfolk, townsfolkKit 1.2.4 + navKit 1.5.3 | 20.4 / 22.5 ms | 25.4 ms | 31 | 46 |
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 / mean | frame p50 | fps run | host-bound fps | |
|---|---|---|---|---|
| no townsfolk | 12.2 / 13.1 ms | 17.3 ms | 55 | 76 |
| all 40 townsfolk | 18.3 / 19.1 ms | 20.3 ms | 45 | 52 |
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 / mean | frame p50 | fps run | host-bound fps | |
|---|---|---|---|---|
| no townsfolk | 12.4 / 13.0 ms, 13.1 / 13.8 ms | 16.7, 17.4 ms | 53, 52 | 77, 73 |
| all 40 townsfolk | 18.3 / 19.7 ms, 18.9 / 19.9 ms | 20.4, 20.7 ms | 42, 43 | 51, 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.
| tier | body (drawing and posing) | thinking | navKit walking |
|---|---|---|---|
| full (every part, every frame) | 0.07-0.14 ms a person | about 0.02 ms a person | 0.04-0.11 ms a person while near or mid |
| mid (10 Hz, small parts hidden) | 0.03-0.05 ms | about 0.02 ms | as above |
| far (one merged mesh) | 0.017-0.024 ms | about 0.02 ms | as above |
| far from every player (trips timed, not walked) | as their body tier | under 0.01 ms | 0.02 ms or less |
| hidden (indoors) | under 0.01 ms | paused | none |
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-ablethinkBudgetMs(2 ms) is spent ormaxThinksPerFrame(8) have thought; the rest think next frame (TF.stats().deferredcounts 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 toretryMaxSeconds(60 s). - Changing
countin 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 frame | frames of 80 ms or more (steady state) | p99 frame | |
|---|---|---|---|
| townsfolkKit 1.0.4 + navKit 1.4.5 | 2,735 ms (navKit search, up to 3.3 s per update) | 20 in 53 s, p90 3.5 s | 43 ms |
| townsfolkKit 1.0.4 + navKit 1.5.0 | 169 ms | 31 in 45 s | 107 ms |
| townsfolkKit 1.0.5 + navKit 1.5.0 | 136 ms | 15 in 40 s | 59 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
scheduleas 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'slookfield, which the network does not carry, so nobody's crowd switches. Switch the crowd's look from the host, or set the Town'slookfield 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.