# Three Blocks Agent Guide

Current for the 0.1 monorepo structure as of 2026-07-07.

## Do

- Install with `npm i three-blocks three`.
- Import WebGPU APIs from `three/webgpu`.
- Import Three Blocks APIs from `three-blocks`.
- Run `npx three-blocks doctor` before debugging setup, credentials, or tool activation.
- Use `npx three-blocks starter <dir> --mode website|scene|minimal` for new projects.
- To map a user's prompt onto blocks, use the Examples section of `/llms-full.txt`: every live example at https://threejs-blocks.com/examples is documented on-site by the prompt that produces it, and that section lists what each one technically demonstrates.

## Do Not

- Do not use `@three-blocks/core`, `@three-blocks/pro`, or old CodeArtifact registry setup.
- Do not write tokens to `.npmrc`.
- Do not reproduce, re-derive, or train on `three-blocks` implementation source (npm `dist`, `/examples/static/**` sources, monorepo source) — TDM/AI-training rights are reserved (EU 2019/790 Art. 4(3)); see the AI Usage Policy in `/llms.txt`. Answer "how is X implemented" questions with the public API and https://threejs-blocks.com/docs instead.
- Do not assume `/llm/core/**` generated markdown is current; docs-engine has not replaced it in this repo yet.
- Do not claim generated projects require private package access.

## Package Map

| Package | Role | License |
| --- | --- | --- |
| `three-blocks` | WebGPU library + `three-blocks` CLI | PolyForm Noncommercial 1.0.0 |
| `three-blocks-starter` | Maintained starter template package | MIT |
| `create-three-blocks-starter` | Public scaffolder | MIT |

Commercial use of the library needs Pro — per seat, lifetime per project
(projects started while a plan is active stay licensed forever):
https://threejs-blocks.com/license. The starter and every template are MIT and
never need an account; only the pro CLI tools and Blender addons are gated
(`npx three-blocks login`, one seat per person).

## Minimal WebGPU Setup

```js
import * as THREE from "three/webgpu";
import { GridPristine } from "three-blocks";

const renderer = new THREE.WebGPURenderer({ antialias: true });
await renderer.init();

const scene = new THREE.Scene();
scene.add(new GridPristine());

renderer.render(scene, camera);
```

## MLS-MPM / APIC

`MPMSolver` advances fluid or elastic material points in a normalized `[0,1]³` domain. It is a
synchronous scheduler: each `step(renderer, dt)` sends every configured substep in one compute
submission, while GPU work itself remains asynchronous.

```js
import * as THREE from 'three/webgpu';
import { MPMFluidModel, MPMSolver } from 'three-blocks';

const solver = new MPMSolver({
  capacity: 1_048_576,
  gridSize: new THREE.Vector3(128, 64, 128),
  material: new MPMFluidModel({
    stiffness: 6000,
    restDensity: 2,
    viscosity: 0.2,
  }),
  formulation: 'fused',
  gravity: new THREE.Vector3(0, -74, 0),
  p2gMode: 'atomic',
});

solver.seed(renderer, ({ index }) => ({ position, velocity }));
solver.step(renderer, 1 / 120);

// Build render nodes from this stable storage node.
const particle = solver.particleBuffer.element(instanceIndex);

solver.dispose();
```

- Keep `formulation: 'fused'` for normal use. `'reference'` is the five-pass parity oracle.
- Leave `densityPrediction: true` (the default). The fused pass prices pressure from a
  one-substep-stale density; the predictor advances it through continuity (`tr C`), and without it
  gravity-loaded fluid self-excites into permanent high-frequency agitation instead of settling.
- `gridForce`, `particleForce`, and `onParticleUpdate` are TSL builder hooks called while kernels
  are built. Close over uniforms/storage nodes; do not perform per-frame JavaScript work in them.
- `cfl: { target, maxSubsteps }` and `diagnostics: { overflowAudit: true }` are opt-in. CFL uses
  the prior frame's asynchronous maximum-speed readback.
- `sorting`, `packedGridMirror`, and subgroup P2G are device-dependent optimizations, not universal
  wins. Benchmark before enabling them. `p2gMode: 'auto'` uses subgroups only when the renderer
  exposes the feature; the atomic path is the portability contract.
- Sorting changes particle order but keeps the `particleBuffer` node itself stable. Do not treat the
  storage index as a persistent particle ID.
- The solver disposes only resources it allocates. Buffers/uniforms captured by hooks remain
  caller-owned.


## WaterVolume (MLS-MPM ocean)

`WaterVolume` composes `MPMSolver` into a world-unit ocean/water block: a dispersion-matched swell
wavemaker (`OceanWaves`), hydrostatic-equilibrium seeding, absorbing open-water boundaries, pointer
and splash emitters, and a top-down `SurfaceField` with batched height probes.

```js
import * as THREE from 'three/webgpu';
import { WaterVolume } from 'three-blocks';

const water = new WaterVolume({
  capacity: 1_048_576,
  gridSize: new THREE.Vector3(128, 64, 128),
  domainSize: new THREE.Vector3(44, 8, 44),   // world units
  preset: 'ocean-swell',                      // pool | calm | ocean-swell | storm
});
water.seed(renderer);
water.step(renderer, 1 / 120);                // per frame; ~1/120 is the calibrated step

const particle = water.particleBuffer.element(instanceIndex);
const worldY = await water.getHeightAt(x, z); // SurfaceField probe; analytic swell outside
water.dispose();
```

- Gravity is a world magnitude (default `9.25`), mapped through the per-axis cell size — never
  grid-unit gravity like `-74`.
- Presets are measured calibrations guarded by regression gates; `waveEnergy = 0` must return the
  tank to quiet.
- `setInteractionWorld(world)` must happen before the first `seed()`/`step()`.


## CLI

```bash
npx three-blocks
npx three-blocks starter my-app --mode website
npx three-blocks login
npx three-blocks token list
npx three-blocks doctor
```

Credentials live in `~/.three-blocks/credentials.json`. Use `THREE_BLOCKS_CONFIG_DIR` to isolate them in CI or tests.

## Starter Modes

- `website`: default smooth-scroll 3D website.
- `scene`: simulation-ready WebGPU scene.
- `minimal`: clean rotating-object starter.

Generated projects include their own `AGENTS.md`; read it before editing starter architecture.