@adatechnology/game-destruction-three 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,136 @@
-# Temporary Holding Version
+# @adatechnology/game-destruction-three
 
-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.
+three.js renderer for [`@adatechnology/game-destruction`](../game-destruction). The core decides what a hit does and reports it as events; this
+package draws them on your meshes: vertex dents, bullet-hole and crack decals, char and heat glow, melting and puddles, fragments with light
+physics, loose pieces after a part comes off, and pooled particles (fire, smoke, sparks, dust, shards, splinters, ...).
+
+- Nothing is changed in place: geometry and materials are cloned on the first visual change of a mesh, and `restore` / `clear` give the originals back.
+- Two pooled `THREE.Points` (additive and normal blending) draw every particle, with a soft sprite computed in the shader (no texture asset).
+- `three` is a peer dependency used for types only: you pass your own `THREE` instance at runtime.
+- Sounds are not played: you get keys (`impact_metal`, `shatter_glass`, ...) through `onSound`.
+
+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-three @adatechnology/game-destruction three
+```
+
+Browser without a bundler (the global is `GameDestructionThree`; it bundles the core, so you only need three.js and this file):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-destruction-three/dist/index.global.js"></script>
+<script>
+  const { spec, parts } = GameDestructionThree.specFromObject3D(THREE, model)
+</script>
+```
+
+## Usage
+
+```ts
+import * as THREE from 'three'
+import { createDestruction } from '@adatechnology/game-destruction'
+import { createDestructionRenderer, specFromObject3D } from '@adatechnology/game-destruction-three'
+
+const scene = new THREE.Scene()
+const world = createDestruction({ seed: 7 })
+const renderer = createDestructionRenderer(THREE, {
+  scene,
+  world,
+  quality: 'medium',
+  groundAt: (x, z) => terrain.heightAt(x, z), // default: flat at y = 0
+  onPiece: (piece) => grabbable.push(piece),
+  onSound: (key, point, volume) => audio.play(key, point, volume),
+})
+
+// 1. describe a model: one part per mesh, materials guessed from names, joints inferred from touching parts
+scene.add(chairModel)
+const { spec, parts } = specFromObject3D(THREE, chairModel, { name: 'chair', anchorBelow: 0.01 })
+
+// 2. register it in the world and bind it to the model (the world follows chairModel's transform)
+const id = world.add(spec, { position: [2, 0, -3] })
+renderer.bind(id, chairModel, { parts })
+
+// 3. hit it, burn it, take it apart
+world.shoot([0, 1.5, 0], [0, 0, -1], 2500, 9)
+world.hit(id, { type: 'fire', point: [2, 0.4, -3], temperature: 900, radius: 0.3, duration: 0.2 })
+
+// 4. every frame
+function frame(dt: number) {
+  world.update(dt)
+  renderer.update(dt)
+}
+
+// make a bound object a thrown prop
+const piece = renderer.makePiece(id, { mass: 6 })
+renderer.impulse(id, [0, 40, -120], [2, 0.6, -3])
+```
+
+`bind` finds the meshes of each part from `options.parts` (what `specFromObject3D` returns), else from `userData.destructionPart` or a mesh name that
+equals a part id, else by the part box that contains the mesh centre. `specFromObject3D` reads `userData.destructionMaterial`,
+`destructionPart`, `destructionIgnore`, `destructionTags` and `hollow`.
+
+## What each event draws
+
+| Event | Visual | Sound key |
+|---|---|---|
+| `dent` | vertices within `dent.radius` pushed in by `depth * (1 - (d/r)^2)^2` (skipped on `low` for meshes over 20k vertices); sparks on metal | `impact_*` |
+| `hole` | dark disc decal on the surface (and on the exit side of a through hole); a crack star on transparent materials; sparks on metal | `impact_*` |
+| `crack` | star of jagged lines, white on glass, dark otherwise | `impact_*` |
+| `ricochet` | sparks along the reflected direction | `ricochet` |
+| `debris` | a burst of the requested kind (`sparks`, `dust`, `shards`, `splinters`, `chips`, `fibers`, `leaves`, `drips`, `ash`, `smoke`, `steam`) | |
+| `fracture` | part hidden; fragments (boxes, thin irregular prisms for shards) with gravity, ground bounce, settling, sleep and shrink-away; debris burst by style | `shatter_glass`, `crumble`, `splinter`, `impact_*` |
+| `detach` | with `autoSplit`, each loose group becomes its own `Group` (world transforms kept) and a `Piece` (`onPiece`) | `detach` |
+| `disassemble_progress` | | `unscrew` (throttled) |
+| `ignite` / `extinguish` / `burnout` | fire and smoke from the surface while `part.burning`; steam when put out; ash at burnout; char lerps the colour to the material `charColor`; status `ashes` hides the part and leaves an ash pile | `ignite`, `burn_loop`, `extinguish` |
+| heat (`damage` of type heat/fire, or any hot glowing part) | emissive `heatColor(temperature)` for materials with `visual.glows` | |
+| `melt` | meshes sag (Y down to 25 %, a bit wider, noisy vertices, bottom stays put); status `melted` hides the part and leaves a puddle | `melt_sizzle` |
+| `drip` | falling drop that leaves a flat puddle (merged, capped) | |
+| `leak` | stream of drops (or a faint puff for gas) from the hole while the part still has liters | |
+| `explode` | flash, fire, smoke, dust and sparks, a pooled `PointLight` pulse, impulses on pieces and fragments in range | `explode` |
+
+Pieces report hard landings: above 3 m/s the renderer calls `world.hit(id, { type: 'blunt', energy: 0.5 m v^2, radius: 0.08, direction: [0, -1, 0], source: 'fall' })`
+(throttled to once per 0.15 s per piece; the object's transform is synced to the world first, so the hit lands on the right spot), so a dropped glass
+pane shatters and a thrown chair can lose a leg. `Piece.localCenter` is the centre of mass relative to the root origin (it moves when a part breaks off).
+
+## Performance
+
+| Budget | `medium` / `high` | `low` |
+|---|---|---|
+| Particles (`maxParticles`) | 2500 | 1250 |
+| Particle burst counts | 100 % | 60 % |
+| Fragment meshes (`maxFragments`) | 160 | 80, and every second fragment of an event is skipped |
+| Vertex dents / melt noise on meshes over 20k vertices | yes | skipped |
+
+- Particles are two fixed-size ring buffers (additive 40 %, normal 60 %), one draw call each; dead particles cost a loop iteration, nothing else.
+- Fragments share one box geometry, six shard geometries and one material per source material id and colour; they shrink away instead of fading.
+- Decals share one disc geometry and one material; a mesh keeps at most 48 and the renderer 600.
+- Heat, char and melt are only read for "active" parts (hot, burning, melting) plus a scan of all parts every 0.4 s.
+- The explosion light is created on the first explosion (one light in the scene afterwards, intensity 0 at rest) so plan for the one-time shader recompile.
+- Melt assumes upright meshes (it scales the mesh along its own Y).
+
+## API
+
+```ts
+createDestructionRenderer(THREE, options: RendererOptions): DestructionRenderer
+specFromObject3D(THREE, root, options?: SpecFromObjectOptions): { spec, parts }
+heatColor(temperatureC: number): number // 0xRRGGBB, 0 below ~450 C, dark red ~500, orange ~800, yellow ~1100, white from 1400
+```
+
+`RendererOptions`: `scene`, `world`, `quality`, `maxFragments`, `maxParticles`, `fragmentLife`, `groundAt`, `gravity`, `autoSplit`, `onPiece`, `onSound`,
+`explosionLight`, `pointScale` (point size in pixels per metre at 1 m; about `viewportHeight / (2 tan(fov / 2))`, default 700).
+
+`DestructionRenderer`: `bind`, `unbind`, `makePiece`, `pieces`, `piece`, `impulse`, `update`, `emit`, `clear`, `restore`, `stats`, `dispose`.
+`clear()` removes fragments, decals, puddles and particles from the scene and restores every bound mesh; `dispose()` also unsubscribes from the world.
+
+## Português
+
+Renderizador three.js para o `@adatechnology/game-destruction`. O núcleo decide o que cada golpe faz e devolve eventos; este pacote desenha: amassados
+nos vértices, furos de bala e rachaduras, carbonização e brilho de calor, derretimento e poças, fragmentos com física leve, peças soltas e partículas
+em pool (fogo, fumaça, faíscas, poeira, cacos, lascas). Geometria e materiais só são clonados na primeira mudança visual de uma malha, e `restore` /
+`clear` devolvem os originais. Os sons não são tocados: o jogo recebe chaves (`impact_metal`, `shatter_glass`, ...) em `onSound`.
+
+Uso: `specFromObject3D(THREE, modelo)` gera a especificação e o mapa parte -> malhas; registre no mundo com `world.add(spec)`, ligue com
+`renderer.bind(id, modelo, { parts })` e chame `world.update(dt)` e `renderer.update(dt)` a cada quadro. Com `quality: 'low'` os orçamentos de
+partículas e fragmentos caem pela metade.

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import * as THREE_NS from 'three';
+import { Vec3, DebrisKind, DestructionWorld, MaterialId, DestructibleSpec } from '@adatechnology/game-destruction';
+export { Quat, Vec3 } from '@adatechnology/game-destruction';
+
+/**
+ * Public types of @adatechnology/game-destruction-three.
+ *
+ * `three` is only imported as a type: the host passes its own THREE namespace. The renderer listens to a `DestructionWorld` and draws what it
+ * reports on the host's meshes: vertex dents, hole and crack decals, char and heat glow through vertex colours / emissive, melting (sag and
+ * drips), fragments with light physics, loose pieces after a `detach`, and pooled particles.
+ */
+
+type ThreeNamespace = typeof THREE_NS;
+type Object3D = THREE_NS.Object3D;
+type Mesh = THREE_NS.Mesh;
+type Quality = 'low' | 'medium' | 'high';
+interface RendererOptions {
+    /** Scene that receives fragments, loose pieces, decals and particles. */
+    scene: THREE_NS.Scene;
+    world: DestructionWorld;
+    /** `low` halves particle and fragment budgets and skips vertex dents on meshes over 20k vertices (default `medium`). */
+    quality?: Quality;
+    /** Upper bound of live fragment meshes (default 160; oldest fade first). */
+    maxFragments?: number;
+    /** Upper bound of live particles (default 2500). */
+    maxParticles?: number;
+    /** Seconds a resting fragment stays before it fades (default 12; 0 = forever). */
+    fragmentLife?: number;
+    /** Ground height at (x, z) for fragments, pieces and drips (default 0). */
+    groundAt?: (x: number, z: number) => number;
+    gravity?: number;
+    /** Turn a loose group into a separate physical piece automatically (default true). */
+    autoSplit?: boolean;
+    /** Called when a loose piece is created (the bench registers it as grabbable). */
+    onPiece?: (piece: Piece) => void;
+    /** Called when a sound should play; the host maps keys to audio (e.g. `impact_metal`, `shatter_glass`, `ignite`, `explode`). */
+    onSound?: (key: string, point: Vec3, volume: number) => void;
+    /** A point light flashes on explosions (default true; costs one light). */
+    explosionLight?: boolean;
+    /**
+     * Particle size scale in pixels per metre at one metre from the camera, roughly `viewportHeight / (2 * tan(fov / 2))` (default 700). Set it
+     * when the viewport is much smaller or larger than about 720 px tall so smoke and fire keep their physical size.
+     */
+    pointScale?: number;
+}
+/** Options of `bind`. */
+interface BindOptions {
+    /**
+     * Part id -> meshes that draw it. When omitted, every Mesh under the root with `userData.destructionPart` (or whose name equals a part id) is
+     * used; meshes with neither are matched to the part whose box contains the mesh's bounding-box centre.
+     */
+    parts?: Record<string, Object3D | Object3D[]>;
+    /** Keep the world transform in sync from the root's matrixWorld every update (default true). */
+    syncTransform?: boolean;
+}
+/** A body the renderer moves with its light physics: a loose piece of an object after a detach (or a whole object handed to it). */
+interface Piece {
+    /** World object id of this piece. */
+    objectId: string;
+    root: Object3D;
+    velocity: Vec3;
+    angularVelocity: Vec3;
+    /** Half extents of the local bounding box used for ground contact and grabbing. */
+    halfExtents: Vec3;
+    /** Centre of mass relative to the root's origin, in the root's local space (metres). It moves when a part breaks off the piece. */
+    localCenter: Vec3;
+    mass: number;
+    sleeping: boolean;
+    /** While held by a player the renderer does not integrate it. */
+    held: boolean;
+}
+interface DestructionRenderer {
+    /** Attach a world object to its three.js root. */
+    bind(objectId: string, root: Object3D, options?: BindOptions): void;
+    unbind(objectId: string): void;
+    /** Make a bound object a physical piece (bench items that can be thrown). */
+    makePiece(objectId: string, options?: {
+        mass?: number;
+        velocity?: Vec3;
+    }): Piece;
+    pieces(): Piece[];
+    piece(objectId: string): Piece | null;
+    /** Push a piece (throws, blasts). */
+    impulse(objectId: string, impulse: Vec3, point?: Vec3): void;
+    /** Integrate fragments, pieces and particles; apply pending visual changes. Call once per frame after `world.update`. */
+    update(dt: number): void;
+    /** Emit particles directly (muzzle flashes, extinguisher foam, tool sparks). */
+    emit(kind: DebrisKind | 'fire' | 'flash' | 'foam', point: Vec3, normal: Vec3, count: number, speed?: number): void;
+    /** Remove every fragment, decal and particle, restore every bound mesh to its original geometry and colours. */
+    clear(): void;
+    /** Restore one object (after `world.reset`). */
+    restore(objectId: string): void;
+    stats(): {
+        fragments: number;
+        particles: number;
+        pieces: number;
+        decals: number;
+    };
+    dispose(): void;
+}
+interface SpecFromObjectOptions {
+    /** Material of a mesh. Default: `userData.destructionMaterial`, else `guessMaterial` on the mesh and material names, else `fallback`. */
+    materialOf?: (mesh: Mesh) => MaterialId | undefined;
+    /** Material when nothing matches (default `plastic`). */
+    fallback?: MaterialId;
+    /** Merge meshes smaller than this (largest box side, metres) into the part they touch (default 0.015). */
+    minSize?: number;
+    /** Infer joints between touching parts (default true). */
+    joints?: boolean;
+    /** Parts whose box bottom is within this distance of y = 0 in root space are `anchored` (default -1 = none). */
+    anchorBelow?: number;
+    /** Fill per material for hollow shells (default: sheet metal 0.04 when the box is thin, 1 otherwise). */
+    fillOf?: (mesh: Mesh, material: MaterialId) => number | undefined;
+    name?: string;
+    tags?: string[];
+}
+/** Result of `specFromObject3D`: the spec and which mesh became which part (pass `parts` to `bind`). */
+interface SpecFromObjectResult {
+    spec: DestructibleSpec;
+    parts: Record<string, Object3D[]>;
+}
+
+/** Create the renderer. See `DestructionRenderer`. */
+declare function createDestructionRenderer(THREE: ThreeNamespace, options: RendererOptions): DestructionRenderer;
+
+/**
+ * Build a `DestructibleSpec` from a three.js object: one part per mesh (meshes sharing `userData.destructionPart` become one part), each an
+ * axis-aligned box in the root's space (rotation omitted), with the material taken from `options.materialOf`, `userData.destructionMaterial`
+ * or a guess from the names. Tiny meshes are merged into the part they overlap most; joints are inferred from touching parts.
+ *
+ * Meshes that are invisible or have `userData.destructionIgnore` (or sit under such an object) are skipped. The result also tells which meshes
+ * became which part, ready to be passed to `bind`.
+ */
+declare function specFromObject3D(THREE: ThreeNamespace, root: Object3D, options?: SpecFromObjectOptions): SpecFromObjectResult;
+
+/**
+ * Glow colour of a hot surface as `0xRRGGBB`: black (no glow) below about 450 °C, dark red around 500, orange around 800, yellow around 1100 and
+ * white from 1400 °C. Brightness never decreases as the temperature rises. Use it as an emissive colour.
+ */
+declare function heatColor(temperatureC: number): number;
+
+/** Every particle kind the renderer can emit. */
+type ParticleKind = DebrisKind | 'fire' | 'flash' | 'foam';
+
+export { type BindOptions, type DestructionRenderer, type Mesh, type Object3D, type ParticleKind, type Piece, type Quality, type RendererOptions, type SpecFromObjectOptions, type SpecFromObjectResult, type ThreeNamespace, createDestructionRenderer, heatColor, specFromObject3D };