@aura3d/rendering 1.0.6

package/src/cinematic/CinematicPostProcess.ts

@@ -0,0 +1,83 @@
+import type { RendererPostProcessOptions } from "../Renderer";
+import { createCinematicBloomPass, type CinematicBloomPass } from "./BloomPass";
+import { createCinematicDepthHazePass, type CinematicDepthHazePass } from "./DepthHazePass";
+import { createCinematicFilmGrainPass, type CinematicFilmGrainPass } from "./FilmGrainPass";
+import { createCinematicVignettePass, type CinematicVignettePass } from "./VignettePass";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export type CinematicColorGradePreset = "neon-noir" | "warm-sunrise" | "cool-moonlit" | "studio-neutral";
+
+export interface CinematicPostProcessStack {
+  readonly id: string;
+  readonly colorGradePreset: CinematicColorGradePreset;
+  readonly bloom: CinematicBloomPass;
+  readonly vignette: CinematicVignettePass;
+  readonly filmGrain: CinematicFilmGrainPass;
+  readonly depthHaze: CinematicDepthHazePass;
+  readonly rendererOptions: RendererPostProcessOptions;
+  readonly rendererOwnedEvidence: readonly CinematicRendererEvidenceFlag[];
+  readonly diagnostics: readonly string[];
+}
+
+export function createCinematicPostProcessStack(options: {
+  readonly id?: string;
+  readonly colorGradePreset?: CinematicColorGradePreset;
+  readonly fogOrHaze?: boolean;
+  readonly glow?: boolean;
+} = {}): CinematicPostProcessStack {
+  const colorGradePreset = options.colorGradePreset ?? "neon-noir";
+  const bloom = createCinematicBloomPass({ intensity: options.glow === false ? 0.08 : 0.28 });
+  const vignette = createCinematicVignettePass();
+  const filmGrain = createCinematicFilmGrainPass();
+  const depthHaze = createCinematicDepthHazePass({ density: options.fogOrHaze === false ? 0.06 : 0.22 });
+  return {
+    id: options.id ?? "cinematic-postprocess",
+    colorGradePreset,
+    bloom,
+    vignette,
+    filmGrain,
+    depthHaze,
+    rendererOptions: {
+      targetFormat: "rgba16f",
+      bloom: { threshold: bloom.threshold, intensity: bloom.intensity, radius: bloom.radius },
+      toneMapping: { operator: "filmic", exposure: exposureFor(colorGradePreset), whitePoint: 1.18, inputColorSpace: "linear", outputColorSpace: "srgb" },
+      colorGrade: colorGradeFor(colorGradePreset, vignette.intensity),
+      filmGrain: { intensity: filmGrain.intensity, seed: filmGrain.animated ? 17 : 1, monochrome: true },
+      fxaa: true
+    },
+    rendererOwnedEvidence: [
+      bloom.rendererOwnedEvidence,
+      vignette.rendererOwnedEvidence,
+      filmGrain.rendererOwnedEvidence,
+      depthHaze.rendererOwnedEvidence,
+      createRendererOwnedEvidenceFlag({
+        id: `postprocess:color-grade:${colorGradePreset}`,
+        feature: "postprocess",
+        label: `Color grade ${colorGradePreset}`,
+        source: "renderer-postprocess",
+        sceneContent: false
+      })
+    ],
+    diagnostics: ["Cinematic postprocess stack is renderer-owned; route DOM overlays cannot satisfy effect evidence."]
+  };
+}
+
+function exposureFor(preset: CinematicColorGradePreset): number {
+  if (preset === "warm-sunrise") return 1.12;
+  if (preset === "cool-moonlit") return 1.3;
+  if (preset === "studio-neutral") return 1.02;
+  return 1.22;
+}
+
+function colorGradeFor(preset: CinematicColorGradePreset, vignette: number): NonNullable<RendererPostProcessOptions["colorGrade"]> {
+  switch (preset) {
+    case "warm-sunrise":
+      return { contrast: 1.08, saturation: 1.08, vibrance: 0.14, vignette, sharpening: 0.16 };
+    case "cool-moonlit":
+      return { contrast: 1.16, saturation: 0.9, vibrance: 0.08, vignette: vignette + 0.04, sharpening: 0.18 };
+    case "studio-neutral":
+      return { contrast: 1.04, saturation: 1, vibrance: 0.06, vignette: 0.06, sharpening: 0.18 };
+    case "neon-noir":
+      return { contrast: 1.18, saturation: 1.12, vibrance: 0.2, vignette: vignette + 0.06, sharpening: 0.16 };
+  }
+}

package/src/cinematic/DepthHazePass.ts

@@ -0,0 +1,30 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicDepthHazePass {
+  readonly name: "depth-haze";
+  readonly color: readonly [number, number, number];
+  readonly density: number;
+  readonly startMeters: number;
+  readonly endMeters: number;
+  readonly requiresDepth: boolean;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+}
+
+export function createCinematicDepthHazePass(options: Partial<Omit<CinematicDepthHazePass, "name" | "rendererOwnedEvidence">> = {}): CinematicDepthHazePass {
+  return {
+    name: "depth-haze",
+    color: options.color ?? [0.22, 0.34, 0.52],
+    density: options.density ?? 0.22,
+    startMeters: options.startMeters ?? 2.5,
+    endMeters: options.endMeters ?? 18,
+    requiresDepth: options.requiresDepth ?? true,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: "postprocess:depth-haze",
+      feature: "postprocess",
+      label: "Depth haze pass",
+      source: "renderer-postprocess",
+      sceneContent: false,
+      diagnostics: ["Depth haze is renderer-owned atmospheric composition; DOM fog panels do not satisfy this evidence."]
+    })
+  };
+}

package/src/cinematic/EmissivePracticalLightSystem.ts

@@ -0,0 +1,45 @@
+import type { CinematicRuntimeLight } from "./CinematicLightingRig";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicEmissivePractical {
+  readonly id: string;
+  readonly sourceObjectId: string;
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+  readonly radiusMeters: number;
+}
+
+export interface CinematicEmissivePracticalLightSystem {
+  readonly id: string;
+  readonly practicals: readonly CinematicEmissivePractical[];
+  readonly lights: readonly CinematicRuntimeLight[];
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createEmissivePracticalLightSystem(
+  practicals: readonly CinematicEmissivePractical[],
+  id = "cinematic-emissive-practicals"
+): CinematicEmissivePracticalLightSystem {
+  return {
+    id,
+    practicals,
+    lights: practicals.map((practical) => ({
+      id: `light:${practical.id}`,
+      role: "practical",
+      type: "point",
+      color: practical.color,
+      intensity: practical.intensity,
+      position: [0, 1, 0],
+      castsShadow: false
+    })),
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `lighting:${id}`,
+      feature: "lighting",
+      label: "Emissive practical light system",
+      source: "renderer-light",
+      diagnostics: ["Neon/glowing props produce renderer light metadata and do not rely on DOM glow."]
+    }),
+    diagnostics: [`Compiled ${practicals.length} emissive practical lights.`]
+  };
+}

package/src/cinematic/FilmGrainPass.ts

@@ -0,0 +1,24 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicFilmGrainPass {
+  readonly name: "film-grain";
+  readonly intensity: number;
+  readonly animated: boolean;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+}
+
+export function createCinematicFilmGrainPass(options: Partial<Omit<CinematicFilmGrainPass, "name" | "rendererOwnedEvidence">> = {}): CinematicFilmGrainPass {
+  return {
+    name: "film-grain",
+    intensity: options.intensity ?? 0.025,
+    animated: options.animated ?? true,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: "postprocess:film-grain",
+      feature: "postprocess",
+      label: "Film grain pass",
+      source: "renderer-postprocess",
+      sceneContent: false,
+      diagnostics: ["Film grain is bounded by default so screenshot gates are not satisfied by noise alone."]
+    })
+  };
+}

package/src/cinematic/FogVolumeSystem.ts

@@ -0,0 +1,30 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicFogVolumeSystem {
+  readonly id: string;
+  readonly mode: "height-fog" | "volume-slices";
+  readonly color: readonly [number, number, number];
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createFogVolumeSystem(options: Partial<Omit<CinematicFogVolumeSystem, "rendererOwnedEvidence" | "diagnostics">> = {}): CinematicFogVolumeSystem {
+  const id = options.id ?? "cinematic-fog";
+  return {
+    id,
+    mode: options.mode ?? "height-fog",
+    color: options.color ?? [0.22, 0.34, 0.52],
+    density: options.density ?? 0.26,
+    heightFalloff: options.heightFalloff ?? 0.42,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `vfx:${id}`,
+      feature: "vfx",
+      label: "Fog volume system",
+      source: "renderer-vfx",
+      diagnostics: ["Fog is represented as renderer fog/volume data, not a translucent DOM layer."]
+    }),
+    diagnostics: ["Fog volume compiled as route-supported renderer atmospheric approximation."]
+  };
+}

package/src/cinematic/GlowCardSystem.ts

@@ -0,0 +1,44 @@
+import { Geometry } from "../Geometry";
+import { UnlitMaterial } from "../UnlitMaterial";
+import type { RenderItem } from "../ForwardPass";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicGlowCard {
+  readonly id: string;
+  readonly targetId: string;
+  readonly color: readonly [number, number, number, number];
+  readonly radiusMeters: number;
+}
+
+export interface CinematicGlowCardSystem {
+  readonly id: string;
+  readonly cards: readonly CinematicGlowCard[];
+  readonly renderItems: readonly RenderItem[];
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createGlowCardSystem(cards: readonly CinematicGlowCard[], id = "cinematic-glow-cards"): CinematicGlowCardSystem {
+  return {
+    id,
+    cards,
+    renderItems: cards.map((card) => ({
+      label: card.id,
+      geometry: Geometry.litCube(card.radiusMeters),
+      material: new UnlitMaterial({
+        name: `cinematic/glow-card/${card.id}`,
+        color: card.color,
+        renderState: { blend: true, depthWrite: false, cullMode: "none" }
+      }),
+      includeInAutoFrame: false
+    })),
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `vfx:${id}`,
+      feature: "vfx",
+      label: "Glow card system",
+      source: "renderer-vfx",
+      diagnostics: ["Glow cards are renderer transparent geometry; DOM halos do not count."]
+    }),
+    diagnostics: [`Compiled ${cards.length} renderer glow cards.`]
+  };
+}

package/src/cinematic/RainParticleSystem.ts

@@ -0,0 +1,151 @@
+import { Geometry } from "../Geometry";
+import { UnlitMaterial } from "../UnlitMaterial";
+import type { RenderItem } from "../ForwardPass";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicRainParticleSystem {
+  readonly id: string;
+  readonly particleCount: number;
+  readonly bounds: {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+  };
+  readonly velocity: readonly [number, number, number];
+  readonly renderItem: RenderItem;
+  readonly renderItems: readonly RenderItem[];
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createRainParticleSystem(options: {
+  readonly id?: string;
+  readonly particleCount?: number;
+  readonly bounds?: CinematicRainParticleSystem["bounds"];
+  readonly seed?: number;
+} = {}): CinematicRainParticleSystem {
+  const id = options.id ?? "cinematic-rain";
+  const particleCount = Math.max(32, Math.floor(options.particleCount ?? 384));
+  const bounds = options.bounds ?? { min: [-4, 0.3, -5], max: [4, 5, 2] };
+  const streaks = createRainStreaks(particleCount, bounds, options.seed ?? 7);
+  const rainRenderItem: RenderItem = {
+    label: id,
+    geometry: Geometry.points(streaks.map((streak) => streak.start)),
+    material: new UnlitMaterial({
+      name: "cinematic/rain-points",
+      color: [0.58, 0.74, 1, 0.62],
+      renderState: { blend: true, depthWrite: false }
+    }),
+    includeInAutoFrame: false
+  };
+  const streakRenderItem: RenderItem = {
+    label: `${id}/streaks`,
+    geometry: Geometry.wideLineSegments(streaks),
+    material: new UnlitMaterial({
+      name: "cinematic/rain-streaks",
+      color: [0.58, 0.74, 1, 0.58],
+      renderState: { blend: true, depthWrite: false }
+    }),
+    includeInAutoFrame: false
+  };
+  const splashRenderItem: RenderItem = {
+    label: `${id}/splash-ripples`,
+    geometry: Geometry.wideLineSegments(createRainSplashRipples(Math.max(24, Math.floor(particleCount * 0.16)), bounds, (options.seed ?? 7) + 31)),
+    material: new UnlitMaterial({
+      name: "cinematic/rain-splash-ripples",
+      color: [0.72, 0.88, 1, 0.42],
+      renderState: { blend: true, depthWrite: false }
+    }),
+    includeInAutoFrame: false
+  };
+  const mistRenderItem: RenderItem = {
+    label: `${id}/mist-banks`,
+    geometry: Geometry.wideLineSegments(createRainMistBands(bounds)),
+    material: new UnlitMaterial({
+      name: "cinematic/rain-mist-banks",
+      color: [0.52, 0.68, 0.82, 0.18],
+      renderState: { blend: true, depthWrite: false }
+    }),
+    includeInAutoFrame: false
+  };
+  return {
+    id,
+    particleCount,
+    bounds,
+    velocity: [-0.35, -5.8, -0.18],
+    renderItem: rainRenderItem,
+    renderItems: [rainRenderItem, streakRenderItem, splashRenderItem, mistRenderItem],
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `vfx:${id}`,
+      feature: "vfx",
+      label: "Rain particle system",
+      source: "renderer-vfx",
+      diagnostics: ["Rain is wide streak, splash ripple, and mist geometry owned by the renderer, not a DOM/CSS overlay."]
+    }),
+    diagnostics: [`Compiled ${particleCount} rain streaks plus splash-ripples and mist-banks into renderer-owned wide-line geometry.`]
+  };
+}
+
+function createRainStreaks(
+  count: number,
+  bounds: CinematicRainParticleSystem["bounds"],
+  seed: number
+): readonly { readonly start: readonly [number, number, number]; readonly end: readonly [number, number, number]; readonly width: number }[] {
+  let state = seed >>> 0;
+  const random = () => {
+    state = (1664525 * state + 1013904223) >>> 0;
+    return state / 0xffffffff;
+  };
+  const streaks: Array<{ start: [number, number, number]; end: [number, number, number]; width: number }> = [];
+  for (let index = 0; index < count; index += 1) {
+    const x = lerp(bounds.min[0], bounds.max[0], random());
+    const y = lerp(bounds.min[1], bounds.max[1], random());
+    const z = lerp(bounds.min[2], bounds.max[2], random());
+    const length = lerp(0.26, 0.82, random());
+    streaks.push({
+      start: [x, y, z],
+      end: [x - 0.08 - random() * 0.08, Math.max(bounds.min[1], y - length), z + 0.03 + random() * 0.05],
+      width: lerp(0.006, 0.018, random())
+    });
+  }
+  return streaks;
+}
+
+function createRainSplashRipples(
+  count: number,
+  bounds: CinematicRainParticleSystem["bounds"],
+  seed: number
+): readonly { readonly start: readonly [number, number, number]; readonly end: readonly [number, number, number]; readonly width: number }[] {
+  let state = seed >>> 0;
+  const random = () => {
+    state = (1664525 * state + 1013904223) >>> 0;
+    return state / 0xffffffff;
+  };
+  const segments: Array<{ start: [number, number, number]; end: [number, number, number]; width: number }> = [];
+  const floorY = Math.max(0.012, bounds.min[1] * 0.04);
+  for (let index = 0; index < count; index += 1) {
+    const x = lerp(bounds.min[0] * 0.72, bounds.max[0] * 0.72, random());
+    const z = lerp(bounds.min[2] * 0.36, bounds.max[2] * 0.52, random());
+    const radiusX = lerp(0.05, 0.16, random());
+    const radiusZ = radiusX * lerp(0.34, 0.58, random());
+    segments.push(
+      { start: [x - radiusX, floorY, z], end: [x + radiusX, floorY, z], width: 0.006 },
+      { start: [x, floorY, z - radiusZ], end: [x, floorY, z + radiusZ], width: 0.006 }
+    );
+  }
+  return segments;
+}
+
+function createRainMistBands(
+  bounds: CinematicRainParticleSystem["bounds"]
+): readonly { readonly start: readonly [number, number, number]; readonly end: readonly [number, number, number]; readonly width: number }[] {
+  const floorY = Math.max(0.08, bounds.min[1] * 0.2);
+  return [
+    { start: [bounds.min[0] * 0.92, floorY + 0.06, bounds.min[2] * 0.28], end: [bounds.max[0] * 0.88, floorY + 0.06, bounds.min[2] * 0.18], width: 0.12 },
+    { start: [bounds.min[0] * 0.74, floorY + 0.17, bounds.min[2] * 0.14], end: [bounds.max[0] * 0.66, floorY + 0.16, bounds.max[2] * 0.18], width: 0.16 },
+    { start: [bounds.min[0] * 0.58, floorY + 0.31, bounds.max[2] * 0.24], end: [bounds.max[0] * 0.58, floorY + 0.29, bounds.max[2] * 0.34], width: 0.14 }
+  ];
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}

package/src/cinematic/VignettePass.ts

@@ -0,0 +1,25 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicVignettePass {
+  readonly name: "vignette";
+  readonly intensity: number;
+  readonly radius: number;
+  readonly softness: number;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+}
+
+export function createCinematicVignettePass(options: Partial<Omit<CinematicVignettePass, "name" | "rendererOwnedEvidence">> = {}): CinematicVignettePass {
+  return {
+    name: "vignette",
+    intensity: options.intensity ?? 0.18,
+    radius: options.radius ?? 0.78,
+    softness: options.softness ?? 0.48,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: "postprocess:vignette",
+      feature: "postprocess",
+      label: "Vignette pass",
+      source: "renderer-postprocess",
+      sceneContent: false
+    })
+  };
+}

package/src/cinematic/WetReflectionApproximation.ts

@@ -0,0 +1,27 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicWetReflectionApproximation {
+  readonly id: string;
+  readonly roughnessFloor: number;
+  readonly reflectionStrength: number;
+  readonly planarReflection: false;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createWetReflectionApproximation(options: Partial<Omit<CinematicWetReflectionApproximation, "id" | "planarReflection" | "rendererOwnedEvidence" | "diagnostics">> & { readonly id?: string } = {}): CinematicWetReflectionApproximation {
+  return {
+    id: options.id ?? "cinematic-wet-reflection",
+    roughnessFloor: options.roughnessFloor ?? 0.16,
+    reflectionStrength: options.reflectionStrength ?? 0.68,
+    planarReflection: false,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `material:${options.id ?? "cinematic-wet-reflection"}`,
+      feature: "material",
+      label: "Wet reflection approximation",
+      source: "renderer-material",
+      diagnostics: ["Wet reflections use renderer PBR/IBL approximation; this is not a live planar reflection claim."]
+    }),
+    diagnostics: ["Wet reflection approximation is bounded to PBR roughness/specular response."]
+  };
+}

package/src/cinematic/index.ts

@@ -0,0 +1,14 @@
+export * from "./CinematicEvidence";
+export * from "./CinematicMaterialPresets";
+export * from "./CinematicLightingRig";
+export * from "./CinematicPostProcess";
+export * from "./BloomPass";
+export * from "./VignettePass";
+export * from "./FilmGrainPass";
+export * from "./DepthHazePass";
+export * from "./RainParticleSystem";
+export * from "./FogVolumeSystem";
+export * from "./GlowCardSystem";
+export * from "./WetReflectionApproximation";
+export * from "./EmissivePracticalLightSystem";
+export * from "./CinematicDepthComposition";

package/src/effects/CollisionModule.ts

@@ -0,0 +1,64 @@
+import type { Particle, Vector3Like } from "./Particle.js";
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+
+export interface CollisionPlane {
+  normal: Vector3Like;
+  constant: number;
+  restitution?: number;
+  mode?: "bounce" | "kill";
+}
+
+function dot(left: Vector3Like, right: Vector3Like): number {
+  return left.x * right.x + left.y * right.y + left.z * right.z;
+}
+
+function normalize(value: Vector3Like): Vector3Like {
+  const length = Math.hypot(value.x, value.y, value.z);
+  if (length === 0) {
+    throw new RangeError("Collision plane normal cannot be zero length.");
+  }
+
+  return { x: value.x / length, y: value.y / length, z: value.z / length };
+}
+
+export class CollisionModule implements ParticleModule {
+  readonly name = "CollisionModule";
+  readonly plane: Required<CollisionPlane>;
+
+  constructor(plane: CollisionPlane) {
+    this.plane = {
+      normal: normalize(plane.normal),
+      constant: plane.constant,
+      restitution: plane.restitution ?? 0.5,
+      mode: plane.mode ?? "bounce",
+    };
+
+    if (!Number.isFinite(this.plane.constant) || !Number.isFinite(this.plane.restitution)) {
+      throw new RangeError("Collision plane constant and restitution must be finite numbers.");
+    }
+  }
+
+  afterIntegrate(particle: Particle, _context: ParticleUpdateContext): void {
+    const distance = dot(this.plane.normal, particle.position) + this.plane.constant;
+    if (distance >= 0) {
+      return;
+    }
+
+    if (this.plane.mode === "kill") {
+      particle.alive = false;
+      return;
+    }
+
+    particle.position.x -= this.plane.normal.x * distance;
+    particle.position.y -= this.plane.normal.y * distance;
+    particle.position.z -= this.plane.normal.z * distance;
+
+    const normalVelocity = dot(particle.velocity, this.plane.normal);
+    if (normalVelocity < 0) {
+      const impulse = -(1 + this.plane.restitution) * normalVelocity;
+      particle.velocity.x += this.plane.normal.x * impulse;
+      particle.velocity.y += this.plane.normal.y * impulse;
+      particle.velocity.z += this.plane.normal.z * impulse;
+    }
+  }
+}

package/src/effects/ColorModule.ts

@@ -0,0 +1,60 @@
+import { type ColorLike } from "./Particle.js";
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+import type { Particle } from "./Particle.js";
+
+export interface ColorKeyframe {
+  time: number;
+  color: ColorLike;
+}
+
+function validateGradient(keyframes: readonly ColorKeyframe[]): void {
+  if (keyframes.length === 0) {
+    throw new RangeError("ColorModule requires at least one color keyframe.");
+  }
+
+  let previous = -Number.POSITIVE_INFINITY;
+  for (const keyframe of keyframes) {
+    if (keyframe.time < 0 || keyframe.time > 1 || keyframe.time < previous) {
+      throw new RangeError("ColorModule keyframe times must be sorted in the normalized range [0, 1].");
+    }
+    previous = keyframe.time;
+  }
+}
+
+export function sampleColorGradient(keyframes: readonly ColorKeyframe[], time: number): ColorLike {
+  if (time <= keyframes[0].time) {
+    return { ...keyframes[0].color };
+  }
+
+  for (let index = 1; index < keyframes.length; index += 1) {
+    const next = keyframes[index];
+    if (time <= next.time) {
+      const previous = keyframes[index - 1];
+      const span = next.time - previous.time || 1;
+      const alpha = (time - previous.time) / span;
+
+      return {
+        r: previous.color.r + (next.color.r - previous.color.r) * alpha,
+        g: previous.color.g + (next.color.g - previous.color.g) * alpha,
+        b: previous.color.b + (next.color.b - previous.color.b) * alpha,
+        a: previous.color.a + (next.color.a - previous.color.a) * alpha,
+      };
+    }
+  }
+
+  return { ...keyframes[keyframes.length - 1].color };
+}
+
+export class ColorModule implements ParticleModule {
+  readonly name = "ColorModule";
+  readonly gradient: readonly ColorKeyframe[];
+
+  constructor(gradient: readonly ColorKeyframe[]) {
+    this.gradient = gradient;
+    validateGradient(gradient);
+  }
+
+  update(particle: Particle, context: ParticleUpdateContext): void {
+    particle.color = sampleColorGradient(this.gradient, context.normalizedAge);
+  }
+}

package/src/effects/ForceModule.ts

@@ -0,0 +1,25 @@
+import type { Particle, Vector3Like } from "./Particle.js";
+import type { ParticleModule, ParticleUpdateContext } from "./ParticleModule.js";
+
+export type ForceSampler = Vector3Like | ((particle: Particle, context: ParticleUpdateContext) => Vector3Like);
+
+export class ForceModule implements ParticleModule {
+  readonly name = "ForceModule";
+  readonly force: ForceSampler;
+
+  constructor(force: ForceSampler) {
+    this.force = force;
+  }
+
+  update(particle: Particle, context: ParticleUpdateContext): void {
+    const force = typeof this.force === "function" ? this.force(particle, context) : this.force;
+
+    particle.velocity.x += force.x * context.deltaTime;
+    particle.velocity.y += force.y * context.deltaTime;
+    particle.velocity.z += force.z * context.deltaTime;
+  }
+}
+
+export function gravityForce(gravity = -9.81): ForceModule {
+  return new ForceModule({ x: 0, y: gravity, z: 0 });
+}