@jayf0x/fluidity-js 0.2.4 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/README.md +55 -40
- package/dist/globals.d.ts +20 -19
- package/dist/index.js +815 -763
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -66,7 +66,7 @@ PATH=/Users/me/.nvm/versions/node/v20.19.6/bin:$PATH bun deploy # → gh-pages
|
|
|
66
66
|
|
|
67
67
|
```tsx
|
|
68
68
|
<FluidText text="Hello" fontSize={120} color="#fff" algorithm="glass" preset="neon" />
|
|
69
|
-
<FluidImage src="/hero.jpg" algorithm="aurora"
|
|
69
|
+
<FluidImage src="/hero.jpg" algorithm="aurora" pixelRatio={1} simResolution={0.5} />
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
### FluidHandle ref
|
package/README.md
CHANGED
|
@@ -74,7 +74,7 @@ export const Interactive = () => {
|
|
|
74
74
|
| -------------------------------- | --------------------------------------------------------- |
|
|
75
75
|
| `reset()` | Restart the simulation |
|
|
76
76
|
| `updateConfig(patch)` | Change any config value live |
|
|
77
|
-
| `move(
|
|
77
|
+
| `move(x, y, strength?)` | Simulate a pointer move |
|
|
78
78
|
| `splat(x, y, vx, vy, strength?)` | Inject fluid directly — safe to call many times per frame |
|
|
79
79
|
|
|
80
80
|
---
|
|
@@ -101,20 +101,33 @@ export const Interactive = () => {
|
|
|
101
101
|
|
|
102
102
|
### Shared props
|
|
103
103
|
|
|
104
|
-
| Prop
|
|
105
|
-
|
|
|
106
|
-
| `
|
|
107
|
-
| `preset`
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
104
|
+
| Prop | Type | Default |
|
|
105
|
+
| --------------------- | ------------------ | ------------ |
|
|
106
|
+
| `algorithm` | `FluidAlgorithm` | `'aurora'` |
|
|
107
|
+
| `preset` | `PresetKey` | — |
|
|
108
|
+
| `pixelRatio` | `number` | `1` |
|
|
109
|
+
| `simResolution` | `number` | `0.5` |
|
|
110
|
+
| `densityDissipation` | `number` | `0.83` |
|
|
111
|
+
| `velocityDissipation` | `number` | `0.91` |
|
|
112
|
+
| `pressureIterations` | `number` | `1` |
|
|
113
|
+
| `curl` | `number` | `0` |
|
|
114
|
+
| `splatRadius` | `number` | `0.1` |
|
|
115
|
+
| `splatForce` | `number` | `0.08` |
|
|
116
|
+
| `refraction` | `number` | `1.0` |
|
|
117
|
+
| `specularExp` | `number` | `0` |
|
|
118
|
+
| `shine` | `number` | `0` |
|
|
119
|
+
| `waterColor` | `FluidColor` | `'#000000'` |
|
|
120
|
+
| `glowColor` | `FluidColor` | `'#b3d9ff'` |
|
|
121
|
+
| `warpStrength` | `number` | `0.04` |
|
|
122
|
+
| `backgroundColor` | `string` | `'#0a0a0a'` |
|
|
123
|
+
| `backgroundSrc` | `string` | — |
|
|
124
|
+
| `backgroundSize` | `string \| number` | `'cover'` |
|
|
125
|
+
| `mouseEnabled` | `boolean` | `true` |
|
|
126
|
+
| `workerEnabled` | `boolean` | `true` |
|
|
127
|
+
| `webGPUEnabled` | `boolean` | `true` |
|
|
128
|
+
| `alphaEnabled` | `boolean` | `true` |
|
|
129
|
+
| `className` | `string` | — |
|
|
130
|
+
| `style` | `CSSProperties` | — |
|
|
118
131
|
|
|
119
132
|
---
|
|
120
133
|
|
|
@@ -122,15 +135,15 @@ export const Interactive = () => {
|
|
|
122
135
|
|
|
123
136
|
| Value | Vibe |
|
|
124
137
|
| ------------ | ------------------------------------------------ |
|
|
125
|
-
| `'
|
|
138
|
+
| `'aurora'` | Liquid metal / lava-lamp (default) |
|
|
139
|
+
| `'standard'` | Colour overlay + gentle refraction |
|
|
126
140
|
| `'glass'` | Bent-glass distortion, no colour |
|
|
127
141
|
| `'ink'` | Dense opaque pigment that accumulates and stains |
|
|
128
|
-
| `'aurora'` | Liquid metal / lava-lamp |
|
|
129
142
|
| `'ripple'` | Still water surface with Fresnel rim |
|
|
130
143
|
|
|
131
144
|
```tsx
|
|
132
145
|
<FluidImage src="/photo.jpg" algorithm="aurora" />
|
|
133
|
-
<FluidText text="fluid" algorithm="ripple"
|
|
146
|
+
<FluidText text="fluid" algorithm="ripple" warpStrength={0.03} />
|
|
134
147
|
```
|
|
135
148
|
|
|
136
149
|
---
|
|
@@ -139,37 +152,39 @@ export const Interactive = () => {
|
|
|
139
152
|
|
|
140
153
|
Control rendering resolution on two independent axes — both reactive at runtime.
|
|
141
154
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
155
|
+
| Prop | Range | Default | What it does |
|
|
156
|
+
| --------------- | ----- | ------- | ----------------------------------------------------------------------------------------- |
|
|
157
|
+
| `pixelRatio` | 0.1–1 | `1` | Canvas resolution as fraction of devicePixelRatio. `0.5` on Retina saves ~75% GPU fill. |
|
|
158
|
+
| `simResolution` | 0.1–1 | `0.5` | Simulation FBO size. Lower = cheaper, less detail. |
|
|
146
159
|
|
|
147
160
|
```tsx
|
|
148
161
|
// Sharp canvas, cheap simulation
|
|
149
|
-
<FluidImage src="/hero.jpg"
|
|
162
|
+
<FluidImage src="/hero.jpg" pixelRatio={1} simResolution={0.2} />
|
|
150
163
|
|
|
151
164
|
// Lower canvas res, full simulation quality
|
|
152
|
-
<FluidImage src="/hero.jpg"
|
|
165
|
+
<FluidImage src="/hero.jpg" pixelRatio={0.5} simResolution={1} />
|
|
153
166
|
```
|
|
154
167
|
|
|
155
168
|
---
|
|
156
169
|
|
|
157
|
-
##
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `warpStrength` | `0.
|
|
170
|
+
## Simulation props reference
|
|
171
|
+
|
|
172
|
+
Simulation props that have a physics range accept a **normalized `0–1` value** — no need to know the raw shader units. Values outside `[0, 1]` are passed through as raw physics values for advanced overrides.
|
|
173
|
+
|
|
174
|
+
| Prop | Default | Range | Physics range | Description |
|
|
175
|
+
| --------------------- | ------- | ------- | --------------- | ----------------------------------------------- |
|
|
176
|
+
| `densityDissipation` | `0.83` | `0–1` | `0.94–1.0` | How long ink lingers |
|
|
177
|
+
| `velocityDissipation` | `0.91` | `0–1` | `0.9–0.999` | How fast fluid slows down |
|
|
178
|
+
| `pressureIterations` | `1` | `1–50` | — | Pressure solve quality vs. cost |
|
|
179
|
+
| `curl` | `0` | `0–1` | — | Swirl intensity |
|
|
180
|
+
| `splatRadius` | `0.1` | `0–1` | `0.001–0.04` | Brush radius |
|
|
181
|
+
| `splatForce` | `0.08` | `0–1` | `0.1–5.0` | Force applied by brush |
|
|
182
|
+
| `refraction` | `1.0` | `0–1` | — | Background warp strength |
|
|
183
|
+
| `specularExp` | `0` | `0–1` | `0.1–10` | Specular highlight sharpness |
|
|
184
|
+
| `shine` | `0` | `0–1` | `0–0.15` | Highlight intensity |
|
|
185
|
+
| `warpStrength` | `0.04` | `0–1` | `0.001–0.1` | UV warp intensity (`aurora` algorithm) |
|
|
186
|
+
| `waterColor` | `#000` | — | — | Base fluid colour (hex or `[R, G, B]` 0–1) |
|
|
187
|
+
| `glowColor` | `#b3d9ff`| — | — | Glow / specular colour (hex or `[R, G, B]` 0–1) |
|
|
173
188
|
|
|
174
189
|
---
|
|
175
190
|
|
package/dist/globals.d.ts
CHANGED
|
@@ -5,15 +5,9 @@ type FluidAlgorithm = 'standard' | 'glass' | 'ink' | 'aurora' | 'ripple';
|
|
|
5
5
|
/** RGB tuple (values 0–1) or a CSS hex string (#RGB, #RRGGBB, #RRGGBBAA — alpha stripped). */
|
|
6
6
|
type FluidColor = [number, number, number] | `#${string}`;
|
|
7
7
|
|
|
8
|
-
/**
|
|
9
|
-
* Granular performance/quality controls. Both axes are independent — you can
|
|
10
|
-
* run a sharp display at a coarser simulation, or vice versa.
|
|
11
|
-
* Reactive: changes after mount are applied on the next animation frame.
|
|
12
|
-
*/
|
|
8
|
+
/** Internal quality object used by FluidController and FluidSimulation. */
|
|
13
9
|
interface FluidQuality {
|
|
14
|
-
/** devicePixelRatio multiplier for canvas backing resolution. Range [0.1, 1]. Default 1 (native). On Retina, 0.5 → 1× pixels (75% less fill). */
|
|
15
10
|
dpr?: number;
|
|
16
|
-
/** Simulation FBO size as a fraction of canvas size. Range [0.1, 1]. Default 0.5 (current behavior). Higher = more fluid detail, more GPU. */
|
|
17
11
|
sim?: number;
|
|
18
12
|
}
|
|
19
13
|
|
|
@@ -42,24 +36,31 @@ interface FluidHandle {
|
|
|
42
36
|
updateConfig(config: Partial<FluidConfig>): void;
|
|
43
37
|
}
|
|
44
38
|
|
|
45
|
-
|
|
46
|
-
|
|
39
|
+
/**
|
|
40
|
+
* All FluidConfig fields are inherited as optional props.
|
|
41
|
+
* Set any simulation knob directly on the component — no config object needed.
|
|
42
|
+
*/
|
|
43
|
+
interface FluidBaseProps extends Partial<FluidConfig> {
|
|
44
|
+
/** Applied to the canvas container element. */
|
|
47
45
|
className?: string;
|
|
48
|
-
/**
|
|
46
|
+
/** Applied to the canvas container element. */
|
|
49
47
|
style?: React.CSSProperties;
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
48
|
+
/** Canvas backing resolution as a fraction of devicePixelRatio. Range [0.1, 1]. Default 1 (native DPR). */
|
|
49
|
+
pixelRatio?: number;
|
|
50
|
+
/** Simulation FBO size as a fraction of canvas size. Range [0.1, 1]. Default 0.5. */
|
|
51
|
+
simResolution?: number;
|
|
54
52
|
preset?: PresetKey;
|
|
55
|
-
algorithm?: FluidAlgorithm;
|
|
56
53
|
backgroundColor?: string;
|
|
57
54
|
backgroundSrc?: string;
|
|
58
55
|
backgroundSize?: string | number;
|
|
59
|
-
/**
|
|
60
|
-
|
|
61
|
-
/**
|
|
62
|
-
|
|
56
|
+
/** Forward pointer events to the simulation. Default true. */
|
|
57
|
+
mouseEnabled?: boolean;
|
|
58
|
+
/** Run simulation in a Web Worker via OffscreenCanvas. Default true. */
|
|
59
|
+
workerEnabled?: boolean;
|
|
60
|
+
/** Prefer WebGPU renderer; falls back to WebGL. Default true. */
|
|
61
|
+
webGPUEnabled?: boolean;
|
|
62
|
+
/** Enable transparent canvas. Default true. Set false for a minor perf gain when transparency is not needed. */
|
|
63
|
+
alphaEnabled?: boolean;
|
|
63
64
|
}
|
|
64
65
|
|
|
65
66
|
interface FluidTextProps extends FluidBaseProps {
|