The pack
trippatron
function trippatron(options: TrippatronOptions = {}): Pack<{ trip: TrippatronApi }>Install the bounded analytic particle runtime and the shared arena/audio state. Requires a 2D world.
Helpers
tripDestructions
const tripDestructions: { readonly 'pixel-explosion': TripDestructionRecipe; readonly scatter: TripDestructionRecipe; readonly 'gravity-shower': TripDestructionRecipe; ... 24 more ...; readonly 'lightning-split': TripDestructionRecipe; } …Twenty-eight named ways for a sprite to come apart, each a style with the settings that make it read: pass the name
to trip.destroy(sprite, 'gravity-shower'), or spread its config and change what you like. side-blast and
corner-gust take an angle for their direction.
Types
TripDestruction
type TripDestruction = keyof typeof tripDestructionsThe name of one of tripDestructions.
TripDestructionRecipe
interface TripDestructionRecipeA named destruction: what the menu calls it, what it looks like, and the effect config that makes it.
readonly label: string— A short title for a menu.readonly description: string— One line: what the sprite does as it goes.readonly config: Readonly<TripEffectConfig>— The configdestroyis given; spread it and override any key (speed,duration,pixelArt…).
TripEffectConfig
interface TripEffectConfigOne compact GPU effect; positions and sizes are world units, times are seconds, angles are degrees.
x?: number— Centre x.y?: number— Centre y.style?: TripStyle— What happens: a free burst, or how a sprite's image comes apart (see the docs page's style table). Default 'burst'.motion?: TripMotion— Fragment motion. Default scatter; radial/depth modes apply to sprite destruction.fragmentShape?: 'image' | 'pixels' | 'rectangles' | 'strips'— Image pieces or solid sampled pixels/rectangles/horizontal strips. Default image.fragmentAspect?: number— Width/height ratio of rectangular fragments, 0.25..32. Default 3 (strips default 16).fragmentSize?: number | 'auto'— Fragment edge in world units (minimum 1), or auto for scaled source pixels clamped to 1 per axis. Default auto with pixelArt; otherwise count determines the grid.count?: number— Maximum fragments, rounded down. Default pack budget with fragmentSize/pixelArt; 1024 otherwise.duration?: number— Duration, 0.05..30 seconds. Default 1.speed?: number— Maximum launch speed; melt spread or stretch lift. Default 220.size?: number— Particle size. Default 3.gravity?: number— Vertical acceleration. Default 0.drag?: number— Exponential velocity damping. Default 1.spin?: number— Fragment rotation speed, radians/sec. Default 5; 0 with pixelArt.stretch?: number— Elongation at birth, or whole-image vertical stretch. Default 0; 2 for stretch style.endSize?: number— Final size as a fraction of birth size. Default 0; 1 with pixelArt.rainbow?: number— Rainbow blend 0..1; 0 retains source colours. Default 1; 0 with pixelArt.rainbowTransition?: number— Fraction of each fragment's lifetime used to transition from source colour to rainbow, 0..1. Default 0.25; 0 is immediate after release.lifetimeVariation?: number— Variation in fragment lifetime, 0..0.9. Default 0.35: lifetimes range from 65% to 100% of the time remaining after release.hue?: number— Hue offset in turns. Default 0.hueSpread?: number— Per-fragment hue variation in turns, 0..1. Default 1; trails default 0.08.cycle?: number— Hue cycles per second. Default 0.3.angle?: number— Direction in degrees. Default 0.spread?: number— Cone width in degrees. Default 360.glow?: number— Soft luminous core 0..1; 0 gives crisp squares. Default 0.frame?: string | number— Sprite frame to fragment, or particle texture. Default white pixel.width?: number— Fragmented image width. Default 48.height?: number— Fragmented image height. Default 48.rotation?: number— Source rotation in radians. Default 0.tint?: string— Base colour, any CSS colour (alpha multipliesalpha), multiplied with the texture. Default white.alpha?: number— Opacity multiplier 0..1. Default 1.pixelArt?: boolean— Display-sized fragments and nearest texture sampling. Default false.fade?: boolean— Fade each released fragment over the last quarter of its own lifetime. Default true, including pixelArt; set false to keep fragments opaque.blend?: 'additive' | 'alpha'— Compositing. Default additive; alpha with pixelArt preserves dark source colours.layer?: string— Layer; defaults to the world's first layer.z?: number— Sort depth. Default 0.seed?: number— Deterministic effect seed; defaults to the kernel RNG.impact?: boolean | Omit<ImpactConfig, 'x' | 'y'>— Also send a world-space impact. Default true; false for quiet trails.
TripEffectHandle
interface TripEffectHandleAn effect can be stopped explicitly; it also expires and follows scene ownership.
readonly alive: boolean— True while the effect exists.readonly count: number— Actual fragment count after budget and rectangular-grid rounding.stop(): void— Immediately release the effect. Idempotent.
TripMotion
type TripMotion = 'scatter' | 'outward' | 'inward' | 'depth-in' | 'depth-out'Fragment travel, including simulated depth on the 2D plane.
TrippatronApi
interface TrippatronApiThe 2D Trippatron API. All heavyweight fragment animation happens in vertex shaders.
burst(config?: TripEffectConfig): TripEffectHandle— Trigger a configured effect and optional arena impulse with one call.destroy(sprite: Handle, config?: TripEffectConfig | TripDestruction, overrides?: TripEffectConfig): TripEffectHandle— Snapshot a live sprite's image/transform, kill it, and animate its fragments: by a config, or by the name of one oftripDestructions('gravity-shower'), withoverrideson top. Throws on a dead sprite or an unknown name.trail(config?: TripEffectConfig & { rate?: number; interval?: number; follow?: Handle }): TripTrailHandle— Start a rainbow trail. rate is fragments/sec; interval is batch spacing in seconds (default 1/30).impact(config: ImpactConfig): void— Send a radial displacement wave shared by backdrop-trippatron and post-trippatron.audio(level: number, waveform?: ArrayLike<number>): void— Feed actual audio amplitude (0..1) and optional normalized waveform samples (-1..1). No microphone is opened.listen(gain?: number): () => void— Follow the composed audio pack’s actual master mix. Returns a scene-scoped stop function; default gain 4.clear(): void— Stop all effects and trails and clear impacts/audio.readonly stats: { effects: number; particles: number; trails: number; maxEffects: number; maxParticles: number; uniformBytes: number }— Current bounded workload; fragments are an upper bound until their batch expires.
TrippatronOptions
interface TrippatronOptionsReusable pack budgets. Overflow recycles the oldest effect rather than growing memory.
maxEffects?: number— Concurrent effect batches, 1..256. Default 64.maxParticles?: number— Total rendered fragments, 64..1,048,576. Default 131072.maxTrails?: number— Concurrent trails, 1..64. Default 16.
TripStyle
type TripStyle = 'burst' | 'shatter' | 'melt' | 'stretch' | 'ring' | 'vortex' | 'crumble' | 'wind' | 'disintegrate' | 'peel' | 'sweep' | 'corner' | 'quadrants' | 'checkerboard' | 'zipper' | 'spiral' | 'drain' | 'fountain' | 'wave' | 'blinds' | 'fold' | 'accordion' | 'rebound' | 'orbit' | 'hourglass' | 'lightning'Analytic bursts and source-image destruction, including progressive erosion and coherent deformations.
TripTrailHandle
interface TripTrailHandleA sampled trail emits small GPU batches at a bounded cadence, independent of frame rate.
move(x: number, y: number): void— Set the current endpoint. Ignored after stop.stop(): void— Stop emitting; existing fragments finish naturally.readonly active: boolean— Whether the trail is emitting.