@web-engine-dev/destruction

Dynamic destruction system powered by Voronoi fracturing and structural integrity simulation. Objects can be pre-fractured at build time for instant runtime breakage or fractured procedurally on impact for emergent destruction patterns.

Layer 4 · Simulation

Features

• Voronoi Fracturing: Procedural mesh splitting into naturally irregular fragments
• 6 Fracture Patterns: Uniform, radial, directional, shatter (glass), slice-grid, Poisson-disk
• Impact-Driven Distribution: More fragments near hit point, larger chunks farther away
• Structural Integrity Graph: Connectivity network with cascading collapse
• Interior Face UV Generation: Automatic UVs with configurable interior materials
• Pre-Fracturing: Build-time fracture for zero-runtime cost
• Material Presets: Concrete, wood, glass, metal with per-material brittleness
• Debris Lifecycle: Configurable lifetime and fade-out for fragment cleanup

Installation

npm install @web-engine-dev/destruction
# or
pnpm add @web-engine-dev/destruction

Quick Start

import { DestructibleBody, FractureConfig } from '@web-engine-dev/destruction';

// Create a destructible object
const wall = new DestructibleBody(mesh, {
  pattern: 'radial',
  fragmentCount: 12,
  material: 'concrete',
  interiorMaterial: concreteCrossSection,
});

// Apply impact force
wall.applyImpact({
  point: hitPosition,
  force: 100,
  direction: impactDirection,
});

// Pre-fracture at build time for instant runtime breakage
const preFractured = DestructibleBody.preFracture(mesh, {
  pattern: 'uniform',
  fragmentCount: 20,
});

Fracture Pipeline

1. Impact Detection — Point, force, and direction of impact
2. Seed Generation — Radial, directional, or Poisson distribution of fracture seeds
3. Voronoi Clipping — Perpendicular bisector planes split the mesh into convex cells
4. Interior UV Generation — Auto-generated UVs with configurable interior material
5. Physics Bodies — Debris fragments become rigid bodies with structural integrity graph

Structural Integrity

The integrity graph connects fragments with strength-rated edges. When impact injects stress:

• Stress propagates outward via BFS
• Each step is multiplied by propagationFactor (default 0.3) and decayed by stressDecay
• Edges break when accumulated stress exceeds breakThreshold × brittleness
• Disconnected fragments collapse under gravity

Material presets control behavior — glass shatters completely on first hit, while wood splinters progressively.

Fracture Patterns

Pattern	Description	Best For
Uniform	Evenly distributed Voronoi seeds	General-purpose destruction
Radial	Concentrated seeds at impact point	Impact/explosion damage
Directional	Elongated along impact vector	Bullet holes, projectile damage
Shatter	High-density seed distribution	Glass, ceramics
Slice-Grid	Regular grid cuts	Slicing effects, clean breaks
Poisson-Disk	Blue-noise seed placement	Natural, organic fracture

Dependencies

• @web-engine-dev/math — Vector and geometry types
• @web-engine-dev/physics3d — Rigid body creation for debris
• @web-engine-dev/spatial — Spatial queries