breakawayKit.package
README.md
Breakaway: Part Durability and Break-Off Kit (breakawayKit)
Give every part of a character, ragdoll, vehicle or prop its own durability, and let it break off. Heads, arms, legs, bodies, hats, helmets, held props and outfit pieces each wear down on their own: soft bumps do nothing, hard hits chip them away, and a part that runs out breaks off as a real free physics body that keeps tumbling, with a sound and a particle burst in its own style (a porcelain shatter, a teddy's stuffing puffing out, a tin robot spilling bolts, a jelly splat...). A durability HUD shows what is left in six layouts and four looks, switched with one call, and scoring hooks let a game end or score a run by what is left. It works with every tumbleTroupe character and outfit out of the box, with any ragdoll or set of entities, in multiplayer, on web and desktop.
local Breakaway = require("breakawayKit.breakaway")
local Troupe = require("tumbleTroupe.troupe")
local dummy = Troupe.spawn({ character = "clank", pos = { 0, 4, 0 } })
local rig = Breakaway.attach(dummy, { profile = "armouredHead" }) -- every part gets durability
Breakaway.onBreak(rig, function(ev) print(ev.part, "broke off for", ev.points) end)
Breakaway.setDisplay("paperDoll", "cartoon") -- the HUD
Troupe.push(dummy, "chest", nil, { 0, 0, 1 }, 400) -- hits do the rest
print(Breakaway.integrity(rig), Breakaway.score(rig)) -- 0..1 left, points
Version
1.0.2 (Breakaway.VERSION). 1.0.2: break and chip effects keep playing after the first play session (fx re-registers a style whenever juiceKit no longer holds it, retries once on an unknown-effect error, and forgets registrations and cached clips on every mode change; fixes "unknown effect bk_<style>"). 1.0.1: network handlers exposed for tests (Breakaway._handlers), a multiplayer mirror and anti-spoof test. 1.0.0: first release.
Install
- Search ZeroMind for breakawayKit (or "break off parts", "part durability", "dismember ragdoll") and
install
breakawayKit.package, or install it by guid:zeromind_install guid=e422108d-c411-4fd2-89de-1046f7a814d9. It brings juiceKit (hitstop, shake and pooled particles) with it. - For the tumbleTroupe adapter install tumbleTroupe 1.2+ too (accessories need 1.2; 1.1 works with body parts only).
local Breakaway = require("breakawayKit.breakaway")from any component or module.
The world Breakaway: Part Durability and Break-Off Kit opens on the showcase: press Play.
Guides inside the package
how-to-make-parts-break-off-with-durability- every part of the API, task by task.example-smash-the-dummy-down-a-ramp-game- a small complete game built on it, step by step.
The showcase
examples/BreakawayShowcase.component (on the world's scenes.main): eleven tumbleTroupe dummies, one per
break style, each with a different toughness profile, and a wrecking ball. Picker bar: every display kind
and look, SMASH, SMASH ALL, REPAIR. Keyboard: Space smash, A smash all, R repair, D next display, L next
look, Left / Right select. Gamepad: south smash, west repair, north next look, shoulders change display,
d-pad select. Touch / mouse: the picker bar, and tap a dummy to select it (tap again to smash). Left
alone it smashes on its own.
API (require("breakawayKit.breakaway"))
Rigs
| call | what |
|---|---|
attach(target, opts?) -> rig | Give a rig durability. target: a tumbleTroupe handle, a root entity (each descendant with a Physics body is a part), or { [partName] = entityId | spec }. |
detach(rig) / detachAll() | Stop tracking (listeners off, pieces fade, other peers drop their mirror). |
refresh(rig) | Re-read drawn parts (after a tumbleTroupe setStyle outfit change). |
rigs(filter?) | Every rig this peer knows; "local" = its own, "remote" = mirrors of other players' rigs. |
setEnabled(rig, on) | Pause / resume hit listening. |
attach options (all optional):
| option | default | what |
|---|---|---|
profile | "balanced" | toughness profile (below) |
style | per adapter | break style for every part (tumbleTroupe: the character's own) |
styles | { [partName or class] = style }, e.g. { head = "glassShards", accessory = "paperConfetti" } | |
materials | { [material] = style } overrides the material map | |
parts | per part: { max, threshold, damage, style, points, core, breakable, parent, label, mode } | |
points | per class | a number for every part, or { [part or class] = n } |
modifiers | all 1 | { durabilityMul, thresholdMul, breakPointsMul, damageMul } (game upgrades) |
mode | "spawn" | "spawn": a copy flies and the original hides; "joint": the part's joint is removed and the real body flies (generic rigs that give joint) |
synced | true | replicate durability and breaks to other peers |
hits | true | listen to physics impacts |
display | true | may be shown by the HUD |
name, debrisLife, wreckIntegrity, measure | label, seconds pieces live, wreck line, "dv" / "speed" / "impulse" |
A spec in the entity table: { entity, class, style, material, drawn = { ids }, mass, joint, parent, core, breakable, shape, max, threshold, points, label }.
Classes: head torso arm hand leg foot accessory prop (guessed from the name when left out).
Damage, breaks, repair
| call | what |
|---|---|
hit(rig, part, strength, info?) | A hit of strength (m/s of velocity change): nothing at or under the part's threshold, (strength - threshold) x 12 x damage past it. Use it for hammers, explosions, scripted hits. |
damage(rig, part, amount, info?) | Take amount durability straight off (no threshold). |
contact(rig, part, impulse, speed, info?) | What the impact listeners call: strength = impulse / part mass, capped at 3x closing speed. |
breakPart(rig, part, info?) | Break it off now. |
repair(rig, part?, amount?) | Heal one part or all; broken parts come back (visible, colliding). |
setModifiers(rig, mods) / getModifiers(rig) | Game multipliers; max durability and threshold follow at once, later breaks use breakPointsMul. |
setStyle(rig, part?, style) | Change a break style live. |
Only the peer that attached a rig may call these on it; on any other peer they do nothing and warn.
Reading it
| call | what |
|---|---|
integrity(rig) | 0..1 of what is left (weighted: torso 3, head 2, limbs 1.5, hands / feet / accessories 0.5; broken parts 0) |
score(rig) | points from breaks so far |
parts(rig) | { [name] = { name, label, class, hp, max, fraction, broken, style, threshold, points, band } } |
partOrder(rig) | part names, head first, accessories last |
summary(rig) | { integrity, score, broken, parts, wrecked, owner, key, local, name } |
styles() / profiles() | names |
Events (hitstop-friendly)
onDamage, onBreak, onWrecked, onRepair take fn (every rig) or (rig, fn) and return an unsubscribe function.
- damage:
{ rig, part, amount, hp, max, fraction, strength, point, source } - break:
{ rig, part, class, style, points, score, point, velocity, carried = { parts that left with it }, integrity, pieces, remote, hitstop = suggested seconds }. It fires right after the piece leaves and before the next physics step, so a game can freeze, zoom or slow time on it. - wrecked:
{ rig, integrity, score, broken, reason = "core" | "integrity" }: the core part (tumbleTroupe:body) broke or integrity fell toTUNING.wreckIntegrity(0.15). A core break first bursts every other part off.
Break styles (style)
| style | the piece leaves | sound | best for |
|---|---|---|---|
popClean | springs off whole with a puff and sparkle ring | cork pop | vinyl, gloss, default |
woodSplinter | snaps in two, splinters and sawdust | wood crack | wood |
ceramicShatter | splits into 5 shards with chips | porcelain shatter | bone, ceramic |
plushStuffing | flops off, stuffing puffs burst and drift | seam rip | plush, fabric, felt |
tinBolts | clanks off, bolts and springs pop out | tin clank + rattle | tin toys |
cookieCrumble | breaks into 4 chunks and crumbs | crunch | cookie |
jellySplat | wobbles off, goo blobs, keeps wobbling | wet splat | jelly |
paperConfetti | pops off in a confetti cone | party popper | paper, party |
glassShards | flash and 6 sharp shards, glitter | glass smash | glass, glow |
rubberBounce | springs off high and keeps bouncing | boing | rubber |
metalSparks | clangs off in a fountain of sparks and smoke | clang + crackle | metal, armour |
defineStyle(name, { base = "popClean", sound, vfx, palette, leave = { pop, up, spin, shards, shardScale, restitution, friction, wobble }, feel = { hitstop, shake } }) adds your own; Fx.setClip(soundName, clip) swaps a sound.
Toughness profiles (profile)
| profile | what it does |
|---|---|
balanced | the base numbers: head 100 / threshold 4, torso 160 / 4.5, arm 70, hand 40, leg 80, foot 45, accessory 30 / 2.5 |
sturdy | x1.6 durability, x1.25 threshold, x0.85 damage |
fragile | x0.6 durability, x0.75 threshold, x1.2 damage |
glassCannon | x0.45 durability but x1.6 threshold, x2.2 damage: shrugs off knocks, shatters on a real hit |
armouredHead | head x3 durability, x2 threshold; helmets / hats x2 |
tank | x2.5 durability, x1.6 threshold, x0.7 damage |
eggshell | x0.25 durability, x0.55 threshold |
noodleLimbs | arms, hands, legs and feet x0.35-0.4 durability at half threshold; head and body ordinary |
defineProfile(name, { classes = { head = { hp, threshold, damage }, ... } }) adds your own.
Durability HUD
setDisplay(kind, look): one call swaps the whole HUD; either may be nil. display() returns the module for the rest.
- kinds:
paperDoll(a body silhouette coloured per part, accessories listed),bars(a bar per part),chips(a pill floating over each part in the world),rings(a ring gauge per part),line(one thin integrity line with a tick per broken part),hearts(three pixel hearts per part). - looks:
cartoon,pixel,sciFi,fantasy. display().setTarget(rig)picks the rig the panel follows (default: the newest one this peer owns),display().configure({ corner = "topRight", scale = 1.2, chipsFor = "all" }),display().show(false).- It takes no input and no pointer (clicks and touches pass through), honours the safe area on phones, and redraws only when something changes (chips at 30 Hz).
Tuning
Breakaway.TUNING: measure, cap, hitCooldown (0.08 s), damagePerUnit (12), wreckIntegrity (0.15),
chipFx, chipMinDamage, hitstop (true), inherit, popScale, debrisLife (7 s), repairClearsDebris, stateRate (6 Hz).
require("breakawayKit.debris"): MAX (40 live pieces), LIFE, FADE. require("breakawayKit.fx"): MAX_VOICES (12).
Multiplayer
The peer that calls attach owns the rig: it alone reads hits, applies damage and decides breaks; every
other peer's calls on that rig do nothing. Breaks, durability (at most 6 updates a second, only while
something changes) and wrecks go to every peer on the breakaway.* channels, and a peer only accepts them
for rigs keyed by the sender's own peer id, so nobody can break another player's parts. Watching peers
build a mirror of the rig (rigs("remote")), hide the broken part on their own copy and throw the same
piece with the same velocity and seed, plus the burst and sound (no hitstop for them). Pieces are local
on every peer. tumbleTroupe characters spawned with synced = true are mirrored automatically (their
pose stream keeps moving the body; the broken part stays hidden); generic rigs replicate their drawn
parts when those entities are synced.
Performance
Breaking costs a few entity spawns; pieces are plain bodies that sleep when still, live 7 s, then shrink away, and never more than 40 are alive (oldest go first). Bursts are juiceKit's instanced particles (a handful of draws for everything) and sound voices are capped at 12. Durability bookkeeping is a few table writes per real hit (soft contacts are filtered by the engine-side impulse floor first). Measured here: all 30 tumbleTroupe character x outfit combinations broken part by part (334 pieces spawned, 294 recycled by the cap) with no errors.
Known limits
- In
"spawn"mode a broken part's own body stays in the ragdoll, hidden and colliding with nothing (so the ragdoll's joints and pose stream stay intact); its mass stays too. "joint"mode (the real body flies) needs a rig that names its joints; it cannot be repaired back on.- tumbleTroupe characters wear accessories from 1.2 on: clank plume, nova helmet, bolt antenna and key, fizz straw, mochi scarf / bow tie, bonesy sash, bruno ears. wobble, pip and juniper wear none.
- After
Troupe.setStylecallBreakaway.refresh(rig). - A watching peer sees pieces from its own simulation (same start, not frame-identical).
What is inside
breakaway.module (API), durability.module (pure math), profiles.module, styles.module, fx.module,
debris.module, display.module, adapters/generic.module, adapters/tumbleTroupe.module, sounds/ (11
generated break sounds), examples/BreakawayShowcase.component, breakawayKit.testSuite (17 tests, including the multiplayer mirror and anti-spoof path and a forgotten juiceKit registry),
two guides.