@call-me-sensei/toonlab 0.1.1 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,131 @@
+# 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` `/water` `/vegetation` (incl. scatter helpers +
+`StylizedForest`) `/sky` `/post` `/character` `/loaders` `/rockgen`
+`/debrisgen` `/debug`; root adds `createStylizedTerrain`,
+`createStylizedWorld`, `createWorldCollision`, `createWorldMinimap`,
+`resolveWorldPreset`.
+
+## 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/README.md

@@ -14,6 +14,18 @@ subpath exports per cluster).
 
 ## Quickstart
 
+**No install** — use the hosted labs at **[toonlab.io](https://toonlab.io)**:
+tune character and environment shaders, design trees and rocks, and export
+presets straight from the browser.
+
+**As a library** in your own Three.js app:
+
+```bash
+npm install @call-me-sensei/toonlab
+```
+
+**Run the labs locally** (this repo):
+
 ```bash
 git clone https://github.com/call-me-sensei/toonlab.git && cd toonlab
 npm install
@@ -38,6 +50,11 @@ the HUD Scene select:
   heightfields, sculpt edits, and GLB export.
 - **Tree Lab** (`/tree-lab/`) — procedural stylized trees,
   flowers, sketches, recipes, and GLB export.
+- **Outdoor World** (`/examples/outdoor-world/`) — the flagship example: a
+  seeded 1×1 km open world built entirely from the public library API —
+  generated terrain, forests, lakes, cliffs, a swimmable character, and a
+  click-to-travel minimap. Re-roll it from the URL:
+  `?seed=42&archetype=lakeland&water=0.4&islands=3`.
 
 Every URL parameter has a HUD control, lab state persists per lab in
 `localStorage`, and **Reset Lab** clears it. Point any lab at your own model
@@ -64,6 +81,59 @@ embedded animation clips.
 
 ## Library usage
 
+### A complete open world in one screen of code
+
+```js
+import { createStylizedTerrain, createStylizedWorld, createWorldMinimap } from '@call-me-sensei/toonlab';
+
+// Seeded terrain generator — ANY seed is a valid, playable world. One knob
+// per big idea: waterCoverage (how much water), height (mountain range),
+// depth (basins), size (number or { x, z }), floatingIslands, sinkholes.
+const terrain = createStylizedTerrain({ seed: 42, size: 1000, archetype: 'terracedKarst' });
+const terrainRoot = new THREE.Group();
+terrainRoot.add(terrain.root);
+scene.add(terrainRoot);
+
+// Environment shading, aligned sun + real shadows, sky, anime water, LOD
+// forests (billboard far trees), follow-window grass, cloud shadows,
+// unified three-layer fog, and collision — all on by default.
+const world = await createStylizedWorld({
+  renderer, scene, camera,
+  terrain: { heightAt: terrain.heightAt, root: terrainRoot, size: terrain.meshExtent },
+  water: { level: terrain.waterLevel },
+  followTarget: character, // your character root (optional): splashes, wakes, grass push
+});
+character.position.copy(terrain.spawn); // probed: walkable, near a shore
+
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(() => {
+  world.update(clock.getDelta());
+  renderer.render(scene, camera);
+});
+```
+
+**Bring your own terrain instead** — the generator is optional. The whole
+contract is a pure `heightAt(x, z)` in meters plus your displaced mesh under
+`terrain.root`; masks, scatter, collision, and the minimap all derive from
+it:
+
+```js
+const heightAt = (x, z) => 12 * Math.sin(x / 90) * Math.cos(z / 90); // yours
+const world = await createStylizedWorld({
+  renderer, scene, camera,
+  terrain: { heightAt, root: myTerrainRoot, size: 1200 },
+  water: { level: 0 },
+});
+```
+
+Add a clickable minimap with `createWorldMinimap({ heightAt, size,
+waterLevel, onPick })`, and solid rocks/trees with the built-in
+`world.collision` (`addCircles` for your own props, `resolve(position,
+radius)` per frame). Archetypes: `terracedKarst`, `lakeland`, `alpine`,
+`rollingPlains`, `archipelago`.
+
+### Individual clusters
+
 ```js
 import { applyToonShader, createToonSettings } from '@call-me-sensei/toonlab/toon';
 
@@ -107,6 +177,9 @@ stack, with WebGL2 fallback through the same TSL path.
 - [Post-processing](docs/post-processing.md)
 - [Characters and animation](docs/characters.md)
 - [Debug panel](docs/debug-panel.md)
+- [World scale and world presets](docs/world-scale.md) — the meters
+  convention, open-world scale presets, rock quality tiers, and vegetation
+  scatter helpers.
 - [Settings reference](docs/settings-reference.md) — every tunable field,
   generated from the schemas (`node scripts/generate-settings-reference.mjs`).
 - [Shader constants](docs/shader-constants.md) — the deliberately unexposed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.1.1",
+  "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",
   "license": "MIT",
   "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",
@@ -29,7 +29,8 @@
     "src",
     "README.md",
     "LICENSE",
-    "ATTRIBUTION.md"
+    "ATTRIBUTION.md",
+    "AGENTS.md"
   ],
   "exports": {
     ".": "./src/index.js",

package/src/debrisgen/debrisPresets.js

@@ -15,6 +15,13 @@ function preset(id, label, type, variant, description, overrides = {}) {
 }
 
 export const BUILT_IN_DEBRIS_PRESETS = Object.freeze([
+  // Studio-managed signature debris, curated by Call Me Sensei and updated
+  // over releases. Currently the bleached-driftwood look.
+  preset('call_me_sensei', 'Call Me Sensei', 'wood', 'driftwood', 'Studio-managed signature debris, updated over releases.', {
+    asset: { count: 1, seed: 7301, spread: 0 },
+    shape: { branchiness: 0.38, crookedness: 0.86, length: 3.05, splinters: 0.8, thickness: 0.23 },
+    surface: { accentColor: [0.52, 0.39, 0.25], primaryColor: [0.52, 0.43, 0.31], secondaryColor: [0.78, 0.68, 0.5], variation: 0.24 },
+  }),
   preset('bleached-driftwood', 'Bleached driftwood', 'wood', 'driftwood', 'Salt-worn pale wood with broken fibers.', {
     asset: { count: 1, seed: 7301, spread: 0 },
     shape: { branchiness: 0.38, crookedness: 0.86, length: 3.05, splinters: 0.8, thickness: 0.23 },

package/src/environment/environmentPresets.js

@@ -441,3 +441,22 @@ registerEnvironmentPreset('showcase', {
     timeOfDayHour: 15,
   },
 });
+
+// Studio-managed signature look, curated by Call Me Sensei and updated over
+// releases (unlike 'showcase', this is a production grade, not a feature
+// tour). Community presets register alongside it via
+// registerEnvironmentPreset / environment preset documents.
+registerEnvironmentPreset('call_me_sensei', {
+  label: 'Call Me Sensei',
+  parameters: {
+    ambientProbeBlend: 0.35,
+    aoWarmth: 0.5,
+    heightFogDensity: 0.006,
+    skyTintStrength: 0.35,
+  },
+  rig: {
+    probe: true,
+    sun: true,
+    timeOfDayHour: 14,
+  },
+});

package/src/environment/environmentSettings.js

@@ -121,6 +121,9 @@ export const DEFAULT_ENVIRONMENT_PARAMETERS = Object.freeze({
   spotLightStrength: null,
   sunBoost: null,
   sunBoostColor: null,
+  triplanarDetail: null,
+  triplanarDetailScale: null,
+  triplanarEdgeHighlight: null,
   untexturedGradientStrength: null,
   vertexAoStrength: null,
 });
@@ -219,6 +222,9 @@ const FIELD_LABEL_OVERRIDES = Object.freeze({
   spotLightStrength: 'Spot Light',
   sunBoost: 'Sun Boost',
   sunBoostColor: 'Sun Boost Color',
+  triplanarDetail: 'Triplanar Detail',
+  triplanarDetailScale: 'Triplanar Detail Scale',
+  triplanarEdgeHighlight: 'Rock Edge Highlight',
   windowCutout: 'Window Cutout',
 });
 
@@ -242,6 +248,7 @@ function rangeForParameter(key) {
   if (key === 'heightFogDensity') return { max: 0.5, min: 0, step: 0.001 };
   if (key === 'heightFogFalloff') return { max: 30, min: 0.05, step: 0.05 };
   if (key === 'planarReflectionFresnel') return { max: 8, min: 0.1, step: 0.05 };
+  if (key === 'triplanarDetailScale') return { max: 64, min: 0.25, step: 0.25 };
   if (key === 'exposure' || key === 'saturation') return { max: 2, min: 0, step: 0.01 };
   if (key.includes('Strength') || key.includes('Influence')) return { max: 2, min: 0, step: 0.01 };
   if (key.includes('LightStrength')) return { max: 4, min: 0, step: 0.01 };
@@ -480,6 +487,9 @@ export function applyEnvironmentSettingsToMaterial(material, settingsInput = {})
   setNumberUniform(uniforms, 'skyTintStrength', parameters.skyTintStrength);
   setNumberUniform(uniforms, 'spotLightStrength', parameters.spotLightStrength);
   setNumberUniform(uniforms, 'sunBoost', parameters.sunBoost);
+  setNumberUniform(uniforms, 'triplanarDetail', parameters.triplanarDetail);
+  setNumberUniform(uniforms, 'triplanarDetailScale', parameters.triplanarDetailScale);
+  setNumberUniform(uniforms, 'triplanarEdgeHighlight', parameters.triplanarEdgeHighlight);
   setColorUniform(uniforms, 'heightFogColor', parameters.heightFogColor);
   setColorUniform(uniforms, 'interiorOcclusionColor', parameters.interiorOcclusionColor);
   setColorUniform(uniforms, 'leftSideShadowColor', parameters.leftSideShadowColor);

package/src/environment/environmentTextureResolver.js

@@ -154,6 +154,9 @@ export async function resolveEnvironmentTextureSet(mat) {
     normalScale: mat?.normalScale?.isVector2 ? mat.normalScale.clone() : new THREE.Vector2(1, 1),
     packedMap,
     resolvedDiffuseMap: Boolean(resolvedDiffuseMap),
+    // Opt-in world-projected material for steep faces (cliffs, rock walls):
+    // sampled triplanar and blended by slope where triplanarDetail > 0.
+    triplanarMap: userData.envTriplanarMap ?? null,
     // True when the material arrived with no real color texture at all — the
     // untextured/flat-color input class that gets the designed gradient look.
     untextured: baseMap === fallbackEnvironmentWhiteTexture,

package/src/environment/index.js

@@ -6,3 +6,4 @@ export * from './environmentRigs.js';
 export * from './environmentTimeOfDay.js';
 export * from './environmentAmbientProbe.js';
 export * from './environmentPlanarReflection.js';
+export * from './environmentSunShadowPass.js';

package/src/index.js

@@ -19,3 +19,10 @@ export * from './character/characterRig.js';
 export * from './character/freestyleSwimClip.js';
 export * from './rockgen/index.js';
 export * from './debrisgen/index.js';
+export * from './vegetation/scatter.js';
+export * from './worldPresets.js';
+export * from './stylizedWorld.js';
+export * from './vegetation/stylizedForest.js';
+export * from './worldCollision.js';
+export * from './worldMinimap.js';
+export * from './stylizedTerrain.js';

package/src/post/postProcessing.js

@@ -104,6 +104,30 @@ export const POST_PROCESSING_PRESETS = Object.freeze({
       warmth: 0.0,
     },
   },
+  // Studio-managed signature grade, curated by Call Me Sensei and updated
+  // over releases. Currently equal to the softAnime grade.
+  call_me_sensei: {
+    features: {
+      bloom: false,
+      colorGrade: false,
+      enabled: true,
+      vignette: true,
+      verticalGrade: false,
+    },
+    parameters: {
+      bloomRadius: 0.08,
+      bloomStrength: 0.0,
+      bloomThreshold: 0.992,
+      bottomDark: 0.0,
+      contrast: 1.0,
+      exposure: 1.0,
+      saturation: 1.0,
+      strength: 0.45,
+      topLight: 0.0,
+      vignetteStrength: 0.018,
+      warmth: 0.0,
+    },
+  },
   debugEdges: {
     features: {
       depthCue: true,
@@ -602,6 +626,10 @@ export function createPostProcessingPresetDocument(id, definition = {}) {
 }
 
 const BUILT_IN_POST_PROCESSING_PRESET_METADATA = Object.freeze({
+  call_me_sensei: Object.freeze({
+    description: 'Studio-managed signature grade, curated by Call Me Sensei and updated over releases.',
+    label: 'Call Me Sensei',
+  }),
   custom: Object.freeze({
     description: 'Neutral starting point that expects host-supplied feature and parameter overrides.',
     label: 'Custom',

package/src/rockgen/rockgenPresets.js

@@ -557,3 +557,11 @@ registerRockgenPreset('shard-monolith', {
     topSlopeStart: 0.55,
   },
 });
+
+// Studio-managed signature rock, curated by Call Me Sensei and updated over
+// releases. Currently the boulder look under the managed label. Community
+// presets register alongside it via registerRockgenPreset().
+registerRockgenPreset('call_me_sensei', {
+  ...resolveRockgenPreset('boulder'),
+  label: 'Call Me Sensei',
+});

package/src/rockgen/rockgenSettings.js

@@ -336,6 +336,53 @@ export const DEFAULT_ROCKGEN_MESHING_SETTINGS = Object.freeze({
   sharpFeatures: true,
 });
 
+// Quality tiers couple meshing resolution and normal mode for a target
+// viewing context, so hosts pick one word instead of tuning both by hand:
+//
+// - `hero` — close-up set pieces (< 20 m camera): highest resolution, flat
+//   faceted normals so planar cuts read as stylized facets.
+// - `gameplayHigh` — open-world gameplay cameras (50–160 m): gradient
+//   normals (flat facets go near-black at range under toon lighting) at the
+//   default resolutions.
+// - `mobile` — low-end targets: reduced resolutions, gradient normals,
+//   sharp-feature solve off.
+export const ROCKGEN_QUALITY_LEVELS = Object.freeze(['hero', 'gameplayHigh', 'mobile']);
+
+export const ROCKGEN_QUALITY_PRESETS = Object.freeze({
+  gameplayHigh: Object.freeze({
+    exportResolution: 224,
+    normalsMode: 'gradient',
+    previewResolution: 96,
+    sharpFeatures: true,
+  }),
+  hero: Object.freeze({
+    exportResolution: 288,
+    normalsMode: 'flat',
+    previewResolution: 128,
+    sharpFeatures: true,
+  }),
+  mobile: Object.freeze({
+    exportLods: false,
+    exportResolution: 128,
+    normalsMode: 'gradient',
+    previewResolution: 56,
+    sharpFeatures: false,
+  }),
+});
+
+/**
+ * Returns full meshing settings for a quality tier merged over
+ * {@link DEFAULT_ROCKGEN_MESHING_SETTINGS}; unknown names return the plain
+ * defaults. Spread the result into a preset's `meshing`:
+ *
+ *   const preset = resolveRockgenPreset('call_me_sensei');
+ *   preset.meshing = { ...preset.meshing, ...resolveRockgenQuality('gameplayHigh') };
+ */
+export function resolveRockgenQuality(name) {
+  const tier = ROCKGEN_QUALITY_PRESETS[name];
+  return { ...DEFAULT_ROCKGEN_MESHING_SETTINGS, ...(tier ?? {}) };
+}
+
 export const ROCKGEN_SETTING_GROUPS = Object.freeze([
   Object.freeze({
     description: 'Base primitive the rock piece is displaced from.',

package/src/shaders-tsl/environment.js

@@ -30,6 +30,7 @@
 
 import * as THREE from 'three';
 import {
+  abs,
   attribute,
   cameraFar,
   cameraNear,
@@ -50,6 +51,7 @@ import {
   mix,
   normalize,
   normalLocal,
+  normalWorld,
   positionWorld,
   pow,
   select,
@@ -174,6 +176,7 @@ export function createEnvironmentNodeMaterial({
     skyTopTint: uniform(new THREE.Color(0.86, 0.96, 1.08)),
     sunBoostColor: uniform(new THREE.Color(1.0, 0.78, 0.42)),
 
+    triplanarMapTex: texture(textureSet.triplanarMap ?? fallbackEnvironmentWhiteTexture),
     normalMapTex: texture(textureSet.normalMap ?? fallbackEnvironmentNormalTexture),
     normalMapStrength: uniform(0.8),
     normalMapScale: uniform(textureSet.normalScale ?? new THREE.Vector2(1, 1)),
@@ -199,6 +202,9 @@ export function createEnvironmentNodeMaterial({
     heightFogDensity: uniform(0.0),
     heightFogFalloff: uniform(6.0),
     heightFogColor: uniform(new THREE.Color(0.75, 0.82, 0.92)),
+    triplanarDetail: uniform(0.0),
+    triplanarDetailScale: uniform(8.0),
+    triplanarEdgeHighlight: uniform(0.6),
     planarReflectionStrength: uniform(isGlossFloor ? 0.3 : 0.0),
     planarReflectionFresnel: uniform(2.4),
 
@@ -253,6 +259,7 @@ export function createEnvironmentNodeMaterial({
     normalMapTex: u.normalMapTex,
     packedMap: u.packedMap,
     planarReflectionMap: shared.planarReflectionMap,
+    triplanarMapTex: u.triplanarMapTex,
   };
 
   const material = new NodeMaterial();
@@ -388,6 +395,22 @@ export function createEnvironmentNodeMaterial({
 
   material.fragmentNode = Fn(() => {
     const texel = tex.baseMap.sample(vUv).toVar();
+    // Triplanar detail: re-sample the base map projected in world space and
+    // blended by the surface normal, so steep faces (cliff walls, terrace
+    // sides) keep the same texture density as the ground. A heightfield's
+    // planar UVs compress an entire wall into a sliver of the map — up
+    // close the wall reads as untextured flat paint. Opt-in: 0 disables.
+    If(u.triplanarDetail.greaterThan(0.0), () => {
+      const scale = max(u.triplanarDetailScale, 0.001);
+      const weights = pow(abs(normalWorld), vec3(4.0)).toVar();
+      const weightSum = max(weights.x.add(weights.y).add(weights.z), 0.0001);
+      const tri = tex.baseMap.sample(vWorldPosition.zy.div(scale)).rgb
+        .mul(weights.x)
+        .add(tex.baseMap.sample(vWorldPosition.xz.div(scale)).rgb.mul(weights.y))
+        .add(tex.baseMap.sample(vWorldPosition.xy.div(scale)).rgb.mul(weights.z))
+        .div(weightSum);
+      texel.rgb.assign(mix(texel.rgb, tri, clamp(u.triplanarDetail, 0.0, 1.0)));
+    });
     if (flags.useVertexColors) {
       // USE_COLOR / USE_COLOR_ALPHA: vertexColor() yields w = 1 for vec3
       // color attributes, so the alpha multiply is a no-op exactly when the
@@ -396,6 +419,43 @@ export function createEnvironmentNodeMaterial({
       texel.rgb.mulAssign(vColor.rgb);
       texel.a.mulAssign(vColor.a);
     }
+    if (textureSet.triplanarMap) {
+      // Dedicated steep-face material (userData.envTriplanarMap): a painted
+      // stone/cliff diffuse sampled triplanar in world space and blended in
+      // by slope. Flats keep the ground detail; a share of the painted
+      // vertex tint bleeds through so strata bands and baked haze still
+      // modulate the stone at range.
+      If(u.triplanarDetail.greaterThan(0.0), () => {
+        const scale = max(u.triplanarDetailScale, 0.001);
+        const weights = pow(abs(normalWorld), vec3(4.0)).toVar();
+        const weightSum = max(weights.x.add(weights.y).add(weights.z), 0.0001);
+        const stone = tex.triplanarMapTex.sample(vWorldPosition.zy.div(scale)).rgb
+          .mul(weights.x)
+          .add(tex.triplanarMapTex.sample(vWorldPosition.xz.div(scale)).rgb.mul(weights.y))
+          .add(tex.triplanarMapTex.sample(vWorldPosition.xy.div(scale)).rgb.mul(weights.z))
+          .div(weightSum).toVar();
+        // Early stone takeover (0.12 ≈ 29°): the grass↔stone transition band
+        // is where the terrain triangulation shows — per-vertex meadow/gold
+        // paint interpolating across wall triangles reads as green sawtooth
+        // wedges, so the band must be narrow and mostly stone.
+        const steep = smoothstep(0.12, 0.3, abs(normalWorld.y).oneMinus());
+        // Tint by the vertex paint's LUMINANCE only: brightness variation
+        // (strata, haze) carries through, but its hue never does — green
+        // tread color bleeding into wall stone is the sawtooth's other half.
+        const paintLum = dot(texel.rgb, vec3(0.299, 0.587, 0.114));
+        const tinted = stone.mul(mix(vec3(1.0), vec3(paintLum).mul(1.7), 0.35));
+        texel.rgb.assign(mix(texel.rgb, tinted, clamp(u.triplanarDetail, 0.0, 1.0).mul(steep)));
+        // Edge highlighting: hand-painted rock brightens its convex lips.
+        // steep·(1−steep) peaks exactly on the wall↔flat transition band —
+        // the rounded top edge of a cliff or terrace — with no baked
+        // curvature data and no per-vertex aliasing. Warm, slightly
+        // saturated lift like a painted highlight.
+        const lip = steep.mul(steep.oneMinus()).mul(4.0)
+          .mul(clamp(normalWorld.y, 0.0, 1.0))
+          .mul(clamp(u.triplanarEdgeHighlight, 0.0, 2.0));
+        texel.rgb.mulAssign(mix(vec3(1.0), vec3(1.26, 1.19, 1.04), lip));
+      });
+    }
 
     Discard(
       u.enableFoliageCutout.greaterThan(0.5)