Configuration

Full prop reference for FluidConfig. Every field is optional — the engine fills in defaults at construction time. Pass these as props to <Fluid> or any preset component.

Simulation

Core physics parameters that control grid resolution, dissipation, and solver behavior.

Prop	Type	Default	Description
`simResolution`	`number`	`128`	Velocity grid resolution.
`dyeResolution`	`number`	`1024`	Dye grid resolution. Clamped to 512 if linear filtering is unsupported.
`densityDissipation`	`number`	`1`	How fast dye fades.
`initialDensityDissipation`	`number`	same as `densityDissipation`	Starting dissipation value, ramped to `densityDissipation` over the duration. No ramp by default.
`initialDensityDissipationDuration`	`number`	`0`	Seconds over which to ramp from initial to steady dissipation. 0 disables the ramp.
`velocityDissipation`	`number`	`0.2`	How fast velocity fades.
`pressure`	`number`	`0.8`	Pressure solver weight.
`pressureIterations`	`number`	`20`	Pressure solver iterations per frame.
`curl`	`number`	`30`	Vorticity confinement strength.

Splats

Control how pointer-driven splats are created.

Prop	Type	Default	Description
`splatRadius`	`number`	`0.25`	Splat radius in NDC units.
`splatForce`	`number`	`6000`	Splat impulse force multiplier.
`splatOnHover`	`boolean`	`false`	Create splats on mouse move without requiring a click. No effect when `pointerInput` is false.
`pointerInput`	`boolean`	`true`	Enable mouse and touch input.
`pointerTarget`	`'canvas' \| 'window'`	`'canvas'`	Where to attach pointer listeners. `'window'` drives the sim from pointer activity anywhere on the page.

Visuals

Shading, pointer color cycling, pause, and background.

Prop	Type	Default	Description
`shading`	`boolean`	`true`	3D-style shading effect.
`colorful`	`boolean`	`true`	Rotate pointer/touch splat colors over time. Does not change hand-authored `presetSplats`.
`colorUpdateSpeed`	`number`	`10`	Pointer/touch color rotation rate (1/seconds). Only matters when `colorful` is true.
`paused`	`boolean`	`false`	Pause the simulation step. Rendering still occurs.
`backColor`	`RGB`	`{ r: 0, g: 0, b: 0 }`	Background color in 0-255 RGB (CSS-style). Normalized internally before reaching the shader.
`transparent`	`boolean`	`false`	Render with a transparent background.

Bloom

Post-processing glow effect.

Prop	Type	Default	Description
`bloom`	`boolean`	`true`	Enable bloom effect.
`bloomIterations`	`number`	`8`	Bloom blur iterations.
`bloomResolution`	`number`	`256`	Bloom framebuffer resolution.
`bloomIntensity`	`number`	`0.8`	Bloom intensity multiplier.
`bloomThreshold`	`number`	`0.6`	Luminance threshold for bloom.
`bloomSoftKnee`	`number`	`0.7`	Bloom soft-knee curve.

Sunrays

Volumetric light ray effect.

Prop	Type	Default	Description
`sunrays`	`boolean`	`true`	Enable sunrays effect.
`sunraysResolution`	`number`	`196`	Sunrays framebuffer resolution.
`sunraysWeight`	`number`	`1`	Sunrays intensity weight.

Initial Splats

Splats created once at engine construction. These are construct-only (Bucket D) — changing them at runtime has no effect.

Prop	Type	Default	Description
`initialSplatCountMin`	`number`	`5`	Minimum number of initial random splats.
`initialSplatCountMax`	`number`	`25`	Maximum number of initial random splats.
`initialSplatCount`	`number \| undefined`	—	Exact initial splat count. Overrides min/max when set.
`seed`	`number`	auto-generated	32-bit unsigned integer seed for the deterministic PRNG. Reused across resizes for consistent patterns.
`presetSplats`	`PresetSplat[]`	—	Hand-crafted splats applied after the random initial splats. Combine with `initialSplatCount: 0` to suppress random splats.

Automatic Splats

Automatic splat generation for ambient motion without pointer input. Think of it as a timer that injects small bursts of dye and velocity.

Prop	Type	Default	Description
`autoSplatRate`	`number`	`0`	Automatic burst rate in splats per second. 0 = disabled.
`autoSplatCount`	`number`	`1`	Number of splats emitted each automatic burst.
`autoSplatColor`	`RGB \| null`	`null`	Fixed color for automatic splats (0-1 linear range). `null` = fresh random color per splat.
`autoSplatVelocityX`	`number`	`0`	X velocity for automatic splats (raw, not scaled by `splatForce`). Ignored when `autoSplatSwirl` is nonzero.
`autoSplatVelocityY`	`number`	`0`	Y velocity for automatic splats (raw). Negative = downward in DOM. Ignored when `autoSplatSwirl` is nonzero.
`autoSplatCenterY`	`number`	`0.5`	Vertical center of the spawn band: `0` = bottom, `0.5` = center, `1` = top.
`autoSplatEvenX`	`boolean`	`false`	Within each burst, use equal x positions such as 25%, 50%, 75% instead of random x positions.
`autoSplatSwirl`	`number`	`0`	Orbital velocity around the container/canvas center. Positive = counter-clockwise; negative = clockwise.
`autoSplatBandHeight`	`number`	`0.1`	Height of the spawn band. `0` = one horizontal line, `0.1` = ±5%, `2.0` = full canvas.

Container

Confine the simulation to a geometric shape. The boundary is physically enforced, not just a visual clip.

Prop	Type	Default	Description
`containerShape`	`ContainerShape \| null`	`null`	Shape constraint for the fluid. Supports `circle`, `frame`, `roundedRect`, `annulus`, and `svgPath`. `null` = full rectangle.
`openBoundary`	`boolean`	`false`	When true, fluid flows freely at boundaries instead of bouncing back. Shape becomes a visual crop, not a physical wall.

Glass

Simulates a glass vessel effect with refraction and specular highlights. Requires a containerShape.

Prop	Type	Default	Description
`glass`	`boolean`	`false`	Enable glass vessel post-processing. Ignored when `containerShape` is null.
`glassThickness`	`number`	`0.04`	Wall thickness in UV units. Controls how wide the refraction band is at the boundary.
`glassRefraction`	`number`	`0.4`	Refraction strength, 0-1. Mapped internally to IOR 1.0-2.0.
`glassReflectivity`	`number`	`0.12`	Specular reflectivity (Fresnel F0), 0-1. 0 = matte, 1 = mirror.
`glassChromatic`	`number`	`0.15`	Chromatic aberration strength, 0-1. Splits refraction into R/G/B for prismatic fringes.

Reveal

Dye acts as an opacity mask — scratch to reveal content behind. Colors are in 0-1 linear range.

Prop	Type	Default	Description
`reveal`	`boolean`	`false`	Enable reveal mode. Dye becomes a transparency mask with iridescent fringes.
`revealSensitivity`	`number`	`0.1`	Multiplier on dye intensity before the power curve. Higher = easier reveal.
`revealCurve`	`number`	`0.5`	Power exponent for reveal alpha. Higher = crisper edge, lower = softer gradient.
`revealCoverColor`	`RGB`	`{ r: 1, g: 1, b: 1 }`	Cover layer color (0-1 linear). Visible before scratching.
`revealAccentColor`	`RGB`	`{ r: 0.05, g: 0.16, b: 0.32 }`	Fringe accent color (0-1 linear). Shown between cover and revealed content.
`revealFringeColor`	`RGB`	`{ r: 0.6, g: 0.7, b: 0.85 }`	Outer fringe color (0-1 linear). Creates a two-tone fringe: cover → fringe → accent → transparent.

Distortion

Velocity field warps an underlying image like liquid glass. Mutually exclusive with reveal.

Prop	Type	Default	Description
`distortion`	`boolean`	`false`	Enable distortion mode. Cursor movement ripples and warps the image.
`distortionPower`	`number`	`0.4`	How strongly velocity warps UV coordinates, 0-1.
`distortionImageUrl`	`string`	—	URL of the image to distort. Required when `distortion` is true. Loaded asynchronously.
`distortionFit`	`'cover' \| 'contain'`	`'cover'`	How the image fits the canvas. `'cover'` fills and crops, `'contain'` fits within.
`distortionScale`	`number`	`1.0`	Image scale factor. Values > 1 zoom out, < 1 zoom in.
`distortionBleedX`	`number`	`0`	Horizontal bleed fraction (0-0.5). Canvas extends invisibly beyond visible area to prevent edge bounce.
`distortionBleedY`	`number`	`0`	Vertical bleed fraction (0-0.5). See `distortionBleedX`.

Sticky

Dye clings to a mask region by modulating physics. Composable with container shapes, bloom, sunrays, and glass. Mutually exclusive with reveal and distortion.

Prop	Type	Default	Description
`sticky`	`boolean`	`false`	Enable sticky mode. Triggers mask texture rebuild.
`stickyMask`	`StickyMask`	—	Mask shape that dye sticks to. Supports text, SVG paths, or both. Required when `sticky` is true.
`stickyStrength`	`number`	`0.9`	How strongly dissipation is reduced on the mask, 0-1. 1 = dye never fades on mask.
`stickyPressure`	`number`	`0.15`	Artificial pressure on the mask to push fluid around the shape.
`stickyAmplify`	`number`	`0.3`	Splat intensity multiplier on the mask region. Higher = more dye deposited.

Hot-update buckets

When props change at runtime, setConfig() classifies each field into one of four buckets that determine how the change takes effect:

Bucket A — Hot scalars

Written directly to the internal config object and picked up on the next simulation frame. Zero overhead. Most numeric props live here: densityDissipation, velocityDissipation, pressure, curl, splatRadius, splatForce, colorUpdateSpeed, bloomIntensity, sunraysWeight, all autoSplat* props, all glass* scalars, all reveal* scalars, all distortion* scalars, stickyStrength, stickyPressure, stickyAmplify, pointerTarget, and openBoundary.

Bucket B — Keyword recompile

Triggers a display shader recompile (~1 ms). Applies to feature toggles that change which GLSL code paths are active: shading, bloom, sunrays, reveal, and distortion.

Bucket C — FBO rebuild

Triggers framebuffer reallocation. Applies to resolution fields: simResolution, dyeResolution, bloomResolution, bloomIterations, and sunraysResolution. Also triggered by containerShape changes (mask texture rebuild) and glass toggle (scene FBO alloc/dispose).

Bucket D — Construct-only

Ignored by setConfig() after construction. These values are consumed once when the engine is created: seed, initialSplatCountMin, initialSplatCountMax, initialSplatCount, and presetSplats.