damage.module
README.md
bots.damage
What you built gets wrecked. Every armour and structure part of a bot is drawn as its own dentable skin riding one plastic SoftBody cage per bot. Hits dent the part they land on and the dents stay, deep in aluminium and barely in AR500 (from Parts.softness(part).dentPerDamage). Hazards scorch the parts they touch, smoke and sparks follow health, and a part the body reports lost ("partLost") flies off as debris while the internals behind it show. "reset" repairs all of it.
local Damage = require("bots.damage")
Damage.attach(slot, root, parts, Rules.stats(slot)) -- after every (re)build of the bot (botcore calls it)
Damage.detach(slot) -- before a rebuild and in release()
Damage.hit(slot, point, normal, damage, kind, partId?) -- what the "hit"/"hazard" listeners call; usable by tests
Damage.loseParts(slot, partId, point?) -- what the "partLost" listener calls
Damage.report(slot) -- per-part dent / plastic / hits / lost, shell plastic + volumeRatio, tick cost
Damage.get(slot) -- the live record
parts is bots.assembler's v2 handle (see design/botmaker-spec.md):
hull: a hidden merged Model of every structure and armour part, in bot space.hullGeometry: the hull's flat arrays.hullRanges[partId] = {firstVertex, vertexCount}: where each part sits in it.entities[partId] = {entity, pivot, meshes, part, inHull}.
A hull without hullRanges (the v1 assembler) is handled as one part using stats.armor's numbers. Attach is idempotent and does nothing in edit mode. While the phase is "garage" the build is deferred until the phase changes, so editor drags cost nothing.
How it is built
- Skins:
- Each hull part's slice of
hullGeometryis subdivided to about 1600 triangles (edges 4.5–12 cm). - It is split into chunks of at most 800 triangles. The chunks are views over one shared vertex set, so normals stay seamless.
- The chunks draw under
<slot>_ArmorSkin, a child ofparts.hullthat rides the bot's Visual exactly, with that part's own material (entities[pid].meshes[1].material). - The part's own Models are hidden while the skin stands in for them, and shown again on detach.
- Subdivision, adjacency and chunks are cached per (hull mesh, part, range). A cold build costs 100–220 ms; a cached one about 20 ms.
- Each hull part's slice of
- Cage:
- The cage is a top-level box
SoftBodyover the hull's bounds (about 30–40 particles; the v1 closed hull uses its own mesh cage). - It is held by its bottom core to a top-level kinematic anchor that copies the hull's world pose every frame. A jump of more than 0.6 m rebuilds it where the hull now is.
- It collides with nothing. Stiffness, yield and plastic max are the vertex-weighted mean of the hull parts'
Parts.softness.
- The cage is a top-level box
- Dents:
- Part choice:
hit.partwhen it is a hull part. Otherwise the nearest surviving hull part whose surface faces the blow. A hit on a wheel, weapon or internal part dents nothing. - Depth is
damage × Parts.softness(part).dentPerDamage, clamped to 0.4–9 cm. - The cage is pin-pressed (
Physics.pinSoftRegion, released after 0.15 s), and the plastic gain is attributed to the part (report().parts[pid].plastic). - The crater is sculpted into that part's skin only, with a position-hashed crumple so crease vertices move together, and the normals around it are rebuilt.
- Dirty chunks re-upload under a 0.6 ms per-frame budget.
- Part choice:
- Lost parts (
"partLost" {slot, part, ...}):- A hull part's chunks hide, and a copy of its current dented skin flies off. The copy is re-centred in the part's own frame, with a
BoxColliderof its size and the part's mass. - Any other part (wheel, weapon, battery, controller) has its Models hidden, and a copy of them flies.
- Debris leaves at under 6 m/s via
Physics.setVelocity, neverapplyImpulse. It ignores collision with its own bot, trails smoke for 1.6 s, throws sparks at the loss point, and despawns after 6 s. - The body (botcore) only does the behaviour: drive, weapons and KO.
- A hull part's chunks hide, and a copy of its current dented skin flies off. The copy is re-centred in the part's own frame, with a
- Hazards:
- Saws cut a glowing orange trench (
bots.damage.gouge, which cools over 3 s) and a soot and temper-tint scorch in the vertex colours of every part they reach. - The pulverizer stamps a crater from above.
- The screw pit scuffs the underside.
- Saws cut a glowing orange trench (
- Smoke: light smoke below 50 % health; heavy smoke and sparks below 25 % (
bots.fx).
Budget
Measured in play, per shell:
| Cost | Measured |
|---|---|
Cage physics (Physics.stepCost().softBodies) | ≈ 0.15 ms |
| Script tick, average | 0.02–0.12 ms |
| Frames with chunk uploads | ≤ ~1.5 ms |
| A hit (on the event, not per frame) | 1–4 ms |
volumeRatio | stays 0.99–1.01 |