@adatechnology/game-destruction 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @adatechnology/game-destruction
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Engine-agnostic destruction model. An object is an assembly of **parts** (box, cylinder or sphere with a material) held together by **joints**.
+Materials decide what a hit does: steel dents and gets holes, glass cracks and shatters, wood splinters and burns to ash, concrete crumbles,
+aluminium and plastic melt and drip. Joints break under impulse, open when their parts are destroyed (the object breaks apart) or are undone with
+the right tool (the object is taken apart). The world reports everything as **events** that a renderer draws. No dependencies, no renderer, no game.
+
+Units: metres, kilograms, seconds, joules, degrees Celsius.
+
+Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-destruction
+```
+
+In a browser without a bundler, load `dist/index.global.js`; it exposes the `GameDestruction` global.
+
+## Quick start
+
+```ts
+import { createDestruction } from '@adatechnology/game-destruction'
+
+const world = createDestruction({ seed: 42 })
+world.on('*', (e) => draw(e)) // dent, hole, crack, fracture, detach, ignite, melt, leak, explode...
+
+const chair = world.add({
+  name: 'chair',
+  parts: [
+    { id: 'seat', material: 'wood_soft', shape: { kind: 'box', size: [0.4, 0.04, 0.4] }, position: [0, 0.42, 0] },
+    { id: 'leg_fl', material: 'wood_soft', shape: { kind: 'box', size: [0.04, 0.4, 0.04] }, position: [0.18, 0.2, 0.18] },
+    // ...joints are inferred from touching parts unless you pass `joints`
+  ],
+})
+
+world.shoot([0, 1, 5], [0, 0, -1], 500, 9) // 9 mm, 500 J: raycast, hit, continue through
+world.hit(chair, { type: 'blunt', point: [0.2, 0.2, 0.18], direction: [-1, 0, 0], energy: 300, radius: 0.05 })
+world.hit(chair, { type: 'fire', point: [0, 0.4, 0], temperature: 1000, radius: 0.5, duration: 2 })
+
+world.disassemble(chair, 'seat~leg_fl', 'screwdriver', dt) // progress 0..1, -1 for the wrong tool
+for (const e of world.update(dt)) draw(e) // burning, melting, heat transfer, leaks, delayed explosions
+```
+
+The renderer or physics engine owns transforms: call `setTransform` to keep the world in sync, and after a `detach` use `splitGroup` to turn a loose
+piece into its own object (and body).
+
+## Materials
+
+26 built-in materials in `src/data/materials.json` (override or extend with the `materials` option). Hit points per kilogram, penetration energy per
+millimetre, ductility and fracture style drive the model.
+
+| Family | Ids | Behaviour |
+|---|---|---|
+| Metal | `steel`, `cast_iron`, `aluminium`, `copper` | dent, holes, sparks, ricochet, glow when hot; melt at 1450 / 1200 / 660 / 1085 °C. Never fracture (cast iron cracks and snaps) |
+| Wood | `wood_soft`, `wood_hard`, `plywood`, `mdf` | splinter or snap, ignite near 300 °C, burn, char, turn to ash |
+| Glass and ceramic | `glass`, `tempered_glass`, `ceramic` | crack, then `shatter` into shards (`tempered_glass` is `crumble` into tiny chunks); thermal shock |
+| Masonry and soil | `concrete`, `brick`, `plaster`, `stone`, `soil` | `crumble` with dust and chips; do not burn |
+| Plastics | `plastic`, `rubber`, `foam`, `wax` | plastic snaps and melts near 200 °C, rubber and foam burn with black smoke, wax melts at 60 °C |
+| Soft | `fabric`, `leather`, `paper` | `tear`, ignite easily and burn fast |
+| Plants | `foliage`, `green_wood`, `cactus`, `flesh_fruit` | `tear` / `splinter`, hard to ignite (high water content) |
+
+`guessMaterial(name)` maps a mesh name to a material id from the keyword table in `src/data/material-hints.json` (English keywords, longest match
+wins): `guessMaterial('Chrome_Bumper') === 'steel'`.
+
+### Tuning
+
+A hit removes `energy * 0.02 * damageScale` hit points. A 9 mm (500 J) breaks a 0.6 m glass pane in 5 hits, tempered glass in 11, a wooden chair leg in 3,
+and never breaks steel (it collects holes). A projectile goes through when `energy > penetration (J/mm) * thickness (mm)`: 9 mm through 1 mm steel
+makes a through hole, through 5 cm concrete it only cracks and lodges. Grazing hits count a longer path through the material and can ricochet.
+
+## Damage types
+
+| Type | Inputs | Effect |
+|---|---|---|
+| `ballistic` | `energy`, `caliber` | hole (through or lodged), dent, crack, ricochet, debris, joint wear next to the impact |
+| `blunt` | `energy`, `radius` | dents on ductile parts, cracks on brittle ones, wears every joint of the part (a hard kick pulls a leg off) |
+| `slash` | `energy` | like blunt, with extra damage on fabric, foliage and wood; opens fabric |
+| `explosive` | `energy`, `radius` | falloff `(1 - d/r)^2`, damage, dents facing the blast, joints break, fragments fly (capped at 40 m/s), flammables ignite |
+| `fire` | `temperature`, `radius`, `duration` | heats towards the flame temperature and ignites at the material's ignition point |
+| `heat` | same | heat without flame (cutting torch, hot plate); melts what it can reach |
+
+`hit(objectId, hit)` finds the part along `direction`; `hitPart` targets a known part; `shoot` and `raycast` work in world space.
+
+## 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
+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
+`direction` and the rate in litres per second, and `PartState.liters` drops in `update` (`setLiters` fills or empties a container).
+
+## Joints and tools
+
+| Kind | Strength | Tools | Seconds |
+|---|---|---|---|
+| `screw` | 80 | screwdriver | 2.5 |
+| `bolt` | 200 | wrench | 4 |
+| `nail` | 60 | pry_bar, hammer | 2 |
+| `weld` | 600 | cutting_torch, saw | 8 |
+| `glue` | 50 | pry_bar, knife | 3 |
+| `hinge` | 120 | screwdriver | 3 |
+| `clip` | 20 | hand | 0.6 |
+| `tie` | 15 | knife, hand | 1 |
+| `mortar` | 400 | hammer | 6 |
+| `fused` | 1000 | none (can only break) | 0 |
+| `stem` | 40 | knife, saw, hand | 1.5 |
+| `rebar` | 1500 | cutting_torch, saw | 20 |
+| `resting` | 30 | hand | 1 |
+
+`inferJoints` joins parts whose bounds touch (default tolerance 1 cm) with the kind from `JOINT_BY_MATERIALS`. Joints open when their hit points
+run out (`detach` with `by: 'break'`), when a part is lost (`'part_lost'`) or when a tool finishes the work (`'tool'`). `ObjectState.groups` lists
+the connected pieces; index 0 keeps the object's id (the anchored one, else the heaviest).
+
+## Structural integrity
+
+Give parts a `structure: { role, capacity? }` (`foundation`, `column`, `beam`, `slab`, `wall`, `partition`, `roof`, `stair`, `none`) and the world
+solves loads: each structural part carries its own mass plus what rests on it, down to the anchored parts (`foundation` implies `anchored`).
+`PartState.load` is in kg and `PartState.stress` is `load / capacity`. Parts without a role (windows, doors, furniture) carry nothing. Objects
+without any `structure` behave exactly as before.
+
+- **Capacity** defaults to `material.compressive` (kg per m²: concrete 444 000, brick 40 000, softwood 100 000, steel 2 000 000) times the section:
+  the two smallest dimensions for columns, beams, roofs and stairs (foundations x10), thickness times longest side for slabs, thickness times
+  horizontal length for walls. A 0.3 m concrete column carries 40 t, a 0.2 m brick wall 8 t per metre, a 0.1 x 0.2 m softwood beam 2 t.
+- **Joints** carry load when `bears` is true (default when both parts have a role). `bears: 'a_on_b'` means part `a` rests on `b`: load flows only
+  that way. A `partition` is supported but supports nothing, so breaking it never drops anything.
+- **Overload**: above stress 1 a part takes `(stress - 1) * maxHp * 0.5` damage per second, emits `stress` (once per 0.5 s) and cascades; brittle
+  parts `crack` from stress 0.8. Metal never fractures, so overloaded steel only reports stress.
+- **Collapse**: a part with no support path to an anchored part falls: it is cut from the supported pieces into its own group (index 1 or more) and
+  one `collapse` event lists the group. Non-structural parts that hang only on collapsed parts fall with them. Make the group its own object with
+  `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.
+
+## 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
+implementation. A module implements `DestructibleImpl` (`describe`, `hit`, `update`, `state`, `reset`, `disassemble`, `extinguish`,
+`serialize`, `load`) and registers it:
+
+```ts
+const id = world.register(myVehicleDoor, { position: [10, 0, 0] })
+world.shoot(origin, dir, 500, 9) // passes through default objects and impls in order
+```
+
+The world routes raycast, shoot, explode, hit, disassemble, extinguish, update, state, reset, remove and `on` to the impl; its events go through the
+same listeners in order. The impl receives hits in world space and returns events in world space (the transform given to `register` and
+`setTransform` is only used for raycast and blast range). `splitGroup` on an impl throws. After a shot that goes through an impl the world assumes
+half of the energy continues when a through `hole` was reported. `checkDestructible(impl, { materials })` returns `{ ok, problems }`: `describe()`
+valid (unique ids, known materials, joints reference parts), a 500 J ballistic hit returns events of this impl naming known parts, `state()` matches
+`describe()`, hit points never go negative, `update(0.016)` returns an array, events are finite JSON.
+
+### Impact contract (what weapons must produce)
+
+| `type` | Required | Optional | Notes |
+|---|---|---|---|
+| `ballistic` | `point`, `direction`, `energy`, `caliber` | `space`, `source` | joules, diameter in millimetres |
+| `blunt` | `point`, `energy` | `direction`, `radius`, `space`, `source` | contact radius in metres |
+| `slash` | `point`, `energy` | `direction`, `radius`, `space`, `source` | axes, knives |
+| `explosive` | `point`, `energy`, `radius` | `space`, `source` | `point` is the blast centre |
+| `fire` | `point`, `temperature`, `radius` | `duration`, `space`, `source` | call every frame with `duration: dt` |
+| `heat` | `point`, `temperature`, `radius` | `duration`, `space`, `source` | cutting torch, hot plate |
+
+`IMPACT_CONTRACT` holds this table as data and `checkHit(hit)` returns the problems of a hit.
+
+## Events
+
+`damage`, `dent`, `hole`, `crack`, `ricochet`, `debris`, `fracture` (with oriented `fragments` in world space), `detach`, `disassemble_progress`,
+`ignite`, `extinguish`, `burnout`, `melt`, `drip`, `leak`, `explode`, `stress`, `collapse`, `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
+
+Every random choice comes from the world seed (mulberry32), never `Math.random`, and the generator state is part of the snapshot. A LAN host can
+run the world and send only the inputs (hits, `update(dt)` calls), or the events. `serialize()` / `load()` give a plain JSON round trip: a loaded
+world continues with the same events as the original. The loading world must use the same materials.
+
+## API
+
+`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.
+
+Also exported: `buildFrame`, `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:
+`resolveStrings('pt-BR').materialNames.glass === 'vidro'`. Unknown locales fall back to `en`.
+
+## Português
+
+Modelo de destruição independente de engine. Um objeto é um conjunto de peças (caixa, cilindro ou esfera com um material) unidas por juntas. O
+material decide o efeito: o aço amassa e fura, o vidro trinca e estilhaça, a madeira lasca e vira cinza, o concreto esfarela, o alumínio e o
+plástico derretem e pingam. As juntas cedem com impacto, quando a peça é destruída ou quando se usa a ferramenta certa (chave de fenda para
+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')`.

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+import { Vec3, Quat, MaterialId, FractureStyle, DamageType, DebrisKind, DestructionEvent, DestructibleSpec, ObjectState, DestructibleImpl, Hit, HitResult, RayHit, ToolKind, JointState, PartState, DestructionEventType, JointKind, PartSpec, JointSpec, PartShape, PartStatus, StructureRole } from '@adatechnology/game-contracts';
+export { Crack, DamageType, DebrisKind, Dent, DestructibleImpl, DestructibleSpec, DestructionEvent, DestructionEventType, 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';
+
+/**
+ * Public types of @adatechnology/game-destruction.
+ *
+ * The model is renderer-free. An object is an assembly of parts (simple shapes with a material) held together by joints. Materials decide what a
+ * hit does: ductile parts dent and get holes, brittle parts crack and shatter, wood splinters, masonry crumbles, flammable parts ignite, char and
+ * turn to ash, fusible parts melt and drip. Joints break under impulse or when their parts are destroyed (the object breaks apart), or are undone
+ * with the right tool (the object is taken apart). The world reports everything as events that a renderer draws.
+ *
+ * Units: metres, kilograms, seconds, joules, degrees Celsius. Every random choice comes from the world seed, so the same inputs give the same
+ * events on every machine (a LAN host can run the world and send only the inputs, or the events).
+ */
+
+interface MaterialThermal {
+    /** Temperature at which the part catches fire. Omit for non-flammable. */
+    ignitionC?: number;
+    /** Flame temperature while burning (default 800). */
+    flameC?: number;
+    /** Fraction of the part's mass that can burn, 0..1 (wood 0.9, fabric 1, plastic 0.8). */
+    fuelFraction?: number;
+    /** Burn speed in kg per second per square metre of surface (wood ~0.012, fabric ~0.05, foliage ~0.08). */
+    burnRate?: number;
+    /** Temperature at which the part starts to melt. Omit for materials that do not melt in game (wood, fabric). */
+    meltC?: number;
+    /** Melt speed: fraction of the part per second per 100 °C above `meltC` (default 0.05). */
+    meltRate?: number;
+    /** Heat transfer to touching parts, 0..1 (copper 1, steel 0.5, wood 0.05). */
+    conductivity: number;
+    /** Temperature change per second per unit of heat input; lower means it heats and cools faster (default 1). */
+    heatCapacity?: number;
+    /** Brittle parts crack when their temperature changes faster than this many °C per second (glass ~150). */
+    thermalShockC?: number;
+    /** Smoke the material gives while burning (`black` for plastic and rubber). */
+    smoke?: 'white' | 'grey' | 'black';
+}
+interface MaterialDef {
+    id: MaterialId;
+    /** Density in kg/m³ (used when a part has no `mass`). */
+    density: number;
+    /** Structural hit points per kilogram. */
+    hpPerKg: number;
+    /**
+     * Energy in joules a projectile needs to go through 1 mm of this material. A projectile that carries more than `penetration * thicknessMm` goes
+     * through and keeps the rest; one that carries less stops (dent, crack or lodge).
+     */
+    penetration: number;
+    /** 0 = brittle (glass), 1 = very ductile (soft steel). Ductile parts dent and bend before they break; brittle parts crack and shatter. */
+    ductility: number;
+    /** How the part fails when its hp reaches 0. */
+    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>>;
+    /** Debris emitted on a hit that does not break the part. */
+    hitDebris: DebrisKind;
+    /** Debris emitted when the part fractures. */
+    breakDebris: DebrisKind;
+    /** A ballistic hit at a grazing angle (below this many degrees from the surface) ricochets; 0 = never (default 0). */
+    ricochetDeg?: number;
+    thermal: MaterialThermal;
+    /** Hints for the renderer. Colours are `0xRRGGBB`. */
+    visual?: {
+        /** Colour a fully charred surface turns to (default 0x1a1410). */
+        charColor?: number;
+        /** The material glows red to white when hot (metals, glass). */
+        glows?: boolean;
+        /** Transparent (glass): cracks are drawn as a star on the surface. */
+        transparent?: boolean;
+    };
+    /** Free tags, e.g. `metal`, `organic`, `conductive`. */
+    tags?: string[];
+    /**
+     * Load a structural part of this material carries per square metre of cross-section, in kg (game-tuned: concrete 444 000, brick 40 000,
+     * softwood 100 000, steel 2 000 000). Default 20 000. See `PartSpec.structure`.
+     */
+    compressive?: number;
+}
+interface DestructionOptions {
+    /** Extra or overriding materials (merged over `MATERIALS` by id). */
+    materials?: MaterialDef[];
+    /** Seed for every random choice (default 1). */
+    seed?: number;
+    /** Ambient temperature (default 20). */
+    ambientC?: number;
+    /** Called for every event, in order. */
+    onEvent?: (event: DestructionEvent) => void;
+    /** Maximum fragments in one `fracture` event (default 24). The renderer can draw fewer. */
+    maxFragments?: number;
+    /** Maximum dents kept per part; older nearby dents merge (default 24). */
+    maxDents?: number;
+    /** Maximum holes kept per part (default 32). */
+    maxHoles?: number;
+    /** Distance at which a burning part heats parts of other objects, in metres (default 0.6). */
+    fireSpread?: number;
+}
+interface AddOptions {
+    /** Object id (default a generated `obj_1`, `obj_2`...). */
+    id?: string;
+    position?: Vec3;
+    rotation?: Quat;
+}
+interface DestructionWorld {
+    readonly materials: ReadonlyMap<MaterialId, MaterialDef>;
+    /** Add an object and return its id. */
+    add(spec: DestructibleSpec, options?: AddOptions): string;
+    /**
+     * Host an object whose behaviour a game module owns (see `DestructibleImpl`) next to the world's own objects. Returns its id (`options.id`, else
+     * `impl.id`). Raycast, shoot, explode, hit, disassemble, extinguish, update, state, reset, remove and `on` route to it; its events go through the
+     * same listeners in order. `splitGroup` on it throws.
+     */
+    register(impl: DestructibleImpl, options?: AddOptions): string;
+    remove(id: string): void;
+    has(id: string): boolean;
+    ids(): string[];
+    /** Move an object (the renderer or physics owns transforms; keep the world in sync so world-space hits land). */
+    setTransform(id: string, position: Vec3, rotation: Quat): void;
+    /**
+     * Split a loose group into its own object (after a `detach`, when the renderer makes the piece a separate body). The parts move with their
+     * state; the new object starts at the old object's transform. Returns the new id.
+     */
+    splitGroup(id: string, group: number, newId?: string): string;
+    /** Apply a hit to one object (to the part it lands on, or for `explosive`/`fire`/`heat`, to every part in `radius`). */
+    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[];
+    /** 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[];
+    /**
+     * 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'`).
+     */
+    disassemble(objectId: string, jointId: string, tool: ToolKind, dt: number): number;
+    /** Joints of an object that `tool` can undo now (open joints excluded). */
+    workableJoints(objectId: string, tool: ToolKind): JointState[];
+    /** Joint nearest to a world point (for "aim at the screw"). */
+    nearestJoint(objectId: string, point: Vec3, maxDistance?: number): JointState | null;
+    /** Put out fire on a part or the whole object, and cool it by `coolC` (default 200). */
+    extinguish(objectId: string, partId?: string, coolC?: number): void;
+    /** Advance fire, heat transfer, cooling, melting, leaks and delayed explosions. */
+    update(dt: number): DestructionEvent[];
+    state(id: string): ObjectState | null;
+    part(id: string, partId: string): PartState | null;
+    /** Repair an object to its spec (test benches use it for "reset"). */
+    reset(id: string): void;
+    on(type: DestructionEventType | '*', fn: (event: DestructionEvent) => void): () => void;
+    /** Plain JSON of every object (spec + state + transform) and the rng state. */
+    serialize(): DestructionSnapshot;
+    load(snapshot: DestructionSnapshot): void;
+    /**
+     * Fill or empty a container part (`PartSpec.contains`); `liters` is clamped to `[0, contains.liters]` of its spec. Used by fluid simulations
+     * that drain or refill the part. Does nothing when the part has no `contains`.
+     */
+    setLiters(objectId: string, partId: string, liters: number): void;
+    /** Seconds since creation. */
+    readonly time: number;
+}
+/** Internal bookkeeping of a part that is saved with the world so that a loaded world continues identically. Treat as opaque. */
+interface PartRuntime {
+    /** Last melt fraction reported in a `melt` event. */
+    meltEmitted: number;
+    /** Seconds since the last `drip`. */
+    dripT: number;
+    /** Temperature at the end of the previous update (thermal shock). */
+    prevTemp: number;
+    /** Seconds left before another thermal crack is allowed. */
+    shockT: number;
+    /** A leaking flammable fluid is burning on this part. */
+    jet: boolean;
+    /** Seconds left before the next `stress` event. */
+    stressT?: number;
+}
+/** Opaque bookkeeping of an object (see `PartRuntime`). `joints` holds the last disassembly step reported per joint id. */
+interface ObjectRuntime {
+    parts: Record<string, PartRuntime>;
+    joints: Record<string, number>;
+    /** Parts of groups that already reported a `collapse`. */
+    collapsed?: string[];
+}
+interface DestructionSnapshot {
+    version: 1;
+    time: number;
+    rng: number;
+    /** Counter for generated object ids (`obj_1`...). */
+    counter?: number;
+    objects: Array<{
+        id: string;
+        spec: DestructibleSpec;
+        state: ObjectState;
+        runtime?: ObjectRuntime;
+    }>;
+    /** Registered impls: transform and `serialize()` data. `load` restores them into impls registered under the same ids. */
+    impls?: Array<{
+        id: string;
+        position: Vec3;
+        rotation: Quat;
+        data?: unknown;
+    }>;
+}
+
+declare const createDestruction: (options?: DestructionOptions) => DestructionWorld;
+
+/** 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. */
+declare const JOINT_DEFAULTS: Record<JointKind, {
+    strength: number;
+    tools: ToolKind[];
+    seconds: number;
+}>;
+/**
+ * The joint kind that fits two materials: glass is glued (clipped to plastic), soft things are tied, plants share a stem, masonry gets mortar,
+ * metal is welded, wood is screwed, plastic clips. `inferJoints` refines weld to bolt for thick metal and screw to nail for thin wood.
+ */
+declare const JOINT_BY_MATERIALS: (a: MaterialDef, b: MaterialDef) => JointKind;
+/** Guess a material id from a mesh or node name (case-insensitive substring; the longest keyword wins). */
+declare const guessMaterial: (name: string) => MaterialId | undefined;
+/** Volume of a shape in m³. */
+declare const partVolume: (shape: PartShape) => number;
+/** Mass of a part in kg: its `mass`, or density × volume × fill. */
+declare const partMass: (part: PartSpec, material: MaterialDef) => number;
+/** Wall thickness of a part in metres (see `PartSpec.thickness`). */
+declare const partThickness: (part: PartSpec) => number;
+/**
+ * Joints for touching parts. Two parts touch when their axis-aligned bounds (after rotation), grown by `tolerance` metres, overlap. The kind comes
+ * from `JOINT_BY_MATERIALS`; thick metal pairs (smallest dimension of both >= 2 cm) get a `bolt` instead of a `weld`, and thin wood pairs (either
+ * under 2 cm) a `nail` instead of a `screw`.
+ */
+declare const inferJoints: (parts: PartSpec[], tolerance?: number, materials?: ReadonlyMap<string, MaterialDef>) => JointSpec[];
+/**
+ * Load in kg a structural part carries before it fails: `structure.capacity`, else `material.compressive` (default 20 000 kg/m²) times the
+ * section. The section is the product of the two smallest dimensions (thickness times longest dimension for slabs; thickness times horizontal length for walls); foundations get x10.
+ */
+declare const partCapacity: (part: PartSpec, material: MaterialDef) => number;
+/**
+ * Multiplier of blunt damage on brittle parts (ductility < 0.3): up to x4.7 for fully brittle materials (glass, ceramic, stone), times a thinness
+ * term that follows bending stress (1 / thickness squared, x1 at 2 cm or more, at most x25). A 3 mm glass bottle breaks from a 1.5 m drop; a
+ * concrete block (thick) is only ever x4.4.
+ */
+declare const fragility: (ductility: number, thickness: number) => number;
+
+interface FrameOptions {
+    /** Total length along x between the outer column centres, metres (default 8). */
+    spanX?: number;
+    /** Total length along z (default 8). */
+    spanZ?: number;
+    /** Columns along x (at least 2, default 3). */
+    columnsX?: number;
+    /** Columns along z (at least 2, default 3). */
+    columnsZ?: number;
+    /** Height of one floor from slab top to the underside of the next slab, metres (default 3). */
+    height?: number;
+    /** Number of floors (default 1). */
+    floors?: number;
+    /** Brick walls on every perimeter bay of every floor; the first bay of the ground floor on the -z side gets a door opening (default false). */
+    walls?: boolean;
+    /** A thin roof slab resting on the top beams (default true); without it the top floor is open. */
+    roof?: boolean;
+    columnSize?: number;
+    beamHeight?: number;
+    slabThickness?: number;
+    wallThickness?: number;
+    doorWidth?: number;
+    doorHeight?: number;
+    /** Material of foundations, columns, beams, slabs and roof (default `concrete`). */
+    material?: MaterialId;
+    wallMaterial?: MaterialId;
+    /** Override the load capacity of every column, kg (see `PartState.load`). */
+    columnCapacity?: number;
+}
+/**
+ * A parametric test structure: a grid of columns on foundations, beams between the column tops, one slab per floor (the last one a roof), and
+ * optional brick walls with a door. Joints are explicit and directional: columns rest on foundations (or on the slab below) with `rebar`, beams on
+ * columns, slabs on beams, the roof rests on the top beams, walls hang on their columns with `mortar`. Part ids: `foundation_i_j`, `column_f_i_j`,
+ * `beam_x_f_i_j`, `beam_z_f_i_j`, `slab_f`, `roof`, `wall_*`, `door`. Ground is y = 0 (the top of the foundations).
+ */
+declare const buildFrame: (o?: FrameOptions) => DestructibleSpec;
+
+/** Small vector helpers (arrays of three numbers). Pure functions; they allocate a new array. */
+declare const vec: {
+    add: (a: Vec3, b: Vec3) => Vec3;
+    sub: (a: Vec3, b: Vec3) => Vec3;
+    scale: (a: Vec3, s: number) => Vec3;
+    dot: (a: Vec3, b: Vec3) => number;
+    cross: (a: Vec3, b: Vec3) => Vec3;
+    length: (a: Vec3) => number;
+    distance: (a: Vec3, b: Vec3) => number;
+    normalize: (a: Vec3, fallback?: Vec3) => Vec3;
+    lerp: (a: Vec3, b: Vec3, t: number) => Vec3;
+    /** `a + b * s` */
+    madd: (a: Vec3, b: Vec3, s: number) => Vec3;
+};
+/** Quaternion helpers (`[x, y, z, w]`). */
+declare const quat: {
+    identity: () => Quat;
+    /** Hamilton product `a * b` (apply `b` first, then `a`). */
+    mul: (a: Quat, b: Quat) => Quat;
+    conjugate: (q: Quat) => Quat;
+    normalize: (q: Quat) => Quat;
+    /** Rotation of `angle` radians around a unit `axis`. */
+    fromAxisAngle: (axis: Vec3, angle: number) => Quat;
+    /** Rotation matrix, row-major 3x3. */
+    toMatrix: (q: Quat) => number[];
+    /** Quaternion from three orthonormal columns (the images of the x, y and z axes). */
+    fromColumns: (cx: Vec3, cy: Vec3, cz: Vec3) => Quat;
+};
+/** Quaternion from Euler angles in radians, order XYZ (the three.js default). */
+declare const quatFromEuler: (x: number, y: number, z: number) => Quat;
+/** Rotate a vector by a quaternion. */
+declare const rotateVec: (q: Quat, v: Vec3) => Vec3;
+/** World point to the local space of a transform (`position`, `rotation`). */
+declare const toLocal: (position: Vec3, rotation: Quat, p: Vec3) => Vec3;
+/** Local point of a transform (`position`, `rotation`) to world space. */
+declare const toWorld: (position: Vec3, rotation: Quat, p: Vec3) => Vec3;
+
+/** Locales shipped with the package. Unknown locales fall back to `en`. */
+type DestructionLocale = 'en' | 'pt-BR';
+interface DestructionStrings {
+    /** Display name per material id (see `MATERIALS`). Unknown ids are not listed. */
+    materialNames: Record<string, string>;
+    partStatus: Record<PartStatus, string>;
+    jointKinds: Record<JointKind, string>;
+    toolKinds: Record<ToolKind, string>;
+    damageTypes: Record<DamageType, string>;
+    /** Short label per event type, for logs and kill-feed style text. */
+    eventLabels: Record<DestructionEventType, string>;
+    fractureStyles: Record<FractureStyle, string>;
+    structureRoles: Record<StructureRole, string>;
+}
+declare const locales: Record<DestructionLocale, DestructionStrings>;
+declare const resolveStrings: (locale: string | undefined) => DestructionStrings;
+
+interface CheckOptions {
+    /** Ids of custom materials the impl uses besides the built-in `MATERIALS`. */
+    materials?: string[];
+}
+/**
+ * `checkDestructible` of `@adatechnology/game-contracts`, with the built-in `MATERIALS` (plus `options.materials`) as the known material ids.
+ * It hits the impl (and calls `reset()` afterwards when there is one).
+ */
+declare const checkDestructible: (impl: DestructibleImpl, options?: CheckOptions) => {
+    ok: boolean;
+    problems: string[];
+};
+
+export { type AddOptions, type CheckOptions, type DestructionLocale, type DestructionOptions, type DestructionSnapshot, type DestructionStrings, type DestructionWorld, type FrameOptions, JOINT_BY_MATERIALS, JOINT_DEFAULTS, MATERIALS, type MaterialDef, type MaterialThermal, type ObjectRuntime, type PartRuntime, buildFrame, checkDestructible, createDestruction, fragility, guessMaterial, inferJoints, locales, partCapacity, partMass, partThickness, partVolume, quat, quatFromEuler, resolveStrings, rotateVec, toLocal, toWorld, vec };