@adatechnology/game-destruction 0.6.1 → 0.7.1

package/README.md

@@ -181,6 +181,59 @@ panels), `drywall`, `wood_frame_wall`, `log_wall`, `sheet_metal_shack`, `glass_p
 - **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.
 
+## Blasts: shelter, fragment hits and confinement
+
+All three are options, **off by default** (a blast then does exactly what it always did, goldens included). Set them for the world with
+`createDestruction({ blast: { shelter: true, ... } })`, or per call: `world.explode(point, energy, radius, source, { shelter: true })`, or on the
+explosive `Hit` (`hit.blast`, `hit.confinement`). A call overrides the world default (`shelter: false` turns it off). Every number below is an
+option; the defaults are exported as `SHELTER_DEFAULTS`, `FRAGMENT_HIT_DEFAULTS` and `CONFINEMENT_DEFAULTS`. This is the kit's own model (no team
+delivery has it), approved by the owner on 2026-10-24.
+
+**Shelter.** For each part (or impl) in range, a segment from the centre to the nearest point of the target is cut against every other part of
+every object, skipping parts already lost and the target itself. A part crossed along a path `p` lets through `exp(-r / k)` of the energy, with
+`r = hpPerKg * density * p * damageScale.shelter` (the hit points of the slab it crosses, per m²) and `k = 2800`. The energy that reaches the target
+is `E * product(t_i)`, and it is used for both the damage and the push. Parts are served from the nearest to the farthest, so a wall takes the blast
+(damage, dents, maybe breaking) before what is behind it. A blocker the same blast destroys or breaches lets `brokenTransmission` (0.5) of what it
+held back go through: `t' = t + (1 - t) * 0.5`. An opening (a breach, a bare rebar cage) from before the blast lets everything through. Impls
+(characters, animals) get one hit with the energy-weighted mean of the share that reaches their parts, and `Hit.shelter` carries it. Impls do not
+shelter anything (they have no material).
+
+| Blocker | Path | Lets through |
+|---|---|---|
+| glass pane | 6 mm | 83% (`damageScale.shelter: 3` in the material) |
+| wooden door (softwood) | 4 cm | 53% |
+| brick wall | 20 cm | 19% |
+| reinforced concrete column | 30 cm | 3% |
+
+**Fragment hits.** The fragments of a part the blast fractures or breaches (the `fracture` and `stage` events) become hits on the first part or impl
+along their flight, in order of energy, at most `max` (24) per blast. Each is a `blunt` hit (or `ballistic` with its mass in grams and a calibre from
+its size) of `energyFactor * m * v² / 2` (0.5), thrown up to `min(range 6 m, speed * flightTime 0.4 s)` within a seeded `spread` (10°) of its
+direction. With `shelter` on, a fragment of a blocker whose line to a target is within `aim` (40°) of its flight goes for that target. The flights
+depend only on the world seed, the blast and the fragment, never on what the world did before. Fragments of what a fragment breaks are not thrown
+again. Events: `fragment_hit` (before the target's own events).
+
+**Confinement.** `confinement: true` shoots `rays` (26) seeded rays from the centre as far as `radius * reach` (1.5) against the world's parts (impls
+do not count; open doors, windows and breaches are absent parts). With `c` the share of rays that hit and `d` their mean distance:
+`multiplier = min(max, 1 + gain * c^power * clamp(radius / d, 0, 2))` with `gain` 1.5, `power` 2, `max` 3. The energy of the whole blast is
+multiplied. Open ground gives 1, a closed room of 6 m about 3, the same room with one wall missing about 2. A number (`confinement: 2.5`, or
+`Hit.confinement`) is the multiplier itself, for a host that knows the room volume.
+
+**What comes back.** `HitResult.blast = { shelter, parts?, confinement, fragmentHits }` per target (`shelter` is the most exposed part's share),
+and one `blast` event per blast (`energy` after confinement, `shelter` per target, `fragmentHits`). `@adatechnology/game-destruction-three` takes
+the results for the push on pieces: `renderer.explode(point, energy, radius, { report: results })`.
+
+### Bullets and blasts against beams and columns
+
+`tests/beams-and-columns.test.ts` documents calibres of `@adatechnology/game-weapons` against a reinforced concrete column and beam, a steel
+I-beam, a hardwood beam and a brick pillar. Two options came out of it, both off or neutral by default:
+
+- `Hit.piercing` (6th argument of `shoot`): how well the bullet cuts through for its energy; the energy compared with the penetration of a hard
+  material (metal, masonry) is `energy * piercing`. `PIERCING_BY_KIND` (fmj 1, hp 0.6, ap 1.6, buck 0.5, slug 0.25) and `PIERCING_BY_CALIBER`
+  (5.56, 5.45 and .22 0.5) give the numbers from `CaliberDef.kind` (`piercingOf(id, kind)`). Without it a 12 ga slug (3000 J) went through 8.5 mm of
+  steel.
+- `breach.blastReach` (default `Infinity`, 0.12 recommended): a blast only opens a breach within `blastReach * cbrt(energy / 1000)` metres of the
+  part. With 0.12 a hand grenade (200 kJ) at 1 m no longer cuts a reinforced column in two (at 0.2 m it strips it).
+
 ## Contracts: implement your own or use the default world
 
 The kit defines contracts; each game module implements them for the objects it owns, and the world in this package is the optional default
@@ -228,9 +281,9 @@ world continues with the same events as the original. The loading world must use
 
 `createDestruction(options)` returns a `DestructionWorld`: `add`, `remove`, `has`, `ids`, `setTransform`, `splitGroup`, `hit`, `hitPart`, `explode`,
 `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.
+`register`, `serialize`, `load`, `time`. `explode(point, energy, radius, source?, blastOptions?)`; `shoot(origin, direction, energy, caliber, source?, piercing?)`. `state()` and `part()` return live views; do not mutate them.
 
-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
+Also exported: `SHELTER_DEFAULTS`, `FRAGMENT_HIT_DEFAULTS`, `CONFINEMENT_DEFAULTS`, `PIERCING_BY_KIND`, `PIERCING_BY_CALIBER`, `piercingOf`, `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:
@@ -244,3 +297,5 @@ plástico derretem e pingam. As juntas cedem com impacto, quando a peça é dest
 parafuso, chave inglesa para porca e parafuso, maçarico para solda). O mundo devolve tudo como eventos para o renderizador desenhar. É
 determinístico (semente fixa) e serializável, então um host de LAN pode rodar o mundo e enviar só as entradas. Os nomes em português
 (materiais, ferramentas, juntas, eventos) estão em `resolveStrings('pt-BR')`.
+
+Explosões: `blast.shelter` (paredes e portas entre a explosão e o alvo ficam com a sua parte: tijolo de 20 cm deixa passar ~19%, porta de madeira ~53%, vidro ~83%; a parede que quebra na mesma explosão deixa passar metade do que segurou), `blast.fragmentHits` (os pedaços do que quebra viram golpes de baixa energia no que está atrás) e `blast.confinement` (pressão num ambiente fechado, de 1 a 3 vezes). Tudo desligado por padrão, por opção do mundo ou da chamada, com os números em `SHELTER_DEFAULTS`, `FRAGMENT_HIT_DEFAULTS` e `CONFINEMENT_DEFAULTS`.

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, 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';
+import { Vec3, Quat, MaterialId, FractureStyle, DamageType, DebrisKind, DestructionEvent, BlastOptions, DestructibleSpec, ObjectState, DestructibleImpl, Hit, HitResult, RayHit, ToolKind, JointState, PartState, DestructionEventType, StructureRole, ConfinementOptions, FragmentHitOptions, ShelterOptions, ExplosionChain, PartSpec, JointKind, JointSpec, PartShape, SurfaceLayer, PartUnits, Reinforcement, PartBreach, PartStatus } from '@adatechnology/game-contracts';
+export { BlastOptions, BlastReport, ChainDelay, ConfinementOptions, Crack, DamageStage, DamageType, DebrisKind, Dent, DestructibleImpl, DestructibleSpec, DestructionEvent, DestructionEventType, ExplosionChain, FluidKind, FractureStyle, Fragment, FragmentHitOptions, FragmentMark, Hit, HitResult, Hole, IMPACT_CONTRACT, ImpactContract, JointKind, JointSpec, JointState, MaterialId, ObjectState, PartBreach, PartShape, PartSpec, PartState, PartStatus, PartUnits, Quat, RayHit, Reinforcement, ShelterOptions, StructureRole, SurfaceLayer, ToolKind, Vec3, checkHit } from '@adatechnology/game-contracts';
 
 /**
  * Public types of @adatechnology/game-destruction.
@@ -52,8 +52,8 @@ interface MaterialDef {
     fracture: FractureStyle;
     /** Fragment size range in metres (default `[0.04, 0.2]`). */
     fragmentSize?: [number, number];
-    /** Damage multipliers per damage type (default 1). */
-    damageScale?: Partial<Record<DamageType, number>>;
+    /** Damage multipliers per damage type (default 1); `shelter` multiplies the resistance the material adds between a blast and a target (`blast.shelter`). */
+    damageScale?: Partial<Record<DamageType | 'shelter', number>>;
     /** Debris emitted on a hit that does not break the part. */
     hitDebris: DebrisKind;
     /** Debris emitted when the part fractures. */
@@ -101,12 +101,23 @@ interface DestructionOptions {
         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;
+        /**
+         * Metres of reach per cube root of kilojoule: a blast only opens a breach in a part within `blastReach * cbrt(energy / 1000)` of the centre
+         * (a hand grenade of 200 kJ: 0.7 m; 2 MJ: 1.5 m). Farther away it still damages, dents and cracks. Without it a falloff that is gentle over a
+         * large radius let a grenade at 1 m cut a reinforced column in two. Default `Infinity` (off, so the goldens stay as they were); 0.12 is the value that matches real charges.
+         */
+        blastReach?: 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;
+    /**
+     * Defaults of every blast (`explode`, an explosive `hit`, a part that explodes); each call can override them. All off by default, and a world
+     * with all of them off gives the results it always gave. See `ShelterOptions`, `FragmentHitOptions` and `ConfinementOptions`.
+     */
+    blast?: BlastOptions;
 }
 interface SizeStructureOptions {
     /** Stress every structural part has at rest after sizing (`load / capacity`), 0..1 (default 0.65). */
@@ -161,12 +172,16 @@ interface DestructionWorld {
     hit(objectId: string, hit: Hit): HitResult;
     /** Apply a hit to a known part (e.g. after the host's own raycast). */
     hitPart(objectId: string, partId: string, hit: Hit): HitResult;
-    /** A blast in world space against every object in range. */
-    explode(point: Vec3, energy: number, radius: number, source?: string): HitResult[];
+    /**
+     * A blast in world space against every object in range. With `options` (else `DestructionOptions.blast`) the blast can be sheltered by what
+     * stands in the way, throw the fragments of what it breaks and gain pressure in an enclosed volume; each `HitResult.blast` says what it did to
+     * that target, and a `blast` event sums it up.
+     */
+    explode(point: Vec3, energy: number, radius: number, source?: string, options?: BlastOptions): HitResult[];
     /** Raycast against every part shape (world space). */
     raycast(origin: Vec3, direction: Vec3, maxDistance?: number): RayHit | null;
     /** Ballistic shot: raycast, hit, and continue through with the exit energy (up to 4 objects/parts). */
-    shoot(origin: Vec3, direction: Vec3, energy: number, caliber: number, source?: string): HitResult[];
+    shoot(origin: Vec3, direction: Vec3, energy: number, caliber: number, source?: string, piercing?: number): HitResult[];
     /**
      * Work on a joint with a tool for `dt` seconds (call every frame while the player holds the button). Returns the progress 0..1, or -1 when the
      * tool cannot undo this joint. At 1 the joint opens (`detach` with `by: 'tool'`).
@@ -257,6 +272,15 @@ interface DestructionSnapshot {
     }>;
 }
 
+/**
+ * Blast options (all off until asked for). Shelter: a part the line from the blast to the target crosses lets through `exp(-r / k)`, `r` being the
+ * hit points of the slab it crosses per square metre (`hpPerKg * density * path * damageScale.shelter`). Fragment hits: up to 24 fragments, half their
+ * kinetic energy lands as a blunt hit, thrown at most 6 m (and `speed * 0.4 s`) within 10 degrees of their aim. Confinement: 26 rays reaching
+ * `1.5 * radius`, multiplier `1 + 1.5 * closedShare^2 * clamp(radius / meanDistance, 0, 2)` up to 3.
+ */
+declare const SHELTER_DEFAULTS: Required<ShelterOptions>;
+declare const FRAGMENT_HIT_DEFAULTS: Required<FragmentHitOptions>;
+declare const CONFINEMENT_DEFAULTS: Required<ConfinementOptions>;
 declare const createDestruction: (options?: DestructionOptions) => DestructionWorld;
 
 /** What can set an explosive part off from outside, in the order a hit can carry it. */
@@ -280,6 +304,18 @@ interface ExplosivePartOptions {
  */
 declare const explosivePart: (explosive: WorldExplosive, part: Omit<PartSpec, "explodes">, options?: ExplosivePartOptions) => PartSpec;
 
+/**
+ * How well a bullet cuts through for its energy (`Hit.piercing`, the 6th argument of `shoot`). The material's `penetration` is joules per
+ * millimetre for a hard bullet; soft lead deforms on steel and concrete and a core of hardened steel does better. A host that knows the kind
+ * of the bullet (`CaliberDef.kind` of `@adatechnology/game-weapons`) takes the number from here, or replaces the tables with its own.
+ *
+ * Reference: a 12 ga slug (3000 J) does not go through 8 mm of mild steel, a .50 BMG (18000 J) goes through 20 mm and more.
+ */
+declare const PIERCING_BY_KIND: Readonly<Record<string, number>>;
+/** Caliber ids whose bullet is lighter on the target than its kind says (a soft-core 5.56 ball does not go through a steel flange). */
+declare const PIERCING_BY_CALIBER: Readonly<Record<string, number>>;
+declare const piercingOf: (caliber: string, kind?: string) => number;
+
 /** Built-in materials (data in `src/data/materials.json`). Override or extend with the `materials` option of `createDestruction`. */
 declare const MATERIALS: MaterialDef[];
 /** Default joint strength (joint hit points), tools that undo it and seconds of tool work. */
@@ -481,4 +517,4 @@ declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions
     problems: string[];
 };
 
-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 };
+export { ASSEMBLIES, type AddOptions, type AssemblyDef, type AssemblyPartOptions, CONFINEMENT_DEFAULTS, type ChainTrigger, type CheckOptions, type DestructionLocale, type DestructionOptions, type DestructionSnapshot, type DestructionStrings, type DestructionWorld, type ExplosivePartOptions, FIRE_PRIME_C, FRAGMENT_HIT_DEFAULTS, type FrameOptions, JOINT_BY_MATERIALS, JOINT_DEFAULTS, MATERIALS, type MaterialDef, type MaterialThermal, type ObjectRuntime, PIERCING_BY_CALIBER, PIERCING_BY_KIND, type PartRuntime, SHELTER_DEFAULTS, type SizeStructureOptions, type WorldExplosive, assemblyDepth, assemblyPart, buildFrame, checkDestructible, createDestruction, explosivePart, fragility, getAssembly, guessMaterial, inferJoints, locales, partCapacity, partMass, partThickness, partVolume, piercingOf, quat, quatFromEuler, registerAssembly, resolveStrings, rotateVec, sizeStructure, toLocal, toWorld, vec };