Living Lanes: Townsfolk Crowds with Daily Routines and Reactions Kit
README.md
humanBodyKit
Generated humanoid bodies for any NPC, with no models to import: villagers, townsfolk, pilgrims, guards, crowd extras. One call builds a whole person from smooth generated meshes and dresses them in one of 17 outfits. 30 procedural poses are animated in Luau every frame, with idle life and smooth blending between them. They can hold any of 17 props, and swap between 3 looks (realistic, painted, toon) in place. 4 LOD levels let a crowd of 40+ stay cheap.
Bodies are LOCAL entities. Every peer builds the same body from the same outfit and seed, so nothing goes over the network: sync the outfit, seed and pose yourself, the way you sync any other state.
Version 1.2.3 (HB.VERSION). The version in this README, package.yaml and HB.VERSION move together. 1.2.3 changes no behaviour: the body shader is built on the current engine library, so installing humanBodyKit no longer places an older engine shadow module (and the older engine_bindings it pulls) than a world on the current engine holds.

Quick start
Install the package, then run this in the console (execute), in edit or play:
local HB = require("humanBodyKit.api")
local root = entity.spawn("Villager", { temporary = true, position = { 0, 0, -3 } })
local body = HB.build(root, { outfit = "merchant", look = "realistic", seed = 17 })
HB.setProp(body, "right", "staff")
task.spawn(function()
for _, pose in { "idle", "walk", "wave", "sit", "haggle", "bow" } do
local t = 0
while t < 3 do
local dt = task.wait()
t += dt
HB.update(body, dt, { pose = pose, speed = pose == "walk" and 1.4 or 0 })
end
end
end)
To see everything at once, run HB.gallery({ 0, 0, 0 }). It lays out every outfit in every look, plus a row with every pose and the prop that suits it, and keeps them animated. HB.clearGallery() removes it.
API
local HB = require("humanBodyKit.api")
local body = HB.build(root, { -- root: an entity you position (feet at its origin, body faces its -Z)
outfit = "merchant", -- HB.OUTFITS
look = "realistic", -- HB.LOOKS: realistic painted toon
seed = 17, -- varies sex, skin tone, cloth colours, height, build, hair and hat
height = nil, build = nil, -- optional overrides (metres; "slim" | "average" | "stout")
hat = nil, -- optional: a hat part name (HB.HATS: "hat_straw", ..., "hat_jingasa") or "none"
colors = nil, -- optional fixed colours (a uniform or livery), see "Fixed colours"
lod = nil, -- optional starting LOD; "far"/"hidden" builds the parts only when needed
})
HB.update(body, dt, { pose = "walk", speed = 1.4, t = nil }) -- every frame (mid/far LOD throttle themselves)
HB.setProp(body, "right" | "left" | "back" | "head", propId | nil)
HB.setLOD(body, "full" | "mid" | "far" | "hidden")
HB.SHADOW_LODS = { full = true, mid = false, far = false } -- which LODs cast shadows (moving bodies' shadows are a crowd's dearest GPU cost)
HB.setLook(body, look) -- swap materials in place
HB.setLookAll(look) -- every body on this peer; returns how many
HB.destroy(body)
HB.stats() -- { bodies, parts, entities, msLast, byLod, materials, updates }
HB.info(body) -- { outfit, seed, height, build, female, child, hat, hair, look, lod, pose, parts, colors? }
HB.parseColors(spec) -- table or "main=#2b3a67;accent=#b03a2e" -> { slot = {r,g,b} } | nil (raises on a bad slot or value)
HB.hex("#rrggbb") -- { r, g, b } in 0..1 (sRGB) | nil
HB.COLOR_SLOTS, HB.HATS -- the slots `colors` takes; every hat part
HB.bodies() -- every live body on this peer
HB.gallery(origin, opts?) / HB.clearGallery()
msLast is the script time HB.update spent across all bodies in the last finished frame. HB.BLEND (0.3 s) is the pose blend time, and HB.MID_HZ (10) is the mid-LOD update rate.
Placing seated poses. sit assumes a seat about 0.45 m high whose front edge sits under the knees: the hips go about 0.38 m behind the root (+Z) and the feet stay at the root. sitGround, kneel, pray, beg, tend, cower and lying put the body on the ground at the root.
Outfits
| outfit | silhouette | hats (seeded) |
|---|---|---|
| farmhand | knee tunic, rolled sleeves, baggy trousers, rope belt | conical straw hat, headwrap, bare |
| porter | bare arms, open vest, baggy trousers, sash; stout | headwrap, skullcap, bare |
| merchant | ankle robe with bell sleeves, sash, often a vest | turban, fez, headwrap |
| monk | ankle robe, bell sleeves, shawl, rope belt; cropped hair | monk's hood, skullcap, bare |
| pilgrim | calf robe, long cape, leg wraps, belt | headwrap, hood |
| child | short tunic or dress; ~1.1-1.3 m with a bigger head | skullcap, headwrap, bare |
| elder | ankle robe, shawl, belt; grey hair, stooped walk, often a long beard | skullcap, turban, headwrap |
| servant | calf dress or tunic with apron, rolled sleeves | headwrap, skullcap, bare |
| fisher | bare chest with open vest, baggy rolled trousers, bare feet | straw hat, headwrap |
| entertainer | bright vest, bell sleeves, harem trousers, short cape, sash | fez, turban |
| beggar | ragged calf robe, short sleeves, bare feet; hunched | headwrap, hood, bare |
| watchman | knee tunic, leather cuirass with pauldrons, long cape, boots | conical helmet with nasal and mail, turban |
| soldier | knee tunic, lacquered cuirass, sash, belt, shin wraps and sandals or boots; indigo/black/rust | flat lacquered war hat (jingasa), headwrap |
| samurai | wide-sleeved robe, ankle-length split skirt, stiff shoulder vest, sash; top-knot bun for all; charcoal/indigo/wine/olive with gold or white | bare, sometimes the war hat |
| cook | pale tunic, rolled sleeves, long apron, coloured sash, calf or knee length; mostly stout | headwrap, skullcap, bare |
| teaServant | neat fitted robe to the ankle or calf, broad sash in an accent colour, hair bun, sandals; rose/sky/sea green; mostly women | bare |
| plain | hip tunic and trousers | bare |
The seed also picks sex (each role has its own mix), skin tone (8 tones), hair (crop, short, long or bun, plus a beard by role), and colours from each role's palette, with small per-body variation.
Fixed colours (uniforms and liveries)
colors replaces the seeded colour of the slots it names, so a game can dress a crew in one uniform while the seed still varies face, skin, hair, height, build and hat. Slots: main (top, robe, skirt), second (trousers, vest or apron by outfit), accent (sash, cape, trim), hat (cloth hats), leather, dkleather (belts, boots, lacquer: the soldier's cuirass is leather, the war hat dkleather), metal (helmet), straw (straw hat). A colour is '#rrggbb' (or '#rgb'), { r, g, b } in 0..1 (or 0..255) or { r =, g =, b = }. The whole option can also be a string 'main=#2b3a67;second=#d9c9a3;accent=#b03a2e' (; or , between entries). An unknown slot or bad value raises. If an outfit's hat follows its accent and you fix accent alone, the hat follows it too.
HB.build(root, { outfit = "porter", seed = i, colors = { main = "#2b3a67", second = "#d9c9a3", accent = "#b03a2e" } })
HB.build(root, { outfit = "soldier", seed = i, hat = "hat_jingasa", colors = "main=#1d1f2e;accent=#8a2a1c;dkleather=#141010" })
HB.info(body).colors reports the fixed slots ({ slot = {r,g,b} }), nil when none were given. HB.setLook keeps them.
Poses
idle walk run sit sitGround kneel pray bow sweep carry carryHead haggle browse tend drink eat queue drawWater fish perform beg guard chat play cower point gawk lying wave knock
- Every pose carries idle life: breathing, weight shifting from foot to foot, and glances that settle and move on.
walkandrunare driven byspeed. Stride length grows with speed, and the cadence is speed divided by stride. Stance feet are held flat and travel with the ground, so they don't skate.idle,carry,carryHead,guard,chat,point,gawk,wave,queue,eat,drink,haggleandbrowsekeep their arms and head but walk their legs whilespeed > 0.05. So "carrying a sack while walking" ispose = "carry", speed = 1.2.- Elders and beggars stoop; children run with a quicker cadence.
- A pose change blends from where the body is over
HB.BLENDseconds.
Props
broom sack jar cup bowl rod spear basket hoe beads lantern balls tray drum staff bundle sword
- Hand props stay upright in the body's frame whatever the arm does: a staff stays vertical when the arm hangs and when it reaches. Each prop has its own lean, so a broom's bristles sweep ahead and a rod points out over the water.
- Basket, sack and bundle in a hand sit between the hands, for
carry. headtakes jar, basket, sack, bundle, tray, cup and bowl (forcarryHead).backtakes most of the rest.ballsjuggles in a cascade while the pose isperformand rests in the hand otherwise.swordis a slim curved single-edged sword (~0.95 m, round guard, wrapped grip). Inrightit is drawn, leaning forward in a ready grip; inleftit hangs sheathed at the left hip (hilt forward); onbackit is sheathed across the back.
Looks
- realistic: PBR. Skin has subsurface scattering, cloth has sheen, and there are leather, metal, straw, and hair with a fibre highlight. Baked vertex occlusion is in every mesh.
- painted: the package's
hbSurfaceshader in its painted style: soft bands whose edges wander with brush strokes laid along each part, warm light, cool shade, and stroke-to-stroke value variation. - toon:
hbSurfacein its cel style: two hard bands, a lifted lilac shadow, a pale rim, and a dark brown ink outline from the Model component's outline fields.
Materials are made once per session and shared, keyed by look, kind and colour quantised to 1/31. Switching HB.setLookAll("toon") touches only material references.
LOD and cost
| LOD | what is drawn | what runs |
|---|---|---|
| full | ~23 parts + props, all animated | every joint every frame |
| mid | small parts hidden (face details, belts, cups, beads) | joints at 10 Hz; gait phase keeps advancing between updates |
| far | ONE merged mesh per body (~5.5k vertices, vertex-coloured, one draw), frozen in the pose's class (standing, seated, on the ground, lying); re-merged only when that class changes | nothing per frame |
| hidden | nothing | nothing |
Measured with 40 bodies (13 outfits, each holding a prop, poses walk/idle/chat/haggle/sweep), 120 frames per LOD, script time of HB.update only:
| LOD | ms per frame (40 bodies) | ms per body | visible parts (40 bodies) |
|---|---|---|---|
| full | 5.81 | 0.145 | 921 |
| mid | 1.01 | 0.025 | 859 |
| far | 0.051 | 0.0013 | 40 |
| hidden | 0.048 | 0.0012 | 0 |
- Each body is about 44 local entities: 1 pivot, 15 joints, 4 sockets, ~23 parts and 1 far mesh, plus props.
- Every Model a body makes is
mobility = "movable". Left atauto, the engine counts script-moved meshes as static level geometry and keeps re-baking what it derives from it (its sky-visibility field rebuilt in the background over and over, the worst hitches a crowd had before 1.2.0). - Posing writes a body's 15 joints and its pelvis as two batched writes from typed buffers (
ecs.bindEntities+entity.batchWrite), with no table per joint: about half the time of joint-by-joint writes and no garbage. If the batched write is refused, the body falls back to joint-by-joint writes and says so once. - Building a body at full in one go costs about 35-107 ms (almost all of it the engine's per-
Modelcost; a batched spawn is only about 30% cheaper). Build crowds atlod = "far". HB.build(root, { lod = "far" })builds only the merged far mesh (about 13 ms). When it later goes to mid or full its parts are made a few a frame: at mostHB.BUILD_MS(3 ms) of part making a frame across every body, at least one part a frame, and the body stays drawn by its far mesh until all of them are there.HB.updateandHB.setLODdrive this; a caller that changes LODs without updating any body every frame callsHB.pump()once a frame.HB.stats().buildingcounts the bodies waiting, and (since 1.2.1)HB.stats().farBuildscounts the merged far meshes made since play started, so a probe can tell a slow frame that made one from one that did not.HB.build(root, { props = { right = "spear", back = "bundle" } })puts props on before any far mesh is made, so a far body with props merges its mesh once (adding each prop afterwards re-merges it, about 10 ms each).- A far body keeps the merged mesh of each pose (and set of props) it has shown, up to
HB.FAR_CACHE(6), least recently shown dropped first; a mesh let go is freed a few frames later, once no frame in flight draws it. Before 1.2.0 every re-merge made a new GPU mesh and never freed the old one. - In townsfolkKit's Mirage Wells crowd (40 bodies, 6 full / 12 mid / the rest far) posing took 0.45 ms a frame at the median and 1.2 ms at p95 (2026-11-17, desktop, loaded machine); the table above is the older measurement of
HB.updatealone for 40 bodies forced to each LOD. - Recommended distances for a third-person camera: full < 12 m, mid < 30 m, far beyond.
How it is built
| part | what it is |
|---|---|
api.module | the public API above: rig, update, blending, props, looks, LOD, far merge |
parts.module | the reference rig (H = 1.75 m, head ≈ 1/7.5 of height) and every body, garment and hat mesh, as code: elliptical lofts with angle-dependent bumps (nose, brow, cheekbones, ears, chin), swept tubes, tori and double-sided sheets |
geo.module | the geometry kit those meshes are built with (loft, limb, tube, torus, sheet, rounded box, append/merge) |
outfits.module | the 17 outfits, the seeded variation and fixed colours |
poses.module | the 30 poses, the gait and idle life |
props.module | the 17 props and how each sits in each socket |
looks.module | the materials of the three looks |
shaders/hbSurface.shader | the painted / toon surface shader |
meshes/ + meshIndex.module | the shipped .mesh assets, written by generate.module (require("humanBodyKit.generate").all() in edit mode after changing a builder). Without them every mesh is built at runtime from the same code. |
gallery.module | HB.gallery |
humanBodyKit.testSuite | zero tests run humanBodyKit (edit mode) |