@adatechnology/game-fluids-three 0.0.0-stage → 0.1.0

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,106 @@
-# Temporary Holding Version
+# @adatechnology/game-fluids-three
 
-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.
+three.js renderer for [`@adatechnology/game-fluids`](../game-fluids). It only reads the simulation state, so it draws exactly what the
+deterministic world says (a LAN client with the same state draws the same liquids). `three` is a peer dependency used for types only: you pass your
+own `THREE` instance at runtime.
+
+What it draws:
+
+- **Liquid in containers**: inside every bound object, the container's inner shape clipped by the world-space liquid surface, so the top is always
+  on the surface plane whatever the tilt (upright, lying down, upside down). One material per liquid (colour, opacity, roughness from gloss).
+  Steam puffs rise from a hot surface.
+- **Streams**: a thread along the ballistic path (tube updated in place) that narrows as it accelerates, with a drop that grows at the leading tip
+  and a trailing drop when it ends; thin streams are a sequence of falling drops.
+- **Stains**: a smooth fan from the 16 flow-front radii (never a perfect disc), lying on the surface plane a hair above it
+  (`polygonOffset`, oriented by the stain's normal), tinted by the liquid with a soft rim, plus an inner glossy fan at `wetRadius` that reflects
+  the environment and recedes while it dries. A dried mark is a faint matte patch.
+- **Splashes**: pooled round droplets (`THREE.Points` with a small `ShaderMaterial`, the round sprite is drawn in the fragment shader, no textures).
+
+Lit with the standard material, no transmission, a handful of draw calls, fixed budgets per quality.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-fluids-three @adatechnology/game-fluids three
+```
+
+Browser without a bundler (the global is `GameFluidsThree`; it bundles the few `game-fluids` helpers it calls, you still load `GameFluids` to create the world):
+
+```html
+<script src="https://unpkg.com/three/build/three.min.js"></script>
+<script src="https://unpkg.com/@adatechnology/game-fluids/dist/index.global.js"></script>
+<script src="https://unpkg.com/@adatechnology/game-fluids-three/dist/index.global.js"></script>
+<script>
+  const fluids = GameFluids.createFluids({ seed: 1 })
+  const view = GameFluidsThree.createFluidRenderer(THREE, { scene, fluids })
+</script>
+```
+
+## Usage
+
+```ts
+import * as THREE from 'three'
+import { createFluids } from '@adatechnology/game-fluids'
+import { createFluidRenderer } from '@adatechnology/game-fluids-three'
+
+const fluids = createFluids({ seed: 7 })
+fluids.addSurface({ id: 'floor', point: [0, 0, 0], normal: [0, 1, 0], halfSize: [10, 10], porosity: 0.05 })
+fluids.addContainer(
+  { capacity: 0.25, liquid: 'coffee', liters: 0.25, temperature: 90, shape: { kind: 'cylinder', radius: 0.04, height: 0.1 }, opening: 0.04 },
+  { id: 'cup' },
+)
+
+const view = createFluidRenderer(THREE, { scene, fluids, quality: 'medium', envMap })
+view.bindContainer('cup', cupObject, { innerOffset: [0, 0.005, 0] }) // inner bottom centre in the object's space
+
+// every frame
+const p = cupObject.localToWorld(new THREE.Vector3(0, 0.005, 0)) // world position of the inner bottom centre
+fluids.setTransform('cup', [p.x, p.y, p.z], [q.x, q.y, q.z, q.w])
+fluids.update(dt)
+view.update(dt)
+```
+
+`innerOffset` is the offset, in the bound object's space, of the origin of the container shape (the inner bottom centre). The transform given to
+`fluids.setTransform` must be that point's world position and the object's world rotation. Objects are assumed to have uniform scale.
+
+Destroying a container's object (for example from `@adatechnology/game-destruction`): call `view.unbindContainer(id)` and
+`fluids.removeContainer(id)`; the stains already on the floor stay and dry on their own.
+
+## API
+
+`createFluidRenderer(THREE, options)` returns a `FluidRenderer`.
+
+| Option | |
+|---|---|
+| `scene` | Where the effects are added (one `fluid_renderer` group) |
+| `fluids` | The `FluidWorld` to draw |
+| `quality` | `'low'`, `'medium'` (default) or `'high'`: sets the mesh resolution and the budgets below |
+| `envMap` | Environment map the wet surfaces reflect (otherwise `scene.environment` if the host set one) |
+| `pointScale` | Pixel scale of the point sprites, about half the canvas height (default 600) |
+
+| Method | |
+|---|---|
+| `bindContainer(containerId, object3D, { innerOffset? })` | Draw the liquid of a world container inside the object |
+| `unbindContainer(containerId)` | Remove that liquid |
+| `update(dt)` | Advance the visuals; call it after `fluids.update(dt)` |
+| `clear()` | Remove stains, streams and particles (bindings stay) |
+| `dispose()` | Remove everything from the scene and free geometries and materials |
+| `stats()` | `{ quality, containers, streams, stains, particles, triangles, budget }` |
+
+Budgets: stains 24 / 48 / 96, streams 12 / 24 / 48 and particles 96 / 256 / 512 for low / medium / high. When the world has more stains than the
+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).
+
+## Português
+
+Renderizador three.js do `@adatechnology/game-fluids`: o líquido dentro do recipiente (um volume cortado pelo plano da superfície, sempre
+horizontal no mundo), fios de líquido com gota na ponta, manchas que crescem a partir de uma frente de fluxo (nunca um disco perfeito), brilho de
+superfície molhada que reflete o cenário e seca da borda para dentro, vapor e gotas de respingo. Só lê o estado da simulação, então é igual em LAN.
+
+```ts
+const view = createFluidRenderer(THREE, { scene, fluids, quality: 'medium', envMap })
+view.bindContainer('copo', objetoDoCopo, { innerOffset: [0, 0.005, 0] })
+// a cada frame: fluids.setTransform(...); fluids.update(dt); view.update(dt)
+```

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import * as THREE_NS from 'three';
+import { Vec3, FluidWorld } 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'>;
+/** Detail level. It sets the budgets (stains, streams, particles) and the mesh resolution. */
+type FluidQuality = 'low' | 'medium' | 'high';
+interface FluidRendererOptions {
+    /** Where the effects live (stains, streams, particles are added under one group). */
+    scene: THREE_NS.Object3D;
+    /** The simulation to draw. The renderer only reads its state and listens to `splash` events: it never changes the world. */
+    fluids: FluidWorld;
+    /** Default `medium`. */
+    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. */
+    pointScale?: number;
+}
+interface BindOptions {
+    /**
+     * Offset, in the bound object's space, of the container's inner bottom centre (the origin of the shape given to `addContainer`).
+     * The world transform you give `fluids.setTransform` must be that point's world position and the object's rotation. Default `[0, 0, 0]`.
+     */
+    innerOffset?: Vec3;
+}
+/** Counts of what is alive right now, plus the budgets of the chosen quality. */
+interface FluidRendererStats {
+    quality: FluidQuality;
+    /** Bound containers with a visible liquid volume. */
+    containers: number;
+    /** Streams drawn, including the ones that are breaking into drops after the world ended them. */
+    streams: number;
+    /** Stain meshes in use (a stain uses an outer film and an inner glossy wet fan). */
+    stains: number;
+    /** Droplet and steam particles alive. */
+    particles: number;
+    /** Triangles currently drawn by the fluids. */
+    triangles: number;
+    budget: {
+        stains: number;
+        streams: number;
+        particles: number;
+    };
+}
+interface FluidRenderer {
+    /** Draw the liquid of a world container inside `object` (a volume clipped by the liquid surface, plus steam). */
+    bindContainer(containerId: string, object: THREE_NS.Object3D, options?: BindOptions): void;
+    unbindContainer(containerId: string): void;
+    /** Advance the visuals (call it after `fluids.update(dt)`). */
+    update(dt: number): void;
+    /** Remove every stain, stream and particle (the bindings stay). */
+    clear(): void;
+    /** Remove everything from the scene and release geometries and materials. */
+    dispose(): void;
+    stats(): FluidRendererStats;
+}
+
+/**
+ * Draws a `FluidWorld` with three.js. It only reads the world state (plus `splash` events for droplets), so a LAN client that receives the
+ * same world state draws the same liquids.
+ */
+declare function createFluidRenderer(THREE: ThreeLib, options: FluidRendererOptions): FluidRenderer;
+
+/** 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 };