@adatechnology/game-fluids-three 0.1.7 → 0.2.0

package/README.md

@@ -93,6 +93,29 @@ budget, the newest are drawn.
 Types exported: `FluidRenderer`, `FluidRendererOptions`, `FluidRendererStats`, `BindOptions`, `FluidQuality`, `ThreeLib`. `smoothOutline(front, subdiv)` is
 exported too (the periodic Catmull-Rom used for the stain rim).
 
+
+## Running film
+
+`createFilmManager(THREE, options)` draws the film of `@adatechnology/game-fluids` (blood, old blood, bile, motor oil, fuel running down a wall or a floor) over
+the host's surfaces. The shader is the Fluid Standard's (thickness to colour, normals from the gradient, gloss, bile bubbles, oil and fuel iridescence, cracks
+where it dried thick); it is drawn transparent, so the host's own surface shows where nothing is wet. The film stays **near the player**: at most 6 grids of
+2 x 2 m (160 x 160 cells), only within 30 m, simulated inside a millisecond budget and uploaded by the dirty rectangle (`gpu`: pass the `WebGLRenderer` so
+`copyTextureToTexture` can be used). A grid that is out of range, still for 20 s or squeezed out by a newer one is **baked** into the stain decals of the
+fluid world (`fluids.splash` with the film's colours) and freed.
+
+```ts
+const film = createFilmManager(THREE, { scene, camera, random: createFilmLcg(1), fluids, gpu: renderer })
+film.launch({ fluid: 'blood', point: [0, 1.2, 0], velocity: [1, -1, 0], radius: 4 }) // a drop; the grid is made under it
+film.drip({ fluid: 'fuel', point: [0, 0.9, 0], every: 0.5 })
+const bridge = createFilmBridge({ fluids, manager: film, random })
+// every frame: fluids.update(dt); bridge.update(dt); film.update(dt)
+bridge.splat({ fluid: 'blood', point, direction, tint: { fresh: 0x8a0a0a, dry: 0x3a1c12 } }) // a wound, in the colours of an infection age
+bridge.setWeather({ rain: 1 }) // the rain hook: drying stops, spread x1.5 (a no-op until game-weather drives it)
+```
+
+`surfaceAt(point)` gives the floor, the wall and the curb of a point (`layoutFromSurfaces`); without it the film lies on the ground. A `leak` of a liquid that has a
+film drips from the hole into it until the stream ends.
+
 ## Português
 
 Renderizador three.js do `@adatechnology/game-fluids`: o líquido dentro do recipiente (um volume cortado pelo plano da superfície, sempre

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import * as THREE_NS from 'three';
-import { Vec3, FluidWorld } from '@adatechnology/game-fluids';
+import { VfxWorld } from '@adatechnology/game-vfx';
+import { ThreeLib as ThreeLib$1 } from '@adatechnology/game-vfx-three';
+import { Vec3, FluidWorld, Film, StainTint, FilmLayout, FilmProfile, FilmRandom, LiquidId, SurfaceSpec, FilmLook, FilmRegion } from '@adatechnology/game-fluids';
 
 /** The only three.js members the renderer needs at runtime. Pass your own `THREE` instance (the whole namespace works). */
-type ThreeLib = Pick<typeof THREE_NS, 'BufferAttribute' | 'BufferGeometry' | 'Color' | 'DoubleSide' | 'DynamicDrawUsage' | 'Group' | 'InstancedMesh' | 'Matrix4' | 'Mesh' | 'MeshStandardMaterial' | 'Points' | 'ShaderMaterial' | 'SphereGeometry' | 'Vector3'>;
+type ThreeLib = ThreeLib$1 & Pick<typeof THREE_NS, 'BufferAttribute' | 'PerspectiveCamera' | 'BufferGeometry' | 'Color' | 'DataTexture' | 'DoubleSide' | 'DynamicDrawUsage' | 'Group' | 'LinearFilter' | 'InstancedMesh' | 'Matrix4' | 'Mesh' | 'MeshStandardMaterial' | 'Points' | 'RGBAFormat' | 'ShaderMaterial' | 'SphereGeometry' | 'Vector2' | 'Vector3'>;
 /** Detail level. It sets the budgets (stains, streams, particles) and the mesh resolution. */
 type FluidQuality = 'low' | 'medium' | 'high';
 interface FluidRendererOptions {
@@ -14,8 +16,15 @@ interface FluidRendererOptions {
     quality?: FluidQuality;
     /** Environment map the wet surfaces and liquids reflect. When omitted they use `scene.environment` if the host set one. */
     envMap?: THREE_NS.Texture | null;
-    /** Pixel scale of the round point sprites (about half the canvas height in pixels). Default 600. */
+    /** Pixel scale of the round point sprites (about half the canvas height in pixels). Default 600. Only read when `vfx` is not given. */
     pointScale?: number;
+    /**
+     * The effects world that holds the droplets and steam (a host lends one to every renderer and steps it once per frame). Without it the renderer
+     * makes its own world and its own three layer and steps them in `update`.
+     */
+    vfx?: VfxWorld;
+    /** Camera of the own effects world (distance LOD); only read when `vfx` is not given. Default a camera at the origin. */
+    camera?: THREE_NS.Camera;
 }
 interface BindOptions {
     /**
@@ -65,4 +74,306 @@ declare function createFluidRenderer(THREE: ThreeLib, options: FluidRendererOpti
 /** Periodic Catmull-Rom of the 16 front radii: a smooth outline with `subdiv` points per sample. */
 declare const smoothOutline: (front: number[], subdiv: number, out?: number[]) => number[];
 
-export { type BindOptions, type FluidQuality, type FluidRenderer, type FluidRendererOptions, type FluidRendererStats, type ThreeLib, createFluidRenderer, smoothOutline };
+interface FilmGridOptions {
+    layout: FilmLayout;
+    profile: FilmProfile;
+    random: FilmRandom;
+    /** The host's surface colour under the film, `0xRRGGBB` (the shader blends over it). Default the page's sidewalk grey. */
+    base?: number;
+    /** World point the grid is about: the distance to the player is measured from it. */
+    center: Vec3;
+    /** The splash colours the profile was tinted with, kept to tell a grid of another tint apart and to bake with them. */
+    tint?: StainTint;
+    stepRate?: number;
+    maxSteps?: number;
+}
+/** A rectangle of cells, inclusive. */
+interface CellRect {
+    firstRow: number;
+    lastRow: number;
+    firstColumn: number;
+    lastColumn: number;
+}
+/**
+ * One film grid on screen: the running film, its texture (thickness, dryness, dampness per cell as the page's `upload` writes them), the strips of the
+ * layout drawn with the film shader, and the drops in flight.
+ */
+declare class FilmGrid {
+    private readonly THREE;
+    readonly film: Film;
+    readonly group: THREE_NS.Group;
+    readonly texture: THREE_NS.DataTexture;
+    readonly center: Vec3;
+    readonly tint: StainTint | undefined;
+    readonly data: Uint8Array<ArrayBuffer>;
+    /** Seconds the grid has been without anything landing, flowing or drying. */
+    idle: number;
+    /** Set once the whole texture went to the GPU (the partial uploads need it there first). */
+    uploaded: boolean;
+    private readonly strips;
+    private readonly material;
+    private readonly dropsView;
+    private previous;
+    private pending;
+    private launched;
+    private lastWet;
+    constructor(THREE: ThreeLib, options: FilmGridOptions);
+    get profile(): FilmProfile;
+    setProfile(profile: FilmProfile): void;
+    /** Where the film's light and eye are (the page's `camP`, `flashP` and `flashD`). */
+    setView(camera: Vec3, forward: Vec3, time: number): void;
+    /** Steps the film one frame and refreshes the texture cells that may have changed. Returns the rectangle to upload, or null. */
+    update(dt: number, dryingSeconds: number): CellRect | null;
+    private takePending;
+    /** The mean dryness of the cells that are wet (1 when nothing is). */
+    dryness(): number;
+    /** Draws the drops and the bead; answers how many drops are in flight. */
+    syncDrops(): number;
+    dropsInFlight(): boolean;
+    /** Writes the cells of the texture from the field, as the page's `upload` does (F360). */
+    encode(rect: CellRect): void;
+    /** Encodes the whole field (a grid made from a state, or after `clear`). */
+    encodeAll(): void;
+    private union;
+    dispose(): void;
+}
+
+/** The surfaces a grid is laid over: the floor, and optionally a wall the film folds up and a curb it folds down. */
+interface FilmSurfaces {
+    floor: SurfaceSpec;
+    wall?: SurfaceSpec;
+    curb?: SurfaceSpec;
+}
+/** The part of the renderer the manager uses to upload only the dirty rectangle of a texture (three 0.160 `copyTextureToTexture`). */
+interface FilmGpu {
+    copyTextureToTexture(position: THREE_NS.Vector2, source: THREE_NS.Texture, destination: THREE_NS.Texture, level?: number): void;
+}
+interface FilmViewer {
+    position: Vec3;
+    forward: Vec3;
+}
+/** What a baked grid leaves behind in the host's stain decals. */
+interface FilmBake {
+    fluid: LiquidId;
+    /** Where the film was thickest (world), litres of it, and the colours of its wet and dry look. */
+    point: Vec3;
+    liters: number;
+    tint: StainTint;
+    /** Radius in metres of the wet cells around `point`. */
+    radius: number;
+    reason: 'range' | 'settled' | 'budget' | 'clear';
+}
+interface FilmManagerOptions {
+    /** Where the grids are added (one group). */
+    scene: THREE_NS.Object3D;
+    /** The host's random stream: the film never calls `Math.random`. */
+    random: FilmRandom;
+    /** The player's eye: grids are simulated near it and drawn lit from it. A camera works; or give `viewer`. */
+    camera?: THREE_NS.Camera;
+    viewer?: () => FilmViewer;
+    /** The surfaces under a world point (floor, wall, curb), or null for none. Default: the ground plane at `groundAt`. */
+    surfaceAt?: (point: Vec3) => FilmSurfaces | null;
+    groundAt?: (x: number, z: number) => number;
+    /** The world whose stain decals take the film when a grid is baked (`fluids.splash`). Without it a bake only calls `onBake`. */
+    fluids?: FluidWorld;
+    onBake?: (bake: FilmBake) => void;
+    /** Profiles by liquid id (default the film profiles of `game-fluids`); override one to tune it. */
+    profiles?: Readonly<Record<string, FilmProfile>>;
+    /** Colour of the surface under the film (default the page's grey). */
+    base?: number;
+    maxGrids?: number;
+    /** Metres from the player past which a grid is not simulated and is baked. */
+    range?: number;
+    /** Milliseconds of film simulation per frame; the grids left out wait for the next frame. */
+    budgetMs?: number;
+    /** Seconds without change after which a grid is baked and freed. */
+    settleSeconds?: number;
+    /** Side of a grid in metres (cells are 1.25 cm) and the cell size. */
+    gridMetres?: number;
+    cellSize?: number;
+    /** Seconds of drying clock that pass in one second of real time (the host scales it; default 1). */
+    dryingSpeed?: number;
+    /** The renderer, for the partial texture uploads. Without it the whole texture goes up when it changes. */
+    gpu?: FilmGpu;
+    /** A clock in milliseconds (default `performance.now`). */
+    now?: () => number;
+}
+interface FilmStats {
+    grids: number;
+    drops: number;
+    wetCells: number;
+    /** Milliseconds the last update spent simulating. */
+    simMs: number;
+    /** Grids left out of the last update by the budget. */
+    starved: number;
+    baked: number;
+    /** Texels written by partial uploads in the last update. */
+    uploadedTexels: number;
+}
+interface FilmLaunch {
+    fluid: LiquidId;
+    point: Vec3;
+    /** Default straight down at 2 m/s. */
+    velocity?: Vec3;
+    /** Millimetres (default 3). */
+    radius?: number;
+    surfaces?: FilmSurfaces;
+    /** The colours of this splash (an infection age: fresh red, dry brown): the film is drawn with them instead of the liquid's own. */
+    tint?: StainTint;
+}
+interface FilmDripSpec {
+    fluid: LiquidId;
+    point: Vec3;
+    /** Average seconds between drops. */
+    every: number;
+    radius?: number;
+    surfaces?: FilmSurfaces;
+    tint?: StainTint;
+}
+/** A profile drawn in the colours of a splash: the thin film and the drops take the fresh colour, the thick middle a darker one, and the dried film the dry colour. */
+declare function tinted(profile: FilmProfile, tint: StainTint): FilmProfile;
+/**
+ * Keeps the running films near the player: at most `maxGrids` grids of 2 x 2 m, only within `range`, simulated inside a millisecond budget and uploaded by their
+ * dirty rectangle. A grid that is out of range, still, or squeezed out by a newer one is baked: its film becomes a stain of the host's world with the same
+ * colours and amount, and the grid is freed.
+ */
+declare class FilmManager {
+    private readonly THREE;
+    private readonly options;
+    readonly group: THREE_NS.Group;
+    private readonly grids;
+    private readonly profiles;
+    private readonly staging;
+    private readonly now;
+    private rain;
+    private time;
+    private bakedCount;
+    private last;
+    private empties;
+    constructor(THREE: ThreeLib, options: FilmManagerOptions);
+    get gridCount(): number;
+    /** The grids, for a host that wants to look at them (a bench, a test). */
+    list(): readonly FilmGrid[];
+    setWeather(weather: {
+        rain: number;
+    }): void;
+    /** Throws a drop of a liquid: it lands in the grid under it (made on the spot) and leaves the impact splash. Null when it is out of range or has no surface. */
+    launch(request: FilmLaunch): FilmGrid | null;
+    /** A drip: a bead swells at `point`, detaches and falls every `every` seconds on average. Replaces the grid's drip. */
+    drip(spec: FilmDripSpec): FilmGrid | null;
+    /** The grid of a liquid that covers `point`, made when there is none. Null when `point` is out of range or has no surface under it. */
+    gridFor(fluid: LiquidId, point: Vec3, surfaces?: FilmSurfaces, tint?: StainTint): FilmGrid | null;
+    /** One frame: simulates the grids near the player inside the budget, uploads what changed, bakes the ones that are far or still. */
+    update(dt: number): FilmStats;
+    stats(): FilmStats;
+    /** Frees every grid. `bake` leaves each one's film as a stain first. */
+    clear(bake?: boolean): void;
+    dispose(): void;
+    private columns;
+    private viewer;
+    private surfacesAt;
+    /** Whether `point` is over the grid, away from its edge, so a splash there does not fall off the strip. */
+    private covers;
+    /** The grid squeezed out for a new one at `point`: the one that has been still the longest, then the farthest from the player. */
+    private evict;
+    /** A grid that has nothing wet for two seconds goes without a trace. */
+    private emptyFor;
+    private free;
+    /** Bakes the film of a grid into the host's stain decals and frees the grid. */
+    private release;
+    /** The film's centre of volume, its litres (millimetres of film times cell area) and the radius of the wet cells. */
+    private measure;
+    /** Copies the dirty rectangle to the GPU texture; answers the texels written. */
+    private upload;
+    private stagingFor;
+}
+declare function createFilmManager(THREE: ThreeLib, options: FilmManagerOptions): FilmManager;
+
+/** The page's `uFl` of each look (blood 0, bile 2, oil 3, fuel 4). */
+declare const LOOK_INDEX: Readonly<Record<FilmLook, number>>;
+interface FilmMaterial {
+    readonly material: THREE_NS.ShaderMaterial;
+    /** Sets the page's liquid uniforms from a profile (`setFluid`, F119-130). */
+    setProfile(profile: FilmProfile): void;
+    dispose(): void;
+}
+/**
+ * The film's material: the Fluid Standard's shader with the grid texture `tF` (r: thickness, g: dryness, b: dampness) and the liquid's colours.
+ * It is transparent over the host's surface: the alpha is the film's coverage.
+ */
+declare function createFilmMaterial(THREE: ThreeLib, texture: THREE_NS.Texture, width: number, height: number, span?: number): FilmMaterial;
+
+/**
+ * One strip of the folded grid as a plane of the surface: `uv` runs over the region's rows and the grid's columns, so the shader reads its own cells.
+ * `aB` is the way the film runs down the strip (rows) and `aT` its columns.
+ */
+declare function createStripGeometry(THREE: ThreeLib, layout: FilmLayout, region: FilmRegion): THREE_NS.BufferGeometry;
+
+interface FilmDrops {
+    readonly drops: THREE_NS.InstancedMesh;
+    readonly bead: THREE_NS.Mesh;
+    setProfile(profile: FilmProfile): void;
+    /** Writes the film's drops in flight and the drip's bead into the meshes; answers how many drops are drawn. */
+    sync(film: Film): number;
+    dispose(): void;
+}
+declare function createFilmDrops(THREE: ThreeLib, capacity: number, profile: FilmProfile): FilmDrops;
+
+/**
+ * The film shader of the Fluid Standard page (F131-209), line by line. Where the page painted the whole surface itself (`baseCol`: wall, sidewalk, curb,
+ * road), the film is drawn over the host's own surface, so `baseCol` is the flat colour `uBase` and the alpha is the film's coverage: the wet part and,
+ * for fuel, the ground it darkened. Three more differences: the grid size and span are uniforms (`uGrid`, `uSpan`; the page hard-codes 256 x 396 and 4.95),
+ * the strip tangent comes from the geometry (`aT`; the page's was the x axis), and the output goes through the r160 colour-space chunk after turning the page's
+ * display-space colours linear. The two lines that mirror the page's own wall in the reflection (`R.z<-.02 ... env=vec3(.30,.32,.35)`, `R.y<-.02 ...`) are left out:
+ * they describe the page's scene, not a surface of the host.
+ */
+declare const FILM_VERTEX = "attribute vec3 aB;attribute vec3 aT;varying vec2 vUv;varying vec3 vPos;varying vec3 vN;varying vec3 vB;varying vec3 vT;\nvoid main(){vUv=uv;vPos=position;vN=normal;vB=aB;vT=aT;gl_Position=projectionMatrix*viewMatrix*vec4(position,1.);}";
+declare const FILM_FRAGMENT = "precision highp float;\nuniform sampler2D tF;uniform vec2 tx;uniform vec2 uGrid;uniform float uSpan;uniform float uT;uniform int uFl;uniform vec3 cThin,cThick,cDry,cDryThin,uBase;uniform float opK,F0,nrm,dbg;\nuniform vec3 camP,lampP,flashP,flashD;varying vec2 vUv;varying vec3 vPos;varying vec3 vN;varying vec3 vB;varying vec3 vT;\nfloat hsh(vec2 p){p=fract(p*vec2(123.34,456.21));p+=dot(p,p+45.32);return fract(p.x*p.y);}\nvec2 hsh2(vec2 p){return vec2(hsh(p),hsh(p+17.7));}\nfloat nz(vec2 p){vec2 i=floor(p),f=fract(p);f=f*f*(3.-2.*f);return mix(mix(hsh(i),hsh(i+vec2(1,0)),f.x),mix(hsh(i+vec2(0,1)),hsh(i+vec2(1,1)),f.x),f.y);}\nfloat vor(vec2 p){vec2 i=floor(p),f=fract(p);float d1=8.,d2=8.;for(int y=-1;y<=1;y++)for(int x=-1;x<=1;x++){vec2 o=vec2(float(x),float(y));vec2 r=o+hsh2(i+o)-f;float d=dot(r,r);if(d<d1){d2=d1;d1=d;}else if(d<d2)d2=d;}return sqrt(d2)-sqrt(d1);}\nfloat hs(vec2 u){float r=texture2D(tF,u).r;return r*r*6.;}\nvoid main(){\n  vec4 S=texture2D(tF,vUv);vec2 q=tx*.5;float h=.25*(hs(vUv+q)+hs(vUv-q)+hs(vUv+vec2(q.x,-q.y))+hs(vUv+vec2(-q.x,q.y)));float dry=S.g;float wg=S.b;\n  vec2 o1=vec2(tx.x*1.5,0.),o2=vec2(0.,tx.y*1.5);\n  float hl=hs(vUv-o1),hr=hs(vUv+o1),hd=hs(vUv-o2),hu=hs(vUv+o2);\n  vec2 g=vec2(hr-hl,hu-hd)/37.5;\n  vec2 cellp=vUv*uGrid;\n  float n1=nz(cellp*2.3),n2=nz(cellp*7.1);\n  float hn=h+(n1-.5)*.045+(n2-.5)*.02;\n  float m=smoothstep(.035,.08,hn);\n  if(uFl==4){float wa=.25*(texture2D(tF,vUv+q).b+texture2D(tF,vUv-q).b+texture2D(tF,vUv+vec2(q.x,-q.y)).b+texture2D(tF,vUv+vec2(-q.x,q.y)).b);m=smoothstep(.35,.75,wa+(n1-.5)*.25)*smoothstep(.0,.012,h);wg=smoothstep(.2,.8,wa+(n1-.5)*.2);}\n  vec2 p=vec2(dot(vPos,normalize(vT)),vUv.y*uSpan);\n  vec3 base=uBase;\n  vec3 T=normalize(vT),Bv=normalize(vB),N0=normalize(vN);\n  vec3 nt=vec3(-g*nrm*m,1.);\n  float dryM=smoothstep(.5,.95,dry);\n  float wet=(1.-dryM)*m;\n  // bile bubbles\n  float bub=0.;\n  if(uFl==2){vec2 bp=cellp/2.6;vec2 bi=floor(bp);vec2 bf=fract(bp)-.5;float rnd=hsh(bi);\n    if(rnd>.5&&h>1.1){float t=fract(uT*(.18+.25*hsh(bi+3.1))+rnd*7.);float rad=.42*smoothstep(0.,.8,t);float d=length(bf-(hsh2(bi+9.)-.5)*.2);\n      if(t<.86&&d<rad){float z=sqrt(max(0.,rad*rad-d*d));nt.xy+=(bf/max(rad,.01))*2.2*(1.-dryM);bub=z/rad;}\n      else if(t>=.86){float rr=.42*1.15;float ring=1.-smoothstep(0.,.07,abs(d-rr*(.9+(t-.86)*.8)));nt.xy-=normalize(bf+.0001)*ring*.8*(1.-dryM);bub=-ring;}}}\n  if(uFl==4){vec2 wp=p;nt.xy+=.05*m*vec2(nz(wp*9.+vec2(uT*1.7,0.))-.5,nz(wp*9.+vec2(0.,uT*1.4)+7.)-.5)*2.;}\n  vec3 Nf=normalize(T*nt.x+Bv*nt.y+N0*nt.z);\n  // albedo\n  float th=smoothstep(.1,1.7,h);\n  vec3 fc=mix(cThin,cThick,th);\n  float op=clamp(1.-exp(-h*opK),0.,1.);\n  vec3 alb;\n  if(uFl==4){alb=base*mix(vec3(1.),cThin*1.15,clamp(h*.9,0.,1.));}\n  else{alb=mix(base*mix(vec3(1.),fc*1.6,clamp(h*2.,0.,1.)),fc,op);}\n  if(uFl==2&&bub>0.)alb=mix(alb,cThin*1.25,bub*.5);\n  // dried look: matte, darker rim, cracks where it was thick\n  float rim=smoothstep(.01,.05,length(g))*(1.-smoothstep(.4,1.,h));\n  vec3 dc=mix(cDryThin,cDry,smoothstep(.06,.8,h))*(1.-.42*rim);\n  float crk=(1.-smoothstep(.015,.05,vor(p*(uFl==2?34.:52.))))*smoothstep(.9,1.6,h);\n  dc=mix(dc,base*.55,crk*.75);\n  if(uFl!=3&&uFl!=4)alb=mix(alb,mix(base,dc,clamp(.4+h*1.4,0.,1.)),dryM);\n  // gasoline darkens the ground while wet\n  float gw=0.;if(uFl==4){gw=wg*(1.-m*.0);base*=mix(1.,.45,gw);alb=mix(base,alb,m);}\n  vec3 col0=mix(base,alb*(uFl<2?mix(.62,1.,dryM):1.),m);\n  // lighting\n  vec3 V=normalize(camP-vPos);\n  vec3 Lv=lampP-vPos;float dl=length(Lv);vec3 L=Lv/dl;float att=2.2/(1.+dl*dl*.12);\n  vec3 lampC=vec3(1.,.88,.7);vec3 moonD=normalize(vec3(-3.,5.,4.));vec3 moonC=vec3(.11,.14,.19);vec3 amb=vec3(.14,.15,.17);\n  vec3 Fv=flashP-vPos;float fd=length(Fv);vec3 FL=Fv/fd;float cone=smoothstep(.86,.97,dot(-FL,flashD));float fatt=cone*1.1/(1.+fd*fd*.6);\n  vec3 dif=col0*(amb+lampC*att*max(dot(Nf,L),0.)+moonC*max(dot(Nf,moonD),0.)+vec3(.95,.97,1.)*fatt*max(dot(Nf,FL),0.));\n  float wv=max(wet,gw*.7);\n  float shin=mix(30.,320.,wv);\n  vec3 Hh=normalize(L+V);vec3 Hf=normalize(FL+V);\n  float sp=pow(max(dot(Nf,Hh),0.),shin)*shin*.011*att;float spf=pow(max(dot(Nf,Hf),0.),shin)*shin*.008*fatt;\n  vec3 R=reflect(-V,Nf);\n  vec3 env=mix(vec3(.03,.035,.04),vec3(.15,.17,.21),clamp(R.y*1.4,0.,1.));\n  env+=lampC*(pow(max(dot(R,L),0.),500.)*7.+pow(max(dot(R,L),0.),40.)*.6)*att;\n  float fr=F0+(1.-F0)*pow(1.-max(dot(Nf,V),0.),5.);\n  vec3 col=dif*(1.-fr*wv*.7)+(env*min(1.,fr*(uFl==4?1.6:3.4))+min(lampC*sp+vec3(.9,.95,1.)*spf,vec3(.85)))*wv;\n  if(uFl==3){float film=(1.-smoothstep(.04,.55,h))*m;vec3 ir=.5+.5*cos(6.283*(h*7.+n1*.5+uT*.03+vec3(0.,.33,.67)));col+=ir*film*(.10+.5*fr)*(.6+att*.4);}\n  if(uFl==4){vec2 wp=p;float film=m*(.4+.6*(1.-smoothstep(.02,.2,h)));vec3 ir=.5+.5*cos(6.283*(nz(wp*6.)*1.4+uT*.02+vec3(0.,.33,.67)));col+=ir*film*.05*(.3+fr*3.);}\n  if(dbg>.5){float k=clamp(h/3.,0.,1.);vec3 hc=mix(vec3(.05,.1,.5),vec3(1.,.9,.2),k);hc=mix(hc,vec3(1.,.2,.1),step(.66,k));col=mix(base*.25,mix(hc,vec3(.6),dryM*.7),step(.004,h));}\n  float cover=max(m,gw*.55);\n  gl_FragColor=vec4(pow(max(col,vec3(0.)),vec3(2.2)),clamp(cover,0.,1.));\n  #include <colorspace_fragment>\n}";
+
+/** A splash on the ground or a wall (a wound, a body falling): the film draws it as a drop landing, in the colours of `tint` when given. */
+interface FilmSplat {
+    fluid: LiquidId;
+    point: Vec3;
+    /** The way the liquid travels (default straight down). */
+    direction?: Vec3;
+    /** Metres per second (default 2.5). */
+    speed?: number;
+    /** Drop radius in millimetres (default 3.2). */
+    radius?: number;
+    /** Drops thrown (default 1). */
+    count?: number;
+    surfaces?: FilmSurfaces;
+    tint?: StainTint;
+}
+interface FilmBridgeOptions {
+    fluids: FluidWorld;
+    manager: FilmManager;
+    /** The seeded stream that spreads the drops (the film never calls `Math.random`). */
+    random: () => number;
+    /** Which film profile a world liquid runs as: by default the liquids that have one (`blood`, `old_blood`, `bile`, `motor_oil`, `fuel`). Map `diesel` to `fuel`, say. */
+    liquids?: Readonly<Record<string, LiquidId>>;
+    /** Litres of one drop of a leak (default 0.00015). */
+    dropLiters?: number;
+    surfaceAt?: (point: Vec3) => FilmSurfaces | null;
+}
+interface FilmBridge {
+    /** Throws drops of a splash into the film. Returns how many found a grid. */
+    splat(splat: FilmSplat): number;
+    /** Weather of the film (the Phase 6 hook): while it rains the film does not dry and spreads 1.5 times faster. */
+    setWeather(weather: {
+        rain: number;
+    }): void;
+    /** Streams of the world that feed the film right now. */
+    readonly leaks: number;
+    /** Feeds the leaks: call it each frame with the frame's seconds, before or after `manager.update`. */
+    update(dt: number): void;
+    dispose(): void;
+}
+/**
+ * Joins a fluid world to the film: a `leak` of a liquid that has a film (blood, fuel, oil) drips onto the ground or wall below as drops thrown from the
+ * hole, at the rate the world gives, until the stream ends. `splat` is what the characters use for a wound (with the colours of the infection age as
+ * `tint`), and `setWeather` is the rain hook.
+ */
+declare function createFilmBridge(options: FilmBridgeOptions): FilmBridge;
+
+export { type BindOptions, type CellRect, FILM_FRAGMENT, FILM_VERTEX, type FilmBake, type FilmBridge, type FilmBridgeOptions, type FilmDripSpec, type FilmDrops, type FilmGpu, FilmGrid, type FilmGridOptions, type FilmLaunch, FilmManager, type FilmManagerOptions, type FilmMaterial, type FilmSplat, type FilmStats, type FilmSurfaces, type FilmViewer, type FluidQuality, type FluidRenderer, type FluidRendererOptions, type FluidRendererStats, LOOK_INDEX, type ThreeLib, createFilmBridge, createFilmDrops, createFilmManager, createFilmMaterial, createFluidRenderer, createStripGeometry, smoothOutline, tinted };