# Fluid Sandbox Skill

Use this note when building Easymap water-flow, terrain, erosion, or 3D sandbox demos from this folder.

Reference files:

- `example/fluid-sandbox.zip`: original offline demo package.
- `example/fluid-sandbox_Fable.zip`: same source package as `fluid-sandbox.zip` by checksum; keep as an alternate source marker.
- `fluid-sandbox-prompt.md`: complete behavior and performance specification.
- `three.min.js`: local Three.js runtime extracted from the original package.
- `api.php?doc=history` and `api.php?doc=skill`: whitelisted markdown readers for protected `.md` files.

## Workflow

1. Keep the first demo small and visual: load a terrain grid, render voxels or mesh, expose only speed, inflow, erosion, brush size, and reset.
2. Treat this sandbox as a concept model. Do not claim hydrology accuracy unless a real solver and calibration data are added.
3. For Easymap integration, export simulation results as WKT or GeoJSON first; add to the map through public APIs such as `new dgWKT(...)`, `new dgGeoJson(...)`, and `map.addItem(...)`.
4. For 3D Easymap work, call `map.enable3D(function () { ... })` before terrain, glTF, 3D Tiles, or camera operations.
5. Keep generated layers removable. Store references and clean them with `map.removeItem(...)`.
6. For showcase terrain, prefer a random height field with several broad peaks plus one carved valley; keep dimensions large enough to see mountain form, but below browser memory pain.

## Source Lessons

- Use local Three.js for demo reliability.
- Render visible surface voxels only; drawing all internal cells makes terrain dark and slow.
- Use material color palettes with small brightness variation instead of flat colors.
- Keep simulation state in typed arrays and Three.js only as the render adapter.
- For larger worlds, copy the original package's chunk sleep and moved-stamp ideas before raising dimensions aggressively.

## Data Shape

- Grid cell: `{ x, y, z, material }`.
- Terrain input: DEM height map or sampled raster.
- 2D output: flow line, erosion polygon, deposition polygon.
- 3D output: height delta mesh, voxel preview, glTF, or 3D Tiles.

## Materials

- Rock and concrete are stable.
- Soil erodes quickly.
- Sand erodes slowly and deposits downstream.
- Water flows from source to drain.
- Wood is optional visual debris, not required for Easymap output.

## Upgrade Point

Replace the toy cellular automata when the demo needs measured flow, real rainfall, watershed analysis, or calibrated sediment transport.