tumbleTroupe
A roster of ten original ragdoll toy characters for any game where something gets pushed, dropped, launched or knocked down a staircase: each one stands perfectly still where you place it until it is pushed, then tumbles on the engine's own physics and reports every real hit, with the part that hit, how hard, on what surface, and a sound in its own voice (squish, clank, crunch, rattle...). Each character has three outfits, its own proportions (big head, chubby, lanky) and a "storybook toy diorama" look: chunky, softly bevelled, saturated toy parts sculpted per body segment and drawn on the segment's colliders.
local Troupe = require("tumbleTroupe.troupe")
local h = Troupe.spawn({ character = "clank", outfit = "gold", pos = { 0, 4.2, -3.8 }, yaw = math.pi })
Troupe.onImpact(h, function(ev)
print(ev.part, ev.impulse, ev.surface) -- "head", 31.5, "stone"
end)
Troupe.push(h, "chest", nil, { 0, 0, 1 }, 150) -- release the hold and shove (N·s)
Open scenes.main in the kit's world and press play for the showroom: the whole lineup on
plinths and one character on top of a staircase. Click it (or press Space) to push, R to stand it
up, O for the next outfit, Left / Right or a click on the lineup to change character.
What is inside
| part | what |
|---|---|
troupe.module | the API, require("tumbleTroupe.troupe") |
characters.module | the roster: names, bios, unlock tiers, body plans, outfits and colours |
designs.module | what each character looks like, segment by segment |
sculpt.module | a small procedural toy modeller (bevelled superquadric blobs, tubes) building runtime meshes with vertex colour |
look.module | dresses a ragdoll: one drawn part per material on each segment, cached per character/outfit |
sfx.module | the impact sounds: a light and a heavy take per flavour, played at the hit point |
materials/ | 12 toy PBR materials (vinyl, gloss, jelly, metal, tin, matte, cookie, plush, bone, wood, glow, glass) |
sounds/ | 20 generated impact sounds |
examples/TroupeShowcase.component | the showroom demo: lineup, runner on the stairs, click to push, attract mode |
examples/stress.module | the physics stress test: every character pushed and dropped onto 4 cm hollow steps |
how-to-add-a-ragdoll-character-that-tumbles-and-reports-hits.guide | how-to for every part of the API |
example-make-a-push-the-ragdoll-down-the-stairs-game.guide | a small game built on it, step by step |
The characters
| id | name | tier | build | sound | outfits |
|---|---|---|---|---|---|
wobble | Wobble: a jelly-bean kid who bounces back from anything, mostly by accident | 1 | big round jelly head, chubby, 28 kg | squish | cherry Cherry Pop, lime Lime Fizz, blueberry Blueberry Hoodie |
clank | Sir Clank: a tin knight sworn to protect every staircase | 2 | stocky, heavy armour, 45 kg | clank | tin Polished Tin, gold Royal Gold, rusty Rusty Old Guard |
pip | Pip: a gingerbread runner who finally stopped running | 1 | flat, lanky, light, 14 kg | crunch | icing Classic Icing, candycane Candy Cane, holiday Holiday Sweater |
nova | Nova: a space cadet; gravity was not on the syllabus | 2 | huge glass bubble helmet, 30 kg | boink | cadet Cadet Orange, starlight Starlight White, nebula Nebula Purple |
mochi | Mochi: a penguin; stairs are just very bumpy ice | 1 | round, short legs, flippers, 26 kg | squeak | tux Classic Tux, scarf Winter Scarf, lifeguard Lifeguard |
bonesy | Bonesy: a friendly skeleton with nothing to lose | 3 | lanky, thin bones, 16 kg | rattle | bare Bare Bones, pirate Pirate, party Party Shirt |
bolt | Bolt: a wind-up robot; wind him up, point him downhill | 2 | boxy tin, 38 kg | clang | retro Retro Red, mint Mint Tin, chrome Chrome |
juniper | Juniper: an artist's mannequin trying a more dynamic pose | 1 | tall, lanky, ball joints, 18 kg | knock | beech Pale Beech, walnut Dark Walnut, folk Painted Folk |
bruno | Bruno: a teddy bear stuffed with fluff and optimism | 3 | chubby, big head, soft, 22 kg | fwump | honey Honey Brown, patchwork Patchwork, sailor Sailor |
fizz | Fizz: a soda can with a sparkling personality | 3 | cylindrical can body, 20 kg | fizz | cherry Cherry Cola, lemonlime Lemon-Lime, grape Grape Soda |
Tier is a suggested unlock order (1 first). Masses are at scale = 1; they scale with the cube of scale.
What changed in 1.1.0
- Built on the shared crashDummies ragdoll. The physical body (15 segments, masses, anatomical joint limits, muscle-tone motors, articulation, CCD) is now made by
crashDummies.buildRagdoll, fed each character's own proportions; the troupe keeps its own looks, sounds, impact reporting, standing hold, spin cap and settle-to-sleep. crashDummies did not have a standing or custom-proportion builder, so this version addsbuildRagdoll,spawnStanding,releaseandpushto it; that change is sent upstream as a pull request and this package depends on the copy installed in its world (parts/crashDummies.package) until it is merged. synced = trueworks for multiplayer viewing. The spawning peer simulates; every other peer draws the same character in the same outfit from a compact pose (about 200 bytes for all 15 segments) sent at 18 Hz while it moves and once a second at rest, interpolated 0.12 s behind, with the owner's impact sounds played where they happen. No synced bodies, no physics on the other peers. It is automatic: a game only spawns withsynced = true(outfit changes and despawns follow).- Rim outline for readability from behind and against busy scenery:
spawn({ rim = true })orTroupe.setRim(handle, { color, intensity }). - Measured: all 10 characters pushed at 160 N·s on the new body: peak 20.5 m/s, spin held at the 40 rad/s cap, no joint stretch (pelvis to chest 0.27-0.34 m as built), 9 of 10 asleep within 8 s. Runtime meshes: 0 of 636,848 triangles over 660 meshes (every character and outfit) wind against their normals.
API
local Troupe = require("tumbleTroupe.troupe")
| call | what |
|---|---|
Troupe.characters() | the roster: { id, name, bio, outfits = {{ id, name }}, tier, portrait, sound, height, mass } |
Troupe.spawn(opts) | spawn a character; returns a handle { root, segments = {[segment] = entityId}, character, outfit } |
Troupe.push(handle, segment?, point?, dir, impulse) | release the hold and shove: impulse N·s along dir, half at point on segment (default chest), half spread by height so it topples rather than launches |
Troupe.release(handle) | let go of the hold: it falls where it stands |
Troupe.despawn(handle) | remove it and everything it spawned |
Troupe.onImpact(handle, fn) | fn(ev) per hit; returns the unsubscribe function |
Troupe.motion(handle) | { maxSpeed, speed, airborne, pelvis, head, velocity, impacts, peakImpulse, released } |
Troupe.bodies(handle) | every rigid body entity id (15) |
Troupe.ownerOf(entityId) | (handle?, segment?) for a body, collider or drawn part |
Troupe.addVelocity(handle, v) | change every segment's velocity by v m/s at once (trampolines, fans, boosts) without tearing limbs apart; releases the hold |
Troupe.pick(origin, dir, maxDist?) | (segment?, point?, handle?): the segment a ray hits, or passes within 12 cm of |
Troupe.setHighlight(handle, segment?) | outline glow on one segment (nil clears) |
Troupe.setStyle(handle, outfitId) | change outfit live |
Troupe.setSound(handle, on, volume?) | the character's own impact sounds on/off (on by default) |
Troupe.setRim(handle, rim) | rim outline round the whole character: true, { color = {r,g,b}, intensity = 0.8 }, or nil to clear |
Troupe.live() | every live handle on this peer (the characters it simulates) |
Troupe.remotes() | the characters other peers simulate that this peer draws: { key, root, segments, character, outfit } |
Troupe.spawnRemote(info), Troupe.applyPose(key, t, pose), Troupe.encodePose(handle) | the replication parts, for a game that carries poses over its own channel (with synced = true they run on their own) |
Troupe.NET | replication tuning: rate (18 Hz), restRate (1), delay (0.12 s), timeout (6 s), announceEvery (2 s), maxHitsPerSecond (8) |
Troupe.TUNING | the tuning table (damping, impact floor, cooldowns, quality, ...) |
spawn options: character (id), outfit (id, default the first), pos = {x,y,z} (the feet's
ground point), yaw (radians; 0 faces -Z), scale (default 1), standing (default true: held
upright and still until pushed), synced (default false: the character is local to the peer
that spawned it, so every player has their own and nobody breaks anyone else's run; true: this
peer simulates it and every other peer draws it, see Multiplayer), sound
(default true), soundVolume, tone (joint muscle 0..1), quality ("high" or "fast", below), rim.
Impact event ev: segment, part ("head" | "torso" | "pelvis" | "arm" | "hand" | "leg" | "foot"),
impulse (N·s the step applied), speed (closing speed, m/s), point, normal, surface (the
surface attribute of the collider hit or an ancestor of it, default "concrete"), other
(entity id), character, sound.
Segments: pelvis chest head upperArmL forearmL handL upperArmR forearmR handR thighL shinL footL thighR shinR footR.
How it is built
- Engine physics, no Luau solver. 15 dynamic bodies (box pelvis and chest, sphere head and
hands, capsule limbs, box feet) built by
crashDummies.buildRagdollon ONE articulation rooted at the pelvis: generic joints with per-axis anatomical limits at the neck, waist, shoulders, wrists, hips and ankles, hinges at the elbows (0..140°) and knees. Neighbours do not collide; non-neighbours that touch in the standing pose are kept apart. Mass ratios follow a human's (chest 30 %, thighs 10 %, head 10 %...). - No tunnelling: every body has CCD; the stress test drops and pushes all ten characters at up to 25 m/s onto 4 cm hollow treads with no body ever passing a step.
- No explosions / jitter: angular damping, a 40 rad/s spin cap, joint "muscle" motors that go limp once the body is at rest (with rest damping) so it sleeps instead of twitching, and tense again when hit.
- Standing hold: gravity off and asleep until pushed, so a standing character costs the solver
nothing;
push/release/addVelocitywake it. - Impacts:
Physics.onImpacton every body (engine-side, every step, so a one-step hit at speed is never missed), filtered by an impulse floor scaled to the character's mass and a minimum closing speed (resting load is not a hit), and debounced per (segment, other) pair.
Measured
On a busy desktop development build at 60 Hz (several agents running beside it):
| solver per step | step total | limits | |
|---|---|---|---|
one character tumbling, quality = "high" (articulation) | ~3.8 ms | ~6 ms | held exactly (0° past any limit) |
one character tumbling, quality = "fast" (impulse joints +4 substeps) | ~0.8 ms | ~2.2 ms | up to ~15° past a hinge limit on the hardest hits |
| one character standing (held) | ~0 ms | 0.04 ms | none |
Budget a browser on a tablet at 2-4x those times: one "high" character fits 30 fps, and
"fast" leaves headroom for many. Set Troupe.TUNING.quality = "fast" (or pass quality to
spawn) on weak devices. Building a character's look the first time costs 30-80 ms (meshes are
cached per character and outfit after that).
Stress test (examples/stress.module, all ten characters per wave): pushes of 40 / 120 / 300 N·s
per 30 kg and drops from 2 / 8 / 20 m: 0 tunnelled samples, 0 blow-ups, every character heard
4-25+ impacts per run, peak speed 24.8 m/s.
Multiplayer
Troupe.spawn({ ..., synced = true }) is all a game does. The spawning peer owns and simulates the
character (bodies, joints and impacts stay local to it). Every other peer that has loaded
tumbleTroupe.troupe (any script requiring it) hears an announcement (character, outfit, scale,
repeated every 2 s for players who join late), builds the same look with no physics, and draws it
from the owner's pose stream: the pelvis position plus every segment's offset in millimetres and
its rotation (smallest-three, 16 bits), about 200 bytes per pose, 18 poses a second while it moves
(about 3.6 KB/s per tumbling character) and one a second at rest, drawn 0.12 s behind and
interpolated. Impact sounds are sent too (up to 8 a second) and play at the hit point; outfit
changes and despawns follow; a copy whose owner goes silent for 6 s is removed. Pushes and
addVelocity are the owner's (call them on the peer that spawned the character).
Known limits
- The look is procedural (sculpted toy parts with vertex colour); there are no textures, and no skinned mesh: each segment is a rigid toy part, which is the jointed-toy look on purpose.
- Synced characters (
synced = true) are drawn on other peers without collision there (a remote copy is a picture, not a body); physics writes (push, addVelocity) only take effect on that peer. - Portraits:
characters()[i].portraitis nil until aportraits/<id>.textureis added.
Comments · 0
Open discussion, no rating attached. Ask questions, swap notes, follow threads.
Documented parts · 2
- set-up-tumble-troupeworkflow
- tumbleTroupepackage