# packages/core/src/features/particles/lib/flow/hook.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/particles/lib/flow/hook.ts#L299). [Back to reference](/reference/hooks/use-flow-field/)
1 import type { PibblParticleSystemOptions } from '../types.js';
2 import {
3   resolveSignalValue,
4   signal,
5   type Signal,
6   type SignalValue,
7 } from "@pibbl/core";
8 import {
9   pibblInternalCurrentRenderOwner,
10   pibblInternalCurrentSimulationOwner,
11   pibblInternalOnRenderFinish,
12   pibblInternalQueueSimulationCommitAcknowledgement,
13   pibblInternalRegisterSimulationAdvance,
14   useInternalHookSlot,
15   type PibblInternalSimulationOwner,
16 } from "@pibbl/core/internal";
17 import { FlowFieldKernel2D, type FlowSource2D } from "./field.js";
18 
19 /**
20  * Committed obstacle geometry and motion packed into borrowed numeric buffers.
21  *
22  * @see {@link PibblFlowObstacleSource2D}
23  */
24 export interface PibblFlowObstacleBatch2D {
25   /**
26    * Revision used to detect changes to the underlying state or geometry. See
27    * {@link PibblFlowObstacleBatch2D}.
28    */
29   readonly revision: number;
30   /** cx, cy, halfWidth, halfHeight, radians, vx, vy, omega, COM x/y. */
31   readonly boxes: Float64Array;
32   /**
33    * Packed ellipse obstacle data consumed by the simulation. See {@link PibblFlowObstacleBatch2D}.
34    */
35   readonly ellipses?: Float64Array;
36   /**
37    * Packed polygon obstacle data consumed by the simulation. See {@link PibblFlowObstacleBatch2D}.
38    */
39   readonly polygons?: Float64Array;
40 }
41 /**
42  * Supplies committed obstacle batches to a flow field without transferring buffer ownership.
43  *
44  * @see {@link PibblFlowObstacleBatch2D}
45  * @see {@link PibblFlowFieldOptions2D}
46  */
47 export interface PibblFlowObstacleSource2D {
48   /**
49    * Returns committed simulation state. Buffers are borrowed for this call only.
50    * @returns The current obstacle revision and packed obstacle geometry. See
51    * {@link PibblFlowObstacleBatch2D} .
52    */
53   read(): PibblFlowObstacleBatch2D;
54 }
55 /**
56  * Logical bounds, grid resolution, obstacle source, and buoyancy for a flow field.
57  *
58  * @see {@link PibblFlowObstacleSource2D}
59  * @see {@link useFlowField2D}
60  */
61 export interface PibblFlowFieldOptions2D {
62   /** Logical region constraining the content or query. See {@link PibblFlowFieldOptions2D}. */
63   readonly bounds: Readonly<{
64     /**
65      * Horizontal extent in the units of the containing geometry or surface. See
66      * {@link PibblFlowFieldOptions2D}.
67      */
68     width: number;
69     /**
70      * Vertical extent in the units of the containing geometry or surface. See
71      * {@link PibblFlowFieldOptions2D}.
72      */
73     height: number;
74   }>;
75   /** Dimensions of the simulation or raster grid. See {@link PibblFlowFieldOptions2D}. */
76   readonly resolution: readonly [columns: number, rows: number];
77   /**
78    * Obstacle geometry used by the flow or water simulation. See {@link PibblFlowObstacleSource2D}.
79    */
80   readonly obstacles?: PibblFlowObstacleSource2D;
81   /** Strength of heat-driven upward motion in the flow field. See {@link PibblFlowFieldOptions2D}. */
82   readonly buoyancy?: number;
83 }
84 declare const flowBrand: unique symbol;
85 /**
86  * A mount-owned flow field with revision tracking and batched velocity sampling.
87  *
88  * @see {@link Signal}
89  * @see {@link useFlowField2D}
90  * @see {@link useFlowSource2D}
91  * @see {@link PibblParticleSystemOptions}
92  */
93 export interface PibblFlowField2D {
94   readonly [flowBrand]: true;
95   /** Revision used to detect changes to the underlying state or geometry. See {@link Signal}. */
96   readonly revision: Signal<number>;
97   /**
98    * Samples velocities for packed position pairs into caller-provided output storage. See
99    * {@link PibblFlowField2D}.
100    * @param positions - Packed input positions, with two floats per particle.
101    * @param velocities - Output buffer receiving sampled velocities, with two floats per particle.
102    * @param count - Number of position pairs to sample.
103    */
104   sampleBatch(positions: Float32Array, velocities: Float32Array, count: number): void;
105 }
106 /**
107  * Reactive position, radius, acceleration, heat, and enablement of a flow source.
108  *
109  * @see {@link SignalValue}
110  * @see {@link useFlowSource2D}
111  */
112 export interface PibblFlowSourceOptions2D {
113   /** Position of the geometry, source, or selected resize handle. See {@link SignalValue}. */
114   readonly position: SignalValue<readonly [number, number]>;
115   /** Radius in the coordinate system of this geometry or effect. See {@link SignalValue}. */
116   readonly radius: SignalValue<number>;
117   /** Acceleration injected by this flow source. See {@link SignalValue}. */
118   readonly acceleration?: SignalValue<readonly [number, number]>;
119   /** Heat injected by this flow source. See {@link SignalValue}. */
120   readonly heat?: SignalValue<number>;
121   /** Whether this operation or resource participates in updates. See {@link SignalValue}. */
122   readonly enabled?: SignalValue<boolean>;
123 }
124 const controllers = new WeakMap<PibblFlowField2D, FlowController2D>();
125 const STEP = 1000 / 60;
126 const EMPTY_OBSTACLES = Object.freeze({ boxes: new Float64Array(0) });
127 
128 /** Private coupling point; ordinary callers see only the read-only field handle. */
129 export function getFlowController2D(handle: PibblFlowField2D): FlowController2D {
130   const controller = controllers.get(handle);
131   if (!controller) throw new TypeError("Expected a Pibbl flow field.");
132   controller.requireActive();
133   return controller;
134 }
135 
136 export class FlowController2D {
137   readonly handle: PibblFlowField2D;
138   private committed: FlowFieldKernel2D | undefined;
139   private candidate: FlowFieldKernel2D | undefined;
140   private readonly revision = signal(0);
141   private readonly sources = new Map<object, FlowSource2D>();
142   private sourceList: readonly FlowSource2D[] = [];
143   private unregister: (() => void) | undefined;
144   private lastTime: number | undefined;
145   private remainder = 0;
146   private obstacleRevision: number | undefined;
147   private obstacleSourceChanged = true;
148   private options: PibblFlowFieldOptions2D;
149   private consumers = 0;
150   constructor(
151     private readonly owner: PibblInternalSimulationOwner,
152     options: PibblFlowFieldOptions2D,
153   ) {
154     this.options = options;
155     const [columns, rows] = options.resolution;
156     this.committed = new FlowFieldKernel2D(
157       columns,
158       rows,
159       options.bounds.width,
160       options.bounds.height,
161     );
162     this.candidate = new FlowFieldKernel2D(
163       columns,
164       rows,
165       options.bounds.width,
166       options.bounds.height,
167     );
168     this.handle = Object.freeze({
169       revision: this.revision.asReadonly(),
170       sampleBatch: (
171         positions: Float32Array,
172         velocities: Float32Array,
173         count: number,
174       ) => {
175         this.requireActive().sampleBatch(positions, velocities, count);
176       },
177     }) as PibblFlowField2D;
178     controllers.set(this.handle, this);
179   }
180   requireActive(): FlowFieldKernel2D {
181     if (!this.committed) throw new Error("Pibbl flow field is disposed.");
182     return this.committed;
183   }
184   validateOptions(options: PibblFlowFieldOptions2D): void {
185     const field = this.requireActive();
186     if (
187       field.width !== options.bounds.width ||
188       field.height !== options.bounds.height ||
189       field.columns !== options.resolution[0] ||
190       field.rows !== options.resolution[1]
191     ) {
192       throw new Error(
193         "Flow bounds and resolution are mount-only; use a keyed remount to change them.",
194       );
195     }
196     if (!Number.isFinite(options.buoyancy ?? -300))
197       throw new RangeError("Flow buoyancy must be finite.");
198   }
199   adoptOptions(options: PibblFlowFieldOptions2D): void {
200     if (!this.committed) return;
201     if (this.options.obstacles !== options.obstacles)
202       this.obstacleSourceChanged = true;
203     this.options = options;
204   }
205   setSource(key: object, source: FlowSource2D | undefined): void {
206     if (!this.committed) return;
207     if (source) this.sources.set(key, source);
208     else this.sources.delete(key);
209     this.sourceList = Array.from(this.sources.values());
210     this.synchronize();
211   }
212   retain(): () => void {
213     this.requireActive();
214     this.consumers++;
215     this.synchronize();
216     let released = false;
217     return () => {
218       if (released) return;
219       released = true;
220       this.consumers--;
221       this.synchronize();
222     };
223   }
224   private synchronize(): void {
225     const active =
226       this.committed && (this.sources.size > 0 || this.consumers > 0);
227     if (active && !this.unregister) {
228       this.unregister = pibblInternalRegisterSimulationAdvance(
229         this.owner,
230         "physics",
231         (frame, batch) => {
232           const committed = this.requireActive();
233           const candidate = this.candidate!;
234           const elapsed =
235             this.lastTime === undefined
236               ? 0
237               : Math.max(0, frame.logicalTime - this.lastTime);
238           const accumulated = this.remainder + Math.min(elapsed, STEP * 4);
239           const steps = Math.min(4, Math.floor((accumulated + 1e-7) / STEP));
240           const remainder = Math.max(0, accumulated - steps * STEP);
241           candidate.copyFrom(committed);
242           const obstacles = this.options.obstacles?.read();
243           const nextObstacleRevision = obstacles?.revision;
244           const obstaclesChanged =
245             this.obstacleSourceChanged ||
246             nextObstacleRevision !== this.obstacleRevision;
247           if (obstaclesChanged) {
248             candidate.setObstacles(obstacles ?? EMPTY_OBSTACLES);
249           }
250           for (let i = 0; i < steps; i++)
251             candidate.advance(
252               STEP / 1000,
253               this.sourceList,
254               this.options.buoyancy ?? -300,
255             );
256           if (steps > 0 || obstaclesChanged) {
257             batch.stage(this.revision, this.revision.get() + 1, this);
258           }
259           pibblInternalQueueSimulationCommitAcknowledgement(
260             this.owner,
261             (_frame, outcome) => {
262               if (!outcome.applied || !this.committed) return;
263               this.committed = candidate;
264               this.candidate = committed;
265               this.lastTime = frame.logicalTime;
266               this.remainder = remainder;
267               this.obstacleRevision = nextObstacleRevision;
268               this.obstacleSourceChanged = false;
269             },
270           );
271         },
272       );
273     } else if (!active && this.unregister) {
274       this.unregister();
275       this.unregister = undefined;
276       this.lastTime = undefined;
277     }
278   }
279   dispose(): void {
280     this.unregister?.();
281     this.unregister = undefined;
282     this.sources.clear();
283     this.sourceList = [];
284     this.committed = undefined;
285     this.candidate = undefined;
286   }
287 }
288 
289 /**
290  * Creates a mount-owned 2D flow field with configured bounds, resolution, and optional obstacles.
291  *
292  * @param options - Field dimensions, sampling, decay, and obstacle settings. See
293  * {@link PibblFlowFieldOptions2D} .
294  * @returns A mount-owned 2D flow field sampled by particle effects. See {@link PibblFlowField2D}.
295  *
296  * @see {@link PibblFlowFieldOptions2D}
297  * @see {@link PibblFlowField2D}
298  */
299 export function useFlowField2D(options: PibblFlowFieldOptions2D): PibblFlowField2D {
300   const simulationOwner = pibblInternalCurrentSimulationOwner();
301   const renderOwner = pibblInternalCurrentRenderOwner();
302   const controller = useInternalHookSlot("flow-field", (teardowns) => {
303     const value = new FlowController2D(simulationOwner, options);
304     teardowns.add(() => value.dispose());
305     return value;
306   }).value;
307   controller.validateOptions(options);
308   pibblInternalOnRenderFinish(renderOwner, (success) => {
309     if (success) controller.adoptOptions(options);
310   });
311   return controller.handle;
312 }
313 
314 /**
315  * Registers a mount-owned source of acceleration or heat in a flow field.
316  *
317  * @param field - Flow field receiving this source. See {@link PibblFlowField2D}.
318  * @param options - Source position, influence, and strength settings. See
319  * {@link PibblFlowSourceOptions2D} .
320  *
321  * @see {@link PibblFlowField2D}
322  * @see {@link PibblFlowSourceOptions2D}
323  */
324 export function useFlowSource2D(
325   field: PibblFlowField2D,
326   options: PibblFlowSourceOptions2D,
327 ): void {
328   const controller = getFlowController2D(field);
329   const renderOwner = pibblInternalCurrentRenderOwner();
330   const position = resolveSignalValue(options.position);
331   const radius = resolveSignalValue(options.radius);
332   const acceleration = resolveSignalValue(
333     options.acceleration ?? ([0, 0] as const),
334   );
335   const heat = resolveSignalValue(options.heat ?? 0);
336   const enabled = resolveSignalValue(options.enabled ?? true);
337   if (
338     !Number.isFinite(position[0]) ||
339     !Number.isFinite(position[1]) ||
340     !Number.isFinite(radius) ||
341     radius <= 0 ||
342     !Number.isFinite(acceleration[0]) ||
343     !Number.isFinite(acceleration[1]) ||
344     !Number.isFinite(heat) ||
345     heat < 0
346   ) {
347     throw new RangeError(
348       "Flow source requires finite values, positive radius and nonnegative heat.",
349     );
350   }
351   const slot = useInternalHookSlot("flow-source", (teardowns) => {
352     const value = { key: {}, controller, revision: 0 };
353     teardowns.add(() => value.controller.setSource(value.key, undefined));
354     return value;
355   }).value;
356   const revision = ++slot.revision;
357   const source: FlowSource2D | undefined = enabled
358     ? {
359         x: position[0],
360         y: position[1],
361         radius,
362         acceleration: [acceleration[0], acceleration[1]],
363         heat,
364       }
365     : undefined;
366   pibblInternalOnRenderFinish(renderOwner, (success) => {
367     if (!success || revision !== slot.revision) return;
368     if (slot.controller !== controller)
369       slot.controller.setSource(slot.key, undefined);
370     slot.controller = controller;
371     controller.setSource(slot.key, source);
372   });
373 }
374
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.