@call-me-sensei/toonlab 0.2.0 → 0.3.1

package/src/stylizedWorld.js

@@ -13,6 +13,10 @@ import { StylizedSky } from './sky/stylizedSky.js';
 import { StylizedGrassField } from './vegetation/stylizedGrass.js';
 import { StylizedFlowerField } from './vegetation/stylizedFlowers.js';
 import { StylizedForest } from './vegetation/stylizedForest.js';
+import {
+  applyVegetationShader,
+  createVegetationShaderSettings,
+} from './vegetation/vegetationShaders.js';
 import {
   combineMasks,
   createSlopeMask,
@@ -22,6 +26,13 @@ import {
 } from './vegetation/scatter.js';
 import { resolveWorldPreset } from './worldPresets.js';
 import { createWorldCollision } from './worldCollision.js';
+import { createStylizedPaths } from './pathgen/stylizedPaths.js';
+import { connectPointsOfInterest } from './pathgen/pathRouter.js';
+import { createStylizedVillage } from './villagegen/stylizedVillage.js';
+import { pickPoiSites } from './villagegen/villageSites.js';
+import { createFauna } from './fauna/index.js';
+import { createAmbientFx } from './ambientfx/index.js';
+import { createWeatherSystem } from './weather/index.js';
 
 // The composed golden path: one call assembles a complete stylized outdoor
 // world — environment-shaded terrain, sun rig, sky dome, interactive water,
@@ -54,6 +65,15 @@ function cleanObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 
+function sunColorArray(value, fallback) {
+  if (value?.isColor) return [value.r, value.g, value.b];
+  if (Array.isArray(value) && value.length >= 3) {
+    const next = value.slice(0, 3).map(Number);
+    if (next.every(Number.isFinite)) return next;
+  }
+  return fallback.slice();
+}
+
 /**
  * Assembles a stylized outdoor world from a world preset.
  *
@@ -70,20 +90,33 @@ function cleanObject(value) {
  * @param {string} [options.preset] World preset name (default 'outdoorGameplay').
  * @param {Object|false} [options.water] `{ level, width, depth, settings }`,
  *   or `false` to skip water.
+ * @param {Object|false} [options.paths] A network from `createStylizedPaths`
+ *   OR options for one (`{ seed, auto, routes, settings }`). Wired fully:
+ *   ribbons join the environment shading + fog, the on-path mask parts
+ *   grass/flowers/trees, bridge rails register collision, and
+ *   `collision.groundHeight` follows the flattened `paths.heightAt`.
  * @param {Object|false} [options.trees] `{ scatter, settings, center }`
  *   overrides over the world preset, or `false` to skip.
  * @param {Object|false} [options.grass] Same shape as trees, or `false`.
  * @param {Object|false} [options.flowers] `{ scatter, settings }`; off unless given.
+ * @param {Object|string} [options.vegetationShader] One IP-wide vegetation
+ *   shader profile/settings object. Albedo, construction, and live world
+ *   values remain owned by trees/grass/flowers and the host scene.
  * @param {Object3D} [options.followTarget] Character root: water ripple
  *   window + interactor splashes/wakes, grass push-away.
  * @param {Object|false} [options.cloudShadows] `{ strength, coverage, scale,
- *   velocity }` shared across terrain, water, grass, and trees.
+ *   velocity }` legacy override merged into the weather cloud field.
+ * @param {Object|false} [options.weather] `{ preset, settings, seed }` builds
+ *   the shared weather coordinator. `false` keeps the legacy static cloud
+ *   shadow path. Defaults to the world preset's Call Me Sensei weather.
  * @param {boolean} [options.sun] Build the environment sun rig (default true).
  * @param {boolean} [options.applyCamera] Apply preset camera planes (default true).
  * @param {Object} [options.environment] Extra `applyEnvironmentShader`
  *   options merged last (features/parameters/roleOverrides/...).
- * @returns {Promise<Object>} `{ update, dispose, sky, water, sunRig, grass,
- *   flowerField, trees, treeGroup, masks, worldPreset, classification }`
+ * @returns {Promise<Object>} `{ update, dispose, sky, water, sunRig, sunState,
+ *   setSun, grass, flowerField, forest, masks, worldPreset, classification }`.
+ *   `setSun({ direction, color, sky })` is the transient scene-light adapter
+ *   used by Lighting and Weather; it does not rewrite portable asset presets.
  */
 export async function createStylizedWorld({
   renderer,
@@ -92,14 +125,20 @@ export async function createStylizedWorld({
   terrain,
   preset = 'outdoorGameplay',
   water = {},
+  paths = false,
+  pois = false,
+  fauna = false,
+  ambientfx = false,
+  weather = {},
   sky: skyOptions = {},
   fog = {},
   shadows = {},
   trees = {},
   grass = {},
   flowers = false,
+  vegetationShader = {},
   followTarget = null,
-  cloudShadows = { strength: 0.35 },
+  cloudShadows = null,
   sun = true,
   applyCamera = true,
   environment = {},
@@ -111,6 +150,7 @@ export async function createStylizedWorld({
 
   const worldPreset = resolveWorldPreset(preset);
   if (!worldPreset) throw new Error(`Unknown world preset "${preset}".`);
+  let vegetationShaderSettings = createVegetationShaderSettings(vegetationShader);
 
   // terrain.size accepts a number (square), { width, depth }, or { x, z }
   // (the shape createStylizedTerrain returns as meshExtent) — silently
@@ -128,6 +168,104 @@ export async function createStylizedWorld({
     camera.updateProjectionMatrix();
   }
 
+  // POIs before paths, paths before the environment conversion. Villages
+  // contribute their street centerlines as explicit routes, and their
+  // entries become router nodes — roads between settlements come free.
+  const earlyWaterLevel = water !== false ? Number(cleanObject(water).level) || 0 : 0;
+  let poiList = [];
+  const poiRoutes = [];
+  if (pois && heightAt) {
+    const poiOptions = cleanObject(pois);
+    const poiSeed = Math.round(Number(poiOptions.seed) || 1);
+    const requests = [];
+    for (const [key, archetype] of [
+      ['villages', 'village'],
+      ['shrines', 'shrine'],
+      ['ruins', 'ruin'],
+      ['campsites', 'campsite'],
+      ['pierHamlets', 'pierHamlet'],
+    ]) {
+      const count = Math.max(Math.round(Number(poiOptions[key]) || 0), 0);
+      if (count > 0) requests.push({ archetype, count });
+    }
+    // Hosts with decorative rims beyond the playable area pass pois.size to
+    // keep settlements reachable.
+    const poiSize = poiOptions.size ?? { x: width, z: depth };
+    const sites = pickPoiSites({
+      heightAt,
+      requests,
+      seed: poiSeed,
+      size: poiSize,
+      waterLevel: earlyWaterLevel,
+    });
+    poiList = sites.map((site) => {
+      const village = createStylizedVillage({
+        archetype: site.archetype,
+        center: { x: site.x, z: site.z },
+        heightAt,
+        parent: terrainRoot,
+        radius: site.radius,
+        seed: site.seed,
+        waterLevel: earlyWaterLevel,
+      });
+      poiRoutes.push(...village.streetRoutes);
+      return village;
+    });
+    // Connect POI entries into a road network (MST + occasional loop).
+    const entryNodes = poiList.map((poi) => ({
+      x: (poi.entries[0].x + poi.entries[1].x) / 2,
+      z: (poi.entries[0].z + poi.entries[1].z) / 2,
+    }));
+    if (entryNodes.length >= 2) {
+      const edges = connectPointsOfInterest(entryNodes, { loopChance: 0.3, seed: poiSeed });
+      for (const [fromIndex, toIndex] of edges) {
+        const fromPoi = poiList[fromIndex];
+        const toPoi = poiList[toIndex];
+        // route from the nearest entry of one place to the nearest of the other
+        let bestPair = null;
+        for (const from of fromPoi.entries) {
+          for (const to of toPoi.entries) {
+            const distance = (from.x - to.x) ** 2 + (from.z - to.z) ** 2;
+            if (!bestPair || distance < bestPair.distance) bestPair = { distance, from, to };
+          }
+        }
+        poiRoutes.push({
+          from: [bestPair.from.x, bestPair.from.z],
+          style: 'dirt',
+          to: [bestPair.to.x, bestPair.to.z],
+        });
+      }
+    }
+  }
+
+  // Path network before the environment conversion, so ribbons and bridges
+  // parented under the terrain root get shaded (and join the height fog)
+  // exactly like the terrain itself. Accepts a prebuilt network or builds
+  // one here from the terrain contract.
+  let pathsSystem = null;
+  let ownsPaths = false;
+  if (paths || poiRoutes.length > 0) {
+    if (paths && typeof paths.maskAt === 'function' && paths.root) {
+      pathsSystem = paths;
+    } else if (heightAt) {
+      const pathOptions = cleanObject(paths);
+      const userRoutes = Array.isArray(pathOptions.routes) ? pathOptions.routes : [];
+      const hasExplicit = userRoutes.length > 0 || poiRoutes.length > 0;
+      pathsSystem = createStylizedPaths({
+        auto: pathOptions.auto
+          ?? (hasExplicit || !paths ? null : { count: pathOptions.count ?? 4, styles: pathOptions.styles ?? ['dirt'] }),
+        heightAt,
+        routes: [...poiRoutes, ...userRoutes],
+        seed: pathOptions.seed ?? 1,
+        settings: pathOptions.settings ?? {},
+        size: { x: width, z: depth },
+        waterLevel: earlyWaterLevel,
+      });
+      ownsPaths = true;
+    }
+    if (pathsSystem?.root && !pathsSystem.root.parent) terrainRoot.add(pathsSystem.root);
+  }
+
   // Environment shading over the terrain (and anything parented under it).
   const environmentBox = new THREE.Box3().setFromObject(terrainRoot);
   const environmentPreset = resolveEnvironmentPreset(worldPreset.environment?.preset ?? 'default') ?? {};
@@ -192,6 +330,15 @@ export async function createStylizedWorld({
       } : {}),
     })
     : null;
+  const sunDirectionState = Array.isArray(skySunDirection)
+    ? new THREE.Vector3(...skySunDirection)
+    : (sunRig?.light
+      ? sunRig.light.position.clone().sub(sunRig.light.target.position)
+      : new THREE.Vector3(0.35, 0.8, 0.45));
+  if (sunDirectionState.lengthSq() < 1e-8) sunDirectionState.set(0.35, 0.8, 0.45);
+  sunDirectionState.normalize();
+  const sunColorState = [1, 0.96, 0.84];
+  const sunSkyColorState = [0.62, 0.78, 0.95];
 
   // Shadows are ON by default — a character that casts nothing on the grass
   // is the fastest way for a stylized world to read fake. The renderer's
@@ -233,14 +380,7 @@ export async function createStylizedWorld({
       // elevation by the terrain box's aspect ratio — a 2 km × 200 m box
       // squashes a 2 PM sun nearly horizontal, and shadows land tens of
       // meters away from their casters.)
-      const direction = Array.isArray(skySunDirection)
-        ? new THREE.Vector3(
-          skySunDirection[0],
-          Math.max(skySunDirection[1], 0.15),
-          skySunDirection[2],
-        )
-        : light.position.clone().sub(environmentBox.getCenter(new THREE.Vector3()));
-      sunShadowOffset = direction.normalize().multiplyScalar(shadowArea * 3 + 120);
+      sunShadowOffset = sunDirectionState.clone().multiplyScalar(shadowArea * 3 + 120);
       scene.add(light.target);
     }
   }
@@ -264,6 +404,46 @@ export async function createStylizedWorld({
   };
   followSunShadow();
 
+  // One scene-input adapter keeps the actual DirectionalLight, shadow follow,
+  // and every custom vegetation shader on the same sun/sky values. These are
+  // transient scene values: authored Grass/Flower/Tree settings stay intact.
+  const setSun = ({ direction, color, sky: skyColor } = {}) => {
+    if (direction !== undefined) {
+      const channels = direction?.isVector3
+        ? [direction.x, direction.y, direction.z]
+        : direction;
+      if (Array.isArray(channels) && channels.length >= 3) {
+        const next = channels.slice(0, 3).map(Number);
+        if (next.every(Number.isFinite)) sunDirectionState.fromArray(next);
+      }
+      if (sunDirectionState.lengthSq() < 1e-8) sunDirectionState.set(0.35, 0.8, 0.45);
+      sunDirectionState.normalize();
+    }
+    if (color !== undefined) sunColorState.splice(0, 3, ...sunColorArray(color, sunColorState));
+    if (skyColor !== undefined) sunSkyColorState.splice(0, 3, ...sunColorArray(skyColor, sunSkyColorState));
+
+    // A direction is not an environment-relative point. The rig owns a true
+    // direction adapter so non-square worlds and shadows:false remain aligned.
+    sunRig?.setDirection?.(sunDirectionState);
+    sunRig?.setState?.({ color: new THREE.Color().setRGB(...sunColorState) });
+    if (sunShadowOffset) {
+      sunShadowOffset.copy(sunDirectionState).multiplyScalar(shadowArea * 3 + 120);
+      followSunShadow();
+    }
+
+    const current = {
+      color: sunColorState.slice(),
+      direction: sunDirectionState.toArray(),
+      sky: sunSkyColorState.slice(),
+    };
+    grassField?.setSun?.(current);
+    flowerField?.setSun?.(current);
+    forest?.setSun?.(current);
+    ambientFx?.setSun?.({ direction: current.direction });
+    return current;
+  };
+  const setSunDirection = (value) => setSun({ direction: value }).direction;
+
   // Sky dome — the water's reflection fallback, so it comes before water.
   const sky = new StylizedSky({
     preset: worldPreset.sky?.preset,
@@ -277,12 +457,23 @@ export async function createStylizedWorld({
   let waterSurface = null;
   if (water !== false) {
     const waterOptions = cleanObject(water);
+    const {
+      depth: configuredDepth,
+      level: _waterLevel,
+      settings: configuredWaterSettings,
+      width: configuredWidth,
+      ...waterRuntimeOptions
+    } = waterOptions;
     waterSurface = new WaterSurface({
       preset: worldPreset.water?.preset,
-      width: Number(waterOptions.width) || width,
-      depth: Number(waterOptions.depth) || depth,
+      width: Number(configuredWidth) || width,
+      depth: Number(configuredDepth) || depth,
       ...(heightAt ? { bedHeight: heightAt } : {}),
-      ...cleanObject(waterOptions.settings),
+      // Runtime stages (passes/simulation/splashes/currentField/etc.) are
+      // valid composed-world options too; previously only material settings
+      // made it through this wrapper.
+      ...waterRuntimeOptions,
+      ...cleanObject(configuredWaterSettings),
     });
     waterSurface.position.y = waterLevel;
     // Match the environment's height fog so far-shore water hazes exactly
@@ -299,14 +490,50 @@ export async function createStylizedWorld({
     }
   }
 
-  // Placement masks: no vegetation on cliffs or under water.
+  // Placement masks: no vegetation on cliffs, under water, or on paths.
   const masks = heightAt
     ? {
       slope: createSlopeMask({ heightAt, maxSlope: 0.55 }),
       water: createWaterMask({ heightAt, margin: 0.4, waterLevel }),
     }
     : null;
-  const vegetationMask = masks ? combineMasks(masks.slope, masks.water) : null;
+  if (masks && pathsSystem) {
+    // Grass/flowers/trees part around the network instead of growing
+    // through the road surface. The low threshold clears a shoulder wide
+    // enough that meter-tall blades can't lean over the ribbon.
+    masks.paths = (x, z) => pathsSystem.maskAt(x, z) <= 0.12;
+  }
+  if (masks && poiList.length > 0) {
+    // No trees through roofs: a coarse spatial hash over every POI blocker
+    // circle (buildings, wells, fences) keeps scatter out of settlements.
+    const cell = 8;
+    const buckets = new Map();
+    for (const poi of poiList) {
+      for (const circle of poi.blockers) {
+        const pad = circle.radius + 1.2;
+        for (let ix = Math.floor((circle.x - pad) / cell); ix <= Math.floor((circle.x + pad) / cell); ix += 1) {
+          for (let iz = Math.floor((circle.z - pad) / cell); iz <= Math.floor((circle.z + pad) / cell); iz += 1) {
+            const key = `${ix},${iz}`;
+            const bucket = buckets.get(key);
+            if (bucket) bucket.push(circle);
+            else buckets.set(key, [circle]);
+          }
+        }
+      }
+    }
+    masks.pois = (x, z) => {
+      const bucket = buckets.get(`${Math.floor(x / cell)},${Math.floor(z / cell)}`);
+      if (!bucket) return true;
+      for (const circle of bucket) {
+        const pad = circle.radius + 1.2;
+        if ((circle.x - x) ** 2 + (circle.z - z) ** 2 < pad * pad) return false;
+      }
+      return true;
+    };
+  }
+  const vegetationMask = masks
+    ? combineMasks(masks.slope, masks.water, masks.paths, masks.pois)
+    : (pathsSystem ? (x, z) => pathsSystem.maskAt(x, z) <= 0.12 : null);
   const defaultCenter = followTarget?.position ?? { x: 0, z: 0 };
   // Per-system custom masks (e.g. a createNoisePatchMask forest-cluster
   // mask) AND with the built-in slope/water masks.
@@ -338,6 +565,7 @@ export async function createStylizedWorld({
       // merged-geometry impostors (~12k verts/tree) that get redrawn by the
       // main, water, and shadow passes — the difference between 20 and 60 fps.
       renderer,
+      vegetationShader: vegetationShaderSettings,
       settings: {
         ...cleanObject(worldPreset.trees?.settings),
         ...cleanObject(treeOptions.settings),
@@ -362,6 +590,7 @@ export async function createStylizedWorld({
   // the window edge. Far grass simply doesn't exist — same as the anime
   // games this emulates.
   let grassField = null;
+  let weatherSystem = null;
   const grassState = { center: null, options: cleanObject(grass), radius: 0 };
   const buildGrassAt = (center) => {
     const grassOptions = grassState.options;
@@ -381,6 +610,7 @@ export async function createStylizedWorld({
       preset: worldPreset.grass?.preset,
       ...cleanObject(worldPreset.grass?.settings),
       ...cleanObject(grassOptions.settings),
+      vegetationShader: vegetationShaderSettings,
       placements,
     });
     field.setDistanceFade({ end: grassState.radius * 0.98, start: grassState.radius * 0.62 });
@@ -407,6 +637,7 @@ export async function createStylizedWorld({
     if (previous && grassField !== previous) {
       scene.remove(previous);
       previous.dispose();
+      weatherSystem?.refresh();
     }
   };
 
@@ -425,18 +656,88 @@ export async function createStylizedWorld({
     if (placements.length > 0) {
       flowerField = new StylizedFlowerField({
         ...cleanObject(flowerOptions.settings),
+        vegetationShader: vegetationShaderSettings,
         placements,
       });
       scene.add(flowerField);
     }
   }
 
+  // The living layer: instanced GPU-animated ambient creatures, staggered
+  // steering, budgets as populations. Off unless asked for.
+  let faunaSystem = null;
+  if (fauna && heightAt) {
+    const faunaOptions = cleanObject(fauna);
+    faunaSystem = createFauna({
+      bounds: { x: width / 2 - 10, z: depth / 2 - 10 },
+      followTarget,
+      heightAt,
+      masks: { flowers: faunaOptions.flowerMask ?? vegetationMask ?? null },
+      preset: faunaOptions.preset ?? null,
+      seed: faunaOptions.seed ?? 1,
+      settings: faunaOptions.settings ?? {},
+      species: faunaOptions.species ?? {},
+      waterLevel,
+    });
+    // Same height-fog layer terrain/water/forest get — birds that skip it
+    // stay sharp saturated specks on hazed mountains.
+    faunaSystem.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,
+    });
+    scene.add(faunaSystem.root);
+  }
+
+  // Ambient atmosphere: petals/leaves/fireflies/pollen/mist over one GPU
+  // particle backbone, in a follow window like the grass. One wind for the
+  // whole world.
+  let ambientFx = null;
+  if (ambientfx) {
+    const fxOptions = cleanObject(ambientfx);
+    ambientFx = createAmbientFx({
+      followTarget,
+      heightAt,
+      seed: Number(fxOptions.seed) || 1,
+      waterLevel: waterSurface ? waterLevel : null,
+      ...fxOptions,
+    });
+    const grassWind = grassField?.settings ?? {};
+    ambientFx.setWind({
+      windDirection: grassWind.windDirection,
+      windSpeed: grassWind.windSpeed,
+      windStrength: grassWind.windStrength,
+    });
+    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 (Array.isArray(skySunDirection)) ambientFx.setSun({ direction: skySunDirection });
+    scene.add(ambientFx.root);
+  }
+
+  // Align all scene consumers with the authored Sky before Weather or an
+  // optional LightingSystem adds transient layers.
+  setSun({
+    color: sky.renderedSettings?.sunColor ?? sky.settings?.sunColor,
+    direction: sunDirectionState,
+    sky: sky.renderedSettings?.horizonColor ?? sky.settings?.horizonColor,
+  });
+
   // Walkability: circle blockers on a spatial hash, tree trunks
   // pre-registered, so characters can't walk through the world ToonLab just
   // built. Hosts add their own blockers (rocks, props) via
   // `world.collision.addCircles(...)` and call
   // `world.collision.resolve(character.position, radius)` per frame.
-  const collision = createWorldCollision({ heightAt });
+  // Ground truth follows the flattened path profile where one exists, so
+  // characters walk the road surface (and bridge decks) instead of the raw
+  // terrain underneath.
+  const collision = createWorldCollision({ heightAt: pathsSystem?.heightAt ?? heightAt });
+  if (pathsSystem?.blockers?.length) collision.addCircles(pathsSystem.blockers);
+  for (const poi of poiList) collision.addCircles(poi.blockers);
   if (forest) {
     const trunkScale = [
       cleanObject(cleanObject(trees).settings).size,
@@ -452,9 +753,65 @@ export async function createStylizedWorld({
     setEnvironmentCloudShadow(field);
     waterSurface?.setCloudShadow(field);
     grassField?.setCloudShadow(field);
+    flowerField?.setCloudShadow(field);
     forest?.setCloudShadow(field);
+    faunaSystem?.setCloudShadow?.(field);
   };
-  if (cloudShadows !== false) applyCloudShadow(cleanObject(cloudShadows));
+  if (weather === false) {
+    if (cloudShadows !== false) applyCloudShadow(
+      cloudShadows === null ? { strength: 0.35 } : cleanObject(cloudShadows),
+    );
+  } else {
+    const weatherOptions = cleanObject(weather);
+    const presetWeatherSettings = cleanObject(worldPreset.weather?.settings);
+    const optionWeatherSettings = cleanObject(weatherOptions.settings);
+    const weatherSettings = {
+      ...presetWeatherSettings,
+      ...optionWeatherSettings,
+      atmosphere: {
+        ...cleanObject(presetWeatherSettings.atmosphere),
+        ...cleanObject(optionWeatherSettings.atmosphere),
+      },
+    };
+    const legacyCloud = cloudShadows === false
+      ? { strength: 0 }
+      : (cloudShadows === null ? {} : cleanObject(cloudShadows));
+    weatherSystem = createWeatherSystem({
+      ambientFx,
+      camera,
+      environmentRoot: terrainRoot,
+      fauna: faunaSystem,
+      flowers: flowerField,
+      followTarget,
+      forest: () => forest,
+      getSun: () => ({
+        color: sunColorState.slice(),
+        direction: sunDirectionState.toArray(),
+        sky: sunSkyColorState.slice(),
+      }),
+      grass: () => grassField,
+      groundHeightAt: heightAt,
+      precipitationFloorY: environmentBox.min.y,
+      preset: weatherOptions.preset ?? worldPreset.weather?.preset ?? 'call_me_sensei',
+      renderer,
+      scene,
+      seed: Number(weatherOptions.seed) || 1,
+      setCloudShadow: applyCloudShadow,
+      setSun,
+      settings: {
+        ...weatherSettings,
+        atmosphere: {
+          ...cleanObject(weatherSettings.atmosphere),
+          ...(Number.isFinite(legacyCloud.strength) ? { cloudShadowStrength: legacyCloud.strength } : {}),
+          ...(Number.isFinite(legacyCloud.coverage) ? { cloudShadowCoverage: legacyCloud.coverage } : {}),
+          ...(Number.isFinite(legacyCloud.scale) ? { cloudShadowScale: legacyCloud.scale } : {}),
+        },
+      },
+      sky,
+      sunRig,
+      water: waterSurface,
+    });
+  }
 
   let disposed = false;
   return {
@@ -465,18 +822,60 @@ export async function createStylizedWorld({
       disposed = true;
       sunShadowPass?.dispose();
       forest?.dispose();
-      for (const object of [sky, waterSurface, forest, grassField, flowerField, sunRig?.group ?? sunRig]) {
+      if (ownsPaths) pathsSystem?.dispose();
+      for (const poi of poiList) poi.dispose();
+      faunaSystem?.dispose();
+      ambientFx?.dispose();
+      weatherSystem?.dispose();
+      for (const object of [sky, waterSurface, forest, grassField, flowerField,
+        faunaSystem?.root, ambientFx?.root, sunRig?.group ?? sunRig]) {
         if (object?.parent) object.parent.remove(object);
       }
     },
     flowerField,
     fog: sceneFog,
     forest,
+    environmentRoot: terrainRoot,
     get grass() { return grassField; },
+    ambientFx,
+    fauna: faunaSystem,
     masks,
+    paths: pathsSystem,
+    pois: poiList,
     setCloudShadow: applyCloudShadow,
+    setSun,
+    setSunDirection,
+    setVegetationShader(profile) {
+      vegetationShaderSettings = createVegetationShaderSettings(profile);
+      const reports = [
+        applyVegetationShader(grassField, vegetationShaderSettings),
+        applyVegetationShader(flowerField, vegetationShaderSettings),
+        forest?.setVegetationShader?.(vegetationShaderSettings)
+          ?? applyVegetationShader(forest, vegetationShaderSettings),
+      ];
+      return {
+        applied: reports.reduce((sum, report) => sum + (report?.applied ?? 0), 0),
+        reports,
+        requiresForestImpostorRebake: Boolean(reports[2]?.requiresImpostorRebake),
+        settings: vegetationShaderSettings,
+        unsupported: reports.flatMap((report) => report?.unsupported ?? []),
+        writes: reports.reduce((sum, report) => sum + (report?.writes ?? 0), 0),
+      };
+    },
+    setWeather(presetOrSettings, options) {
+      return weatherSystem?.transitionTo(presetOrSettings, options) ?? null;
+    },
     sky,
+    get sunState() {
+      return {
+        color: sunColorState.slice(),
+        direction: sunDirectionState.toArray(),
+        sky: sunSkyColorState.slice(),
+      };
+    },
+    get sunDirection() { return sunDirectionState.toArray(); },
     sunRig,
+    weather: weatherSystem,
     /** Call once per frame before rendering. */
     update(delta = 0.016) {
       if (disposed) return;
@@ -488,6 +887,10 @@ export async function createStylizedWorld({
       shadowFrame += 1;
       if (sunShadowPass && shadowFrame % shadowInterval === 0) sunShadowPass.update();
       refreshGrassWindow();
+      weatherSystem?.update(delta);
+      for (const poi of poiList) poi.update(delta, camera);
+      faunaSystem?.update(delta);
+      ambientFx?.update(delta, camera);
       waterSurface?.update(renderer, scene, camera, delta);
       sky.update(delta, camera);
       grassField?.update(delta);