### Install dependencies and start dev server

Source: https://github.com/zyfou/proceduralterrains/blob/main/README.md

Run these commands in the project root to install dependencies and start the Vite development server. The server listens on all interfaces and prints a LAN URL; if port 6061 is busy, it selects the next available port.

```sh
npm install
npm run dev
```

--------------------------------

### Install and launch API with PM2

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Commands to install dependencies, configure .env, run migrations, and start the API with PM2. The PM2 configuration runs one process; use a shared Redis-backed limiter before enabling multiple instances.

```sh
cd /srv/procedural-terrains/api
cp .env.example .env
nano .env

npm ci --omit=dev
npm run migrate

sudo npm install --global pm2
pm2 start ecosystem.config.cjs --env production
pm2 save
pm2 startup systemd
```

--------------------------------

### Install from local archive

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/getting-started.md

Install the built archive from the repository instead of npm. The archive is written to dist/npm/ after building.

```sh
npm install /path/to/procedural-terrains-0.1.0-alpha.0.tgz three@~0.185.1
```

--------------------------------

### Install procedural-terrains from npm

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/getting-started.md

Install the alpha package from npm. Three.js ~0.185.1 is a peer dependency and is installed automatically when needed.

```sh
npm install procedural-terrains
```

--------------------------------

### Run locally: copy env, install, migrate, dev

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Commands to set up and run the API locally. Requires Node.js 22+, MySQL 8+/MariaDB 10.6+, and PM2 installed globally. The API listens on http://localhost:6062.

```sh
cp .env.example .env
npm install
npm run migrate
npm run dev
```

--------------------------------

### GET /api/v1/admin/overview

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Provides an overview of admin metrics. Accepts a `days` query parameter for range.

```APIDOC
## GET /api/v1/admin/overview

### Description
Provides an overview of admin metrics. Accepts a `days` query parameter for range.

### Method
GET

### Endpoint
/api/v1/admin/overview

### Parameters
#### Query Parameters
- **days** (string) - Optional - Range: `7`, `30`, or `90` (default: `7`)

```

--------------------------------

### GET /api/v1/admin/security

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves security-related information for admin purposes.

```APIDOC
## GET /api/v1/admin/security

### Description
Retrieves security-related information for admin purposes.

### Method
GET

### Endpoint
/api/v1/admin/security

```

--------------------------------

### GET /api/v1/auth/session

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves the current session information.

```APIDOC
## GET /api/v1/auth/session

### Description
Retrieves the current session information.

### Method
GET

### Endpoint
/api/v1/auth/session

```

--------------------------------

### Create database and user for Linux deployment

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

SQL to create the procedural_terrains database and a dedicated user with privileges. Run from the MySQL console before installing the API.

```sql
CREATE DATABASE procedural_terrains
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_0900_ai_ci;

CREATE USER 'terrain'@'127.0.0.1' IDENTIFIED BY 'replace-with-a-long-password';
GRANT ALL PRIVILEGES ON procedural_terrains.* TO 'terrain'@'127.0.0.1';
FLUSH PRIVILEGES;
```

--------------------------------

### Set up optional accounts API

Source: https://github.com/zyfou/proceduralterrains/blob/main/README.md

Copy environment files, install API dependencies, and run both the main dev server and the API dev server. The API is an independent, self-hostable Node.js/MySQL service.

```sh
cp .env.example .env
cp api/.env.example api/.env
npm --prefix api install
npm run dev
npm run dev:api
```

--------------------------------

### POST /api/v1/auth/register

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Registers a new user with email, username, and password.

```APIDOC
## POST /api/v1/auth/register

### Description
Registers a new user with email, username, and password.

### Method
POST

### Endpoint
/api/v1/auth/register

### Request Body
- **email** (string) - Required - User's email address
- **username** (string) - Required - Desired username
- **password** (string) - Required - Password (at least 10 characters)

### Request Example
```json
{ "email": "you@example.com", "username": "terrain_creator", "password": "at least 10 characters" }
```

```

--------------------------------

### GET /api/v1/admin/users

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Lists admin users with optional filters.

```APIDOC
## GET /api/v1/admin/users

### Description
Lists admin users with optional filters.

### Method
GET

### Endpoint
/api/v1/admin/users

### Parameters
#### Query Parameters
- **verified** (string) - Optional - Filter by verification status: `verified` or `unverified`
- **activity** (string) - Optional - Filter by activity: `7d`, `30d`, or `never`
- **terrains** (string) - Optional - Filter by terrain ownership: `has` or `none`
- **sessions** (string) - Optional - Filter by session status: `active` or `none`

```

--------------------------------

### POST /api/v1/analytics/visit

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Records a visit event for analytics.

```APIDOC
## POST /api/v1/analytics/visit

### Description
Records a visit event for analytics.

### Method
POST

### Endpoint
/api/v1/analytics/visit

```

--------------------------------

### POST /api/v1/auth/login

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Logs in a user using either email or username and password.

```APIDOC
## POST /api/v1/auth/login

### Description
Logs in a user using either email or username and password.

### Method
POST

### Endpoint
/api/v1/auth/login

### Request Body
- **identifier** (string) - Required - Email or username
- **password** (string) - Required - User's password

### Request Example
```json
{ "identifier": "terrain_creator", "password": "your password" }
```

```

--------------------------------

### GET /api/v1/me

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves the current user's profile information.

```APIDOC
## GET /api/v1/me

### Description
Retrieves the current user's profile information.

### Method
GET

### Endpoint
/api/v1/me

```

--------------------------------

### POST /api/v1/analytics/plugin-event

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Records a plugin event for analytics.

```APIDOC
## POST /api/v1/analytics/plugin-event

### Description
Records a plugin event for analytics.

### Method
POST

### Endpoint
/api/v1/analytics/plugin-event

```

--------------------------------

### GET /api/v1/admin/visits

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves visit analytics. Accepts a `days` query parameter for range.

```APIDOC
## GET /api/v1/admin/visits

### Description
Retrieves visit analytics. Accepts a `days` query parameter for range.

### Method
GET

### Endpoint
/api/v1/admin/visits

### Parameters
#### Query Parameters
- **days** (string) - Optional - Range: `7`, `30`, or `90` (default: `7`)

```

--------------------------------

### GET /api/v1/admin/audit

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves audit logs for admin purposes.

```APIDOC
## GET /api/v1/admin/audit

### Description
Retrieves audit logs for admin purposes.

### Method
GET

### Endpoint
/api/v1/admin/audit

```

--------------------------------

### GET /api/v1/admin/terrains

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves terrain data for admin purposes.

```APIDOC
## GET /api/v1/admin/terrains

### Description
Retrieves terrain data for admin purposes.

### Method
GET

### Endpoint
/api/v1/admin/terrains

```

--------------------------------

### Deploy an update with PM2

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Commands to pull latest changes, reinstall dependencies, run migrations, and reload the PM2 process.

```sh
git pull
cd api
npm ci --omit=dev
npm run migrate
pm2 reload ecosystem.config.cjs --env production --update-env
```

--------------------------------

### Useful PM2 commands

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Commands to check status, view logs, restart, and stop the API process.

```sh
pm2 status
pm2 logs procedural-terrains-api
pm2 restart procedural-terrains-api --update-env
pm2 stop procedural-terrains-api
```

--------------------------------

### Create and update a terrain

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/getting-started.md

Use an existing renderer, scene, and camera. Call frame from your animation loop with seconds rather than milliseconds.

```js
import { createTerrain } from 'procedural-terrains';

const terrain = await createTerrain({
  renderer,
  configuration: {
    layout: { chunkCount: 8, chunkSize: 128 },
    heightScale: 560,
    source: { kind: 'noise', seed: 1337 },
  },
});
scene.add(terrain.object);
camera.position.set(900, 700, 900);
camera.lookAt(0, 150, 0);
await terrain.prepare(camera);

function frame(deltaSeconds) {
  terrain.update(deltaSeconds, { camera });
  renderer.render(scene, camera);
}
```

--------------------------------

### Configure API environment variables

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Set the API host, port, frontend origins, cookie settings, and admin emails. Use `COOKIE_SAME_SITE=none` if frontend and API are on different top-level domains; browsers require `COOKIE_SECURE=true` in that configuration.

```env
NODE_ENV=production
API_HOST=127.0.0.1
API_PORT=6062
# Keep the packaged desktop origin alongside the web application origin.
FRONTEND_ORIGINS=https://procedural-terrains.com,procedural-terrain://app
COOKIE_SECURE=true
COOKIE_SAME_SITE=lax
TRUST_PROXY=true
ADMIN_EMAILS=owner@example.com
PRIVACY_HASH_SECRET=replace-with-at-least-32-random-characters
```

--------------------------------

### Run database migrations

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Applies SQL migrations in filename order. Uses a MySQL advisory lock, records a SHA-256 checksum in schema_migrations, and refuses to continue if an already-applied migration was edited. Creates the database automatically if it does not exist and DB_USER has permission.

```sh
npm run migrate
```

--------------------------------

### POST /api/v1/auth/logout

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Logs out the current user and invalidates the session.

```APIDOC
## POST /api/v1/auth/logout

### Description
Logs out the current user and invalidates the session.

### Method
POST

### Endpoint
/api/v1/auth/logout

```

--------------------------------

### Create a terrain viewer

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/getting-started.md

The viewer owns a renderer, camera, orbit controls, and animation loop. It currently creates finite terrain only. The container needs a nonzero height. Call viewer.dispose() when closing.

```js
import { createTerrainViewer } from 'procedural-terrains/viewer';

const viewer = await createTerrainViewer(
  document.querySelector('#terrain'),
  { configuration: { source: { seed: 42 } } },
);
// The container needs a nonzero height.
// When closing:
viewer.dispose();
```

--------------------------------

### Create mini terrain and configure

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Mini manages its finite configuration, relief, composition, resolution and footprint. Apply changes through `terrain.mini.configure`. Framing is a suggestion; your application moves its own camera. Water and clouds are optional layers; vegetation and editor controls are not installed.

```js
import { createMiniTerrain } from 'procedural-terrains/mini';
const terrain = await createMiniTerrain({
  renderer, mini: { recipe: 'cove', seed: 1337, width: 1024 },
  backdrop: true,
});
await terrain.mini.configure({ waterLevel: 0.6 });
const framing = terrain.mini.framing();
```

--------------------------------

### GET /api/v1/users/:userId/avatar

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Retrieves the avatar of a specific user.

```APIDOC
## GET /api/v1/users/:userId/avatar

### Description
Retrieves the avatar of a specific user.

### Method
GET

### Endpoint
/api/v1/users/:userId/avatar

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user

```

--------------------------------

### GET /health

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Health check endpoint for the service. Returns service status.

```APIDOC
## GET /health

### Description
Health check endpoint for the service.

### Method
GET

### Endpoint
/health

```

--------------------------------

### GET /api/v1/health

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Health check endpoint for the API v1. Returns API status.

```APIDOC
## GET /api/v1/health

### Description
Health check endpoint for the API v1.

### Method
GET

### Endpoint
/api/v1/health

```

--------------------------------

### Nginx reverse proxy configuration

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Example Nginx virtual host before adding TLS configuration. Keep port 3001 and MySQL private in the firewall; expose only Nginx on ports 80/443 and terminate HTTPS there.

```nginx
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:6062;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

--------------------------------

### Update and dispose terrain

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/getting-started.md

Configuration patches merge into the current configuration. Do not mutate terrain.configuration. Dispose the terrain when removing its scene; its renderer remains yours.

```js
await terrain.configure({ source: { seed: 42 } });
const height = terrain.sampleHeight(0, 0);
const document = terrain.serialize();
terrain.dispose();
```

--------------------------------

### PUT /api/v1/me/password

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Updates the current user's password.

```APIDOC
## PUT /api/v1/me/password

### Description
Updates the current user's password.

### Method
PUT

### Endpoint
/api/v1/me/password

```

--------------------------------

### Register request body

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

JSON body for POST /api/v1/auth/register. Requires email, username, and a password of at least 10 characters.

```json
{ "email": "you@example.com", "username": "terrain_creator", "password": "at least 10 characters" }
```

--------------------------------

### Login request body

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

JSON body for POST /api/v1/auth/login. Accepts either email or username as the identifier.

```json
{ "identifier": "terrain_creator", "password": "your password" }
```

--------------------------------

### Profile settings update body

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

JSON body for PATCH /api/v1/me. Accepts any subset of username, displayName, websiteUrl, and defaultProjectVisibility. Visibility can be private, unlisted, or public.

```json
{
  "username": "terrain_creator",
  "displayName": "Terrain Creator",
  "websiteUrl": "https://example.com",
  "defaultProjectVisibility": "private"
}
```

--------------------------------

### PATCH /api/v1/me

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Updates the current user's profile settings. Accepts any subset of the specified fields.

```APIDOC
## PATCH /api/v1/me

### Description
Updates the current user's profile settings. Accepts any subset of the specified fields.

### Method
PATCH

### Endpoint
/api/v1/me

### Request Body
- **username** (string) - Optional - New username
- **displayName** (string) - Optional - Display name
- **websiteUrl** (string) - Optional - Website URL
- **defaultProjectVisibility** (string) - Optional - Visibility setting: `private`, `unlisted`, or `public`

### Request Example
```json
{
  "username": "terrain_creator",
  "displayName": "Terrain Creator",
  "websiteUrl": "https://example.com",
  "defaultProjectVisibility": "private"
}
```

```

--------------------------------

### Set VITE_API_URL for frontend build

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Configure the frontend API URL at build time. Local development defaults to the same-origin `/api/v1` path, which Vite proxies to port 6062.

```env
VITE_API_URL=https://api.example.com/api/v1
```

--------------------------------

### PUT /api/v1/me/avatar

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Uploads or updates the current user's profile picture. The image is sent as a data URL.

```APIDOC
## PUT /api/v1/me/avatar

### Description
Uploads or updates the current user's profile picture. The image is sent as a data URL.

### Method
PUT

### Endpoint
/api/v1/me/avatar

### Request Body
- **dataUrl** (string) - Required - PNG, JPEG, or WebP data URL (max 1 MB)

### Request Example
```json
{ "dataUrl": "..." }
```

```

--------------------------------

### Run all validation checks

Source: https://github.com/zyfou/proceduralterrains/blob/main/packages/procedural-terrains/README.md

Executes the full validation suite: library checks, unit tests, Node tests, build, example build, Playwright install, and browser/world tests. Requires npm and Node.js. Browser checks can use TERRAIN_BROWSER_PATH for an installed Chromium binary.

```sh
npm run check:lib
npm test
node --test tests/*.node.mjs
npm run build
npm ci --prefix examples/three-finite-terrain
npm run build --prefix examples/three-finite-terrain
npx playwright install chromium
npm run test:lib:browser
npm run test:lib:worlds
```

--------------------------------

### DELETE /api/v1/me/avatar

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Deletes the current user's profile picture.

```APIDOC
## DELETE /api/v1/me/avatar

### Description
Deletes the current user's profile picture.

### Method
DELETE

### Endpoint
/api/v1/me/avatar

```

--------------------------------

### POST /api/v1/admin/users/:userId/revoke-sessions

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Revokes all active sessions for a specific user.

```APIDOC
## POST /api/v1/admin/users/:userId/revoke-sessions

### Description
Revokes all active sessions for a specific user.

### Method
POST

### Endpoint
/api/v1/admin/users/:userId/revoke-sessions

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user

```

--------------------------------

### PATCH /api/v1/admin/users/:userId

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Updates a specific user's details as an admin.

```APIDOC
## PATCH /api/v1/admin/users/:userId

### Description
Updates a specific user's details as an admin.

### Method
PATCH

### Endpoint
/api/v1/admin/users/:userId

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user to update

```

--------------------------------

### API route list

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

Lists all HTTP routes for the API, including health, authentication, user profile, avatar, password, analytics, and admin endpoints. Admin reporting accepts days=7|30|90; user listings accept verified, activity, terrains, and sessions filters.

```text
GET  /health
GET  /api/v1/health
POST /api/v1/auth/register
POST /api/v1/auth/login
GET  /api/v1/auth/session
POST /api/v1/auth/logout
GET  /api/v1/me
PATCH /api/v1/me
PUT  /api/v1/me/avatar
DELETE /api/v1/me/avatar
PUT  /api/v1/me/password
GET  /api/v1/users/:userId/avatar
POST /api/v1/analytics/visit
POST /api/v1/analytics/plugin-event
GET  /api/v1/admin/overview
GET  /api/v1/admin/users
PATCH /api/v1/admin/users/:userId
POST /api/v1/admin/users/:userId/revoke-sessions
GET  /api/v1/admin/visits
GET  /api/v1/admin/terrains
GET  /api/v1/admin/audit
GET  /api/v1/admin/security
```

--------------------------------

### Fix auth_gssapi_client: ALTER USER to mysql_native_password

Source: https://github.com/zyfou/proceduralterrains/blob/main/api/README.md

SQL to change an existing MariaDB account to use password authentication, resolving the auth_gssapi_client error. Replace the placeholder password and set the same value in DB_PASSWORD.

```sql
ALTER USER 'terrain'@'127.0.0.1'
  IDENTIFIED VIA mysql_native_password USING PASSWORD('replace-with-a-long-password');
```

--------------------------------

### Create Infinite, Planet, and Mini Terrains

Source: https://github.com/zyfou/proceduralterrains/blob/main/packages/procedural-terrains/README.md

Imports and constructs three world modes: infinite, planet, and mini. Mini is a finite presentation that can be configured via terrain.mini.configure and does not install editor controls or vegetation. Choose a world at construction and create another instance when switching modes.

```javascript
import { createInfiniteTerrain } from 'procedural-terrains/infinite';
import { createPlanetTerrain } from 'procedural-terrains/planet';
import { createMiniTerrain } from 'procedural-terrains/mini';

const infinite = await createInfiniteTerrain({ renderer, configuration: {
  layout: { chunkSize: 128, viewRadius: 8, cacheResolution: 256 },
} });
const planet = await createPlanetTerrain({ renderer, configuration: {
  layout: { radius: 16000, faceGrid: 8, bakeResolution: 256 },
} });
const mini = await createMiniTerrain({ renderer,
  mini: { recipe: 'cove', seed: 1337, width: 1024, quality: 'balanced' },
  backdrop: false,
});
await mini.mini.configure({ waterLevel: 0.6 });
const framing = mini.mini.framing(); // suggestion; does not move your camera
```

--------------------------------

### Create production build and preview

Source: https://github.com/zyfou/proceduralterrains/blob/main/README.md

Build the project for production and preview the result locally.

```sh
npm run build
npm run preview
```

--------------------------------

### Packaged Windows shader benchmark commands

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/PERFORMANCE.md

Run benchmark from packaged app. Only accepted by initial single-instance launch; close running app first. `--shader-benchmark=all` runs sequential smoke-test suite.

```powershell
& '.\Procedural Terrains.exe' --shader-benchmark=terrain
& '.\Procedural Terrains.exe' --shader-benchmark=water --shader-benchmark-token=water-01
& '.\Procedural Terrains.exe' --shader-benchmark=all
```

--------------------------------

### Shader benchmark URLs

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/PERFORMANCE.md

Developer-only opt-in benchmark mode. Measures active launch configuration before normal submission. Use separate cold launches for attribution.

```text
http://localhost:6061/?shaderBenchmark=terrain
http://localhost:6061/?shaderBenchmark=water
http://localhost:6061/?shaderBenchmark=cloud
http://localhost:6061/?shaderBenchmark=post
http://localhost:6061/?shaderBenchmark=scene
```

--------------------------------

### water.prepare(camera)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/water.md

Prepares the water for rendering with the given camera. Should be called before rendering.

```APIDOC
## water.prepare(camera)

### Description
Prepares the water for rendering with the given camera. Should be called before rendering.

### Method
async function

### Parameters
- **camera** (object) - Required - The camera to prepare for.

### Example
```js
await water.prepare(camera);
```
```

--------------------------------

### clouds.prepare(camera)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/clouds.md

Prepares the renderer for the given camera. Must be awaited before rendering.

```APIDOC
## clouds.prepare(camera)

### Description
Prepares the renderer for the given camera. Must be awaited before rendering.

### Parameters
- **camera** (object) - Required - The camera to prepare for.

### Returns
A Promise that resolves when preparation is complete.
```

--------------------------------

### water.prepare(camera, { signal })

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/water.md

Prepares the water layer for a given camera. Accepts an optional AbortSignal to cancel preparation.

```APIDOC
## water.prepare(camera, { signal })

### Description
Prepares the water layer for a given camera. Accepts an optional AbortSignal to cancel preparation.

### Parameters
- `camera` (Camera) - Required - The camera to prepare for.
- `signal` (AbortSignal) - Optional - Abort signal to cancel preparation.

### Returns
- `Promise` - Resolves when preparation is complete.
```

--------------------------------

### Create PBR surface materials

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Loads a PBR material pack from a hosted base URL and attaches it to a terrain. Requires a surface document and a hosted catalog.json and .pbr packs. Detach from every terrain before disposing shared resources.

```javascript
import { TerrainSurfaceProvider, createSurfaceResources } from 'procedural-terrains/assets';

const provider = new TerrainSurfaceProvider({
  baseUrl: 'https://your-host/material-pack/',
});
const surface = await createSurfaceResources({
  provider, document: surfaceDocument,
});
await terrain.setSurface(surface);
// Detach from every terrain before destroying shared resources:
await terrain.setSurface(null);
surface.dispose();
provider.dispose();
```

--------------------------------

### Run validation tests

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/SPATIAL_UPSCALER.md

Run the dependency-free test suite, full test suite, and build to validate the spatial upscaler implementation.

```sh
node --test tests/spatial-upscaler.node.mjs
npm test
npm run build
```

--------------------------------

### createMiniTerrain (Mini)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Creates a mini terrain with managed configuration and optional backdrop. Use terrain.mini.configure to apply changes.

```APIDOC
## createMiniTerrain (Mini)

### Description
Creates a mini terrain with managed configuration and optional backdrop. Use terrain.mini.configure to apply changes.

### Method
createMiniTerrain

### Endpoint
procedural-terrains/mini

### Parameters
#### Configuration
- **renderer** (object) - Required - The renderer instance.
- **mini** (object) - Required - Mini configuration.
  - **recipe** (string) - Required - Recipe name (e.g., 'cove').
  - **seed** (number) - Required - Seed.
  - **width** (number) - Required - Width of the mini terrain.
- **backdrop** (boolean) - Optional - Whether to include a backdrop.

### Request Example
```js
import { createMiniTerrain } from 'procedural-terrains/mini';
const terrain = await createMiniTerrain({
  renderer, mini: { recipe: 'cove', seed: 1337, width: 1024 },
  backdrop: true,
});
await terrain.mini.configure({ waterLevel: 0.6 });
const framing = terrain.mini.framing();
```
```

--------------------------------

### prepare(camera, { signal? })

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/api.md

Compiles shaders and prepares GPU caches for the terrain. Returns a promise that resolves when the terrain is ready to render.

```APIDOC
## prepare(camera, { signal? })

### Description
Compile shaders and prepare GPU caches. Returns a promise.

### Method
prepare

### Parameters
- **camera** (Camera) - Required - The camera used for rendering.
- **signal** (AbortSignal) - Optional - An abort signal to cancel the preparation.

### Returns
Promise<void>
```

--------------------------------

### Set up terrain surface with external material pack

Source: https://github.com/zyfou/proceduralterrains/blob/main/packages/procedural-terrains/README.md

Creates a TerrainSurfaceProvider with a base URL for a hosted material pack, loads surface resources from a document, and attaches them to a terrain. After detaching, disposes the surface and provider. Host the catalog.json and .pbr files yourself; catalog hashes and material budgets are checked. No implicit request to the studio's /textures, storage, account, or API.

```javascript
import { TerrainSurfaceProvider, createSurfaceResources } from 'procedural-terrains/assets';
const provider = new TerrainSurfaceProvider({ baseUrl: 'https://your-host/material-pack/' });
const surface = await createSurfaceResources({ provider, document: surfaceDocument });
await terrain.setSurface(surface);
// After detaching from every terrain:
await terrain.setSurface(null);
surface.dispose();
provider.dispose();
```

--------------------------------

### createHeightCache

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Creates an optional height cache for finite terrain. Uses double buffering and owns its worker and GPU pages.

```APIDOC
## createHeightCache

### Description
Creates a height cache for a finite terrain. The cache uses double buffering and prepares detail pages automatically on update.

### Method
async function

### Parameters
- **terrain** (object) - Required - The terrain object.
- **resolution** (number) - Optional - Resolution of the cache (default 512).

### Returns
- **cache** (object) - The height cache object.

### Example
```js
const cache = await createHeightCache({ terrain, resolution: 512 });
```
```

--------------------------------

### TerrainSurfaceProvider

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Provides surface materials from a base URL. Hosts catalog.json and .pbr packs yourself.

```APIDOC
## TerrainSurfaceProvider

### Description
Provides surface materials from a base URL. The provider validates hashes and material budgets.

### Constructor
`new TerrainSurfaceProvider({ baseUrl })`

### Parameters
- **baseUrl** (string) - Required - Base URL for the material pack.

### Methods
- **dispose()** - Disposes the provider.

### Example
```js
const provider = new TerrainSurfaceProvider({ baseUrl: 'https://your-host/material-pack/' });
```
```

--------------------------------

### clouds.configure(options, signal?)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/clouds.md

Merges changes to mode, parameters, and quality, and replaces the layer only after successful preparation.

```APIDOC
## clouds.configure(options, signal?)

### Description
Merges changes to mode, parameters, and quality, and replaces the layer only after successful preparation.

### Parameters
- **options** (object) - Required - Configuration options.
  - **mode** (string) - Optional - The mode: `legacy` or `realistic`.
  - **parameters** (object) - Optional - Effect parameters.
  - **quality** (string) - Optional - Quality setting.
- **signal** (AbortSignal) - Optional - Abort signal for cancellation.

### Returns
A Promise that resolves when the layer is replaced.
```

--------------------------------

### createDetailCache

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Creates an optional detail cache for finite terrain. Overrides the automatic detail page lifecycle until disposed.

```APIDOC
## createDetailCache

### Description
Creates a detail cache for a finite terrain. An explicit detail cache overrides the automatic lifecycle until disposed.

### Method
async function

### Parameters
- **terrain** (object) - Required - The terrain object.
- **quality** (number) - Optional - Quality level (default 2).

### Returns
- **cache** (object) - The detail cache object.

### Example
```js
const cache = await createDetailCache({ terrain, quality: 2 });
```
```

--------------------------------

### water.configure({ parameters, quality })

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/water.md

Configures water parameters and quality settings. Can be called after creation to adjust water appearance.

```APIDOC
## water.configure({ parameters, quality })

### Description
Configures water parameters and quality settings. Can be called after creation to adjust water appearance.

### Method
async function

### Parameters
- **parameters** (object) - Optional - Water parameters.
  - **waterWaveStrength** (number) - Optional - Wave strength.
- **quality** (object) - Optional - Quality settings.
  - **waterDetail** (number) - Optional - Water detail level.

### Example
```js
await water.configure({ parameters: { waterWaveStrength: 0.6 }, quality: { waterDetail: 0.8 } });
```
```

--------------------------------

### water.configure({ mode?, parameters?, quality? }, { signal? })

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/water.md

Merges configuration changes into the water layer. If candidate preparation fails, the live water layer is retained.

```APIDOC
## water.configure({ mode?, parameters?, quality? }, { signal? })

### Description
Merges configuration changes into the water layer. If candidate preparation fails, the live water layer is retained.

### Parameters
- `mode` (string) - Optional - The water mode to set.
- `parameters` (object) - Optional - Additional parameters, including `waterMode` and `waterQualityPreset` (compatibility/metadata only).
- `quality` (object) - Optional - Quality budget settings (e.g., `waterQuality`, `waterDetail`, `waterReflection`, `waterWaves`).
- `signal` (AbortSignal) - Optional - Abort signal for the configuration operation.

### Returns
- `Promise` - Resolves when configuration is applied.
```

--------------------------------

### Run automated energy-saving tests

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/ENERGY_SAVING.md

Runs the dependency-free Node test suite for energy-saving policy, display cadence, visibility, wake-up, clock handling, setting normalization, quality safeguards, and disposal using a mock base engine. Then runs the full test suite and build.

```sh
node --test tests/energy-saving.node.mjs
npm test
npm run build
```

--------------------------------

### Load terrain document and export terrain to GLB with zip

Source: https://github.com/zyfou/proceduralterrains/blob/main/packages/procedural-terrains/README.md

Restores a terrain from a serialized document, exports it as GLB with specified mesh and texture resolutions, and zips the export bytes. Exports return named byte arrays, filename, and diagnostics without download or filesystem side effects. Await GPU operations before starting another export or disposing borrowed assets.

```javascript
import { loadTerrainDocument } from 'procedural-terrains/documents';
import { exportTerrain, zipTerrainExport } from 'procedural-terrains/export';
const restored = await loadTerrainDocument(terrain.serialize(), { renderer });
const result = await exportTerrain(terrain, {
  format: 'glb', meshRes: 128, texRes: 512,
  bakeColor: true, exportHeightmap: true,
});
const zipBytes = zipTerrainExport(result); // caller chooses how/where to save
```

--------------------------------

### Create water, clouds, and render pipeline

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Sets up independent water and clouds layers plus a terrain render pipeline. Requires a terrain, renderer, and scene. Water modes include 'volumetric'; cloud modes include 'realistic'. Use one water and one cloud layer per terrain.

```javascript
import { createWater } from 'procedural-terrains/water';
import { createClouds } from 'procedural-terrains/clouds';
import { TerrainRenderPipeline } from 'procedural-terrains/render';

const water = await createWater({ terrain, mode: 'volumetric' });
const clouds = await createClouds({ terrain, mode: 'realistic' });
const pipeline = new TerrainRenderPipeline({ renderer, terrains: [terrain] });
await terrain.prepare(camera);

function frame(dt) {
  terrain.update(dt, { camera });
  pipeline.render(scene, camera);
}
```

--------------------------------

### sampleHeight(x, z)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/api.md

Returns a CPU approximation of the terrain height at the given world coordinates. Returns null outside finite boards.

```APIDOC
## sampleHeight(x, z)

### Description
CPU height approximation; null outside finite boards.

### Method
sampleHeight

### Parameters
- **x** (number) - Required - The x-coordinate in world units.
- **z** (number) - Required - The z-coordinate in world units.

### Returns
number | null
```

--------------------------------

### createInfiniteTerrain (Infinite World)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Creates an infinite terrain that streams chunks based on camera position. Supports noise and unbounded 2D graphs.

```APIDOC
## createInfiniteTerrain (Infinite World)

### Description
Creates an infinite terrain that streams chunks based on camera position. Supports noise and unbounded 2D graphs.

### Method
createInfiniteTerrain

### Endpoint
procedural-terrains/infinite

### Parameters
#### Configuration
- **renderer** (object) - Required - The renderer instance.
- **configuration** (object) - Required - Configuration object.
  - **layout** (object) - Required - Layout settings.
    - **chunkSize** (number) - Required - Size of each chunk.
    - **viewRadius** (number) - Required - Radius of chunks to load around camera.
    - **cacheResolution** (number) - Required - Resolution of cached data.
    - **triangleBudget** (number) - Required - Maximum number of triangles.
    - **maxCreatesPerFrame** (number) - Required - Maximum chunk creations per frame.
    - **streamBudgetMs** (number) - Required - Streaming budget in milliseconds.

### Request Example
```js
import { createInfiniteTerrain } from 'procedural-terrains/infinite';
const terrain = await createInfiniteTerrain({ renderer, configuration: {
  layout: {
    chunkSize: 128, viewRadius: 8, cacheResolution: 256,
    triangleBudget: 1000000, maxCreatesPerFrame: 16, streamBudgetMs: 1.5,
  },
} });
```
```

--------------------------------

### createClouds

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Creates a cloud layer for a terrain. Supports legacy and realistic modes.

```APIDOC
## createClouds

### Description
Creates a cloud layer for a terrain. The mode parameter controls the rendering style.

### Method
async function

### Parameters
- **terrain** (object) - Required - The terrain object to attach the clouds to.
- **mode** (string) - Required - Cloud mode: `legacy` or `realistic`.
- **parameters** (object) - Optional - Appearance configuration.
- **quality** (object) - Optional - Rendering budget configuration.

### Returns
- **clouds** (object) - The cloud layer object.

### Example
```js
const clouds = await createClouds({ terrain, mode: 'realistic' });
```
```

--------------------------------

### createTerrain (Tile)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Creates a finite terrain with a square board and chunk LOD. Use this for tile-based worlds.

```APIDOC
## createTerrain (Tile)

### Description
Creates a finite terrain with a square board and chunk LOD. Use this for tile-based worlds.

### Method
createTerrain

### Endpoint
procedural-terrains

### Parameters
#### Configuration
- **renderer** (object) - Required - The renderer instance.
- **configuration** (object) - Required - Configuration object.
  - **layout** (object) - Required - Layout settings.
    - **chunkCount** (number) - Required - Number of chunks per side.
    - **chunkSize** (number) - Required - Size of each chunk.
  - **source** (object) - Required - Source configuration.
    - **kind** (string) - Required - Source kind (e.g., 'noise').
    - **seed** (number) - Required - Seed for noise.

### Request Example
```js
import { createTerrain } from 'procedural-terrains';
const terrain = await createTerrain({ renderer, configuration: {
  layout: { chunkCount: 8, chunkSize: 128 },
  source: { kind: 'noise', seed: 1337 },
} });
```
```

--------------------------------

### createWater(options)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/water.md

Creates a water layer instance. Returns the layer object that can be prepared, configured, updated, serialized, and disposed.

```APIDOC
## createWater(options)

### Description
Creates a water layer instance. Returns the layer object that can be prepared, configured, updated, serialized, and disposed.

### Parameters
- `options` (object) - Required - Configuration options, including `renderer` and any saved state from `serialize()`.

### Returns
- `water` (object) - The water layer instance.
```

--------------------------------

### Create infinite terrain with streaming layout

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Streaming follows the camera supplied to `update`. Noise and unbounded 2D graphs are supported; bounded manual and heightmap sources require finite terrain.

```js
import { createInfiniteTerrain } from 'procedural-terrains/infinite';
const terrain = await createInfiniteTerrain({ renderer, configuration: {
  layout: {
    chunkSize: 128, viewRadius: 8, cacheResolution: 256,
    triangleBudget: 1000000, maxCreatesPerFrame: 16, streamBudgetMs: 1.5,
  },
} });
```

--------------------------------

### createInfiniteTerrain(options)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/api.md

Creates an infinite terrain instance. Takes the same options as createTerrain, with additional world-specific layout fields.

```APIDOC
## createInfiniteTerrain(options)

### Description
Creates an infinite terrain instance. Takes the same options as createTerrain, with additional world-specific layout fields.

### Parameters
- `renderer` (THREE.WebGLRenderer) - Required - Caller-owned WebGL renderer.
- `configuration` (object) - Optional - Partial terrain configuration.
- `signal` (AbortSignal) - Optional - Abort signal.
- `resources` (TerrainResources) - Optional - Shared resource scope using the same renderer.
- Additional world-specific layout fields.

### Returns
`Promise<FiniteTerrain>`
```

--------------------------------

### createMiniTerrain(options)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/api.md

Creates a mini terrain instance. Takes the same options as createTerrain, plus mini and backdrop options.

```APIDOC
## createMiniTerrain(options)

### Description
Creates a mini terrain instance. Takes the same options as createTerrain, plus mini and backdrop options.

### Parameters
- `renderer` (THREE.WebGLRenderer) - Required - Caller-owned WebGL renderer.
- `configuration` (object) - Optional - Partial terrain configuration.
- `signal` (AbortSignal) - Optional - Abort signal.
- `resources` (TerrainResources) - Optional - Shared resource scope using the same renderer.
- `mini` - Required - Mini terrain options.
- `backdrop` - Required - Backdrop options.

### Returns
`Promise<FiniteTerrain>`
```

--------------------------------

### createRealWorldTerrain (Real-world data)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Creates a real-world terrain using an explicit provider with loadHeightmap and optional loadImagery. Requires tile URLs and attribution.

```APIDOC
## createRealWorldTerrain (Real-world data)

### Description
Creates a real-world terrain using an explicit provider with loadHeightmap and optional loadImagery. Requires tile URLs and attribution.

### Method
createRealWorldTerrain

### Endpoint
procedural-terrains

### Parameters
#### Provider
- **loadHeightmap** (function) - Required - Function to load heightmap data.
- **loadImagery** (function) - Optional - Function to load imagery data.

### Notes
- Bounding boxes use west/east/south/north, Web Mercator latitude limits, and at most 6×6 tiles.
- Split antimeridian-crossing regions yourself.
- No account or studio map service is used implicitly.
```

--------------------------------

### Configure heightmap source

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Heightmaps span the finite board, with row zero at negative Z. Values are world-unit heights within ±60000, uploaded as filtered half floats. Data and dimensions must match.

```js
await terrain.configure({ source: {
  kind: 'heightmap', width: 2, height: 2,
  data: new Float32Array([0, 50, 120, 30]),
} });
```

--------------------------------

### configure(patch, { signal? })

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/api.md

Applies a validated patch to the terrain configuration and prepares changed resources. Returns a promise that resolves when the configuration is applied.

```APIDOC
## configure(patch, { signal? })

### Description
Apply a validated patch and prepare changed resources.

### Method
configure

### Parameters
- **patch** (object) - Required - The configuration patch to apply.
- **signal** (AbortSignal) - Optional - An abort signal to cancel the operation.

### Returns
Promise<void>
```

--------------------------------

### clouds.serialize()

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/clouds.md

Returns effect settings and standalone world, when present. Can be used to recreate the clouds with createClouds.

```APIDOC
## clouds.serialize()

### Description
Returns effect settings and standalone world, when present. Can be used to recreate the clouds with createClouds.

### Returns
An object containing effect settings and standalone world (if present).
```

--------------------------------

### createPlanetTerrain (Planet)

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/worlds.md

Creates a planet terrain using cube-sphere patches. Requires a Noise Stack with 3D evaluation.

```APIDOC
## createPlanetTerrain (Planet)

### Description
Creates a planet terrain using cube-sphere patches. Requires a Noise Stack with 3D evaluation.

### Method
createPlanetTerrain

### Endpoint
procedural-terrains/planet

### Parameters
#### Configuration
- **renderer** (object) - Required - The renderer instance.
- **configuration** (object) - Required - Configuration object.
  - **layout** (object) - Required - Layout settings.
    - **radius** (number) - Required - Planet radius.
    - **faceGrid** (number) - Required - Grid resolution per face.
    - **bakeResolution** (number) - Required - Resolution for baking.
  - **source** (object) - Required - Source configuration.
    - **kind** (string) - Required - Source kind (e.g., 'noise').
    - **seed** (number) - Required - Seed for noise.

### Request Example
```js
import { createPlanetTerrain } from 'procedural-terrains/planet';
const terrain = await createPlanetTerrain({ renderer, configuration: {
  layout: { radius: 16000, faceGrid: 8, bakeResolution: 256 },
  source: { kind: 'noise', seed: 1337 },
} });
```
```

--------------------------------

### createSurfaceResources

Source: https://github.com/zyfou/proceduralterrains/blob/main/docs/effects.md

Creates surface resources from a provider and a surface document. Can be attached to a terrain.

```APIDOC
## createSurfaceResources

### Description
Creates surface resources for a terrain. The resources can be attached to a terrain and must be detached before disposal.

### Method
async function

### Parameters
- **provider** (object) - Required - A TerrainSurfaceProvider instance.
- **document** (object) - Required - The surface document.

### Returns
- **surface** (object) - The surface resources object.

### Example
```js
const surface = await createSurfaceResources({ provider, document: surfaceDocument });
```
```