Log inGet started
Package

humanBodyKit.package

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

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.

gallery

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

outfitsilhouettehats (seeded)
farmhandknee tunic, rolled sleeves, baggy trousers, rope beltconical straw hat, headwrap, bare
porterbare arms, open vest, baggy trousers, sash; stoutheadwrap, skullcap, bare
merchantankle robe with bell sleeves, sash, often a vestturban, fez, headwrap
monkankle robe, bell sleeves, shawl, rope belt; cropped hairmonk's hood, skullcap, bare
pilgrimcalf robe, long cape, leg wraps, beltheadwrap, hood
childshort tunic or dress; ~1.1-1.3 m with a bigger headskullcap, headwrap, bare
elderankle robe, shawl, belt; grey hair, stooped walk, often a long beardskullcap, turban, headwrap
servantcalf dress or tunic with apron, rolled sleevesheadwrap, skullcap, bare
fisherbare chest with open vest, baggy rolled trousers, bare feetstraw hat, headwrap
entertainerbright vest, bell sleeves, harem trousers, short cape, sashfez, turban
beggarragged calf robe, short sleeves, bare feet; hunchedheadwrap, hood, bare
watchmanknee tunic, leather cuirass with pauldrons, long cape, bootsconical helmet with nasal and mail, turban
soldierknee tunic, lacquered cuirass, sash, belt, shin wraps and sandals or boots; indigo/black/rustflat lacquered war hat (jingasa), headwrap
samuraiwide-sleeved robe, ankle-length split skirt, stiff shoulder vest, sash; top-knot bun for all; charcoal/indigo/wine/olive with gold or whitebare, sometimes the war hat
cookpale tunic, rolled sleeves, long apron, coloured sash, calf or knee length; mostly stoutheadwrap, skullcap, bare
teaServantneat fitted robe to the ankle or calf, broad sash in an accent colour, hair bun, sandals; rose/sky/sea green; mostly womenbare
plainhip tunic and trousersbare

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.
  • walk and run are driven by speed. 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, haggle and browse keep their arms and head but walk their legs while speed > 0.05. So "carrying a sack while walking" is pose = "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.BLEND seconds.

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.
  • head takes jar, basket, sack, bundle, tray, cup and bowl (for carryHead). back takes most of the rest.
  • balls juggles in a cascade while the pose is perform and rests in the hand otherwise.
  • sword is a slim curved single-edged sword (~0.95 m, round guard, wrapped grip). In right it is drawn, leaning forward in a ready grip; in left it hangs sheathed at the left hip (hilt forward); on back it 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 hbSurface shader 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: hbSurface in 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

LODwhat is drawnwhat runs
full~23 parts + props, all animatedevery joint every frame
midsmall parts hidden (face details, belts, cups, beads)joints at 10 Hz; gait phase keeps advancing between updates
farONE 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 changesnothing per frame
hiddennothingnothing

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:

LODms per frame (40 bodies)ms per bodyvisible parts (40 bodies)
full5.810.145921
mid1.010.025859
far0.0510.001340
hidden0.0480.00120
  • 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 at auto, 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-Model cost; a batched spawn is only about 30% cheaper). Build crowds at lod = "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 most HB.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.update and HB.setLOD drive this; a caller that changes LODs without updating any body every frame calls HB.pump() once a frame. HB.stats().building counts the bodies waiting, and (since 1.2.1) HB.stats().farBuilds counts 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.update alone 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

partwhat it is
api.modulethe public API above: rig, update, blending, props, looks, LOD, far merge
parts.modulethe 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.modulethe geometry kit those meshes are built with (loft, limb, tube, torus, sheet, rounded box, append/merge)
outfits.modulethe 17 outfits, the seeded variation and fixed colours
poses.modulethe 30 poses, the gait and idle life
props.modulethe 17 props and how each sits in each socket
looks.modulethe materials of the three looks
shaders/hbSurface.shaderthe painted / toon surface shader
meshes/ + meshIndex.modulethe 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.moduleHB.gallery
humanBodyKit.testSuitezero tests run humanBodyKit (edit mode)