@adatechnology/game-destruction 0.4.2 → 0.6.0

package/README.md

@@ -88,7 +88,7 @@ for 3 mm glass), so a 9 mm shatters a window pane in one shot while a 5 cm block
 ## Fire, melting and leaks
 
 `update(dt)` advances everything that is hot. Burning parts consume fuel (`burnRate * surface`), lose hit points, char and finally turn to ashes
-(`fuelFraction >= 0.8`) or stay charred. Heat flows through closed joints by conductivity and to parts of other objects within `fireSpread`. Heat
+(`fuelFraction >= 0.8`) or stay charred. Heat flows through closed joints by conductivity and to parts of other objects within `fireSpread`. With `blastFrontSpeed` (m/s, 340 is the speed of sound; default off) the glass an explosion reaches breaks `distance / speed` seconds later, in `update`, instead of on the spot. Heat
 only moves towards a source temperature, so a wood fire (800 °C) never melts steel (1450 °C) but melts aluminium and plastic, and a 3000 °C torch
 melts anything. Melting emits `melt` and `drip`; a melted part is lost and its joints open. Pressurized gas that leaks near fire burns (or explodes
 when the part has `explodes`). `contains` parts leak through punctures: the `leak` event carries the hole's world point, the outward normal as
@@ -146,11 +146,40 @@ without any `structure` behave exactly as before.
   `splitGroup`.
 - `buildFrame({ spanX, spanZ, columnsX, columnsZ, height, floors, walls, roof, columnCapacity, ... })` returns a test structure: columns on
   foundations (`rebar`), beams, a slab per floor, optional brick walls (`mortar`) with a door opening, and a roof that rests (`resting`) on the top beams.
-- `sizeStructure(spec, { safety?, redundancy? })` returns a copy of the spec with `structure.capacity` set from the loads the world itself solves
+- `sizeStructure(spec, { safety?, redundancy?, redundancyRoles?, safetyByRole? })` returns a copy of the spec with `structure.capacity` set from the loads the world itself solves
   for the intact spec, so every structural part rests at stress `safety` (default 0.65). With `redundancy` (e.g. 0.97) the capacities are also
   raised where needed so that losing any single `column` keeps every other part at or below that stress: the structure stands with one column
   gone and, without help, falls with two neighbours gone. Raw material capacities are rarely a sensible design (a 54 t roof on 20 cm columns is
   already over 1 at rest); size the structure instead of hand-tuning. Parts without `structure` or with role `none` are untouched.
+  `redundancyRoles` (default `['column']`) says which parts the N-1 check removes one at a time: a house uses `['column', 'wall']` so it also
+  stands with a bearing wall gone. `safetyByRole` overrides `safety` per role: `{ beam: 0.45, slab: 0.45, roof: 0.45, stair: 0.45 }` keeps the
+  floors well under their limit so they outlast the member that fails.
+
+## Walls: layers, stages, breach and reinforcement
+A wall is one part that opts in with `layers`, `units`, `reinforcement` or `breach` (`PartSpec`, all optional; parts without them behave as before).
+`assemblyPart(id, { id, width, height, position, structure? })` builds one from the eight built-in **assemblies** (`ASSEMBLIES`, data in
+`src/data/assemblies.json`; add or replace with `registerAssembly`): `brick_wall_plastered` (0.09 m brick, 2 x 0.02 m plaster, 0.23 x 0.075 x 0.11 m
+bricks in running bond), `concrete_block_wall` (0.39 x 0.19 x 0.14 m hollow blocks), `reinforced_concrete` (0.2 m, rebar every 0.18 m, 0.6 x 0.42 m
+panels), `drywall`, `wood_frame_wall`, `log_wall`, `sheet_metal_shack`, `glass_pane`.
+
+- **Layers and spall.** A bullet spends `penetration x thickness` of every coat still on the faces it crosses, plus the core's. The outermost coat at the
+  impact comes off first (`spall` event, `area`), and a patch that spalled no longer stops anything: the same round that stops at fresh plaster can
+  go through once it has come off. A coat only spalls once per patch. Blunt hits spall the coat too.
+- **Stages** (`PartState.stage`, `stage` event). 0 intact; 1 at the first hole, crack or spall; 2 when through damage within 0.55 m adds up to
+  `breach.area` (0.25 m²): the units around the hit come out as fragments the size of one unit (`stage.fragments`, laid in the assembly's bond), the part
+  stays with an `opening` (shots and rays pass through it, its mass and capacity drop) and nothing is hidden; 3 when the part fractures or collapses.
+  Through damage is the area of through holes plus, for blunt, slash and explosive damage, the volume the damage takes out (`damage / (hpPerKg x
+  density)`) over the thickness it crosses, times `breach.blastFactor` (6) for blasts. An opening as wide as the part cuts it instead (a pilaster, a column):
+  that is a fracture. So a 9 mm burst never leaves stage 1 on plastered brick (it does not even go through), a rifle never breaches reinforced
+  concrete, a sledgehammer opens plastered brick after ~47 swings and a C4 or RPG opens reinforced concrete at once. The engine stays in joules: the
+  game tunes energies, `breach: { radius, blastFactor }` and each assembly's `breach.area`.
+- **Reinforced concrete.** At 0 hp the concrete crumbles (`fracture`, in panels when `units` is set) but the part does not go: it becomes its rebar cage
+  (`PartState.stripped`, `expose` with the bars in world space, stage 3), still part of the structure with `capacity x residualCapacity` (default 0.15).
+  A bare cage under load is overloaded in seconds (`overloadRate`), so the frame fails progressively: `expose`, `stress`, the cage is lost (`expose` with
+  no bars), then the neighbours and the slab (`collapse`). Bullets pass through a cage. The `rebar` joints of a reinforced part are not worn by blows:
+  only the cutting torch or a saw cuts them (or the cage giving way). A breach at stage 2 exposes only the bars inside the opening.
+- **Holes stay on the pieces.** Every `fracture` and breach fragment carries `marks` (`FragmentMark`: point, normal and diameter in the fragment's own
+  axes) for the holes that fell inside it, at most 12 per fragment.
 
 ## Contracts: implement your own or use the default world
 
@@ -186,7 +215,7 @@ valid (unique ids, known materials, joints reference parts), a 500 J ballistic h
 ## Events
 
 `damage`, `dent`, `hole`, `crack`, `ricochet`, `debris`, `fracture` (with oriented `fragments` in world space), `detach`, `disassemble_progress`,
-`ignite`, `extinguish`, `burnout`, `melt`, `drip`, `leak`, `explode`, `primed`, `stress`, `collapse`, `destroyed`. All points are in world space. Subscribe with
+`ignite`, `extinguish`, `burnout`, `melt`, `drip`, `leak`, `explode`, `primed`, `stress`, `collapse`, `spall`, `stage`, `expose`, `destroyed`. All points are in world space. Subscribe with
 `world.on(type | '*', fn)` or the `onEvent` option; `hit` and `update` also return their events.
 
 ## Determinism and LAN
@@ -201,7 +230,7 @@ world continues with the same events as the original. The loading world must use
 `raycast`, `shoot`, `disassemble`, `workableJoints`, `nearestJoint`, `extinguish`, `setLiters`, `update`, `state`, `part`, `reset`, `on`,
 `register`, `serialize`, `load`, `time`. `state()` and `part()` return live views; do not mutate them.
 
-Also exported: `buildFrame`, `sizeStructure`, `partCapacity`, `checkDestructible`, `checkHit`, `IMPACT_CONTRACT`, `MATERIALS`, `JOINT_DEFAULTS`, `JOINT_BY_MATERIALS`, `inferJoints`, `guessMaterial`, `partVolume`, `partMass`, `partThickness`, the
+Also exported: `buildFrame`, `sizeStructure`, `assemblyPart`, `registerAssembly`, `getAssembly`, `ASSEMBLIES`, `assemblyDepth`, `partCapacity`, `checkDestructible`, `checkHit`, `IMPACT_CONTRACT`, `MATERIALS`, `JOINT_DEFAULTS`, `JOINT_BY_MATERIALS`, `inferJoints`, `guessMaterial`, `partVolume`, `partMass`, `partThickness`, the
 helpers `vec`, `quat`, `quatFromEuler`, `rotateVec`, `toLocal`, `toWorld`, the locale (`locales`, `resolveStrings`, `DestructionStrings`) and all types.
 
 The locale table has `en` and `pt-BR` strings for material names, part statuses, joint kinds, tools, damage types, event labels and fracture styles:

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Vec3, Quat, MaterialId, FractureStyle, DamageType, DebrisKind, DestructionEvent, DestructibleSpec, ObjectState, DestructibleImpl, Hit, HitResult, RayHit, ToolKind, JointState, PartState, DestructionEventType, ExplosionChain, PartSpec, JointKind, JointSpec, PartShape, PartStatus, StructureRole } from '@adatechnology/game-contracts';
-export { ChainDelay, Crack, DamageType, DebrisKind, Dent, DestructibleImpl, DestructibleSpec, DestructionEvent, DestructionEventType, ExplosionChain, FluidKind, FractureStyle, Fragment, Hit, HitResult, Hole, IMPACT_CONTRACT, ImpactContract, JointKind, JointSpec, JointState, MaterialId, ObjectState, PartShape, PartSpec, PartState, PartStatus, Quat, RayHit, StructureRole, ToolKind, Vec3, checkHit } from '@adatechnology/game-contracts';
+import { Vec3, Quat, MaterialId, FractureStyle, DamageType, DebrisKind, DestructionEvent, DestructibleSpec, ObjectState, DestructibleImpl, Hit, HitResult, RayHit, ToolKind, JointState, PartState, DestructionEventType, StructureRole, ExplosionChain, PartSpec, JointKind, JointSpec, PartShape, SurfaceLayer, PartUnits, Reinforcement, PartBreach, PartStatus } from '@adatechnology/game-contracts';
+export { ChainDelay, Crack, DamageStage, DamageType, DebrisKind, Dent, DestructibleImpl, DestructibleSpec, DestructionEvent, DestructionEventType, ExplosionChain, FluidKind, FractureStyle, Fragment, FragmentMark, Hit, HitResult, Hole, IMPACT_CONTRACT, ImpactContract, JointKind, JointSpec, JointState, MaterialId, ObjectState, PartBreach, PartShape, PartSpec, PartState, PartStatus, PartUnits, Quat, RayHit, Reinforcement, StructureRole, SurfaceLayer, ToolKind, Vec3, checkHit } from '@adatechnology/game-contracts';
 
 /**
  * Public types of @adatechnology/game-destruction.
@@ -95,12 +95,28 @@ interface DestructionOptions {
     maxHoles?: number;
     /** Distance at which a burning part heats parts of other objects, in metres (default 0.6). */
     fireSpread?: number;
+    /** Breach of staged parts (see `PartSpec.breach`). */
+    breach?: {
+        /** Metres around a hit within which through damage adds up (default 0.55). */
+        radius?: number;
+        /** Multiplier of the breach area a blast makes over a blow of the same damage: a blast loads the whole crater (default 6). */
+        blastFactor?: number;
+    };
+    /**
+     * Speed of the blast front in m/s. A glass part at distance `d` from an explosion breaks `d / blastFrontSpeed` seconds later, in `update`
+     * (the speed of sound is 340). Default off: every part takes the blast at once.
+     */
+    blastFrontSpeed?: number;
 }
 interface SizeStructureOptions {
     /** Stress every structural part has at rest after sizing (`load / capacity`), 0..1 (default 0.65). */
     safety?: number;
+    /** Stress at rest per structural role, over `safety` (a house: beams, slabs, roofs and stairs at 0.45 so they outlast a lost column). */
+    safetyByRole?: Partial<Record<StructureRole, number>>;
+    /** Roles whose parts are removed one at a time by the redundancy check (default `['column']`; a house adds `'wall'`). */
+    redundancyRoles?: readonly StructureRole[];
     /**
-     * Redundancy target: when set, the capacity of a part is raised (never lowered) until losing any single `column` leaves every other
+     * Redundancy target: when set, the capacity of a part is raised (never lowered) until losing any single part of `redundancyRoles` leaves every other
      * structural part at this stress or below, e.g. 0.97 (an N-1 design: the building stands with one column gone). Omit to skip the check.
      * Should be above `safety` and, to let the structure fall when a second column goes, below 1.
      */
@@ -206,6 +222,12 @@ interface PartRuntime {
     stressT?: number;
     /** World time at which a primed explosive part goes off (`explodes.chain`). */
     chainDue?: number;
+    /** Patches of surface layers that came off (`layers.ts`). */
+    spalls?: Array<[number, number, number, number, number, number]>;
+    /** Through damage so far: `[x, y, z, area]` in object space, newest last. */
+    breach?: Array<[number, number, number, number]>;
+    /** Mass in kg that left the part in a breach. */
+    removed?: number;
 }
 /** Opaque bookkeeping of an object (see `PartRuntime`). `joints` holds the last disassembly step reported per joint id. */
 interface ObjectRuntime {
@@ -297,6 +319,54 @@ declare const partCapacity: (part: PartSpec, material: MaterialDef) => number;
  */
 declare const fragility: (ductility: number, thickness: number) => number;
 
+/**
+ * A wall as a builder builds it: a core with coats, the masonry unit it is laid in, its rebar and when it breaches. Dimensions are metres (data in
+ * `src/data/assemblies.json`); `assemblyPart` turns one into a `PartSpec`. Extend or override with `registerAssembly`.
+ */
+interface AssemblyDef {
+    id: string;
+    name: string;
+    /** `thickness` is the core's, in metres: what a bullet has to get through besides the coats. */
+    core: {
+        material: MaterialId;
+        thickness: number;
+    };
+    /** Coats, outermost first. */
+    layers?: readonly SurfaceLayer[];
+    /** Physical depth of the wall when it is not core plus coats (a drywall partition is mostly air between the boards). */
+    depth?: number;
+    /** Solid fraction of the core (hollow blocks, round logs): scales its mass and the thickness a bullet crosses. Default 1. */
+    fill?: number;
+    units?: PartUnits;
+    reinforcement?: Reinforcement;
+    breach?: PartBreach;
+}
+interface AssemblyPartOptions {
+    id: string;
+    /** Along the part's x axis. */
+    width: number;
+    /** Along the part's y axis. */
+    height: number;
+    position: Vec3;
+    rotation?: Vec3;
+    structure?: PartSpec['structure'];
+    /** Other `PartSpec` fields (tags, anchored, hp...). */
+    extra?: Partial<PartSpec>;
+    /** Materials to read densities from (default the built-in `MATERIALS`). */
+    materials?: ReadonlyMap<MaterialId, MaterialDef>;
+}
+/** Built-in assemblies; `registerAssembly` adds to this list. */
+declare const ASSEMBLIES: AssemblyDef[];
+declare const registerAssembly: (def: AssemblyDef) => void;
+declare const getAssembly: (id: string) => AssemblyDef | undefined;
+/** Physical depth of the wall in metres. */
+declare const assemblyDepth: (def: AssemblyDef) => number;
+/**
+ * The wall as a box `[width, height, depth]` (thin along local z) with the assembly's layers, units, rebar and breach. Mass is the core (times `fill`)
+ * plus the coats; `thickness` is the core's, so each coat adds its own `penetration x thickness` to what a bullet must cross.
+ */
+declare const assemblyPart: (assemblyId: string, options: AssemblyPartOptions) => PartSpec;
+
 interface FrameOptions {
     /** Total length along x between the outer column centres, metres (default 8). */
     spanX?: number;
@@ -337,8 +407,9 @@ declare const buildFrame: (o?: FrameOptions) => DestructibleSpec;
 /**
  * Sizes the load capacity of a structure the way an engineer would, from the loads the world itself computes. The intact spec goes through the
  * same load solver `createDestruction` uses, and each structural part (`structure.role` other than `none`) gets `structure.capacity = load / safety`,
- * so its at-rest stress is exactly `safety`. With `redundancy` set, every `column` is also removed in turn and the capacity of the parts that
- * would carry more is raised so they stay at or below `redundancy`. Parts without `structure`, with role `none`, or with no support path to an
+ * so its at-rest stress is exactly `safety` (`safetyByRole` overrides it per role). With `redundancy` set, every part whose role is in
+ * `redundancyRoles` (default `column`) is also removed in turn and the capacity of the parts that would carry more is raised so they stay at or below
+ * `redundancy`. Parts without `structure`, with role `none`, or with no support path to an
  * anchored part are left as they are. The spec is not modified; a copy is returned.
  */
 declare const sizeStructure: (spec: DestructibleSpec, options?: SizeStructureOptions) => DestructibleSpec;
@@ -410,4 +481,4 @@ declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions
     problems: string[];
 };
 
-export { type AddOptions, type ChainTrigger, type CheckOptions, type DestructionLocale, type DestructionOptions, type DestructionSnapshot, type DestructionStrings, type DestructionWorld, type ExplosivePartOptions, FIRE_PRIME_C, type FrameOptions, JOINT_BY_MATERIALS, JOINT_DEFAULTS, MATERIALS, type MaterialDef, type MaterialThermal, type ObjectRuntime, type PartRuntime, type SizeStructureOptions, type WorldExplosive, buildFrame, checkDestructible, createDestruction, explosivePart, fragility, guessMaterial, inferJoints, locales, partCapacity, partMass, partThickness, partVolume, quat, quatFromEuler, resolveStrings, rotateVec, sizeStructure, toLocal, toWorld, vec };
+export { ASSEMBLIES, type AddOptions, type AssemblyDef, type AssemblyPartOptions, type ChainTrigger, type CheckOptions, type DestructionLocale, type DestructionOptions, type DestructionSnapshot, type DestructionStrings, type DestructionWorld, type ExplosivePartOptions, FIRE_PRIME_C, type FrameOptions, JOINT_BY_MATERIALS, JOINT_DEFAULTS, MATERIALS, type MaterialDef, type MaterialThermal, type ObjectRuntime, type PartRuntime, type SizeStructureOptions, type WorldExplosive, assemblyDepth, assemblyPart, buildFrame, checkDestructible, createDestruction, explosivePart, fragility, getAssembly, guessMaterial, inferJoints, locales, partCapacity, partMass, partThickness, partVolume, quat, quatFromEuler, registerAssembly, resolveStrings, rotateVec, sizeStructure, toLocal, toWorld, vec };