Skip to content

Code-first video & image, rendered natively on WebGPU.

3.6 KB
Raw Blame
/**
 * The contract between a particle system's authoring object (framefields'
 * `Particles` effect, carried on the op as `effect`) and this renderer.
 * Static settings are read once per system; per-frame inputs (driven values,
 * a performer's silhouette) are asked for each simulated frame.
 */

export type EmitterShape = "point" | "line" | "rect" | "circle" | "ring";
export type ParticleShape = "circle" | "soft" | "square" | "spark";
export type ParticleBlend = "normal" | "add" | "screen";
export type ParticleBounds = "none" | "kill" | "bounce" | "wrap";

export interface ParticleStatic {
	/** Capacity: the most particles alive at once. */
	max: number;
	seed: number;
	/** Layer box in composition px (sampling silhouettes needs the origin). */
	layer: { x: number; y: number; width: number; height: number };
	emitter: {
		shape: EmitterShape;
		x: number;
		y: number;
		width: number;
		height: number;
		radius: number;
		/** Aim away from the emitter's center instead of along `direction`. */
		radial: boolean;
	};
	/** Seconds. */
	lifetime: [number, number];
	/** px/s. */
	speed: [number, number];
	/** Degrees, 0 = right, -90 = up. */
	direction: number;
	/** Degrees around `direction`. */
	spread: number;
	bounds: ParticleBounds;
	/** Floor line in layer px, or null. */
	floor: number | null;
	bounce: number;
	/** px at birth and death. */
	size: [number, number];
	/** 0–1 random scale per particle. */
	sizeJitter: number;
	/** Fractions of life spent fading in and out. */
	fade: [number, number];
	shape: ParticleShape;
	/** Spark length per px/s of speed. */
	stretch: number;
	blend: ParticleBlend;
	/** Up to 8 colors, evenly spaced over life (or speed). */
	colors: Array<[number, number, number, number]>;
	/** Color by speed instead of age: speed (px/s) that reaches the last color. */
	colorBySpeed: number | null;
	opacity: number;
	substeps: number;
	/** Seconds simulated before the first frame, so it starts full. */
	prewarm: number;
}

export interface ParticleAttractor {
	x: number;
	y: number;
	/** px/s² at the center; negative repels. */
	strength: number;
	/** Falloff radius, px. */
	radius: number;
}

/** A silhouette grid (0–1 per cell) and how composition px map onto it. */
export interface ParticleMask {
	data: Float32Array;
	width: number;
	height: number;
	/** cell = (px − origin) / scale − 0.5 */
	originX: number;
	originY: number;
	scaleX: number;
	scaleY: number;
}

export interface ParticleFrame {
	/** Emitter position this frame, when it moves (layer px); births spread back toward `previous`. */
	emitter?: { x: number; y: number; previousX: number; previousY: number };
	/** Particles per second this frame. */
	rate: number;
	/** Extra particles born this frame. */
	burst: number;
	gravity: [number, number];
	/** Velocity damping per second. */
	drag: number;
	noise: { strength: number; scale: number; speed: number };
	attractors: ParticleAttractor[];
	push: {
		strength: number;
		/** Extra push where the silhouette just arrived. */
		sweep: number;
		mask: ParticleMask | null;
		previous: ParticleMask | null;
	} | null;
}

export interface ParticleProgram {
	readonly particleStatic: ParticleStatic;
	/** Inputs for composition frame `frame` (layer-local frames are the effect's concern). */
	particleFrame(frame: number, fps: number): ParticleFrame;
	/** Renderer-owned state, kept on the authoring object so it lives as long as the system. */
	particleState?: unknown;
}

export function isParticleProgram(value: unknown): value is ParticleProgram {
	return (
		typeof value === "object" &&
		value !== null &&
		"particleStatic" in value &&
		typeof (value as ParticleProgram).particleFrame === "function"
	);
}