@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/mcp/workspace.mjs

@@ -0,0 +1,397 @@
+import { randomUUID } from 'node:crypto';
+import {
+  access,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+export const TOONLAB_WORKSPACE_VERSION = 1;
+export const DEFAULT_WORKSPACE_DIRECTORY = '.toonlab';
+
+const WORKSPACE_DIRECTORIES = Object.freeze([
+  'assets',
+  'creations',
+  'exports',
+  'imports',
+  'library/entries',
+  'presets',
+  'storage',
+]);
+
+const WRITABLE_ROOTS = new Set(['assets', 'creations', 'exports', 'imports', 'presets']);
+const SENSITIVE_STORAGE_KEYS = new Set([
+  'toonlab.asset-lab.polypizza-key.v1',
+  'toonlab.texture-lab.ai.v1',
+]);
+
+const MIME_BY_EXTENSION = Object.freeze({
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.zip': 'application/zip',
+});
+
+function now() {
+  return new Date().toISOString();
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await rename(temporary, path);
+}
+
+async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function assertWorkspaceChild(workspacePath, path) {
+  const rel = relative(workspacePath, path);
+  if (!rel || rel === '.') return path;
+  if (rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) {
+    throw new Error('Path escapes the ToonLab workspace.');
+  }
+  return path;
+}
+
+function normalizeRelativePath(value) {
+  const parts = String(value ?? '')
+    .replaceAll('\\', '/')
+    .replace(/^\/+/, '')
+    .split('/')
+    .filter((part) => part && part !== '.');
+  if (parts.includes('..')) throw new Error('Workspace paths cannot contain "..".');
+  return parts.join('/');
+}
+
+function safeSlug(value, fallback = 'untitled') {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || fallback;
+}
+
+function libraryFilename(id) {
+  return `${Buffer.from(String(id)).toString('base64url')}.json`;
+}
+
+function storagePath(workspacePath) {
+  return join(workspacePath, 'storage', 'local-storage.json');
+}
+
+function manifestPath(workspacePath) {
+  return join(workspacePath, 'toonlab.json');
+}
+
+export function isPersistableStorageKey(key) {
+  const normalized = String(key ?? '');
+  if (SENSITIVE_STORAGE_KEYS.has(normalized)) return false;
+  if (normalized.includes('.thumb') || normalized.endsWith('.__probe__')) return false;
+  return normalized.startsWith('toonlab.') || normalized.startsWith('threejs-toon-shader.');
+}
+
+export function resolveWorkspacePath(input = DEFAULT_WORKSPACE_DIRECTORY, cwd = process.cwd()) {
+  return resolve(cwd, input || DEFAULT_WORKSPACE_DIRECTORY);
+}
+
+export async function ensureWorkspace(workspacePath) {
+  const root = resolve(workspacePath);
+  await mkdir(root, { recursive: true });
+  await Promise.all(WORKSPACE_DIRECTORIES.map((directory) => mkdir(join(root, directory), { recursive: true })));
+  const path = manifestPath(root);
+  if (!(await exists(path))) {
+    await writeJsonAtomic(path, {
+      createdAt: now(),
+      migrations: {},
+      updatedAt: now(),
+      version: TOONLAB_WORKSPACE_VERSION,
+    });
+  }
+  return root;
+}
+
+export async function readWorkspaceManifest(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  return readJson(manifestPath(root), {
+    createdAt: now(),
+    migrations: {},
+    updatedAt: now(),
+    version: TOONLAB_WORKSPACE_VERSION,
+  });
+}
+
+export async function updateWorkspaceManifest(workspacePath, update) {
+  const root = await ensureWorkspace(workspacePath);
+  const current = await readWorkspaceManifest(root);
+  const next = typeof update === 'function' ? update(current) : { ...current, ...update };
+  next.updatedAt = now();
+  next.version = TOONLAB_WORKSPACE_VERSION;
+  await writeJsonAtomic(manifestPath(root), next);
+  return next;
+}
+
+export async function getWorkspaceInfo(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  const manifest = await readWorkspaceManifest(root);
+  const storageInitialized = await exists(storagePath(root));
+  const library = await getLibraryState(root);
+  return {
+    libraryCount: library.entries.length,
+    manifest,
+    path: root,
+    storageInitialized,
+    version: TOONLAB_WORKSPACE_VERSION,
+  };
+}
+
+export async function readBrowserStorage(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  const path = storagePath(root);
+  if (!(await exists(path))) return { entries: {}, initialized: false };
+  const parsed = await readJson(path, {});
+  const entries = {};
+  for (const [key, value] of Object.entries(parsed ?? {})) {
+    if (isPersistableStorageKey(key) && typeof value === 'string') entries[key] = value;
+  }
+  return { entries, initialized: true };
+}
+
+export async function importBrowserStorage(workspacePath, input) {
+  const root = await ensureWorkspace(workspacePath);
+  const current = await readBrowserStorage(root);
+  if (current.initialized) return current;
+  const entries = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    if (isPersistableStorageKey(key) && typeof value === 'string') entries[key] = value;
+  }
+  await writeJsonAtomic(storagePath(root), entries);
+  await updateWorkspaceManifest(root, (manifest) => ({
+    ...manifest,
+    migrations: { ...manifest.migrations, browserLocalStorage: now() },
+  }));
+  return { entries, initialized: true };
+}
+
+export async function setBrowserStorageValue(workspacePath, key, value) {
+  if (!isPersistableStorageKey(key)) throw new Error('This browser-storage key is not persisted.');
+  if (typeof value !== 'string') throw new Error('Browser-storage values must be strings.');
+  const root = await ensureWorkspace(workspacePath);
+  const current = await readBrowserStorage(root);
+  const entries = { ...current.entries, [key]: value };
+  await writeJsonAtomic(storagePath(root), entries);
+  return entries;
+}
+
+export async function deleteBrowserStorageValue(workspacePath, key) {
+  const root = await ensureWorkspace(workspacePath);
+  const current = await readBrowserStorage(root);
+  if (!current.initialized) return {};
+  const entries = { ...current.entries };
+  delete entries[key];
+  await writeJsonAtomic(storagePath(root), entries);
+  return entries;
+}
+
+export async function clearBrowserStorage(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  await writeJsonAtomic(storagePath(root), {});
+  return {};
+}
+
+export async function listLibraryEntries(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  const directory = join(root, 'library', 'entries');
+  const files = (await readdir(directory, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
+  const entries = [];
+  for (const file of files) {
+    const entry = await readJson(join(directory, file.name), null);
+    if (entry?.id && typeof entry.id === 'string') entries.push(entry);
+  }
+  return entries.sort((a, b) => String(a.label ?? a.id).localeCompare(String(b.label ?? b.id)));
+}
+
+export async function getLibraryState(workspacePath) {
+  const root = await ensureWorkspace(workspacePath);
+  const manifest = await readWorkspaceManifest(root);
+  return {
+    entries: await listLibraryEntries(root),
+    migrated: Boolean(manifest.migrations?.indexedDbCatalog),
+  };
+}
+
+export async function saveLibraryEntry(workspacePath, entry) {
+  if (!entry || typeof entry !== 'object' || typeof entry.id !== 'string' || !entry.id.trim()) {
+    throw new Error('A library entry with an id is required.');
+  }
+  const root = await ensureWorkspace(workspacePath);
+  const path = join(root, 'library', 'entries', libraryFilename(entry.id));
+  await writeJsonAtomic(path, entry);
+  return entry;
+}
+
+export async function deleteLibraryEntry(workspacePath, id) {
+  const root = await ensureWorkspace(workspacePath);
+  const path = join(root, 'library', 'entries', libraryFilename(id));
+  try {
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function migrateLibraryEntries(workspacePath, entries) {
+  const root = await ensureWorkspace(workspacePath);
+  const state = await getLibraryState(root);
+  if (!state.migrated) {
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (entry?.id) await saveLibraryEntry(root, entry);
+    }
+    await updateWorkspaceManifest(root, (manifest) => ({
+      ...manifest,
+      migrations: { ...manifest.migrations, indexedDbCatalog: now() },
+    }));
+  }
+  return getLibraryState(root);
+}
+
+export function resolveWritableWorkspaceFile(workspacePath, relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  const [topLevel] = normalized.split('/');
+  if (!normalized || !WRITABLE_ROOTS.has(topLevel)) {
+    throw new Error(`Files must be saved below ${[...WRITABLE_ROOTS].join(', ')}.`);
+  }
+  const path = assertWorkspaceChild(resolve(workspacePath), resolve(workspacePath, normalized));
+  return { path, relativePath: normalized };
+}
+
+export async function writeWorkspaceFile(workspacePath, relativePath, data) {
+  const root = await ensureWorkspace(workspacePath);
+  const resolved = resolveWritableWorkspaceFile(root, relativePath);
+  await mkdir(dirname(resolved.path), { recursive: true });
+  await writeFile(resolved.path, data);
+  return describeWorkspaceFile(root, resolved.path);
+}
+
+async function describeWorkspaceFile(workspacePath, path) {
+  const info = await stat(path);
+  const relativePath = relative(workspacePath, path).split(sep).join('/');
+  return {
+    absolutePath: path,
+    id: `file:${relativePath}`,
+    kind: extname(path).slice(1).toLowerCase() || 'file',
+    mimeType: MIME_BY_EXTENSION[extname(path).toLowerCase()] ?? 'application/octet-stream',
+    modifiedAt: info.mtime.toISOString(),
+    name: basename(path),
+    relativePath,
+    sizeBytes: info.size,
+    source: 'workspace',
+  };
+}
+
+async function walkFiles(workspacePath, directory, output) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) await walkFiles(workspacePath, path, output);
+    else if (entry.isFile()) output.push(await describeWorkspaceFile(workspacePath, path));
+  }
+}
+
+export async function listWorkspaceFiles(workspacePath, { roots = [...WRITABLE_ROOTS] } = {}) {
+  const root = await ensureWorkspace(workspacePath);
+  const files = [];
+  for (const directory of roots) {
+    if (!WRITABLE_ROOTS.has(directory)) continue;
+    await walkFiles(root, join(root, directory), files);
+  }
+  return files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+}
+
+export async function readWorkspaceFile(workspacePath, relativePath) {
+  const root = await ensureWorkspace(workspacePath);
+  const normalized = normalizeRelativePath(relativePath.replace(/^file:/, ''));
+  const [topLevel] = normalized.split('/');
+  if (!WRITABLE_ROOTS.has(topLevel)) throw new Error('File is outside a readable workspace collection.');
+  const path = assertWorkspaceChild(root, resolve(root, normalized));
+  const description = await describeWorkspaceFile(root, path);
+  return { ...description, data: await readFile(path) };
+}
+
+export async function saveCreation(workspacePath, {
+  document,
+  filename = null,
+  kind = 'creation',
+  name = 'Untitled',
+} = {}) {
+  if (document === undefined) throw new Error('document is required.');
+  const collection = safeSlug(kind, 'creation');
+  const requested = filename ? safeSlug(basename(filename), `${safeSlug(name)}.json`) : `${safeSlug(name)}.json`;
+  const finalName = extname(requested) ? requested : `${requested}.json`;
+  const payload = typeof document === 'string' ? document : `${JSON.stringify(document, null, 2)}\n`;
+  return writeWorkspaceFile(workspacePath, `creations/${collection}/${finalName}`, payload);
+}
+
+function inferStorageCluster(key) {
+  const match = String(key).match(/^toonlab\.([a-z0-9-]+?)(?:\.document|\.presets|\.projects|$)/i);
+  return match?.[1] ?? 'lab';
+}
+
+export async function listStorageDocuments(workspacePath) {
+  const storage = await readBrowserStorage(workspacePath);
+  const documents = [];
+  for (const [key, raw] of Object.entries(storage.entries)) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    const values = Array.isArray(parsed) ? parsed : [parsed];
+    values.forEach((document, index) => {
+      if (!document || typeof document !== 'object') return;
+      const documentId = String(document.id ?? document.presetId ?? index);
+      documents.push({
+        cluster: inferStorageCluster(key),
+        document,
+        id: `storage:${Buffer.from(key).toString('base64url')}:${Buffer.from(documentId).toString('base64url')}`,
+        key,
+        kind: Array.isArray(parsed) ? 'preset' : 'document',
+        label: String(document.label ?? document.name ?? document.id ?? `${inferStorageCluster(key)} ${index + 1}`),
+        source: 'workspace-storage',
+      });
+    });
+  }
+  return documents;
+}
+
+export function matchesText(value, query) {
+  if (!query) return true;
+  return JSON.stringify(value).toLowerCase().includes(String(query).toLowerCase());
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.2.0",
-  "description": "Stylized (anime/toon) game starter kit for Three.js: character toon shading, environment shading, water, vegetation, sky, and post-processing",
+  "version": "0.3.0",
+  "description": "Stylized (anime/toon) game starter kit for Three.js: character and environment shading, lighting, weather, water, vegetation, sky, and post-processing",
   "license": "MIT",
   "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",
   "repository": {
@@ -19,14 +19,24 @@
     "cel-shading",
     "anime",
     "shader",
+    "lighting",
     "water",
+    "weather",
     "game-starter"
   ],
   "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "toonlab-mcp": "./mcp/server.mjs"
+  },
   "main": "./src/index.js",
   "module": "./src/index.js",
   "files": [
     "src",
+    "mcp",
+    "docs",
     "README.md",
     "LICENSE",
     "ATTRIBUTION.md",
@@ -36,12 +46,29 @@
     ".": "./src/index.js",
     "./toon": "./src/toon/index.js",
     "./environment": "./src/environment/index.js",
+    "./lighting": "./src/lighting/index.js",
     "./water": "./src/water/index.js",
     "./vegetation": "./src/vegetation/index.js",
+    "./vegetation-shaders": "./src/vegetation/vegetationShaders.js",
+    "./grass-palettes": "./src/vegetation/grassPalettes.js",
+    "./styles": "./src/styles/index.js",
     "./sky": "./src/sky/index.js",
+    "./weather": "./src/weather/index.js",
     "./post": "./src/post/index.js",
+    "./camera": "./src/camera/index.js",
+    "./game-feel": "./src/game-feel/index.js",
     "./rockgen": "./src/rockgen/index.js",
     "./debrisgen": "./src/debrisgen/index.js",
+    "./pathgen": "./src/pathgen/index.js",
+    "./propgen": "./src/propgen/index.js",
+    "./buildinggen": "./src/buildinggen/index.js",
+    "./villagegen": "./src/villagegen/index.js",
+    "./ambientfx": "./src/ambientfx/index.js",
+    "./vfxgen": "./src/vfxgen/index.js",
+    "./fauna": "./src/fauna/index.js",
+    "./catalog": "./src/catalog/index.js",
+    "./texgen": "./src/texgen/index.js",
+    "./assetlib": "./src/assetlib/index.js",
     "./character": "./src/character/index.js",
     "./loaders": "./src/loaders/index.js",
     "./debug": "./src/debug/index.js",
@@ -55,18 +82,49 @@
     "assets:environments": "node scripts/generate-local-environment-assets.mjs",
     "assets:local": "npm run assets:characters && npm run assets:environments",
     "dev": "vite",
+    "mcp": "node mcp/server.mjs",
     "build": "vite build",
     "baseline:compare": "node scripts/compare-baselines.mjs",
     "preview": "vite preview",
     "baseline:capture": "node scripts/baseline-capture.mjs",
     "verify:rockgen": "node scripts/verify-rockgen.mjs",
-    "visual:check": "node scripts/visual-check.mjs"
+    "verify:pathgen": "node scripts/verify-pathgen.mjs",
+    "visual:check": "node scripts/visual-check.mjs",
+    "verify:propgen": "node scripts/verify-propgen.mjs",
+    "verify:buildinggen": "node scripts/verify-buildinggen.mjs",
+    "verify:villagegen": "node scripts/verify-villagegen.mjs",
+    "verify:fauna": "node scripts/verify-fauna.mjs",
+    "verify:ambientfx": "node scripts/verify-ambientfx.mjs",
+    "verify:vfxgen": "node scripts/verify-vfxgen.mjs",
+    "verify:water": "node scripts/verify-watergen.mjs",
+    "verify:lighting": "node scripts/verify-lighting.mjs",
+    "verify:lighting-lab": "node scripts/verify-lighting-lab.mjs",
+    "verify:weather": "node scripts/verify-weather.mjs",
+    "verify:sky": "node scripts/verify-sky.mjs",
+    "verify:grass": "node scripts/verify-grass-palettes.mjs",
+    "verify:vegetation-shader": "node scripts/verify-vegetation-shader.mjs",
+    "verify:api": "node scripts/verify-public-api.mjs",
+    "verify:generation": "node scripts/verify-generation.mjs",
+    "verify:post": "node scripts/verify-post.mjs",
+    "verify:camera": "node scripts/verify-camera.mjs",
+    "verify:motion": "node scripts/verify-motion.mjs",
+    "verify:biome": "node scripts/verify-biome.mjs",
+    "verify:soundscape": "node scripts/verify-soundscape.mjs",
+    "verify:game-feel": "node scripts/verify-game-feel.mjs",
+    "verify:all": "npm run verify:generation && npm run verify:post && npm run verify:camera && npm run verify:motion && npm run verify:biome && npm run verify:soundscape && npm run verify:game-feel && npm run verify:rockgen && npm run verify:pathgen && npm run verify:propgen && npm run verify:buildinggen && npm run verify:villagegen && npm run verify:fauna && npm run verify:ambientfx && npm run verify:vfxgen && npm run verify:water && npm run verify:lighting && npm run verify:lighting-lab && npm run verify:weather && npm run verify:sky && npm run verify:grass && npm run verify:vegetation-shader && npm run verify:api && npm run verify:catalog && npm run verify:assetlib && npm run verify:mcp",
+    "verify:catalog": "node scripts/verify-catalog.mjs",
+    "verify:assetlib": "node scripts/verify-assetlib.mjs",
+    "verify:mcp": "node scripts/verify-mcp.mjs",
+    "thumbs:prop": "node scripts/generate-prop-thumbs.mjs",
+    "thumbs:building": "node scripts/generate-building-thumbs.mjs",
+    "thumbs:catalog": "node scripts/generate-catalog-thumbs.mjs",
+    "thumbs:home": "node scripts/generate-home-shots.mjs"
   },
   "peerDependencies": {
     "@pixiv/three-vrm": "^3.5.4",
+    "three": "^0.185.1",
     "three-mesh-bvh": "^0.8.3",
-    "three-stdlib": "^2.36.1",
-    "three": "^0.185.1"
+    "three-stdlib": "^2.36.1"
   },
   "peerDependenciesMeta": {
     "@pixiv/three-vrm": {
@@ -87,6 +145,7 @@
     "@vitejs/plugin-react": "^4.7.0",
     "ecctrl": "^1.0.97",
     "lucide-react": "^1.23.0",
+    "marked": "^18.0.6",
     "playwright": "^1.60.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",

package/src/ambientfx/INTEGRATION.md

@@ -0,0 +1,164 @@
+# Ambient VFX — integration snippets
+
+The `src/ambientfx/` cluster is self-contained; these are the EXACT edits to
+shared files that wire it into the library. Apply verbatim.
+
+## 1. `src/index.js` — root export
+
+Add after the `stylizedTerrain.js` line:
+
+```js
+export * from './ambientfx/index.js';
+```
+
+## 2. `package.json` — subpath export
+
+Add to `"exports"` after `"./pathgen"`:
+
+```json
+"./ambientfx": "./src/ambientfx/index.js",
+```
+
+## 3. `vite.config.js` — package alias
+
+Add `'ambientfx'` to the subpath array (order inside the array doesn't
+matter; subpath entries must stay before the bare root entry, which the array
+already guarantees):
+
+```js
+  ...['toon', 'environment', 'water', 'vegetation', 'sky', 'post', 'rockgen',
+    'debrisgen', 'pathgen', 'texgen', 'character', 'loaders', 'debug', 'ambientfx'].map((subpath) => ({
+    find: `@call-me-sensei/toonlab/${subpath}`,
+    replacement: resolve(__dirname, `src/${subpath}/index.js`),
+  })),
+```
+
+Once aliased, `examples/ambientfx-demo/main.js` line
+`import { createAmbientFx } from '../../src/ambientfx/index.js';` can become
+`import { createAmbientFx } from '@call-me-sensei/toonlab/ambientfx';`.
+
+## 4. `src/stylizedWorld.js` — `createStylizedWorld({ ambientfx })` wiring
+
+Import at the top:
+
+```js
+import { createAmbientFx } from './ambientfx/index.js';
+```
+
+Add an `ambientfx = false` option to the destructured signature. After the
+grass/flowers blocks (so `heightFogParams`, `environmentBox`, `waterSurface`,
+and `followTarget` are in scope), create the system — the important part is
+that it RECEIVES the world's wind, height-fog, sun, and time-of-day instead
+of inventing its own:
+
+```js
+  // Ambient atmosphere: petals/leaves/fireflies/pollen/mist over one GPU
+  // particle backbone, in a follow window like the grass.
+  let ambientFx = null;
+  if (ambientfx) {
+    const fxOptions = cleanObject(ambientfx);
+    ambientFx = createAmbientFx({
+      followTarget,
+      heightAt,
+      seed: Number(fxOptions.seed) || 1,
+      waterLevel: waterSurface ? waterLevel : null,
+      ...fxOptions,
+    });
+    // One wind for the whole world: reuse the exact grass wind settings.
+    const grassWind = grassField?.settings ?? {};
+    ambientFx.setWind({
+      windDirection: grassWind.windDirection,
+      windSpeed: grassWind.windSpeed,
+      windStrength: grassWind.windStrength,
+    });
+    // Same height-fog layer terrain/water/forest already share.
+    ambientFx.setDistanceFog({
+      color: heightFogParams.heightFogColor ?? [0.66, 0.8, 0.94],
+      density: Number(heightFogParams.heightFogDensity) || 0.0016,
+      falloff: Number(heightFogParams.heightFogFalloff) || 400,
+      floorY: environmentBox.min.y,
+    });
+    if (sunDirection) ambientFx.setSun({ direction: sunDirection });
+    scene.add(ambientFx.root);
+  }
+```
+
+In the returned object add `ambientFx,` and in `world.update(delta)` add:
+
+```js
+    ambientFx?.update(delta, camera);
+```
+
+In `dispose()` add `ambientFx?.dispose();` and include `ambientFx?.root` in
+the parent-removal list.
+
+Time of day: hosts that drive `applyEnvironmentTimeOfDay(state, ...)` should
+also call `world.ambientFx?.setTimeOfDay(state.hour)` in the same place (or
+pass `ambientfx: { timeOfDay: () => clock.hour }` and never think about it) —
+fireflies/pollen/mist gates follow that one canonical hour.
+
+Bloom sources (petals from flowering canopies, leaves from autumn ones) are
+host-registered because only the host knows which recipes flower:
+
+```js
+world.ambientFx?.addBloomSources(
+  floweringTreePlacements.map((p) => ({
+    color: [1.0, 0.66, 0.8],        // the recipe's bloom color
+    effect: 'petals',                // or 'leaves' for autumn canopies
+    radius: treeSize * 0.85,
+    x: p.x, y: p.y + treeSize * 1.6, z: p.z,
+  })),
+);
+```
+
+Water note: the mist mesh carries `userData.waterExclude` itself; fireflies
+and petals deliberately stay in the water passes so they reflect. Verify the
+firefly reflection reads once wired into a world with water (the standalone
+demo has no water surface).
+
+## 5. `scripts/generate-settings-reference.mjs` — MODULES entry
+
+Add to the `MODULES` array (after the Paths entry):
+
+```js
+  {
+    title: 'Ambient VFX',
+    subpath: 'toonlab/ambientfx',
+    module: '/src/ambientfx/ambientFxSettings.js',
+    groups: 'AMBIENTFX_SETTING_GROUPS',
+    schema: 'AMBIENTFX_SETTING_FIELD_SCHEMA',
+    note: 'Settings are nested per group: `createAmbientFx({ settings: { fireflies: { blinkSpeed: 0.8 } } })`. Effect entries in `effects` override their group; `density` there is a multiplier.',
+  },
+```
+
+## 6. `AGENTS.md` — subpath list line
+
+In the "Subpath imports" paragraph, add `/ambientfx` to the list, e.g.:
+
+```
+`/toon` `/environment` `/water` `/vegetation` (incl. scatter helpers +
+`StylizedForest`) `/sky` `/post` `/character` `/loaders` `/rockgen`
+`/debrisgen` `/pathgen` `/ambientfx` (petals/leaves/fireflies/pollen/mist —
+one particle backbone, 3 draw calls, follow-window like grass) `/debug`; ...
+```
+
+## 7. `examples/outdoor-world/main.js` — `?nofx` perf toggle sketch
+
+With the world wiring from §4 the example only needs the toggle plus the
+per-effect URL knobs (matching the existing `?nograss`/`?notrees` idiom):
+
+```js
+    // Ambient atmosphere (?nofx=1 disables; ?fireflies=2 &petals=0 etc.
+    // scale/kill individual effects for perf triage).
+    ambientfx: params.has('nofx') ? false : {
+      effects: Object.fromEntries(['petals', 'leaves', 'fireflies', 'pollen', 'mist']
+        .map((id) => [id, params.has(id)
+          ? (Number(params.get(id)) > 0 ? { density: Number(params.get(id)) } : false)
+          : true])),
+      seed: WORLD.seed,
+      timeOfDay: () => 14, // swap for the game clock when one exists
+    },
+```
+
+…passed inside the existing `createStylizedWorld({ ... })` options object.
+Update the `#hint` copy to mention `?nofx`.