@adatechnology/game-fluids 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @adatechnology/game-fluids
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Engine-agnostic liquids for games, with no renderer. It knows nothing about any game: the host moves the containers, gives it surfaces and calls
+`update(dt)`; the package answers with events and plain state that any renderer (see `@adatechnology/game-fluids-three`) can draw.
+
+- **Containers** (cup, bottle, jerrycan, tank) with a level computed from their shape and tilt, a temperature (cools towards ambient, steams when
+  hot), an opening and an optional lid. Fill, pour, drink, spill over the lip when tilted, leak through holes.
+- **Streams**: the jet leaving a lip or a hole. Ballistic, it ends on the first surface it hits (planes with half extents) or on the ground.
+- **Stains**: grow from a flow front (16 radial samples, never a perfect disc), run downhill, soak into porous surfaces, dry from the edge in and
+  either vanish or leave a permanent mark (coffee, blood, oil).
+- **19 built-in liquids** (`LIQUIDS`): water, coffee, tea, milk, soda, juice, beer, wine, spirits, fuel, diesel, motor_oil, cooking_oil, blood,
+  sap, acid, paint, bleach, honey. Each one has its own colour, viscosity, drying time, gloss and drink effects (`caffeine`, `alcohol`, `poison`,
+  `disgust`).
+- **Item uses** (`ITEM_USES`): scripted `sip`, `drink`, `chug`, `pour`, `pour_out`, `open` and `close`, as pure keyframe data plus a player.
+- Deterministic from a seed (no `Math.random`), so a LAN host can run it and send events. `serialize()` / `load()` round trip the whole world.
+- Units: metres, litres, seconds, degrees Celsius. Locale table `en` / `pt-BR` for liquid names and event labels.
+
+Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-fluids
+```
+
+Browser without a bundler (the global is `GameFluids`):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-fluids/dist/index.global.js"></script>
+<script>
+  const world = GameFluids.createFluids({ seed: 1 })
+</script>
+```
+
+## Usage
+
+```ts
+import { createFluids, createItemUse, ITEM_USES } from '@adatechnology/game-fluids'
+
+const fluids = createFluids({ seed: 42, locale: 'en', onEvent: (e) => console.log(fluids.describe(e)) })
+
+fluids.addSurface({ id: 'floor', point: [0, 0, 0], normal: [0, 1, 0], halfSize: [10, 10], porosity: 0.05 })
+fluids.addSurface({ id: 'rug', point: [2, 0.01, 0], normal: [0, 1, 0], halfSize: [1, 1], porosity: 0.9 })
+
+const cup = fluids.addContainer(
+  {
+    capacity: 0.25,
+    liquid: 'coffee',
+    liters: 0.25,
+    temperature: 90,
+    shape: { kind: 'cylinder', radius: 0.04, height: 0.1 }, // inner shape, origin at the inner bottom centre, +Y up
+    opening: 0.04,
+  },
+  { id: 'cup', position: [0, 0.8, 0] },
+)
+
+// every frame: keep the container in sync with the object that carries it, then step
+fluids.setTransform(cup, object.position, object.quaternion, velocity)
+for (const event of fluids.update(dt)) {
+  if (event.type === 'drink' && event.effects.includes('caffeine')) player.energy += event.thirst * 0.1
+}
+```
+
+Events from direct calls (`drink`, `fill`, `puncture`, `splash`...) are delivered once: to the listeners at once and, for `drink`, as its return value; `update` never repeats them. `update` returns the events it produced, in order, and also fires `onEvent` and the listeners registered with
+`fluids.on(type | '*', fn)`. Use `fluids.describe(event)` for a localised one-liner, handy for a debug panel or a log.
+
+Draw from the state, never from the events: `container(id)`, `containers()`, `streams()` and `stains()` return plain copies.
+
+### Spilling, pouring and holes
+
+Tilt the container (`setTransform` with a rotated quaternion): the liquid surface keeps its volume and stays horizontal; when it rises above the
+lowest point of the lip, liquid spills over it with a rate proportional to the excess and the opening (Torricelli, divided by the square root of the
+viscosity), creating a `spill` stream. A closed container never spills or pours. `fluids.pour(id, dt, into?)` forces flow out of the opening for
+`dt` seconds (optionally into another container). `puncture(id, point, normal, diameter)` makes a hole: it leaks (one `leak` stream per hole) while
+the liquid is above it and stops once the level falls below.
+
+### Taps
+
+A tap is a fixed source (a sink, a pipe, a hose end):
+
+```ts
+const sink = fluids.addTap({ position: [0, 1.0, -2], liquid: 'water', rate: 0.1 }) // direction [0, -1, 0], on by default
+fluids.setTap(sink, false) // off; fluids.setTap(sink, true, 0.2) turns it on at 0.2 l/s
+fluids.removeTap(sink)
+```
+
+While on it is a `tap` stream (`streams()` lists it with `tap: <id>`): it fills any container whose opening it lands in (the same logic as pouring
+into a cup) and otherwise makes a stain where it lands. Switching emits `{ type: 'tap', tap, on }`. `taps()` returns the state of every tap, and
+taps are part of `serialize` / `load`.
+
+### Using it with `@adatechnology/game-destruction`
+
+The damage model reports `leak` events for parts that hold a fluid. Map them one to one onto `puncture`; the container then loses liquid by
+Torricelli and the stream and stains follow:
+
+```ts
+import type { DamageEvent } from '@adatechnology/game-destruction'
+
+destruction.on('leak', (e) => {
+  // e.part is the damaged part, e.point the world hit point of the hole, e.direction where the fluid leaves
+  const id = containerOfPart(e.part)
+  if (!id) return
+  const local = worldToContainer(id, e.point) // container space: origin at the inner bottom centre
+  const normal = worldDirToContainer(id, e.direction)
+  fluids.puncture(id, local, normal, 0.009) // hole diameter in metres (e.g. a 9 mm bullet)
+})
+```
+
+Keep `fluids.setTransform` in sync with the destructible object so the hole follows it. A fuel tank punctured near the bottom leaks until the level
+falls under the hole; the fuel stain (`flammable` liquid) can be handed to the fire system by the host.
+
+### Item uses
+
+```ts
+const use = createItemUse(fluids, 'cup', ITEM_USES.find((u) => u.id === 'sip')!, () => ({ position: handPos, rotation: handQuat }))
+// every frame
+for (const event of use.update(dt)) log(fluids.describe(event))
+viewmodel.position.set(...use.pose().position) // hand-relative pose, Euler XYZ for the rotation
+if (use.done) /* ... */
+```
+
+| id | duration | what it does |
+|---|---|---|
+| `sip` | 1.2 s | raise to the mouth, small tilt, drinks 0.03 l |
+| `drink` | 2.5 s | raise, tilt about 70 degrees, drinks about 0.2 l, back down |
+| `chug` | 4 s | long tilt, drinks until empty or 0.5 l |
+| `pour` | 3 s | tilt 100 degrees outward, `pour` action |
+| `pour_out` | 4 s | empties the container on the floor |
+| `open` / `close` | 1 s | removes / puts the lid |
+
+While the current key has `action: 'drink'` the player calls `world.drink(rate × dt)` (litres per second in `rate`); with `'pour'` it calls
+`world.pour(dt × rate)`; `'open'` and `'close'` fire once when their key is reached. If a `getHandTransform` callback is given, the container follows
+hand ∘ pose; otherwise the host animates its own viewmodel from `pose()`. `def.liquids` restricts the use to some liquids. Write your own
+`ItemUseDef` to add `eat`, `wipe` and so on.
+
+## API
+
+| Export | What it is |
+|---|---|
+| `createFluids(options?)` | Creates a `FluidWorld`. Options: `liquids`, `locale`, `seed`, `ambientC`, `gravity`, `groundAt(x, z)`, `mergeDistance`, `maxStains`, `onEvent` |
+| `LIQUIDS` | The 19 built-in `LiquidDef`s (`id`, `color`, `opacity`, `stainColor`, `viscosity`, `density`, `dryTime`, `leavesMark`, `gloss`, `drink`...) |
+| `ITEM_USES` | The built-in `ItemUseDef`s |
+| `createItemUse(world, containerId, def, getHandTransform?)` | Returns an `ItemUsePlayer` (`pose()`, `update(dt)`, `cancel()`, `time`, `done`) |
+| `sampleStream(stream, gravity, t)` | Point of a stream's path at time `t` (0 to `flightTime`) |
+| `stainDirection(stain, i)`, `STAIN_SAMPLES` | World direction of the front sample `i` of a stain (16 samples) |
+| `describeEvent(strings, event)`, `resolveStrings(locale)`, `locales` | Localised event text and liquid names |
+
+`FluidWorld` methods: `addContainer`, `removeContainer`, `setTransform`, `open`, `close`, `fill`, `pour`, `drink`, `puncture`, `heat`, `addSurface`,
+`removeSurface`, `addTap`, `setTap`, `removeTap`, `taps`, `splash`, `clearStains`, `update`, `container`, `containers`, `streams`, `stains`, `on`, `describe`, `serialize`, `load`, plus
+`liquids` and `gravity`.
+
+Events (`FluidEvent.type`): `fill`, `pour`, `spill`, `leak`, `drink`, `empty`, `stream_end`, `splash`, `stain`, `dried`, `steam`, `mix`, `tap`.
+
+Notes: liquid ids and event types are snake_case data ids and part of the public contract. Colours in `liquids.json` are `0xRRGGBB` stored as
+integers; density is in kg/m³ and viscosity is relative to water. The surface id `ground` is reserved for the implicit ground (`groundAt`).
+
+## Português
+
+Líquidos sem renderizador, para qualquer engine: copos, garrafas, galões e tanques com nível calculado pelo formato e pela inclinação,
+temperatura (esfria e solta vapor), beber, despejar, derramar ao inclinar e vazar por furos (ligue os eventos `leak` do
+`@adatechnology/game-destruction` em `fluids.puncture`). O líquido que cai vira mancha: cresce a partir de uma frente de fluxo (nunca um disco
+perfeito), escorre ladeira abaixo, é absorvido por superfícies porosas e seca de fora para dentro, deixando marca permanente (café, sangue, óleo)
+ou sumindo (água). Determinístico por semente, pronto para LAN.
+
+```ts
+const fluids = createFluids({ seed: 1, locale: 'pt-BR' })
+const use = createItemUse(fluids, 'copo', ITEM_USES.find((u) => u.id === 'drink')!)
+for (const e of use.update(dt)) console.log(fluids.describe(e)) // "bebeu: copo café 0.01 l [caffeine]"
+```
+
+Com `locale: 'pt-BR'`, `describe` usa os nomes em português ("água", "café", "chá", "leite", "refrigerante", "suco", "cerveja", "vinho",
+"destilado", "gasolina", "diesel", "óleo de motor", "óleo de cozinha", "sangue", "seiva", "ácido", "tinta", "água sanitária", "mel") e os rótulos
+dos eventos ("bebeu", "derramou", "vazando", "encheu", "esvaziou", "mancha", "secou"...). Os usos de item prontos são `sip`, `drink`, `chug`,
+`pour`, `pour_out`, `open` e `close`.
+
+Torneiras: `fluids.addTap({ position, liquid: 'water', rate: 0.1 })` cria uma fonte fixa (pia, cano); `setTap(id, on, rate?)` liga e desliga e
+`removeTap(id)` remove. Ligada, é um fluxo `tap` que enche o recipiente em que cai ou deixa uma mancha, e emite o evento `tap`.

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { LiquidId, Vec3, ContainerSpec, Quat, ItemUseDef } from '@adatechnology/game-contracts';
+export { ContainerSpec, ItemUseDef, LiquidId, Quat, Vec3 } from '@adatechnology/game-contracts';
+
+/**
+ * Public types of @adatechnology/game-fluids.
+ *
+ * Renderer-free liquids. Three things:
+ * - Containers: a cup, a bottle, a jerrycan, a fuel tank, a water tank. They hold one liquid with a level and a temperature, know their opening
+ *   and their tilt, and can be filled, poured, drunk from, spilled (tilted past the lip) or leak through holes (from a damage model).
+ * - Streams: liquid leaving a container or a hole. Each stream is a falling jet that ends on a surface.
+ * - Stains: what a stream or a spill leaves on a surface. A stain grows from a flow front (never a perfect disc), soaks into porous surfaces,
+ *   and dries from the edge in. Each liquid is its own material (water, coffee, fuel, oil, blood...).
+ *
+ * Units: metres, litres, seconds, °C. Deterministic from the seed (a LAN host can run it and send events).
+ */
+
+interface LiquidDef {
+    id: LiquidId;
+    /** Colour `0xRRGGBB` and opacity 0..1 of the body of liquid. */
+    color: number;
+    opacity: number;
+    /** Colour of a wet/dried stain (default darker `color`). */
+    stainColor?: number;
+    /** Viscosity relative to water (water 1, oil 60, honey 3000). Slows streams and stain spread, thickens drops. */
+    viscosity: number;
+    density: number;
+    /** Seconds a thin stain takes to dry at 20 °C (water 600, fuel 120, oil never = 0). */
+    dryTime: number;
+    /** Leaves a permanent mark after drying (coffee, blood, oil, paint). */
+    leavesMark?: boolean;
+    flammable?: boolean;
+    /** Gloss of a wet surface 0..1 (water 0.9, oil 1, milk 0.5). */
+    gloss: number;
+    /** Steams when hotter than this (default 60 for drinks). */
+    steamC?: number;
+    /** Drinkable: thirst points per litre (positive) and any effect key the host maps (e.g. `caffeine`, `alcohol`, `poison`). */
+    drink?: {
+        thirst: number;
+        effects?: string[];
+    };
+    tags?: string[];
+}
+interface ContainerState {
+    id: string;
+    liquid: LiquidId | null;
+    liters: number;
+    capacity: number;
+    temperature: number;
+    closed: boolean;
+    /** Height of the liquid surface above the inner bottom along world up, metres (with tilt). */
+    surfaceHeight: number;
+    /** Liquid surface plane in world space (for the renderer): a point and the normal (always world up while still; sloshes when moved). */
+    surfacePoint: Vec3;
+    surfaceNormal: Vec3;
+    /** Holes from damage, in local space. */
+    holes: Array<{
+        point: Vec3;
+        normal: Vec3;
+        diameter: number;
+    }>;
+    /** Flowing out now (litres per second) through the opening (pour/spill) and holes. */
+    outflow: number;
+    steaming: boolean;
+    /** Inner shape and effective lip radius (metres), so a renderer can draw the liquid body without knowing the spec. */
+    shape?: ContainerSpec['shape'];
+    lipRadius?: number;
+    /** World transform the container was last given with `setTransform`. */
+    position?: Vec3;
+    rotation?: Quat;
+}
+type StreamCause = 'pour' | 'spill' | 'leak' | 'tap';
+/** A fixed water source (a tap, a pipe, a hose end) that runs a stream while it is on. See `FluidWorld.addTap`. */
+interface TapSpec {
+    /** Id (default `tap_<n>`). Adding a tap with an id that already exists replaces it. */
+    id?: string;
+    /** World position of the nozzle. */
+    position: Vec3;
+    /** Direction the liquid leaves in (normalised; default straight down `[0, -1, 0]`). */
+    direction?: Vec3;
+    liquid: LiquidId;
+    /** Litres per second while on (a kitchen tap is about 0.1). */
+    rate: number;
+    /** Temperature of the liquid in °C (default the ambient temperature). */
+    temperature?: number;
+    /** Starts running (default `true`). */
+    on?: boolean;
+}
+interface TapState {
+    id: string;
+    position: Vec3;
+    direction: Vec3;
+    liquid: LiquidId;
+    rate: number;
+    temperature: number;
+    on: boolean;
+    /** Id of the `tap` stream while it runs. */
+    stream?: string;
+}
+interface StreamState {
+    id: string;
+    liquid: LiquidId;
+    cause: StreamCause;
+    container?: string;
+    /** The tap that feeds it (`cause: 'tap'`). */
+    tap?: string;
+    /** World start point and initial velocity. */
+    origin: Vec3;
+    velocity: Vec3;
+    /** Litres per second. */
+    rate: number;
+    /** Where it lands (null while still in the air or nothing below). */
+    landing: Vec3 | null;
+    /** Thin trickle (drops) or a jet. */
+    thin: boolean;
+    /** Seconds the jet flies before it lands (capped when it lands nowhere). Sample the path with `sampleStream`. */
+    flightTime?: number;
+}
+interface SurfaceSpec {
+    id: string;
+    /** Horizontal rectangle (floors, tables) or any plane: a point, a normal and its half extents along two axes. */
+    point: Vec3;
+    normal: Vec3;
+    /** Half extents along `tangent` and normal × tangent. */
+    halfSize: [number, number];
+    tangent?: Vec3;
+    /** 0 = sealed (tile, glass, metal), 1 = soaks fast (fabric, soil, wood). Soaking shrinks the stain area and darkens it. */
+    porosity: number;
+}
+interface StainState {
+    id: string;
+    surface: string;
+    liquid: LiquidId;
+    /** Centre in world space and the flow front: radii per direction (16 samples around the centre) so the outline is irregular. */
+    center: Vec3;
+    front: number[];
+    /** Litres on the surface (pooled) and soaked. */
+    liters: number;
+    soaked: number;
+    /** 0..1: 1 = wet, 0 = dry; a dried `leavesMark` stain stays as a mark. */
+    wetness: number;
+    /** The wet area recedes from the edge in: radius fraction still wet. */
+    wetRadius: number;
+    /** Surface normal and tangent of the plane the stain lies on; `front[i]` points along `cos(2πi/16)·tangent + sin(2πi/16)·(normal × tangent)`. */
+    normal?: Vec3;
+    tangent?: Vec3;
+    /** Unit direction (in the surface plane) the liquid arrived from moving towards, when it landed with horizontal speed (the impact shows where it came from). */
+    flow?: Vec3;
+    /** True once the wet part dried and only the permanent mark of a `leavesMark` liquid remains. */
+    mark?: boolean;
+    /** Seconds since the stain was created. */
+    age?: number;
+}
+type FluidEvent = {
+    type: 'fill';
+    container: string;
+    liquid: LiquidId;
+    liters: number;
+} | {
+    type: 'pour';
+    container: string;
+    liquid: LiquidId;
+    rate: number;
+    stream: string;
+} | {
+    type: 'spill';
+    container: string;
+    liquid: LiquidId;
+    rate: number;
+    stream: string;
+} | {
+    type: 'leak';
+    container: string;
+    liquid: LiquidId;
+    rate: number;
+    stream: string;
+    point: Vec3;
+} | {
+    type: 'drink';
+    container: string;
+    liquid: LiquidId;
+    liters: number;
+    temperature: number;
+    thirst: number;
+    effects: string[];
+    burn: boolean;
+} | {
+    type: 'empty';
+    container: string;
+} | {
+    type: 'stream_end';
+    stream: string;
+} | {
+    type: 'splash';
+    liquid: LiquidId;
+    point: Vec3;
+    intensity: number;
+} | {
+    type: 'stain';
+    stain: string;
+    surface: string;
+    liquid: LiquidId;
+    point: Vec3;
+} | {
+    type: 'dried';
+    stain: string;
+    mark: boolean;
+} | {
+    type: 'steam';
+    container: string;
+    on: boolean;
+} | {
+    type: 'mix';
+    container: string;
+    from: LiquidId;
+    into: LiquidId;
+}
+/** A tap was switched on or off (`setTap`, `addTap` with `on`). */
+ | {
+    type: 'tap';
+    tap: string;
+    on: boolean;
+};
+interface FluidOptions {
+    /** Extra or replacing liquid definitions (matched by `id`) on top of the built-in `LIQUIDS`. */
+    liquids?: LiquidDef[];
+    /** Locale of the strings returned by `describe` (`en` default, `pt-BR`; unknown locales fall back to `en`). */
+    locale?: string;
+    seed?: number;
+    ambientC?: number;
+    gravity?: number;
+    /** Ground height for streams that hit no surface (default 0). */
+    groundAt?: (x: number, z: number) => number;
+    /** Merge stains closer than this (default 0.15 m). Upper bound of live stains (default 64; oldest dry ones go first). */
+    mergeDistance?: number;
+    maxStains?: number;
+    onEvent?: (event: FluidEvent) => void;
+}
+interface FluidWorld {
+    readonly liquids: ReadonlyMap<LiquidId, LiquidDef>;
+    /** Gravity in m/s² used by streams (so a renderer can sample the same path). */
+    readonly gravity: number;
+    /** Human readable one-liner of an event in the configured locale, for logs and debug panels. */
+    describe(event: FluidEvent): string;
+    addContainer(spec: ContainerSpec, options?: {
+        id?: string;
+        position?: Vec3;
+        rotation?: Quat;
+    }): string;
+    removeContainer(id: string): void;
+    /** Keep in sync with the object that carries it (tilt decides spilling and the surface plane; velocity makes it slosh). */
+    setTransform(id: string, position: Vec3, rotation: Quat, velocity?: Vec3): void;
+    open(id: string): void;
+    close(id: string): void;
+    /** Add liquid (from a tap, another container); mixing different liquids keeps the bigger one and emits `mix`. Returns litres accepted. */
+    fill(id: string, liquid: LiquidId, liters: number, temperature?: number): number;
+    /** Pour on purpose for `dt` seconds (tilts the flow out of the opening even when not tilted far). Returns litres out. */
+    pour(id: string, dt: number, into?: string): number;
+    /** Drink `liters` (sip ~0.03 l); returns the drink event or null when empty/closed. Too hot (> 65 °C) sets `burn`. */
+    drink(id: string, liters: number): Extract<FluidEvent, {
+        type: 'drink';
+    }> | null;
+    /** Punch a hole (local space) — call it from a damage model's `hole`/`leak` events. */
+    puncture(id: string, point: Vec3, normal: Vec3, diameter: number): void;
+    /** Heat or cool the content (a stove under a kettle, a fire). */
+    heat(id: string, deltaC: number): void;
+    addSurface(spec: SurfaceSpec): void;
+    removeSurface(id: string): void;
+    /**
+     * Add a tap: while `on` it runs a `tap` stream (cause `'tap'`) from `position` along `direction` at `rate` litres per second. The stream fills any
+     * container whose opening it lands in (the same logic as a pour) and otherwise makes a stain on the surface below. Returns the tap id.
+     * Switching on or off emits a `tap` event.
+     */
+    addTap(spec: TapSpec): string;
+    /** Switch a tap on or off, optionally changing its `rate`. Unknown ids are ignored. */
+    setTap(id: string, on: boolean, rate?: number): void;
+    /** Remove a tap (and end its stream). */
+    removeTap(id: string): void;
+    taps(): TapState[];
+    /** Pour liquid straight onto a point (a broken bottle, a blood splash). */
+    splash(liquid: LiquidId, point: Vec3, liters: number, velocity?: Vec3): void;
+    /** Wipe or burn stains in a radius (fire dries water and burns fuel stains). */
+    clearStains(point: Vec3, radius: number): void;
+    update(dt: number): FluidEvent[];
+    container(id: string): ContainerState | null;
+    containers(): ContainerState[];
+    streams(): StreamState[];
+    stains(): StainState[];
+    on(type: FluidEvent['type'] | '*', fn: (event: FluidEvent) => void): () => void;
+    serialize(): unknown;
+    load(snapshot: unknown): void;
+}
+interface ItemUsePlayer {
+    readonly def: ItemUseDef;
+    readonly time: number;
+    readonly done: boolean;
+    /** Current hand-relative pose (interpolated). */
+    pose(): {
+        position: Vec3;
+        rotation: Vec3;
+    };
+    /** Advance; applies the container actions to the fluid world and returns the events it produced. */
+    update(dt: number): FluidEvent[];
+    cancel(): void;
+}
+
+declare function createFluids(options?: FluidOptions): FluidWorld;
+
+/**
+ * Built-in liquids (data in `data/liquids.json`; colours are `0xRRGGBB` stored as integers).
+ * Viscosity is relative to water, density in kg/m³, `dryTime` in seconds for a thin film at 20 °C (0 = never dries).
+ */
+declare const LIQUIDS: LiquidDef[];
+
+/** Built-in scripted uses of a held item (data in `data/item-uses.json`): `sip`, `drink`, `chug`, `pour`, `pour_out`, `open`, `close`. */
+declare const ITEM_USES: ItemUseDef[];
+/** World transform of the hand (or any holder) the item pose is relative to. */
+type HandTransform = () => {
+    position: Vec3;
+    rotation: Quat;
+};
+/**
+ * Plays an item use on a container: interpolates the keys, applies `drink` (rate × dt litres) and `pour` (`world.pour`, `rate` multiplies the
+ * time) while the current key has that action, and fires `open` / `close` once when their key is reached. When `getHandTransform` is given, the
+ * container's world transform follows hand ∘ pose every update; otherwise the host animates the viewmodel from `pose()`.
+ */
+declare function createItemUse(world: FluidWorld, containerId: string, def: ItemUseDef, getHandTransform?: HandTransform): ItemUsePlayer;
+
+/** Locales shipped with the package. Unknown locales fall back to `en`. */
+type FluidLocale = 'en' | 'pt-BR';
+interface FluidStrings {
+    /** Display name per liquid id (unknown ids fall back to the id itself). */
+    liquids: Record<LiquidId, string>;
+    /** Short label per event type. */
+    events: Record<FluidEvent['type'], string>;
+    on: string;
+    off: string;
+}
+declare const locales: Record<FluidLocale, FluidStrings>;
+declare const resolveStrings: (locale: string | undefined) => FluidStrings;
+/** One-line description of an event for logs and debug panels, e.g. `drank: coffee 0.03 l`. */
+declare const describeEvent: (strings: FluidStrings, event: FluidEvent) => string;
+
+/** Number of radial samples of the flow front. */
+declare const SAMPLES = 16;
+/** Unit direction (world space) of front sample `i` of a stain, from its `normal` and `tangent`. */
+declare const stainDirection: (s: Pick<StainState, "normal" | "tangent">, i: number) => Vec3;
+
+/** Position of a ballistic jet `t` seconds after leaving its origin. */
+declare const ballistic: (origin: Vec3, velocity: Vec3, gravity: number, t: number) => Vec3;
+/** Point of a stream's path `t` seconds after its origin (use with `StreamState.flightTime` and the world's `gravity`). */
+declare const sampleStream: (stream: Pick<StreamState, "origin" | "velocity">, gravity: number, t: number) => Vec3;
+
+export { type ContainerState, type FluidEvent, type FluidLocale, type FluidOptions, type FluidStrings, type FluidWorld, type HandTransform, ITEM_USES, type ItemUsePlayer, LIQUIDS, type LiquidDef, SAMPLES as STAIN_SAMPLES, type StainState, type StreamCause, type StreamState, type SurfaceSpec, type TapSpec, type TapState, ballistic, createFluids, createItemUse, describeEvent, locales, resolveStrings, sampleStream, stainDirection };