# packages/core/src/features/textures/lib/rain-drops.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/textures/lib/rain-drops.ts#L401). [Back to reference](/reference/types/textures/)
1 import { defineTexture, type TextureContext, type TextureRecipe } from "@pibbl/core";
2 import { validateSeed } from "./palette.js";
3 
4 /**
5  * Rain rate, gravity, initial drops, condensation, trail, and outline controls for a raindrop texture.
6  *
7  * @see {@link rainDrops}
8  */
9 export interface RainDropsOptions {
10   /**
11    * Seed used for deterministic sampling or simulation initialization. See
12    * {@link RainDropsOptions}.
13    */
14   readonly seed?: number;
15   /** New beads per second, from 0 through 120. */
16   readonly rainRate?: number;
17   /** Downward acceleration multiplier, from 0 through 10. */
18   readonly gravity?: number;
19   /** Number of drops seeded before continuous rain starts. See {@link RainDropsOptions}. */
20   readonly initialDrops?: number;
21   /** Whether simulation or playback advancement is suspended. See {@link RainDropsOptions}. */
22   readonly paused?: boolean;
23   /** Fine droplet film coverage, from 0 (clear) through 1 (mist). */
24   readonly condensation?: number;
25   /** Seconds controlling trail drying and condensation recovery, from 0 through 60. */
26   readonly trailPersistence?: number;
27   /** Residual water left behind a moving drop, from 0 through 1. */
28   readonly trailStrength?: number;
29   /** Outline and path variation, from 0 (smooth) through 1. */
30   readonly irregularity?: number;
31 }
32 
33 /**
34  * Pause, reset, finger-wipe, release, and localized nudge commands for a raindrop texture.
35  *
36  * @see {@link rainDrops}
37  */
38 export type RainDropsMessage =
39   | {
40       /** The literal "pause" identifying this variant. See {@link RainDropsMessage}. */
41       readonly type: "pause";
42       /** Whether simulation or playback advancement is suspended. See {@link RainDropsMessage}. */
43       readonly paused: boolean;
44     }
45   | {
46       /** The literal "reset" identifying this variant. See {@link RainDropsMessage}. */
47       readonly type: "reset";
48     }
49   /** Begin or move one finger contact; successive positions wipe a continuous path. */
50   | {
51       /** The literal "finger" identifying this variant. See {@link RainDropsMessage}. */
52       readonly type: "finger";
53       /**
54        * Horizontal coordinate or displacement in the containing coordinate system. See
55        * {@link RainDropsMessage}.
56        */
57       readonly x: number;
58       /**
59        * Vertical coordinate or displacement in the containing coordinate system. See
60        * {@link RainDropsMessage}.
61        */
62       readonly y: number;
63       /** Radius in the coordinate system of this geometry or effect. See {@link RainDropsMessage}. */
64       readonly radius?: number;
65     }
66   | {
67       /** The literal "release" identifying this variant. See {@link RainDropsMessage}. */
68       readonly type: "release";
69     }
70   /** Center and movement use normalized width/height; radius uses the shorter side. */
71   | {
72       /** The literal "nudge" identifying this variant. See {@link RainDropsMessage}. */
73       readonly type: "nudge";
74       /**
75        * Horizontal coordinate or displacement in the containing coordinate system. See
76        * {@link RainDropsMessage}.
77        */
78       readonly x: number;
79       /**
80        * Vertical coordinate or displacement in the containing coordinate system. See
81        * {@link RainDropsMessage}.
82        */
83       readonly y: number;
84       /** Horizontal displacement applied by the interaction. See {@link RainDropsMessage}. */
85       readonly dx: number;
86       /** Vertical displacement applied by the interaction. See {@link RainDropsMessage}. */
87       readonly dy: number;
88       /** Radius in the coordinate system of this geometry or effect. See {@link RainDropsMessage}. */
89       readonly radius?: number;
90     };
91 
92 interface Drop { x: number; y: number; radius: number; vx: number; vy: number; phase: number }
93 interface Config { seed: number; rainRate: number; gravity: number; initialDrops: number; paused: boolean; condensation: number; trailPersistence: number; trailStrength: number; irregularity: number }
94 interface State {
95   finger?: { x: number; y: number; radius: number; drop?: Drop };
96   config: Config;
97   drops: Drop[];
98   random: number;
99   births: number;
100   paused: boolean;
101   fresh: boolean;
102   image: ImageData;
103   film: Float32Array;
104   trails: Float32Array;
105   surface: Float32Array;
106   grain: Float32Array;
107   fieldActive: boolean;
108 }
109 const MAX_DROPS = 256;
110 
111 function bounded(value: number, name: string, maximum: number): number {
112   if (!Number.isFinite(value) || value < 0 || value > maximum) throw new RangeError(`Rain ${name} must be finite and within [0, ${maximum}].`);
113   return value;
114 }
115 function options(input: RainDropsOptions): Config {
116   const initialDrops = bounded(input.initialDrops ?? 100, "initialDrops", MAX_DROPS);
117   if (!Number.isInteger(initialDrops)) throw new RangeError("Rain initialDrops must be an integer.");
118   return { seed: validateSeed(input.seed ?? 7), rainRate: bounded(input.rainRate ?? 24, "rainRate", 120), gravity: bounded(input.gravity ?? 1, "gravity", 10), initialDrops, paused: input.paused ?? false,
119     condensation: bounded(input.condensation ?? 0, "condensation", 1),
120     trailPersistence: bounded(input.trailPersistence ?? 8, "trailPersistence", 60),
121     trailStrength: bounded(input.trailStrength ?? 0.65, "trailStrength", 1),
122     irregularity: bounded(input.irregularity ?? 0.8, "irregularity", 1) };
123 }
124 function assertMap(context: TextureContext): void {
125   if (context.palette !== undefined) throw new TypeError("rainDrops is a numeric displacement map and does not accept a palette.");
126 }
127 function random(state: State): number {
128   state.random = (Math.imul(state.random, 1664525) + 1013904223) >>> 0;
129   return state.random / 4294967296;
130 }
131 function spawn(state: State, context: TextureContext): void {
132   if (state.drops.length >= MAX_DROPS) return;
133   const side = Math.min(context.canvas.width, context.canvas.height);
134   state.drops.push({ x: random(state) * context.canvas.width / side, y: random(state) * context.canvas.height / side, radius: 0.005 + random(state) ** 2 * 0.015, vx: 0, vy: 0, phase: random(state) * Math.PI * 2 });
135 }
136 function reset(state: State, context: TextureContext): void {
137   state.finger = undefined;
138   state.random = state.config.seed; state.drops = []; state.births = 0; state.fresh = true;
139   state.film.fill(1); state.trails.fill(0); state.fieldActive = false;
140   for (let i = 0; i < state.grain.length; i++) {
141     let value = Math.imul(i + 1, 0x45d9f3b) ^ state.config.seed;
142     value = Math.imul(value ^ (value >>> 16), 0x45d9f3b);
143     state.grain[i] = ((value ^ (value >>> 16)) >>> 0) / 4294967296;
144   }
145   for (let i = 0; i < state.config.initialDrops; i++) spawn(state, context);
146 }
147 /** Coalescence conserves volume and volume-weighted position/momentum. */
148 function merge(drops: Drop[]): void {
149   for (let i = 0; i < drops.length; i++) {
150     const a = drops[i];
151     for (let j = i + 1; j < drops.length; j++) {
152       const b = drops[j];
153       if (Math.hypot(a.x - b.x, a.y - b.y) >= a.radius + b.radius) continue;
154       const av = a.radius ** 3, bv = b.radius ** 3, volume = av + bv;
155       a.x = (a.x * av + b.x * bv) / volume; a.y = (a.y * av + b.y * bv) / volume;
156       a.vx = (a.vx * av + b.vx * bv) / volume; a.vy = (a.vy * av + b.vy * bv) / volume;
157       a.radius = Math.cbrt(volume);
158       drops.splice(j--, 1);
159     }
160   }
161 }
162 function active(state: State): boolean {
163   return state.fieldActive || state.config.rainRate > 0 || state.drops.some(d => (state.config.gravity > 0 && d.radius > 0.012) || Math.abs(d.vx) + Math.abs(d.vy) > 0.0001);
164 }
165 function schedule(state: State, context: TextureContext): void {
166   if (!state.paused && active(state)) context.requestFrame();
167 }
168 
169 /** Sweep the actual drop footprint, collecting film and leaving a beaded residual trail. */
170 function sweep(state: State, drop: Drop, oldX: number, oldY: number, context: TextureContext): void {
171   const { width, height } = context.canvas, side = Math.min(width, height);
172   const ax = oldX * side, ay = oldY * side, bx = drop.x * side, by = drop.y * side;
173   const dx = bx - ax, dy = by - ay, length2 = dx * dx + dy * dy;
174   if (length2 < 0.000001) return;
175   const radius = Math.max(1, drop.radius * side * 1.1);
176   let collected = 0;
177   for (let y = Math.max(0, Math.floor(Math.min(ay, by) - radius)); y < Math.min(height, Math.ceil(Math.max(ay, by) + radius)); y++) {
178     for (let x = Math.max(0, Math.floor(Math.min(ax, bx) - radius)); x < Math.min(width, Math.ceil(Math.max(ax, bx) + radius)); x++) {
179       const t = Math.max(0, Math.min(1, ((x + 0.5 - ax) * dx + (y + 0.5 - ay) * dy) / length2));
180       const distance = Math.hypot(x + 0.5 - ax - t * dx, y + 0.5 - ay - t * dy) / radius;
181       if (distance >= 1) continue;
182       const i = y * width + x;
183       const remaining = Math.max(0, Math.min(1, (distance - 0.7) / 0.3));
184       const removed = Math.max(0, state.film[i] - remaining);
185       collected += removed;
186       state.film[i] = Math.min(state.film[i], remaining);
187       // Spatially stable necks and beads avoid frame-rate-dependent trail stamping.
188       const neck = 0.18 + 0.12 * Math.sin(y * 0.7 + drop.phase);
189       const bead = Math.pow(state.grain[i], 7);
190       const residual = Math.max(0, 1 - distance / (neck + bead * 0.6));
191       state.trails[i] = Math.max(state.trails[i], residual * (0.00045 + bead * 0.0018) * state.config.trailStrength);
192     }
193   }
194   // Film volume is swept area times a small effective thickness.
195   drop.radius = Math.cbrt(drop.radius ** 3 + collected / (side * side) * state.config.condensation * 0.0002);
196   state.fieldActive = true;
197 }
198 
199 /** At capacity, coalesce the closest free beads before releasing newly gathered water. */
200 function makeReleaseRoom(drops: Drop[]): void {
201   if (drops.length < MAX_DROPS) return;
202   let first = 0, second = 1, nearest = Infinity;
203   for (let i = 0; i < drops.length; i++) for (let j = i + 1; j < drops.length; j++) {
204     const distance = Math.hypot(drops[i].x - drops[j].x, drops[i].y - drops[j].y);
205     if (distance < nearest) { nearest = distance; first = i; second = j; }
206   }
207   const a = drops[first], b = drops[second], av = a.radius ** 3, bv = b.radius ** 3, volume = av + bv;
208   a.x = (a.x * av + b.x * bv) / volume; a.y = (a.y * av + b.y * bv) / volume;
209   a.vx = (a.vx * av + b.vx * bv) / volume; a.vy = (a.vy * av + b.vy * bv) / volume;
210   a.radius = Math.cbrt(volume); drops.splice(second, 1);
211 }
212 
213 /** A finger removes film and residual water, and carries intersected beads without inertia. */
214 function wipeFinger(state: State, oldX: number, oldY: number, context: TextureContext): void {
215   const finger = state.finger;
216   if (!finger) return;
217   const { width, height } = context.canvas, side = Math.min(width, height);
218   const dx = finger.x - oldX, dy = finger.y - oldY, length2 = dx * dx + dy * dy;
219   const distance = (x: number, y: number): number => {
220     const t = length2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - oldX) * dx + (y - oldY) * dy) / length2));
221     return Math.hypot(x - oldX - t * dx, y - oldY - t * dy);
222   };
223   let volume = finger.drop ? finger.drop.radius ** 3 : 0;
224   for (let i = state.drops.length - 1; i >= 0; i--) {
225     const drop = state.drops[i];
226     if (distance(drop.x, drop.y) > finger.radius + drop.radius * 1.3) continue;
227     volume += drop.radius ** 3;
228     state.drops.splice(i, 1);
229   }
230   for (let y = Math.max(0, Math.floor((Math.min(oldY, finger.y) - finger.radius) * side)); y < Math.min(height, Math.ceil((Math.max(oldY, finger.y) + finger.radius) * side)); y++) {
231     for (let x = Math.max(0, Math.floor((Math.min(oldX, finger.x) - finger.radius) * side)); x < Math.min(width, Math.ceil((Math.max(oldX, finger.x) + finger.radius) * side)); x++) {
232       const coverage = Math.max(0, Math.min(1, (1 - distance((x + 0.5) / side, (y + 0.5) / side) / finger.radius) / 0.15));
233       if (coverage === 0) continue;
234       const i = y * width + x, remaining = 1 - coverage;
235       const removedFilm = Math.max(0, state.film[i] - remaining);
236       const removedTrail = state.trails[i] * coverage;
237       volume += (removedFilm * state.config.condensation * 0.0002 + removedTrail) / (side * side);
238       state.film[i] = Math.min(state.film[i], remaining);
239       state.trails[i] -= removedTrail;
240     }
241   }
242   if (volume > 0) {
243     finger.drop ??= { x: finger.x, y: finger.y, radius: 0, vx: 0, vy: 0, phase: 0 };
244     finger.drop.x = finger.x; finger.drop.y = finger.y; finger.drop.radius = Math.cbrt(volume);
245   }
246   state.fieldActive = true;
247 }
248 
249 function recoverFilm(state: State, elapsed: number): void {
250   if (!state.fieldActive) return;
251   const retention = state.config.trailPersistence === 0 ? 0 : Math.exp(-elapsed / state.config.trailPersistence);
252   let active = false;
253   for (let i = 0; i < state.film.length; i++) {
254     const missing = (1 - state.film[i]) * retention;
255     state.film[i] = missing < 0.002 ? 1 : 1 - missing;
256     const trail = state.trails[i] * retention;
257     state.trails[i] = trail < 0.000005 ? 0 : trail;
258     active ||= state.film[i] < 1 || state.trails[i] > 0;
259   }
260   state.fieldActive = active;
261 }
262 
263 const recipe = defineTexture<RainDropsOptions, State, RainDropsMessage>({
264   create(context, input) {
265     assertMap(context);
266     const config = options(input);
267     const cells = context.canvas.width * context.canvas.height;
268     const state: State = { film: new Float32Array(cells), trails: new Float32Array(cells), surface: new Float32Array(cells), grain: new Float32Array(cells), fieldActive: false, config, drops: [], random: config.seed, births: 0, paused: config.paused, fresh: true, image: context.canvas.getContext("2d")!.createImageData(context.canvas.width, context.canvas.height) };
269     reset(state, context); schedule(state, context); return state;
270   },
271   update(state, input, context) {
272     assertMap(context);
273     const next = options(input), previous = state.config;
274     state.config = next;
275     if (next.condensation !== previous.condensation || next.irregularity !== previous.irregularity || next.trailStrength !== previous.trailStrength) context.invalidate();
276     if (next.paused !== previous.paused) { state.paused = next.paused; state.fresh = true; }
277     if (next.rainRate !== previous.rainRate || next.gravity !== previous.gravity) state.fresh = true;
278     if (next.seed !== previous.seed || next.initialDrops !== previous.initialDrops) { reset(state, context); context.invalidate(); }
279     schedule(state, context);
280   },
281   receive(state, message, context) {
282     if (message.type === "pause") { state.paused = message.paused; state.fresh = true; }
283     else if (message.type === "reset") { reset(state, context); context.invalidate(); }
284     else if (message.type === "finger") {
285       const x = bounded(message.x, "finger x", 1), y = bounded(message.y, "finger y", 1);
286       const radius = bounded(message.radius ?? 0.045, "finger radius", 2);
287       if (radius === 0) throw new RangeError("Rain finger radius must be positive.");
288       const side = Math.min(context.canvas.width, context.canvas.height);
289       const nextX = x * context.canvas.width / side, nextY = y * context.canvas.height / side;
290       const oldX = state.finger?.x ?? nextX, oldY = state.finger?.y ?? nextY;
291       state.finger ??= { x: nextX, y: nextY, radius };
292       state.finger.x = nextX; state.finger.y = nextY; state.finger.radius = radius;
293       wipeFinger(state, oldX, oldY, context); context.invalidate();
294     }
295     else if (message.type === "release") {
296       if (state.finger?.drop) { makeReleaseRoom(state.drops); state.drops.push(state.finger.drop); }
297       state.finger = undefined; context.invalidate();
298     }
299     else if (message.type === "nudge") {
300       const x = bounded(message.x, "nudge x", 1), y = bounded(message.y, "nudge y", 1);
301       const radius = bounded(message.radius ?? 0.12, "nudge radius", 2);
302       if (radius === 0) throw new RangeError("Rain nudge radius must be positive.");
303       for (const delta of [message.dx, message.dy]) if (!Number.isFinite(delta) || Math.abs(delta) > 1) throw new RangeError("Rain nudge movement must be finite and within [-1, 1].");
304       if (message.dx === 0 && message.dy === 0) return;
305       const side = Math.min(context.canvas.width, context.canvas.height);
306       const width = context.canvas.width / side, height = context.canvas.height / side;
307       for (const drop of state.drops) {
308         const distance = Math.hypot(drop.x - x * width, drop.y - y * height);
309         const weight = Math.max(0, 1 - distance / radius) ** 2;
310         const oldX = drop.x, oldY = drop.y;
311         drop.x = Math.max(0, Math.min(width, drop.x + message.dx * width * weight));
312         drop.y = Math.max(0, Math.min(height, drop.y + message.dy * height * weight));
313         sweep(state, drop, oldX, oldY, context);
314         drop.vx += message.dx * width * weight * 3; drop.vy += message.dy * height * weight * 3;
315       }
316       merge(state.drops); context.invalidate();
317     } else throw new TypeError("Unknown rain drop message.");
318     schedule(state, context);
319   },
320   advance(state, frame, context) {
321     if (state.paused) return;
322     if (state.fresh) state.fresh = false;
323     else {
324       // Bounded substeps prevent tab suspension from creating a rainfall burst.
325       const elapsed = Math.min(frame.delta / 1000, 0.05);
326       recoverFilm(state, elapsed);
327       const steps = Math.max(1, Math.ceil(elapsed * 120)), dt = elapsed / steps;
328       const side = Math.min(context.canvas.width, context.canvas.height);
329       for (let step = 0; step < steps; step++) {
330         state.births += state.config.rainRate * dt;
331         while (state.births >= 1) { spawn(state, context); state.births--; }
332         for (const drop of state.drops) {
333           const slide = Math.max(0, drop.radius / 0.012 - 1);
334           const oldX = drop.x, oldY = drop.y;
335           drop.vx += Math.sin(drop.y * 85 + drop.phase) * slide * state.config.gravity * state.config.irregularity * 0.09 * dt;
336           drop.vy += state.config.gravity * slide * 0.3 * dt;
337           drop.vx *= Math.exp(-7 * dt); drop.vy *= Math.exp(-3 * dt);
338           if (Math.abs(drop.vx) < 0.00005) drop.vx = 0;
339           if (Math.abs(drop.vy) < 0.00005) drop.vy = 0;
340           drop.x += drop.vx * dt; drop.y += drop.vy * dt;
341           sweep(state, drop, oldX, oldY, context);
342         }
343         merge(state.drops);
344         state.drops = state.drops.filter(d => d.y - d.radius < context.canvas.height / side && d.y + d.radius > 0 && d.x + d.radius > 0 && d.x - d.radius < context.canvas.width / side);
345       }
346       if (state.finger) wipeFinger(state, state.finger.x, state.finger.y, context);
347       context.invalidate();
348     }
349     schedule(state, context);
350   },
351   rasterize(state, context) {
352     const { width, height } = context.canvas, side = Math.min(width, height);
353     const data = state.image.data, surface = state.surface;
354     for (let i = 0; i < surface.length; i++) {
355       surface[i] = state.trails[i] + state.grain[i] * 0.00018 * state.config.condensation * state.film[i];
356     }
357     const visibleDrops = state.finger?.drop ? [...state.drops, state.finger.drop] : state.drops;
358     for (const drop of visibleDrops) {
359       const stretch = 1 + Math.min(1.3, Math.abs(drop.vy) * 3);
360       const rx = drop.radius * side / Math.sqrt(stretch), ry = drop.radius * side * stretch;
361       const cx = drop.x * side, cy = drop.y * side;
362       const extent = 1.3;
363       for (let y = Math.max(0, Math.floor(cy - ry * extent)); y < Math.min(height, Math.ceil(cy + ry * extent)); y++) {
364         for (let x = Math.max(0, Math.floor(cx - rx * extent)); x < Math.min(width, Math.ceil(cx + rx * extent)); x++) {
365           const ny = (y + 0.5 - cy) / ry;
366           const nx = (x + 0.5 - cx) / rx - state.config.irregularity * 0.09 * Math.sin(ny * 3 + drop.phase);
367           const angle = Math.atan2(ny, nx);
368           const edge = 1 + state.config.irregularity * (0.12 * Math.sin(angle * 3 + drop.phase) + 0.07 * Math.sin(angle * 5 - drop.phase));
369           const r2 = (nx * nx + ny * ny) / (edge * edge);
370           if (r2 >= 1) continue;
371           const i = y * width + x;
372           surface[i] = Math.max(surface[i], drop.radius * Math.sqrt(1 - r2));
373         }
374       }
375     }
376     for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
377       const i = y * width + x, index = i * 4;
378       const dx = (surface[y * width + Math.min(width - 1, x + 1)] - surface[y * width + Math.max(0, x - 1)]) * side * 0.5;
379       const dy = (surface[Math.min(height - 1, y + 1) * width + x] - surface[Math.max(0, y - 1) * width + x]) * side * 0.5;
380       data[index] = Math.round(128 + Math.max(-1, Math.min(1, dx)) * 110);
381       data[index + 1] = Math.round(128 + Math.max(-1, Math.min(1, dy)) * 110);
382       const droplet = Math.min(1, Math.max(0, (surface[i] - 0.001) * 1500));
383       data[index + 2] = Math.round(255 * state.config.condensation * state.film[i] * (0.8 + state.grain[i] * 0.2) * (1 - droplet));
384       data[index + 3] = state.config.condensation > 0 ? 255 : Math.round(Math.min(1, surface[i] * side * 2) * 255);
385     }
386     context.canvas.getContext("2d")!.putImageData(state.image, 0, 0);
387   },
388 });
389 
390 /**
391  * A seeded rain-on-glass displacement map, advanced by Pibbl's scheduler.
392  *
393  * @param options - Raindrop simulation and appearance settings. See {@link RainDropsOptions}.
394  * @returns A raindrop texture recipe accepting raindrop messages. See {@link TextureRecipe} ,
395  * {@link RainDropsMessage} .
396  *
397  * @see {@link RainDropsOptions}
398  * @see {@link TextureRecipe}
399  * @see {@link RainDropsMessage}
400  */
401 export function rainDrops(options: RainDropsOptions = {}): TextureRecipe<RainDropsMessage> { return recipe(options); }
402
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.