@call-me-sensei/toonlab 0.1.1 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,254 @@
+# ToonLab — guide for AI coding agents
+
+You are helping a developer use `@call-me-sensei/toonlab` (alias: `toonlab`),
+a stylized anime game kit for Three.js (WebGPU-first TSL materials, WebGL2
+fallback; 1 world unit = 1 meter). The look is NOT in any single API — it
+emerges from the assembly: sky feeds water reflections, an aligned sun rig +
+three-layer fog set the palette, cloud shadows tie ground/canopy/water
+together. Skipping the assembly produces gray, flat, "programmer-art" scenes.
+
+## Golden path — a full world in minutes
+
+```js
+import { createStylizedTerrain, createStylizedWorld } from '@call-me-sensei/toonlab';
+
+// 1. Terrain: any seed is a valid world. waterCoverage is the "more water"
+//    knob; height/depth set mountain amplitude and basin depth; size takes
+//    a number or { x, z }; floatingIslands / sinkholes are one option each.
+const terrain = createStylizedTerrain({
+  seed: 42,
+  size: 1000,
+  archetype: 'terracedKarst', // 'lakeland' | 'alpine' | 'rollingPlains' | 'archipelago'
+});
+const terrainRoot = new THREE.Group();
+terrainRoot.add(terrain.root);
+scene.add(terrainRoot);
+
+// 2. Everything else: environment shading, aligned sun + shadows, sky,
+//    water, LOD forests, follow-window grass, cloud shadows, collision.
+const world = await createStylizedWorld({
+  renderer, scene, camera,
+  terrain: { heightAt: terrain.heightAt, root: terrainRoot, size: terrain.meshExtent },
+  water: { level: terrain.waterLevel },
+  followTarget: characterRoot,               // splashes, wakes, grass push
+});
+characterRoot.position.copy(terrain.spawn);  // probed: walkable, near shore
+// render loop, before rendering:
+world.update(delta);
+```
+
+**Bring your own terrain** (no generator): the ONLY contract is a pure
+`heightAt(x, z) → meters` plus a displaced mesh under `terrain.root` with
+`frustumCulled = false`. Everything else (masks, scatter, collision,
+minimap) derives from `heightAt` and `water.level`. Even
+`heightAt = (x, z) => 12 * Math.sin(x / 90) * Math.cos(z / 90)` gives a
+complete shaded, forested, swimmable world.
+
+Character: `applyToonShader(root, { settings: createToonSettings({ preset:
+'call_me_sensei' }) })` + `createCharacterRenderPasses` (call
+`passes.update()` per frame). Post: `createPostProcessingPipeline` with
+preset `call_me_sensei`; `post.render(delta)` replaces `renderer.render`.
+Minimap: `createWorldMinimap({ heightAt, size, waterLevel, onPick })` —
+call `minimap.setPlayer(x, z, heading)` per frame.
+Every cluster has a `default` and a studio-managed `call_me_sensei` preset.
+
+## Quality rules (validated against reference-class modern anime worlds)
+
+- Align the visible sky sun and the light rig, and match the hour: 2 PM sun
+  is HIGH (`sunDirection` y ≈ 0.8, warm-white); golden hour is LOW (y ≈ 0.4).
+- Three-layer atmosphere: scene.fog (set by createStylizedWorld) +
+  environment heightFog (`heightFogColor` luminous blue [0.63,0.8,0.98],
+  density ≈ 0.0012–0.0016, falloff ≈ 400) + post depthCue (~0.3, blue).
+  White or absent fog is the #1 giveaway of a bad scene. EVERY custom
+  surface must join the height-fog layer or it reads as pasted on —
+  `createStylizedWorld` wires water and forest impostors automatically
+  (`setDistanceFog`); lower the density per aerial view or flyovers gray out.
+- Cast shadows: terrain `castShadow = true`, near rocks both flags, forests
+  `lod: { castShadow: true }` (only live near trees cast — correct).
+- Vividness is palette + saturation, not brightness: environment
+  `saturation ≈ 1.24`, `exposure ≈ 1.1`, `shadowTintColor [0.6,0.66,0.82]`,
+  saturated cerulean zenith, two-tone cumulus with blue-shaded bottoms,
+  green-dominant canopy list with ONE gold accent variant (muddy autumn
+  mixes read as confetti), turquoise water ramp.
+- Cluster forests with `createNoisePatchMask`; tree `size` 2.5–4.
+- Cliffs: steep faces need material, not flat paint — set
+  `material.userData.envTriplanarMap` (painted stone tile) +
+  `triplanarDetail: 1`, `triplanarDetailScale ≈ 14`,
+  `triplanarEdgeHighlight` for painted lip highlights; keep per-vertex
+  paint LOW-frequency (bands finer than the mesh grid alias into zigzag
+  triangles) and gate meadow/gold paint hard by slope.
+- Never let ground hover within ±1.6 m of water level over large areas
+  (broken water slivers); end the map in a hazy mountain rim;
+  `frustumCulled = false` on world-scale meshes.
+- Budgets: trees ≤ 3,000 via `StylizedForest` (16-vert billboard far LOD —
+  pass `renderer` or you get the expensive legacy path), grass ≤ 320k
+  blades in a follow window, startup < 10 s. Give every repeated mesh set
+  (rocks, cliff decor) a hi/lo distance LOD using TRUE 3D distance so
+  aerial cameras demote everything. Exclude above-water dressing from
+  water passes: `userData.waterExclude` (all passes) or
+  `waterGrabExclude` (refraction only, keeps the reflection).
+- Perf triage: add URL toggles per system and read the FPS meter — the
+  water scene passes (grab/depth/reflection) multiply every other cost, so
+  measure with and without water first. Scale them via
+  `water.settings.passes = { reflectionScale: 0.4, sceneColorScale: 0.6 }`.
+
+## Subpath imports
+
+`/toon` `/environment` `/lighting` `/weather` `/water` `/vegetation` (incl. scatter helpers +
+`StylizedForest`) `/vegetation-shaders` `/grass-palettes` `/sky` `/post` `/character` `/loaders` `/rockgen`
+`/debrisgen` `/pathgen` `/debug`; root adds `createStylizedTerrain`,
+`createStylizedWorld`, `createWorldCollision`, `createWorldMinimap`,
+`resolveWorldPreset`, `createStylizedPaths`.
+
+Authoring scope: Character/Vegetation/Environment Shader Labs save reusable
+IP-wide material treatments; Tree/Flower/Grass and other Asset Labs save asset
+identity and geometry; Water/Sky Labs save complete runtime-system presets
+with their shader controls embedded, so do not create separate Water Shader or
+Sky Shader documents. Current lighting, weather, camera, and interactions
+remain host-owned.
+
+Sky and Water keep authored and current-scene state separate. `.settings` is
+the portable authored baseline; `.renderedSettings` is the composition after
+named transient layers. Lighting, Weather, and other owners must use unique
+ids with `setSceneOverrideLayer`, clear only their own id with
+`clearSceneOverrideLayer`, and never persist the composed result. The manual
+`setSceneOverrides`/`clearSceneOverrides` pair owns only the `scene` layer;
+`clearAllSceneOverrideLayers` is for explicit host teardown.
+
+`lighting.attachWorld(world)` owns the world sun adapter plus private
+priority-100 Sky/Water layers. If Weather is present it also installs Lighting
+as Weather's sun/ambient/fog bridge: Lighting remains the sole writer, Weather
+provides modulation and private priority-200 Sky/Water layers, and either
+system removes only its own state on detach/dispose.
+The adapter is `world.setSun({ direction, color, sky })`; it aligns the real
+light/shadows with Grass, Flower, Forest, Ambient FX, Sky, and Water inputs.
+For a standalone custom Weather coordinator, supply paired `getSun`/`setSun`
+and baselines for any write-only cloud/surface adapters so teardown is exact.
+
+Sky documents contain exactly 46 portable art fields; constructor-only radius
+and quality are excluded. Sky quality is compile-time (`low`/`medium`/`high`
+= 2/3/4 cloud octaves, or custom `{ cloudOctaves: 1..5 }`), and
+`sky.setQuality()` rebuilds the material while preserving authored/layered
+state. Water quality is selected when constructing `WaterSurface`; a tier
+change requires replacing/rebuilding the surface, never `applySettings()`.
+
+Lighting (`/lighting`) owns portable, versioned recipes and looks rather than
+a replacement renderer. Use `createLightingManager({ scene, camera, renderer,
+recipe, quality })`, call `update()` as the focus/camera moves, and save JSON
+with the recipe/look serializers. Luminaire, rig, look, and quality presets
+come from `getLightingPresetOptions(kind)`. Disc/tube area lights, IES, tag
+linking, and Unreal Engine 5.8 MegaLights/Lumen are explicit adapter intent;
+the capability report and diagnostics state each runtime fallback. Author and
+stress-test them in `/lighting-lab/`.
+
+`createLightingManager` is the lower-level rig-realization API. For a composed
+world and day cycle, use `createLightingSystem(...)`, then call
+`lighting.attachWorld(world)` for the sun/Sky/Water ownership and Weather
+modulation bridge described above.
+
+Paths/roads/bridges: `createStylizedWorld({ paths: { seed, auto: { count: 4,
+styles: ['dirt', 'stone'] } } })` routes seeded trails around slopes, bridges
+water crossings, parts grass/trees around the ribbon, and feeds the flattened
+profile to `world.collision.groundHeight` — use that (not raw `heightAt`) for
+character ground so bridges carry the walk. Minimap: pass `paths: world.paths`
+to `createWorldMinimap` for the network overlay.
+
+Catalog (`@call-me-sensei/toonlab/catalog`): the whole procedural library,
+queryable and spawnable —
+`catalog.list({ tags, cluster, text })`, `catalog.get(id)`, and the headline
+`catalog.spawn(id, { seed })` → a PropAsset for any prop / building / tree /
+rock / debris entry (settings presets throw with their copy-paste snippet
+instead). `catalog.register(entry)` adds user assets;
+`catalog.addSource(url, { headers })` mounts remote registries (the pro
+seam). The browser Gallery at `/gallery/` searches third-party open assets;
+the procedural Catalog itself is a runtime API rather than a standalone lab.
+
+Villages (`/villagegen`): `createStylizedWorld({ pois: { seed, villages: 2,
+shrines: 1, pierHamlets: 1, size } })` → named settlements (seeded syllable
+names) with streets merged into the world path network, buildings facing
+their street behind picket fences, wells/lanterns/clutter by archetype, POI
+entries auto-connected by roads. `world.pois` feeds
+`createWorldMinimap({ markers })` labels. Fully-shadowed building facades
+need `parameters.sunShadowStrength ≈ 0.7` in worlds that run near-zero
+ambient (full-strength cast shadows crush large vertical masses to black).
+
+Fauna (`/fauna`) and ambient VFX (`/ambientfx`) are one option each:
+`createStylizedWorld({ fauna: { species: { birds: 40, fish: 80 } },
+ambientfx: { effects: { petals: true, fireflies: true } } })` — both join
+the world's fog/wind/cloud-shadow automatically.
+
+Weather (`/weather`) is a cross-system coordinator, not an environment
+catch-all: `createStylizedWorld({ weather: { preset: 'snow' } })`, then
+`world.setWeather('thunderstorm', { duration: 4 })`. Its 22 shared presets
+drive sky/sun/fog/cloud shadows, wind across vegetation/fauna/ambient FX,
+one-draw GPU rain/snow/sleet/hail/dust, water waves/ripples, lightning and
+thunder events. Surface `{ wetness, snowCover, ice }` values are host-facing
+outputs for custom terrain/prop/character materials. Labs should read
+`getWeatherPresetOptions()` rather than maintaining a private condition list.
+
+Gameplay VFX (`/vfxgen`): event-driven combat/movement effects, spawned at
+gameplay moments (not a world option) — `createVfxSystem({ seed, preset,
+heightAt })` then `vfx.spawn('slash' | 'impact' | 'fireball' | 'footstep' |
+'landing', { at | follow, power, look })` and `vfx.update(delta, camera)`
+per frame. All bursts share TWO draw calls; slash trails / fireball cores
+are pooled meshes. `vfx.setDistanceFog(...)` joins the height-fog layer;
+`vfx.setTimeScale(0)` is hit-stop. Weapons + moves are batteries-included:
+`createStylizedWeapon({ type: 'sword' | 'greatsword' | 'spear' | 'dagger'
+| 'hammer' })` + `createMoveController({ weapon, vfx })` →
+`attack.play('slash' | 'overhead' | 'thrust' | 'spin' | 'plunge')` — authored
+phase-based motions whose event tracks fire the VFX at the right beats
+(plunge = the full crouch→leap→dive→landfall decomposition); weapon weight
+scales timing and hit power. Design interactively in the VFX Lab
+(`/vfx-lab/`): weapon picker + move triggers + schema panels, exports a
+recipe (preset + seed + overrides) that drops straight into `createVfxSystem`.
+The `call_me_sensei` preset targets the reference action-RPG hit language
+(smooth gradient arcs, four-point star + shockwave circle per hit,
+hard-saturated pyro fireball). Demo loop: `examples/vfx-arena/`.
+
+Buildings (`/buildinggen`): seeded grammar exteriors —
+`buildingAsset({ type: 'cottage' | 'shed' | 'farmhouse' | 'watchtower' |
+'shrine', seed })` is a PropAsset (multi-circle footprint, buried foundation
+skirt for slopes ≤ ~20°, hi/lo LOD, `door` anchor with outward normal for
+street-facing placement). `createBuildingFromRecipe(recipe)` rebuilds
+deterministically; ≤ 6 draw calls per building.
+
+Props (`/propgen`): every placeable thing is a PropAsset —
+`createPropAsset({ asset: { type: 'lantern', variant: 'stoneToro', seed } })`
+or `propAssetFromObject(importedGlb)` (auto footprint + ground anchor).
+Place with ONE call: `placeAlongSpline({ asset, spline: world.paths.splines[0],
+spacing, offset, mask, heightAt: world.paths.heightAt, collision:
+world.collision, parent })` (fences/walls build continuously; point props
+instance with hi/lo LOD — call the returned `update(delta, camera)` per
+frame), or `scatterProps`/`placeProps`. Props added after `createStylizedWorld`
+need `applyEnvironmentShader(propsRoot, { parameters: { …fog } })` to join the
+look; pass a dry-land `mask` so dressing never marches into water.
+
+## Symptom table — check before debugging blind
+
+| Looks like | Cause → fix |
+|---|---|
+| Terrain gray/flat | environment shader never applied → put meshes under `terrain.root` |
+| Distant trees sharp saturated dots on hazed mountains | surface missing the height-fog layer → update ToonLab (impostors/water auto-wired via `setDistanceFog`); custom surfaces must join it |
+| Distant water bright band "cutting into" mountains | same fog-layer mismatch → `waterSurface.setDistanceFog({ color, density })` |
+| Giant white "iceberg" wedges at far shorelines | outdated ToonLab (swash film climbed steep banks) → update |
+| Full-detail trees popping in aerial views | LOD by horizontal distance → update ToonLab (3D distance) |
+| Gold/orange tree with green-shadow or pink-crown leaves | outdated ToonLab (palette derivation broke on warm hues) → update |
+| Billboards upside down / trunk-up | render-target bakes are written top-down → update ToonLab |
+| Trees like confetti from the air | uniform scatter → `createNoisePatchMask`; palette too mixed → green-dominant + one gold |
+| White valley blotches | white height fog → sky-blue `heightFogColor` |
+| Fog has no effect | `heightFogFalloff` too small → ≈ 400 |
+| Everything pale/gray from the air | one fog density for all views → lower `heightFogDensity` for aerial cameras (terrain uniforms + `water/forest.setDistanceFog`) |
+| Cliff walls flat, untextured up close | planar UVs stretch on walls → `envTriplanarMap` + `triplanarDetail` |
+| Zigzag triangles on cliff walls | per-vertex paint finer than the grid, or hue bleeding through stone → low-frequency bands; luminance-only tint is built in |
+| Flat light, no shadows | vertical/misaligned sun, nothing casts → align sun, enable castShadow |
+| Mountains vanish when centered | frustum culling on displaced meshes → `frustumCulled = false` |
+| Minute-long startup | unique tree per placement → `StylizedForest` |
+| ~20 fps in a big world | full-res meshes in every water pass → billboard forests (pass `renderer`), hi/lo rock LOD, `waterExclude`/`waterGrabExclude`, pass scales, `?dpr=1` on retina |
+| Character walks through rocks/trees | blockers unregistered → `world.collision.addCircles([{x,z,radius}])` + `world.collision.resolve(character.position, 0.35)` per frame (trunks are pre-registered) |
+| Character floats over/sinks into water | float on `water.getHeightAt(x, z)` with chest at the waterline; calm swim default, fast stroke on Shift, `action.timeScale = clamp(speed/1.7, 0.75, 1.35)` |
+
+Full runbook with budgets and verification workflow:
+`agents/skills/*/outdoor-world/SKILL.md` in the repo; complete reference
+app: `examples/outdoor-world/`. Verify by headless Playwright screenshot
+(`--enable-unsafe-webgpu --enable-gpu`), not by assumption — and LOOK at
+the images.

package/ATTRIBUTION.md

@@ -8,9 +8,18 @@ Code is MIT-licensed by Hyperbond Studio PTE. LTD. (see LICENSE). The assets bun
 |---|---|---|---|
 | Mannequin character (45 embedded animation clips) | `public/characters/mannequin.glb` | CC0 1.0 | [Quaternius — Universal Animation Library](https://quaternius.com/packs/universalanimationlibrary.html), recolored to neutral grays. See `public/characters/LICENSE.md`. |
 | Landscape textures (grassy-land, land, mountain, rock, sand, tree-trunk) | `labs/shared/textures/` | CC0 1.0 | First-party (created by the toonlab authors), dedicated to the public domain. |
+| Water Lab sea fern model | `public/water-lab/cc0/quaternius/fern-1.glb` | CC0 1.0 | [Quaternius — Fern 1, Stylized Nature MegaKit](https://quaternius.itch.io/stylized-nature-megakit), selected through the [ToonLab catalog](https://toonlab.io/asset/quaternius:stylized-nature-megakit-fern-1). |
+| Water Lab Coast Sand 01 texture set | `public/water-lab/cc0/polyhaven/` | CC0 1.0 | [Rob Tuytel — Coast Sand 01, Poly Haven](https://polyhaven.com/a/coast_sand_01), selected through the [ToonLab catalog](https://toonlab.io/asset/polyhaven:coast_sand_01). |
+| City street models (buildings, roads, cars, street props — 28 models) | `public/props/cc0/kaykit-city/` | CC0 1.0 | [Kay Lousberg — KayKit City Builder Bits](https://kaylousberg.com). Attribution optional under CC0; credited with thanks. See the bundled `LICENSE.txt`. |
+| Furniture models (tables, chairs, couch, lamps, shelves — 17 models) | `public/props/cc0/kaykit-furniture/` | CC0 1.0 | [Kay Lousberg — KayKit Furniture Bits](https://kaylousberg.com). Attribution optional under CC0; credited with thanks. See the bundled `LICENSE.txt`. |
+| Environment Lab Wood Floor texture | `public/environments/cc0/polyhaven/wood-floor-diff-1k.jpg` | CC0 1.0 | [Dimitrios Savva — Wood Floor, Poly Haven](https://polyhaven.com/a/wood_floor) |
+| Environment Lab Painted Plaster Wall texture | `public/environments/cc0/polyhaven/painted-plaster-wall-diff-1k.jpg` | CC0 1.0 | [Amal Kumar — Painted Plaster Wall, Poly Haven](https://polyhaven.com/a/painted_plaster_wall) |
+| Environment Lab photoscanned furniture (Sofa 02, Modern Arm Chair 01, Round Wooden Table 01, Classic Console 01, Steel Frame Shelves 01, Potted Plant 04) | `public/environments/cc0/polyhaven/models/` | CC0 1.0 | [Poly Haven models](https://polyhaven.com/models) (1k glTF), per-asset credits on each asset page |
+| Environment Lab museum scans (baluster vase F1980.190-.194; Colonoware pot) | `public/environments/cc0/smithsonian/` | CC0 1.0 | [Smithsonian Open Access 3D](https://3d.si.edu), selected through the [ToonLab catalog](https://toonlab.io/gallery?src=smithsonian) |
+| Draco + Basis decoders (model decompression) | `public/draco/`, `public/basis/` | Apache 2.0 | [google/draco](https://github.com/google/draco), [BinomialLLC/basis_universal](https://github.com/BinomialLLC/basis_universal) — bundled three.js decoder builds |
 
 Everything else that renders — water, sky, grass, flowers, trees, foliage,
-splashes, post-processing — is procedural code, no asset files.
+splashes, post-processing — is procedural code.
 
 ## Not bundled (bring your own)
 
@@ -32,9 +41,38 @@ folder that is **not** part of this repository:
 
 ## Recommended free sources
 
+The machine-readable version of this list (license facts, integration level,
+quality tier, enable/disable flags) is `src/assetlib/sources.js`; the Asset
+Browser lab surfaces it.
+
 - [Quaternius](https://quaternius.com) — CC0 models + the Universal
-  Animation Library (v1 and v2 free tiers).
+  Animation Library (v1 and v2 free tiers); most of the catalog is
+  searchable via Poly Pizza.
 - [Poly Haven](https://polyhaven.com) — CC0 textures/HDRIs/models.
-- [Kenney](https://kenney.nl) — CC0 game assets.
+- [Kenney](https://kenney.nl) — CC0 game assets (no file API; manual import).
+- [KayKit](https://kaylousberg.com) — CC0 stylized low-poly packs (city,
+  furniture, dungeon, characters …) on GitHub; integrated in the Asset
+  Browser (disabled by default — below the platform quality bar).
+  Attribution optional; credited with thanks.
+- [Open Source 3D Assets](https://opensource3dassets.com) — keyless CC0
+  registry (Polygonal Mind collections); integrated, pending quality review.
+- [Poly Pizza](https://poly.pizza) — low-poly aggregator, CC0/CC-BY
+  (BYO free API key).
+- [Smithsonian 3D Open Access](https://3d.si.edu) — museum scans; only
+  records explicitly marked CC0.
+- [Sketchfab CC0 search](https://sketchfab.com/search?features=downloadable&licenses=cc0&type=models)
+  — download manually (their download API is per-user OAuth with branding
+  terms; deliberately not automated).
+- [The Base Mesh](https://thebasemesh.com) — CC0 base meshes (manual import).
+- [3DTextures.me](https://3dtextures.me) — CC0 stylized materials
+  (manual import).
+- [TextureCan](https://www.texturecan.com) — CC0 textures (manual import).
+- [ShareTextures](https://www.sharetextures.com) — CC0 files, but their
+  platform terms prohibit automated downloads/hotlinking — browse manually
+  only, never wire an adapter.
 - [OpenGameArt](https://opengameart.org) — filter by CC0/CC-BY.
+- [Openverse](https://openverse.org) — openly licensed images/audio
+  (per-record license).
+- [Freesound](https://freesound.org) — sounds; free API tier is
+  non-commercial.
 - [VRoid Hub](https://hub.vroid.com) — VRM avatars (check per-model terms).