# Settings reference

<!-- GENERATED FILE — do not edit by hand. -->
<!-- Regenerate with: node scripts/generate-settings-reference.mjs -->

Every tunable field in the settings schemas, generated from the
`*_SETTING_GROUPS` / `*_SETTING_FIELD_SCHEMA` exports. The same schemas
drive the Lab controls and inspectors. A Lab may place
scene/runtime inputs in its Preview controls instead of the saved editor;
the **Portable** column makes that ownership explicit.

- [Character toon shading](#character-toon-shading)
- [Environment shading](#environment-shading)
- [Rock shader profile](#rock-shader-profile)
- [Ground shader profile](#ground-shader-profile)
- [Water](#water)
- [Post-processing](#post-processing)
- [Vegetation shader family](#vegetation-shader-family)
- [Grass](#grass)
- [Flowers](#flowers)
- [Trees](#trees)
- [Sky](#sky)
- [Paths, roads & bridges](#paths-roads-bridges)
- [Ambient VFX](#ambient-vfx)
- [Gameplay VFX](#gameplay-vfx)
- [Fauna](#fauna)
- [Procedural textures](#procedural-textures)

## Character toon shading

Module: `toonlab/toon` — 23 groups, 298 fields.

Settings are nested per group: `createToonSettings({ rimLight: { intensity: 0.2 } })`.

### Character toon shading: Base Texture

Preserves source texture, source material color, and saturation policy before toon lighting.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `customSaturation` | number | `1` | 0 – 2 | Yes | Configures custom saturation for base texture. |
| `materialColorMode` | select | `'legacy'` | `legacy` \| `source` \| `texture` \| `white` | Yes | Sets the color used by material color mode. |
| `saturationMode` | select | `'legacy'` | `legacy` \| `source` \| `custom` | Yes | Selects the policy used by saturation mode. |

### Character toon shading: Alpha

Controls cutout, blend, opacity, eye overlay sorting, and transparent decoration behavior.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `blendCutoff` | number | `0.02` | 0 – 1 | Yes | Configures blend cutoff for alpha. |
| `costumeCutout` | boolean | `true` | — | Yes | Configures costume cutout for alpha. |
| `cutoutCutoff` | number | `0.35` | 0 – 1 | Yes | Configures cutout cutoff for alpha. |
| `ditherOpacity` | number | `1` | 0 – 1 | Yes | Configures dither opacity for alpha. |
| `enabled` | boolean | `true` | — | Yes | Turns alpha on or off. |
| `expressionTokenCutout` | boolean | `true` | — | Yes | Configures expression token cutout for alpha. |
| `eyeHighlightOrder` | number | `12` | -30 – 30 | Yes | Controls transparent draw order for eye highlight order. |
| `eyeOrder` | number | `11` | -30 – 30 | Yes | Controls transparent draw order for eye order. |
| `faceCutout` | boolean | `true` | — | Yes | Configures face cutout for alpha. |
| `hairCutout` | boolean | `true` | — | Yes | Configures hair cutout for alpha. |
| `mapTransparentCutout` | boolean | `true` | — | Yes | Configures map transparent cutout for alpha. |
| `overlayDepthWrite` | boolean | `false` | — | Yes | Configures overlay depth write for alpha. |
| `overlayOrder` | number | `20` | -30 – 30 | Yes | Controls transparent draw order for overlay order. |
| `preserveSourceAlphaTest` | boolean | `true` | — | Yes | Configures preserve source alpha test for alpha. |
| `scleraOrder` | number | `10` | -30 – 30 | Yes | Controls transparent draw order for sclera order. |
| `skinCutout` | boolean | `true` | — | Yes | Configures skin cutout for alpha. |
| `sortOverlays` | boolean | `true` | — | Yes | Configures sort overlays for alpha. |
| `sourceAlphaMapCutout` | boolean | `true` | — | Yes | Configures source alpha map cutout for alpha. |
| `sourceTransparentCutout` | boolean | `true` | — | Yes | Configures source transparent cutout for alpha. |
| `transparentOverlayBlend` | boolean | `true` | — | Yes | Configures transparent overlay blend for alpha. |
| `transparentOpacityThreshold` | number | `0.999` | 0 – 1 | Yes | Configures transparent opacity threshold for alpha. |

### Character toon shading: Skin Tone

Keeps skin and face shadows warm, readable, and separate from costume/hair shadows.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Turns skin tone on or off. |
| `faceMaxDirectLight` | number | `100` | 0 – 8 | Yes | Configures face max direct light for skin tone. |
| `faceMinimumIndirectLight` | number | `0.35` | 0 – 1 | Yes | Sets the minimum light floor for face minimum indirect light. |
| `faceShadowBrightness` | number | `1` | 0 – 2 | Yes | Configures face shadow brightness for skin tone. |
| `faceShadowSaturation` | number | `1` | 0 – 2 | Yes | Configures face shadow saturation for skin tone. |
| `faceShadowTint` | color | `[1, 0.92, 0.9]` (#ffebe6) | — | Yes | Sets the color used by face shadow tint. |
| `faceShadowTintStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for face shadow tint strength. |
| `skinMaxDirectLight` | number | `100` | 0 – 8 | Yes | Configures skin max direct light for skin tone. |
| `skinMinimumIndirectLight` | number | `0.35` | 0 – 1 | Yes | Sets the minimum light floor for skin minimum indirect light. |
| `skinShadowBrightness` | number | `0.92` | 0 – 2 | Yes | Configures skin shadow brightness for skin tone. |
| `skinShadowSaturation` | number | `1` | 0 – 2 | Yes | Configures skin shadow saturation for skin tone. |
| `skinShadowTint` | color | `[1, 0.76, 0.74]` (#ffc2bd) | — | Yes | Sets the color used by skin shadow tint. |
| `skinShadowTintStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for skin shadow tint strength. |

### Character toon shading: Face Lighting

Overrides face-area cel response so noses, cheeks, and eyes do not receive harsh body shadows.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Turns face lighting on or off. |
| `faceCelMidPoint` | number | `-0.48` | -1 – 1 | Yes | Moves the center point for face cel mid point. |
| `faceCelSoftness` | number | `0.22` | 0 – 1 | Yes | Controls transition softness for face cel softness. |
| `faceLocalLightLift` | number | `0.22` | 0 – 1 | Yes | Configures face local light lift for face lighting. |
| `faceMainLightIgnoreCelShade` | number | `0.45` | 0 – 1 | Yes | Configures face main light ignore cel shade for face lighting. |
| `faceNormalProxyBlend` | number | `0.75` | 0 – 1 | Yes | Configures face normal proxy blend for face lighting. |
| `faceProxyNormal` | vector3 | `[0, 0, 1]` | — | Yes | Configures face proxy normal for face lighting. |
| `faceSceneShadowStrength` | number | `0.5` | 0 – 8 | Yes | Controls the blend strength for face scene shadow strength. |
| `faceSphereBlend` | number | `0.75` | 0 – 1 | Yes | Configures face sphere blend for face lighting. |
| `headSpaceMode` | select | `'headBone'` | `static` \| `headBone` | Yes | Selects the policy used by head space mode. |

### Character toon shading: Cel Shade

Sets the primary directional cel band threshold, softness, and light-ignore amount.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `bodyCelMidPoint` | number | `0.06` | -1 – 1 | Yes | Moves the center point for body cel mid point. |
| `bodyCelSoftness` | number | `0.045` | 0 – 1 | Yes | Controls transition softness for body cel softness. |
| `bodyMainLightIgnoreCelShade` | number | `0.02` | 0 – 1 | Yes | Configures body main light ignore cel shade for cel shade. |
| `edgeAntiAliasStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for edge anti alias strength. |
| `enabled` | boolean | `true` | — | Yes | Turns cel shade on or off. |

### Character toon shading: Shadow Color

Tints and reshapes lit-to-shadow transitions and fully shadowed regions.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Turns shadow color on or off. |
| `lowSaturationFallbackColor` | vector4 | `[0.3764706, 0.4141177, 0.5019608, 0]` | — | Yes | Sets the color used by low saturation fallback color. |
| `selfShadowAlbedoMulStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for self shadow albedo mul strength. |
| `selfShadowAreaHSVStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for self shadow area h s v strength. |
| `selfShadowAreaHueOffset` | number | `0` | -1 – 1 | Yes | Configures self shadow area hue offset for shadow color. |
| `selfShadowAreaSaturationBoost` | number | `0.2` | 0 – 2 | Yes | Configures self shadow area saturation boost for shadow color. |
| `selfShadowAreaValueMul` | number | `0.68` | 0 – 2 | Yes | Configures self shadow area value mul for shadow color. |
| `selfShadowTintColor` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Sets the color used by self shadow tint color. |
| `transitionAreaHueOffset` | number | `0.01` | -1 – 1 | Yes | Configures transition area hue offset for shadow color. |
| `transitionAreaIntensity` | number | `1` | 0 – 8 | Yes | Controls how strongly transition area intensity contributes. |
| `transitionAreaSaturationBoost` | number | `0.36` | 0 – 2 | Yes | Configures transition area saturation boost for shadow color. |
| `transitionAreaTintColor` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Sets the color used by transition area tint color. |
| `transitionAreaValueMul` | number | `1` | 0 – 2 | Yes | Configures transition area value mul for shadow color. |

### Character toon shading: Scene Shadows

Controls how renderer shadow maps darken character materials.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultMinLight` | number | `0.24` | 0 – 1 | Yes | Sets the minimum light floor for default min light. |
| `defaultStrength` | number | `0.76` | 0 – 8 | Yes | Controls the blend strength for default strength. |
| `enabled` | boolean | `true` | — | Yes | Turns scene shadows on or off. |
| `eyeMinLight` | number | `0.42` | 0 – 1 | Yes | Sets the minimum light floor for eye min light. |
| `eyeStrength` | number | `0.05` | 0 – 8 | Yes | Controls the blend strength for eye strength. |
| `faceMinLight` | number | `0.42` | 0 – 1 | Yes | Sets the minimum light floor for face min light. |
| `faceStrength` | number | `0.46` | 0 – 8 | Yes | Controls the blend strength for face strength. |
| `shadowAreaStrength` | number | `0.65` | 0 – 8 | Yes | Controls the blend strength for shadow area strength. |
| `skinMinLight` | number | `0.34` | 0 – 1 | Yes | Sets the minimum light floor for skin min light. |
| `skinStrength` | number | `0.62` | 0 – 8 | Yes | Controls the blend strength for skin strength. |

### Character toon shading: Self Shadow

Controls character-local self-shadow proxy contribution until a dedicated self-shadow pass exists.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultMinLight` | number | `0.62` | 0 – 1 | Yes | Sets the minimum light floor for default min light. |
| `defaultStrength` | number | `0.22` | 0 – 8 | Yes | Controls the blend strength for default strength. |
| `enabled` | boolean | `true` | — | Yes | Turns self shadow on or off. |
| `eyeMinLight` | number | `1` | 0 – 1 | Yes | Sets the minimum light floor for eye min light. |
| `eyeStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for eye strength. |
| `faceMinLight` | number | `1` | 0 – 1 | Yes | Sets the minimum light floor for face min light. |
| `faceStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for face strength. |
| `hairMinLight` | number | `0.58` | 0 – 1 | Yes | Sets the minimum light floor for hair min light. |
| `hairStrength` | number | `0.26` | 0 – 8 | Yes | Controls the blend strength for hair strength. |
| `shadowAreaStrength` | number | `0.5` | 0 – 8 | Yes | Controls the blend strength for shadow area strength. |
| `skinMinLight` | number | `0.72` | 0 – 1 | Yes | Sets the minimum light floor for skin min light. |
| `skinStrength` | number | `0.16` | 0 – 8 | Yes | Controls the blend strength for skin strength. |
| `sourceMode` | select | `2` | `0` \| `1` \| `2` | Yes | Selects the policy used by source mode. |

### Character toon shading: Average Shadow

Adds averaged shadow visibility used for softer role-specific shadow damping.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultMinLight` | number | `0.28` | 0 – 1 | Yes | Sets the minimum light floor for default min light. |
| `defaultStrength` | number | `0.28` | 0 – 8 | Yes | Controls the blend strength for default strength. |
| `enabled` | boolean | `false` | — | Yes | Turns average shadow on or off. |
| `measuredBlend` | number | `0.65` | 0 – 1 | Yes | Configures measured blend for average shadow. |
| `eyeMinLight` | number | `1` | 0 – 1 | Yes | Sets the minimum light floor for eye min light. |
| `eyeStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for eye strength. |
| `faceMinLight` | number | `1` | 0 – 1 | Yes | Sets the minimum light floor for face min light. |
| `faceStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for face strength. |
| `hairMinLight` | number | `0.3` | 0 – 1 | Yes | Sets the minimum light floor for hair min light. |
| `hairStrength` | number | `0.22` | 0 – 8 | Yes | Controls the blend strength for hair strength. |
| `skinMinLight` | number | `0.4` | 0 – 1 | Yes | Sets the minimum light floor for skin min light. |
| `skinStrength` | number | `0.18` | 0 – 8 | Yes | Controls the blend strength for skin strength. |
| `softness` | number | `0.35` | 0 – 1 | Yes | Configures softness for average shadow. |

### Character toon shading: Indirect Light

Mixes ambient, hemisphere, and environment light into toon shading.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `ambientTint` | color | `[0.86, 0.91, 1]` (#dbe8ff) | — | Yes | Sets the color used by ambient tint. |
| `defaultIntensity` | number | `0.35` | 0 – 8 | Yes | Controls how strongly default intensity contributes. |
| `defaultMinimumIndirectLight` | number | `0.35` | 0 – 1 | Yes | Sets the minimum light floor for default minimum indirect light. |
| `enabled` | boolean | `true` | — | Yes | Turns indirect light on or off. |
| `environmentIndirectLight` | number | `0.56` | 0 – 1 | Yes | Configures environment indirect light for indirect light. |
| `eyeIntensity` | number | `0.35` | 0 – 8 | Yes | Controls how strongly eye intensity contributes. |
| `eyeMinimumIndirectLight` | number | `0.35` | 0 – 1 | Yes | Sets the minimum light floor for eye minimum indirect light. |
| `faceIntensity` | number | `0.35` | 0 – 8 | Yes | Controls how strongly face intensity contributes. |
| `faceMinimumIndirectLight` | object | — | — | No — local/runtime | Sets the minimum light floor for face minimum indirect light. |
| `hairIntensity` | number | `0.35` | 0 – 8 | Yes | Controls how strongly hair intensity contributes. |
| `hairMinimumIndirectLight` | number | `0.35` | 0 – 1 | Yes | Sets the minimum light floor for hair minimum indirect light. |
| `hemisphereLightIntensity` | number | `0.42` | 0 – 8 | Yes | Controls how strongly hemisphere light intensity contributes. |
| `skinIntensity` | number | `0.35` | 0 – 8 | Yes | Controls how strongly skin intensity contributes. |
| `skinMinimumIndirectLight` | object | — | — | No — local/runtime | Sets the minimum light floor for skin minimum indirect light. |

### Character toon shading: Local Lights

Controls point and spot light response for characters without overpowering cel bands.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultIntensity` | number | `0.72` | 0 – 8 | Yes | Controls how strongly default intensity contributes. |
| `defaultMaxContribution` | number | `0.34` | 0 – 1 | Yes | Configures default max contribution for local lights. |
| `defaultShadowLift` | number | `0.58` | 0 – 1 | Yes | Configures default shadow lift for local lights. |
| `enabled` | boolean | `true` | — | Yes | Turns local lights on or off. |
| `eyeIntensity` | number | `0.42` | 0 – 8 | Yes | Controls how strongly eye intensity contributes. |
| `eyeMaxContribution` | number | `0.18` | 0 – 1 | Yes | Configures eye max contribution for local lights. |
| `eyeShadowLift` | number | `0.9` | 0 – 1 | Yes | Configures eye shadow lift for local lights. |
| `faceIntensity` | number | `0.56` | 0 – 8 | Yes | Controls how strongly face intensity contributes. |
| `faceMaxContribution` | number | `0.24` | 0 – 1 | Yes | Configures face max contribution for local lights. |
| `faceShadowLift` | number | `0.84` | 0 – 1 | Yes | Configures face shadow lift for local lights. |
| `hairIntensity` | number | `0.72` | 0 – 8 | Yes | Controls how strongly hair intensity contributes. |
| `hairMaxContribution` | number | `0.34` | 0 – 1 | Yes | Configures hair max contribution for local lights. |
| `hairShadowLift` | number | `0.58` | 0 – 1 | Yes | Configures hair shadow lift for local lights. |
| `skinIntensity` | number | `0.64` | 0 – 8 | Yes | Controls how strongly skin intensity contributes. |
| `skinMaxContribution` | number | `0.3` | 0 – 1 | Yes | Configures skin max contribution for local lights. |
| `skinShadowLift` | number | `0.72` | 0 – 1 | Yes | Configures skin shadow lift for local lights. |

### Character toon shading: Rim Light

Adds view-dependent edge light that can be blocked or softened by shadow.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `blockByShadow` | number | `0.65` | 0 – 1 | Yes | Configures block by shadow for rim light. |
| `defaultIntensity` | number | `0.13` | 0 – 8 | Yes | Controls how strongly default intensity contributes. |
| `defaultTintColor` | color | `[0.82, 0.9, 1]` (#d1e6ff) | — | Yes | Sets the color used by default tint color. |
| `depthCloseWidthReduce` | number | `1` | 0 – 0.08 | Yes | Controls the width used by depth close width reduce. |
| `depthDottedLineFix` | boolean | `true` | — | Yes | Configures depth dotted line fix for rim light. |
| `depthFadeEndDistance` | number | `30` | 0 – 60 | Yes | Configures depth fade end distance for rim light. |
| `depthFadeRange` | number | `1` | 0 – 1 | Yes | Controls transition softness for depth fade range. |
| `depthFadeStartDistance` | number | `20` | 1 – 100 | Yes | Configures depth fade start distance for rim light. |
| `depthMask3D` | boolean | `false` | — | Yes | Configures depth mask3 d for rim light. |
| `depthSafeDistance` | number | `1` | 0 – 1 | Yes | Configures depth safe distance for rim light. |
| `depthThresholdOffset` | number | `0` | -1 – 1 | Yes | Configures depth threshold offset for rim light. |
| `depthWidth` | number | `1` | 0 – 0.08 | Yes | Controls the width used by depth width. |
| `enabled` | boolean | `true` | — | Yes | Turns rim light on or off. |
| `eyeIntensity` | number | `0.04` | 0 – 8 | Yes | Controls how strongly eye intensity contributes. |
| `faceIntensity` | number | `0.13` | 0 – 8 | Yes | Controls how strongly face intensity contributes. |
| `hairIntensity` | number | `0.23` | 0 – 8 | Yes | Controls how strongly hair intensity contributes. |
| `midPoint` | number | `0.48` | 0 – 1 | Yes | Configures mid point for rim light. |
| `mixWithBaseMapColor` | number | `0.35` | 0 – 1 | Yes | Sets the color used by mix with base map color. |
| `mode` | select | `'depthTexture'` | `fresnel` \| `depthTexture` | Yes | Configures mode for rim light. |
| `skinIntensity` | number | `0.13` | 0 – 8 | Yes | Controls how strongly skin intensity contributes. |
| `softness` | number | `0.1` | 0 – 1 | Yes | Configures softness for rim light. |

### Character toon shading: Contact Shadow

Adds thin screen-space contact shadows (hair-on-face, arm-on-torso) from the depth prepass.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Turns contact shadow on or off. |
| `strength` | number | `0.5` | 0 – 1 | Yes | Configures strength for contact shadow. |
| `faceHeadUpBlend` | number | `0` | 0 – 1 | Yes | Configures face head up blend for contact shadow. |
| `faceStrength` | number | `0.4` | 0 – 8 | Yes | Controls the blend strength for face strength. |
| `fadeRange` | number | `1` | 0 – 1 | Yes | Controls transition softness for fade range. |
| `thresholdOffset` | number | `0` | -1 – 1 | Yes | Configures threshold offset for contact shadow. |
| `width` | number | `1` | 0 – 1 | Yes | Configures width for contact shadow. |

### Character toon shading: Specular

Adds role-aware stylized highlights and optional source specular masks.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultColor` | color | `[1, 0.96, 0.9]` (#fff5e6) | — | Yes | Sets the color used by default color. |
| `defaultIntensity` | number | `0.075` | 0 – 8 | Yes | Controls how strongly default intensity contributes. |
| `defaultMidPoint` | number | `0.72` | -1 – 1 | Yes | Moves the center point for default mid point. |
| `defaultPower` | number | `56` | 1 – 128 | Yes | Controls the sharpness of default power. |
| `defaultRange` | number | `0.12` | 0 – 1 | Yes | Controls transition softness for default range. |
| `defaultShowInShadowArea` | number | `0.25` | 0 – 1 | Yes | Configures default show in shadow area for specular. |
| `directionMode` | select | `'light'` | `light` \| `view` | Yes | Selects the policy used by direction mode. |
| `enabled` | boolean | `true` | — | Yes | Turns specular on or off. |
| `eyeIntensity` | number | `0.62` | 0 – 8 | Yes | Controls how strongly eye intensity contributes. |
| `eyeMidPoint` | number | `0.35` | -1 – 1 | Yes | Moves the center point for eye mid point. |
| `eyePower` | number | `18` | 1 – 128 | Yes | Controls the sharpness of eye power. |
| `eyeRange` | number | `0.18` | 0 – 1 | Yes | Controls transition softness for eye range. |
| `eyeShowInShadowArea` | number | `1` | 0 – 1 | Yes | Configures eye show in shadow area for specular. |
| `faceIntensity` | number | `0.025` | 0 – 8 | Yes | Controls how strongly face intensity contributes. |
| `hairIntensity` | number | `0.18` | 0 – 8 | Yes | Controls how strongly hair intensity contributes. |
| `hairPower` | number | `40` | 1 – 128 | Yes | Controls the sharpness of hair power. |
| `maskChannel` | select | `0` | `0` \| `1` \| `2` \| `3` | Yes | Configures mask channel for specular. |
| `maskMap` | texture | — | — | No — local/runtime | Configures mask map for specular. |
| `maskStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for mask strength. |
| `metalIntensity` | number | `0.075` | 0 – 8 | Yes | Controls how strongly metal intensity contributes. |
| `skinIntensity` | number | `0.025` | 0 – 8 | Yes | Controls how strongly skin intensity contributes. |
| `sourceMaskMode` | select | `'off'` | `off` \| `source` | Yes | Selects the policy used by source mask mode. |

### Character toon shading: Hair Highlight

Adds hair-specific highlight bands, optional anisotropic strand response, and source masks.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `direction` | vector3 | `[0, 1, 0.15]` | — | Yes | Configures direction for hair highlight. |
| `enabled` | boolean | `true` | — | Yes | Turns hair highlight on or off. |
| `intensity` | number | `0.14` | 0 – 1 | Yes | Configures intensity for hair highlight. |
| `maskChannel` | select | `0` | `0` \| `1` \| `2` \| `3` | Yes | Configures mask channel for hair highlight. |
| `maskMap` | texture | — | — | No — local/runtime | Configures mask map for hair highlight. |
| `maskStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for mask strength. |
| `mode` | select | `'legacy'` | `legacy` \| `anisotropic` | Yes | Configures mode for hair highlight. |
| `shadowFloor` | number | `0.35` | 0 – 1 | Yes | Configures shadow floor for hair highlight. |
| `sideBandPower` | number | `2` | 1 – 128 | Yes | Controls the sharpness of side band power. |
| `sourceMaskMode` | select | `'off'` | `off` \| `source` | Yes | Selects the policy used by source mask mode. |
| `strandPower` | number | `7` | 1 – 128 | Yes | Controls the sharpness of strand power. |
| `uvBandAxis` | select | `0` | `0` \| `1` | Yes | Configures uv band axis for hair highlight. |
| `uvBandCenter` | number | `0.5` | 0 – 1 | Yes | Configures uv band center for hair highlight. |
| `uvBandHalfWidth` | number | `0.5` | 0 – 0.08 | Yes | Controls the width used by uv band width. |
| `uvPreset` | select | `'center'` | `center` \| `full` \| `left` \| `right` \| `vertical` \| `wide` | Yes | Selects the policy used by uv preset. |

### Character toon shading: Eye Highlight

Adds role-aware eye/catchlight boosts and optional source masks.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `color` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Configures color for eye highlight. |
| `enabled` | boolean | `true` | — | Yes | Turns eye highlight on or off. |
| `intensity` | number | `0.58` | 0 – 1 | Yes | Configures intensity for eye highlight. |
| `maskChannel` | select | `0` | `0` \| `1` \| `2` \| `3` | Yes | Configures mask channel for eye highlight. |
| `maskMap` | texture | — | — | No — local/runtime | Configures mask map for eye highlight. |
| `maskStrength` | number | `1` | 0 – 8 | Yes | Controls the blend strength for mask strength. |
| `power` | number | `22` | 0 – 44 | Yes | Configures power for eye highlight. |
| `showInShadowArea` | number | `0.4` | 0 – 1 | Yes | Configures show in shadow area for eye highlight. |
| `sourceMaskMode` | select | `'off'` | `off` \| `source` | Yes | Selects the policy used by source mask mode. |

### Character toon shading: Material Maps

Routes source normal, AO, emissive, MatCap, ramp, detail, roughness, metalness, and specular maps.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `aoStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for ao strength. |
| `detailRepeat` | vector2 | `[1, 1]` | — | Yes | Configures detail repeat for material maps. |
| `detailStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for detail strength. |
| `emissiveColor` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Sets the color used by emissive color. |
| `emissiveStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for emissive strength. |
| `enabled` | boolean | `true` | — | Yes | Turns material maps on or off. |
| `matcapStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for matcap strength. |
| `metalnessStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for metalness strength. |
| `normalScale` | vector2 | `[1, 1]` | — | Yes | Configures normal scale for material maps. |
| `normalStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for normal strength. |
| `rampStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for ramp strength. |
| `roughnessStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for roughness strength. |
| `sourceMode` | select | `'source'` | `off` \| `source` | Yes | Selects the policy used by source mode. |
| `specularColorStrength` | number | `0` | 0 – 8 | Yes | Controls the blend strength for specular color strength. |

### Character toon shading: Outlines

Controls the inverted-hull outline pass, including role-specific widths and colors.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `defaultLightingMix` | number | `0.28` | 0 – 1 | Yes | Configures default lighting mix for outlines. |
| `defaultMaxBrightness` | number | `0.38` | 0 – 2 | Yes | Configures default max brightness for outlines. |
| `defaultMinBrightness` | number | `0.04` | 0 – 2 | Yes | Configures default min brightness for outlines. |
| `defaultTintColor` | color | `[0.34, 0.33, 0.4]` (#575466) | — | Yes | Sets the color used by default tint color. |
| `defaultWidth` | number | `0.002` | 0 – 0.08 | Yes | Controls the width used by default width. |
| `depthOffset` | number | `0` | -1 – 1 | Yes | Configures depth offset for outlines. |
| `depthTest` | boolean | `true` | — | Yes | Configures depth test for outlines. |
| `depthWrite` | boolean | `false` | — | Yes | Configures depth write for outlines. |
| `enabled` | boolean | `true` | — | Yes | Turns outlines on or off. |
| `eyeLightingMix` | number | `0.28` | 0 – 1 | Yes | Configures eye lighting mix for outlines. |
| `eyeMaxBrightness` | number | `0.38` | 0 – 2 | Yes | Configures eye max brightness for outlines. |
| `eyeMinBrightness` | number | `0.04` | 0 – 2 | Yes | Configures eye min brightness for outlines. |
| `eyeTintColor` | color | `[0.34, 0.33, 0.4]` (#575466) | — | Yes | Sets the color used by eye tint color. |
| `eyeWidth` | number | `0` | 0 – 0.08 | Yes | Controls the width used by eye width. |
| `faceLightingMix` | number | `0.28` | 0 – 1 | Yes | Configures face lighting mix for outlines. |
| `faceMaxBrightness` | number | `0.48` | 0 – 2 | Yes | Configures face max brightness for outlines. |
| `faceMinBrightness` | number | `0.04` | 0 – 2 | Yes | Configures face min brightness for outlines. |
| `faceTintColor` | color | `[0.62, 0.36, 0.34]` (#9e5c57) | — | Yes | Sets the color used by face tint color. |
| `faceWidth` | number | `0` | 0 – 0.08 | Yes | Controls the width used by face width. |
| `hairCutoutWidth` | number | `0` | 0 – 0.08 | Yes | Controls the width used by hair cutout width. |
| `hairLightingMix` | number | `0.08` | 0 – 1 | Yes | Configures hair lighting mix for outlines. |
| `hairMaxBrightness` | number | `0.68` | 0 – 2 | Yes | Configures hair max brightness for outlines. |
| `hairMinBrightness` | number | `0.085` | 0 – 2 | Yes | Configures hair min brightness for outlines. |
| `hairTintColor` | color | `[0.72, 0.78, 0.9]` (#b8c7e6) | — | Yes | Sets the color used by hair tint color. |
| `hairWidth` | number | `0.00055` | 0 – 0.08 | Yes | Controls the width used by hair width. |
| `maxWidth` | number | `0.006` | 0 – 0.08 | Yes | Controls the width used by max width. |
| `metalLightingMix` | number | `0.28` | 0 – 1 | Yes | Configures metal lighting mix for outlines. |
| `metalMaxBrightness` | number | `0.38` | 0 – 2 | Yes | Configures metal max brightness for outlines. |
| `metalMinBrightness` | number | `0.04` | 0 – 2 | Yes | Configures metal min brightness for outlines. |
| `metalTintColor` | color | `[0.34, 0.33, 0.4]` (#575466) | — | Yes | Sets the color used by metal tint color. |
| `metalWidth` | number | `0.002` | 0 – 0.08 | Yes | Controls the width used by metal width. |
| `polygonOffset` | boolean | `false` | — | Yes | Configures polygon offset for outlines. |
| `polygonOffsetFactor` | number | `1` | -1 – 1 | Yes | Configures polygon offset factor for outlines. |
| `polygonOffsetUnits` | number | `1` | -1 – 1 | Yes | Configures polygon offset units for outlines. |
| `referenceDistance` | number | `4` | 0.5 – 20 | Yes | Configures reference distance for outlines. |
| `referenceFov` | number | `40` | 10 – 120 | Yes | Configures reference fov for outlines. |
| `screenSpaceWidth` | number | `1` | 0 – 0.08 | Yes | Controls the width used by screen space width. |
| `smoothNormals` | boolean | `true` | — | Yes | Configures smooth normals for outlines. |
| `widthFadeDistance` | number | `12` | 1 – 100 | Yes | Configures width fade distance for outlines. |
| `skinLightingMix` | number | `0.28` | 0 – 1 | Yes | Configures skin lighting mix for outlines. |
| `skinMaxBrightness` | number | `0.48` | 0 – 2 | Yes | Configures skin max brightness for outlines. |
| `skinMinBrightness` | number | `0.04` | 0 – 2 | Yes | Configures skin min brightness for outlines. |
| `skinTintColor` | color | `[0.62, 0.36, 0.34]` (#9e5c57) | — | Yes | Sets the color used by skin tint color. |
| `skinWidth` | number | `0.001` | 0 – 0.08 | Yes | Controls the width used by skin width. |
| `transparentOverlayWidth` | number | `0` | 0 – 0.08 | Yes | Controls the width used by transparent overlay width. |
| `widthScale` | number | `1` | 0 – 4 | Yes | Configures width scale for outlines. |

### Character toon shading: Glitter

Adds procedural view-dependent sparkles for sparkly costumes and accessories. Off by default.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Turns glitter on or off. |
| `intensity` | number | `1` | 0 – 1 | Yes | Configures intensity for glitter. |
| `density` | number | `1` | 0 – 1 | Yes | Configures density for glitter. |
| `size` | number | `1` | 0 – 1 | Yes | Configures size for glitter. |
| `randomNormalStrength` | number | `0.5` | 0 – 8 | Yes | Controls the blend strength for random normal strength. |
| `showInShadowArea` | number | `0.15` | 0 – 1 | Yes | Configures show in shadow area for glitter. |
| `uvChannel` | select | `1` | `0` \| `1` | Yes | Configures uv channel for glitter. |
| `defaultIntensity` | number | `1` | 0 – 8 | Yes | Controls how strongly default intensity contributes. |
| `eyeIntensity` | number | `0` | 0 – 8 | Yes | Controls how strongly eye intensity contributes. |
| `faceIntensity` | number | `0` | 0 – 8 | Yes | Controls how strongly face intensity contributes. |
| `hairIntensity` | number | `0` | 0 – 8 | Yes | Controls how strongly hair intensity contributes. |
| `skinIntensity` | number | `0` | 0 – 8 | Yes | Controls how strongly skin intensity contributes. |

### Character toon shading: Sticker

Blends a decal/overlay texture into the albedo before lighting (ice, tattoos, damage). Off by default.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `blendMode` | select | `'normal'` | `normal` \| `add` \| `multiply` | Yes | Selects the policy used by blend mode. |
| `enabled` | boolean | `false` | — | Yes | Turns sticker on or off. |
| `map` | texture | — | — | No — local/runtime | Configures map for sticker. |
| `offset` | vector2 | `[0, 0]` | — | Yes | Configures offset for sticker. |
| `repeat` | vector2 | `[1, 1]` | — | Yes | Configures repeat for sticker. |
| `strength` | number | `1` | 0 – 1 | Yes | Configures strength for sticker. |
| `uvChannel` | select | `0` | `0` \| `1` | Yes | Configures uv channel for sticker. |

### Character toon shading: Perspective Removal

Flattens perspective around the tracked head for anime-portrait closeups. Off by default.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `amount` | number | `0` | 0 – 1 | Yes | Configures amount for perspective removal. |
| `enabled` | boolean | `false` | — | Yes | Turns perspective removal on or off. |
| `radius` | number | `1.4` | 0 – 2.8 | Yes | Configures radius for perspective removal. |
| `startHeight` | number | `0` | 0 – 1 | Yes | Configures start height for perspective removal. |
| `endHeight` | number | `1` | 0 – 1 | Yes | Configures end height for perspective removal. |

### Character toon shading: Fur

Opt-in shell fur for matched materials (collars, trims, animal parts). Off by default.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Turns fur on or off. |
| `shellCount` | number | `8` | 0 – 16 | Yes | Configures shell count for fur. |
| `length` | number | `0.02` | 0 – 1 | Yes | Configures length for fur. |
| `gravity` | number | `0.35` | 0 – 1 | Yes | Configures gravity for fur. |
| `density` | number | `3` | 0 – 6 | Yes | Configures density for fur. |
| `rootOffset` | number | `-0.2` | -1 – 1 | Yes | Configures root offset for fur. |
| `rootShade` | number | `0.55` | 0 – 1 | Yes | Configures root shade for fur. |
| `materials` | object | — | — | No — local/runtime | Configures materials for fur. |
| `roles` | object | — | — | No — local/runtime | Configures roles for fur. |

## Environment shading

Module: `toonlab/environment` — 2 groups, 87 fields.

Settings are `{ features, parameters }`: `createEnvironmentSettings({ parameters: { exposure: 0.95 } })`.

### Environment shading: Features

Enables or disables individual environment shader feature paths.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `alphaCutout` | boolean | `true` | — | Yes | Turns alpha cutout processing on or off for environment materials. |
| `alphaMap` | boolean | `true` | — | Yes | Turns alpha map processing on or off for environment materials. |
| `ambientLight` | boolean | `true` | — | Yes | Turns ambient light processing on or off for environment materials. |
| `ambientProbe` | boolean | `true` | — | Yes | Turns ambient probe processing on or off for environment materials. |
| `aoMap` | boolean | `true` | — | Yes | Turns ao map processing on or off for environment materials. |
| `aoOverlay` | boolean | `true` | — | Yes | Turns ao overlay processing on or off for environment materials. |
| `directionalLights` | boolean | `true` | — | Yes | Turns directional lights processing on or off for environment materials. |
| `emissive` | boolean | `true` | — | Yes | Turns emissive processing on or off for environment materials. |
| `emissiveMap` | boolean | `true` | — | Yes | Turns emissive map processing on or off for environment materials. |
| `foliageCutout` | boolean | `true` | — | Yes | Turns foliage cutout processing on or off for environment materials. |
| `heightFog` | boolean | `true` | — | Yes | Turns height fog processing on or off for environment materials. |
| `interiorOcclusion` | boolean | `true` | — | Yes | Turns interior occlusion processing on or off for environment materials. |
| `leftSideShadow` | boolean | `true` | — | Yes | Turns side shadow processing on or off for environment materials. |
| `lightMap` | boolean | `true` | — | Yes | Turns lightmap processing on or off for environment materials. |
| `normalMap` | boolean | `true` | — | Yes | Turns normal map processing on or off for environment materials. |
| `packedMap` | boolean | `true` | — | Yes | Turns packed map processing on or off for environment materials. |
| `planarReflection` | boolean | `true` | — | Yes | Turns floor reflection processing on or off for environment materials. |
| `pointLights` | boolean | `true` | — | Yes | Turns point lights processing on or off for environment materials. |
| `shadowMask` | boolean | `true` | — | Yes | Turns shadow mask processing on or off for environment materials. |
| `shadowMesh` | boolean | `true` | — | Yes | Turns shadow mesh processing on or off for environment materials. |
| `skyTint` | boolean | `true` | — | Yes | Turns sky tint processing on or off for environment materials. |
| `specular` | boolean | `true` | — | Yes | Turns specular processing on or off for environment materials. |
| `spotLights` | boolean | `true` | — | Yes | Turns spot lights processing on or off for environment materials. |
| `sunBoost` | boolean | `true` | — | Yes | Turns sun boost processing on or off for environment materials. |
| `untexturedGradient` | boolean | `true` | — | Yes | Turns untextured gradient processing on or off for environment materials. |
| `vertexAo` | boolean | `true` | — | Yes | Turns vertex ao processing on or off for environment materials. |
| `windowCutout` | boolean | `true` | — | Yes | Turns window cutout processing on or off for environment materials. |

### Environment shading: Shader Parameters

Overrides numeric environment shader uniforms. Auto values preserve material defaults.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `ambientProbeBlend` | number | — | 0 – 1 | Yes | Overrides ambient probe blend; leave unset in code to use the material default. |
| `ambientStrength` | number | — | 0 – 2 | Yes | Overrides ambient strength; leave unset in code to use the material default. |
| `ambientLightInfluence` | number | — | 0 – 2 | Yes | Overrides ambient influence; leave unset in code to use the material default. |
| `aoMapStrength` | number | — | 0 – 2 | Yes | Overrides ao map strength; leave unset in code to use the material default. |
| `aoWarmth` | number | — | 0 – 1 | Yes | Overrides ao warmth; leave unset in code to use the material default. |
| `bakedGlowStrength` | number | — | 0 – 2 | Yes | Overrides baked glow; leave unset in code to use the material default. |
| `cloudShadowCoverage` | number | — | 0 – 1 | Yes | Overrides cloud shadow coverage; leave unset in code to use the material default. |
| `cloudShadowScale` | number | — | 0 – 0.1 | Yes | Overrides cloud shadow scale; leave unset in code to use the material default. |
| `cloudShadowStrength` | number | — | 0 – 2 | Yes | Overrides cloud shadow; leave unset in code to use the material default. |
| `directLightStrength` | number | — | 0 – 2 | Yes | Overrides direct light; leave unset in code to use the material default. |
| `emissiveMapStrength` | number | — | 0 – 2 | Yes | Overrides emissive map strength; leave unset in code to use the material default. |
| `emissiveStrength` | number | — | 0 – 2 | Yes | Overrides emissive strength; leave unset in code to use the material default. |
| `exposure` | number | — | 0 – 2 | Yes | Overrides exposure; leave unset in code to use the material default. |
| `heightFogColor` | color | — | — | Yes | Overrides height fog color; leave unset in code to use the material default. |
| `heightFogDensity` | number | — | 0 – 0.5 | Yes | Overrides height fog density; leave unset in code to use the material default. |
| `heightFogFalloff` | number | — | 0.05 – 600 | Yes | Overrides height fog falloff; leave unset in code to use the material default. |
| `interiorOcclusionColor` | color | — | — | Yes | Overrides interior occlusion color; leave unset in code to use the material default. |
| `interiorOcclusionStrength` | number | — | 0 – 2 | Yes | Overrides interior occlusion strength; leave unset in code to use the material default. |
| `leftSideShadow` | number | — | 0 – 1 | Yes | Overrides side shadow; leave unset in code to use the material default. |
| `leftSideShadowColor` | color | — | — | Yes | Overrides side shadow color; leave unset in code to use the material default. |
| `lightMapLift` | number | — | 0 – 1 | Yes | Overrides lightmap lift; leave unset in code to use the material default. |
| `lightMapStrength` | number | — | 0 – 2 | Yes | Overrides lightmap strength; leave unset in code to use the material default. |
| `lightingInfluence` | number | — | 0 – 2 | Yes | Overrides lighting influence; leave unset in code to use the material default. |
| `normalMapStrength` | number | — | 0 – 2 | Yes | Overrides normal map strength; leave unset in code to use the material default. |
| `packedOcclusionStrength` | number | — | 0 – 2 | Yes | Overrides packed occlusion; leave unset in code to use the material default. |
| `planarReflectionFresnel` | number | — | 0.1 – 8 | Yes | Overrides floor reflection fresnel; leave unset in code to use the material default. |
| `planarReflectionStrength` | number | — | 0 – 2 | Yes | Overrides floor reflection strength; leave unset in code to use the material default. |
| `pointLightStrength` | number | — | 0 – 2 | Yes | Overrides point light; leave unset in code to use the material default. |
| `saturation` | number | — | 0 – 2 | Yes | Overrides saturation; leave unset in code to use the material default. |
| `shadeSoftness` | number | — | 0 – 1 | Yes | Overrides shade softness; leave unset in code to use the material default. |
| `shadeStrength` | number | — | 0 – 2 | Yes | Overrides shade strength; leave unset in code to use the material default. |
| `shadowLift` | number | — | 0 – 1 | Yes | Overrides shadow lift; leave unset in code to use the material default. |
| `sunShadowStrength` | number | — | 0 – 2 | Yes | Overrides sun shadow strength; leave unset in code to use the material default. |
| `shadowTintColor` | color | — | — | Yes | Overrides shadow tint; leave unset in code to use the material default. |
| `skyGroundTint` | color | — | — | Yes | Overrides sky ground tint; leave unset in code to use the material default. |
| `skyTintStrength` | number | — | 0 – 2 | Yes | Overrides sky tint strength; leave unset in code to use the material default. |
| `skyTopTint` | color | — | — | Yes | Overrides sky top tint; leave unset in code to use the material default. |
| `specularColor` | color | — | — | Yes | Overrides specular color; leave unset in code to use the material default. |
| `specularShininess` | number | — | 1 – 256 | Yes | Overrides specular shininess; leave unset in code to use the material default. |
| `specularSoftness` | number | — | 0 – 1 | Yes | Overrides specular softness; leave unset in code to use the material default. |
| `specularStrength` | number | — | 0 – 2 | Yes | Overrides specular strength; leave unset in code to use the material default. |
| `spotLightStrength` | number | — | 0 – 2 | Yes | Overrides spot light; leave unset in code to use the material default. |
| `sunBoost` | number | — | 0 – 1 | Yes | Overrides sun boost; leave unset in code to use the material default. |
| `sunBoostColor` | color | — | — | Yes | Overrides sun boost color; leave unset in code to use the material default. |
| `cliffFade` | number | — | 0 – 1 | Yes | Overrides cliff fade; leave unset in code to use the material default. |
| `cliffNoiseScale` | number | — | 0 – 1 | Yes | Overrides cliff noise scale; leave unset in code to use the material default. |
| `cliffNoiseStrength` | number | — | 0 – 2 | Yes | Overrides cliff noise strength; leave unset in code to use the material default. |
| `cliffStart` | number | — | 0 – 1 | Yes | Overrides cliff start; leave unset in code to use the material default. |
| `colormapDecode` | number | — | 0 – 1 | Yes | Overrides colormap decode; leave unset in code to use the material default. |
| `colormapMode` | number | — | 0 – 1 | Yes | Overrides colormap mode; leave unset in code to use the material default. |
| `colormapStrength` | number | — | 0 – 2 | Yes | Overrides macro colormap; leave unset in code to use the material default. |
| `dualDetailMix` | number | — | 0 – 1 | Yes | Overrides dual detail mix; leave unset in code to use the material default. |
| `dualDetailScale` | number | — | 0 – 1 | Yes | Overrides dual detail scale; leave unset in code to use the material default. |
| `triplanarDetail` | number | — | 0 – 1 | Yes | Overrides triplanar detail; leave unset in code to use the material default. |
| `triplanarDetailScale` | number | — | 0.25 – 64 | Yes | Overrides triplanar detail scale; leave unset in code to use the material default. |
| `triplanarEdgeHighlight` | number | — | 0 – 1 | Yes | Overrides rock edge highlight; leave unset in code to use the material default. |
| `untexturedGradientStrength` | number | — | 0 – 2 | Yes | Overrides untextured gradient strength; leave unset in code to use the material default. |
| `vtBlendHeight` | number | — | 0 – 1 | Yes | Overrides ground melt height; leave unset in code to use the material default. |
| `vtBlendStrength` | number | — | 0 – 2 | Yes | Overrides ground melt; leave unset in code to use the material default. |
| `vertexAoStrength` | number | — | 0 – 2 | Yes | Overrides vertex ao strength; leave unset in code to use the material default. |

## Rock shader profile

Module: `toonlab/rock-shader` — 13 groups, 70 fields.

Reusable grouped material settings consumed by `applyRockShader(root, settings)`. Rock geometry, erosion, seed, LOD, collision, and current scene conditions remain separate.

### Rock shader profile: Base Projection

World-space base projection and graphic texture treatment.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `scale` | number | `1.6` | 0.05 – 256 | Yes | World-space size of the projected rock texture in meters. |
| `saturation` | number | `0.78` | 0 – 2 | Yes | Saturation retained from the projected base texture. |
| `contrast` | number | `1.12` | 0 – 3 | Yes | Contrast around the rock projection midpoint. |
| `brightness` | number | `0.015` | -1 – 1 | Yes | Linear brightness offset applied after saturation and contrast. |
| `projectionContrast` | number | `0.62` | 0.05 – 4 | Yes | Sharpness of the triplanar blend between projection axes. |
| `sideOnly` | boolean | `false` | — | Yes | Restricts the base projection to side-oriented axes. |
| `nearDetailScale` | number | `1.4` | 0.05 – 32 | Yes | World-space size of the close-range detail octave in meters. |
| `nearDetailStrength` | number | `0.24` | 0 – 1 | Yes | Strength of close-range geological value breakup. |
| `nearDetailDistance` | number | `55` | 0.1 – 2000 | Yes | Camera distance in meters over which the close-range detail octave fades out. |

### Rock shader profile: Material Response

Shared stone tint and physically based response.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `tint` | color | `[0.92, 0.88, 0.8]` (#ebe0cc) | — | Yes | IP-wide stone tint multiplied over asset color and projected detail. |
| `metallic` | number | `0` | 0 – 1 | Yes | Metallic response of ordinary rock surfaces. |
| `smoothness` | number | `0.08` | 0 – 1 | Yes | Base smoothness before top-layer masking and wetness. |
| `useSmoothnessTexture` | boolean | `false` | — | Yes | Reads the optional smoothness texture instead of a constant source. |
| `smoothnessContrast` | number | `1` | 0 – 4 | Yes | Contrast applied to the optional smoothness texture. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Base emission multiplier for deliberately luminous stone styles. |

### Rock shader profile: Shared Lighting

Rock-specific exposure and shaded-face readability under the current scene lighting.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `exposure` | number | `1` | 0 – 4 | Yes | HDR albedo exposure before scene lighting and tone mapping. |
| `ambientFloor` | number | `0.04` | 0 – 0.4 | Yes | Albedo-relative indirect floor that keeps downward-facing overhangs readable. |
| `skyFillStrength` | number | `1` | 0 – 2 | Yes | Rock-specific strength of the scene sky probe; direct sunlight is unchanged. |
| `skyFillTint` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Rock-specific RGB weighting for indirect sky light and blue back-shadow separation. |

### Rock shader profile: Shoreline Response

Portable wet-rock response around the current scene water level.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `wetBandWidth` | number | `0.8` | 0 – 20 | Yes | Meters around the current water level that receive the wet-rock treatment. |
| `wetBandDarkening` | number | `0.22` | 0 – 1 | Yes | Maximum albedo darkening inside the wet band. |
| `wetRoughness` | number | `0.26` | 0.02 – 1 | Yes | Roughness approached inside the wet band. |

### Rock shader profile: Distance Tint

Distance color recession shared by rocks, cliffs, and mountains.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `closeDistance` | number | `18` | 0 – 2000 | Yes | World distance where the far tint begins. |
| `farDistance` | number | `140` | 0.1 – 50000 | Yes | World distance where the far tint reaches full strength. |
| `color` | color | `[0.55, 0.62, 0.66]` (#8c9ea8) | — | Yes | Atmospheric stone tint used at long distance. |
| `strength` | number | `0.28` | 0 – 1 | Yes | Maximum blend toward the far-distance tint. |

### Rock shader profile: Normal Detail

Near and far normal-detail behavior.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `distance` | number | `75` | 0.1 – 50000 | Yes | Distance over which projected normal detail fades. |
| `nearFlatten` | number | `0.08` | -0.5 – 1.5 | Yes | Amount of projected normal flattening near the camera. |
| `farFlatten` | number | `0.75` | -0.5 – 1.5 | Yes | Amount of projected normal flattening at the fade distance. |
| `useSmoothed` | boolean | `false` | — | Yes | Uses an optional authored smoothed-normal texture as the base normal. |
| `normalGreenSign` | select | `1` | `-1` \| `1` | Yes | Normal-map green-channel convention: 1 retains Y, -1 flips it. |

### Rock shader profile: Striping

Optional graphic sediment or mineral striping over side faces.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Enables the optional side-projected stripe layer. |
| `scale` | number | `3.5` | 0.05 – 5000 | Yes | World-space size of the stripe texture. |
| `contrast` | number | `0.8` | 0 – 4 | Yes | Contrast of the stripe opacity mask. |
| `color` | color | `[0.65, 0.48, 0.3]` (#a67a4d) | — | Yes | Graphic color overlaid through the stripe mask. |

### Rock shader profile: Moss Response

Slope-aware moss treatment; current climate coverage remains scene-owned.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Enables the style capability for slope-aware moss. |
| `size` | number | `2.4` | 0.05 – 50 | Yes | World-space size of the projected moss pattern. |
| `sharpness` | number | `2.4` | 0 – 8 | Yes | Sharpness of the upward-facing moss slope mask. |
| `offset` | number | `0.35` | -1 – 1 | Yes | Upward-normal threshold where moss begins. |
| `multiply` | number | `1.6` | 0 – 6 | Yes | Strength of the projected moss coverage pattern. |
| `colorPower` | number | `1.25` | 0.1 – 6 | Yes | Contrast curve applied to the moss texture color. |
| `lowColor` | color | `[0.18, 0.28, 0.09]` (#2e4717) | — | Yes | Dark end of the shared moss color range. |
| `highColor` | color | `[0.42, 0.55, 0.2]` (#6b8c33) | — | Yes | Light end of the shared moss color range. |

### Rock shader profile: Top-Layer Mask

Shared upward-facing mask for geological top layers.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `useAssetMask` | boolean | `true` | — | Yes | Multiplies the slope mask by an optional asset-authored top mask. |
| `sharpness` | number | `2.3` | 0 – 8 | Yes | Sharpness of the shared upward-facing layer transition. |
| `offset` | number | `0.42` | -1 – 1 | Yes | Upward-normal threshold where top layers begin. |

### Rock shader profile: Grass Layer

Optional authored grass-over-rock layer, separate from current weather.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Enables grass texture projection on the shared top-layer mask. |
| `useGroundShader` | boolean | `false` | — | Yes | Uses the environment ground field for the grass cap color and surface response. |
| `scale` | number | `1.8` | 0.05 – 50 | Yes | World-space size of the projected grass texture. |
| `tint` | color | `[0.65, 0.78, 0.42]` (#a6c76b) | — | Yes | Style tint multiplied over the grass layer. |
| `saturation` | number | `0.8` | 0 – 2 | Yes | Saturation retained from the grass texture. |
| `emission` | number | `0` | 0 – 2 | Yes | Emission multiplier for the grass layer. |

### Rock shader profile: Snow Layer

Authored snow response; the current snow amount remains runtime state.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Enables the material capability for a snow top layer. |
| `scale` | number | `2` | 0.05 – 50 | Yes | World-space size of the projected snow texture. |
| `tint` | color | `[0.9, 0.95, 1]` (#e6f2ff) | — | Yes | Shared snow tint. |
| `saturation` | number | `0.3` | 0 – 2 | Yes | Saturation retained from the snow texture. |
| `emission` | number | `0` | 0 – 2 | Yes | Emission multiplier for the snow layer. |

### Rock shader profile: Sand Layer

Optional authored sand-over-rock layer and its normal response.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Enables sand projection on the shared top-layer mask. |
| `useGroundShader` | boolean | `false` | — | Yes | Uses the environment ground field for the sand cap color and surface response. |
| `scale` | number | `1.5` | 0.05 – 50 | Yes | World-space size of the projected sand texture. |
| `tint` | color | `[0.82, 0.65, 0.4]` (#d1a666) | — | Yes | Style tint multiplied over the sand layer. |
| `saturation` | number | `0.65` | 0 – 2 | Yes | Saturation retained from the sand texture. |
| `emission` | number | `0` | 0 – 2 | Yes | Emission multiplier for the sand layer. |
| `normalScale` | number | `1.5` | 0.05 – 50 | Yes | World-space size of the projected sand normal. |
| `normalStrength` | number | `0.35` | 0 – 2 | Yes | Strength of the sand-layer normal. |
| `normalRotationDegrees` | number | `30` | -180 – 180 | Yes | Rotation of the sand normal projection in degrees. |

### Rock shader profile: Asset Integration

How stable asset-authored channels participate in the shared shader.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sourceAlbedoMode` | select | `'replace'` | `replace` \| `blend` \| `retain` | Yes | Replace gives the strongest cross-library consistency; Blend admits a controlled amount of the imported texture; Retain uses it as the projected base. |
| `sourceAlbedoStrength` | number | `0.2` | 0 – 1 | Yes | Imported-albedo influence when Source Albedo is Blend. Ignored by Replace and Retain. |
| `vertexColorStrength` | number | `0.8` | 0 – 1 | Yes | Influence of asset-authored vertex color over projected rock detail. |
| `vertexAoStrength` | number | `1` | 0 – 2 | Yes | Influence of the asset-authored envVertexAo channel. |

## Ground shader profile

Module: `toonlab/ground-shader` — 10 groups, 67 fields.

Reusable grouped terrain-material settings consumed by `createGroundShaderMaterial(settings)` and `createGroundShaderMesh(geometry, settings)`. Terrain geometry, coverage, LOD, collision, and current scene conditions remain separate.

### Ground shader profile: Ground Layers

Coordinated base treatment for the four semantic ground layers.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `grassTint` | color | `[0.38, 0.61, 0.3]` (#619c4d) | — | Yes | Anime meadow tint for lawn and groundcover-painted terrain. |
| `dirtTint` | color | `[0.48, 0.43, 0.37]` (#7a6e5e) | — | Yes | Warm anime-earth tint for trails and exposed soil. |
| `rockTint` | color | `[0.58, 0.63, 0.69]` (#94a1b0) | — | Yes | Cool luminous stone tint for cliffs and embedded-rock layers. |
| `sandTint` | color | `[0.88, 0.78, 0.52]` (#e0c785) | — | Yes | Graphic shoreline tint for beaches and dry sediment. |
| `textureStrength` | number | `1` | 0 – 1 | Yes | Strength of authored layer textures relative to the graphic layer tints. |
| `saturation` | number | `1` | 0 – 2 | Yes | Saturation applied after splat-layer composition. |
| `contrast` | number | `1` | 0 – 2.5 | Yes | Contrast around the ground-color midpoint. |
| `brightness` | number | `0` | -0.5 – 0.5 | Yes | Linear brightness offset after layer composition. |

### Ground shader profile: Projection

World-space layer scale and steep-surface projection.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `grassScale` | number | `16` | 0.05 – 64 | Yes | World-space repeat size in meters for the grass layer. |
| `dirtScale` | number | `13` | 0.05 – 64 | Yes | World-space repeat size in meters for the dirt layer. |
| `rockScale` | number | `25` | 0.05 – 128 | Yes | World-space repeat size in meters for rock and cliff detail. |
| `sandScale` | number | `10` | 0.05 – 64 | Yes | World-space repeat size in meters for sand detail. |
| `triplanarStrength` | number | `1` | 0 – 1 | Yes | Strength of triplanar projection on steep surfaces. |
| `triplanarSharpness` | number | `2` | 0.25 – 12 | Yes | Sharpness of blending between triplanar projection axes. |

### Ground shader profile: Macro Variation

Large-scale color variation that prevents flat, repeating terrain.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `amount` | number | `0.16` | 0 – 1 | Yes | Primary world-space brightness variation. |
| `scale` | number | `0.045` | 0.0005 – 0.5 | Yes | Primary macro-noise frequency in inverse meters. |
| `secondaryAmount` | number | `0.08` | 0 – 1 | Yes | Secondary broad variation that breaks the primary pattern. |
| `secondaryScale` | number | `0.012` | 0.0002 – 0.25 | Yes | Secondary macro-noise frequency in inverse meters. |
| `tint` | color | `[0.74, 0.86, 0.58]` (#bddb94) | — | Yes | Graphic color introduced through macro variation. |
| `tintStrength` | number | `0.12` | 0 – 1 | Yes | Maximum blend toward the macro tint. |
| `rockDetailAmount` | number | `0.3` | 0 – 1 | Yes | Triplanar geological value variation applied to steep rock surfaces even when no authored layer map is supplied. |
| `rockDetailScale` | number | `0.42` | 0.005 – 4 | Yes | World-space frequency for procedural triplanar cliff detail. |
| `rockStrataAmount` | number | `0.2` | 0 – 1 | Yes | Horizontal geological band variation applied to steep cliff surfaces. |
| `rockStrataScale` | number | `0.72` | 0.01 – 8 | Yes | Vertical frequency for procedural cliff strata. |

### Ground shader profile: Slope Response

How steep terrain transitions toward the rock treatment.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `autoRockStrength` | number | `0.82` | 0 – 1 | Yes | Maximum automatic rock-layer takeover on steep terrain. |
| `start` | number | `0.18` | 0 – 1 | Yes | World-normal slope value where automatic rock begins. |
| `fade` | number | `0.16` | 0.001 – 1 | Yes | Width of the grass-to-rock slope transition. |
| `noiseStrength` | number | `0.08` | 0 – 0.5 | Yes | World-noise offset that prevents analytic contour bands. |
| `noiseScale` | number | `0.035` | 0.0005 – 0.5 | Yes | Frequency of the slope-transition noise. |
| `edgeHighlight` | number | `0.28` | 0 – 2 | Yes | Warm graphic lift along the flat-to-cliff transition. |

### Ground shader profile: Shoreline Response

Response to the current scene water level; the water level itself is never serialized.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `autoSandStrength` | number | `0.55` | 0 – 1 | Yes | Automatic blend toward the sand treatment near current water level. |
| `bandWidth` | number | `3.5` | 0.05 – 40 | Yes | Meters around water level that can receive automatic sand. |
| `softness` | number | `1.25` | 0.01 – 20 | Yes | Softness in meters of the automatic shoreline transition. |
| `wetBandWidth` | number | `0.7` | 0 – 10 | Yes | Meters above water level that receive a damp shoreline response. |
| `wetBandDarkening` | number | `0.18` | 0 – 1 | Yes | Maximum darkening in the damp shoreline band. |

### Ground shader profile: Material Response

Shared physically based response for the ground surface.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `roughness` | number | `0.9` | 0 – 1 | Yes | Dry ground roughness before current wetness. |
| `metalness` | number | `0` | 0 – 1 | Yes | Metallic response for deliberately unusual ground styles. |
| `microOcclusionStrength` | number | `0.16` | 0 – 1 | Yes | Subtle broad surface occlusion derived from terrain form and macro variation. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Emission multiplier for deliberately luminous ground styles. |

### Ground shader profile: Lighting

Ground-specific response to the current scene sun and sky.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sunIntensity` | number | `1` | 0 – 4 | Yes | Exposure of sun-facing ground after the graphic light/shade split. Values above one preserve HDR headroom for tone mapping. |
| `backShadowStrength` | number | `0.38` | 0 – 0.8 | Yes | Directional value loss on terrain faces turned away from the current sun; keeps cliffs from reading as unlit flat color. |
| `shadowTint` | color | `[0.68, 0.74, 0.94]` (#adbdf0) | — | Yes | Cool tint introduced on surfaces facing away from the current sun. |
| `shadowTintStrength` | number | `0.34` | 0 – 1 | Yes | Strength of the cool ground-shadow treatment. |
| `shadowLift` | number | `0.4` | 0 – 1 | Yes | Albedo-relative floor retained in shaded ground. |
| `sunTintStrength` | number | `0.18` | 0 – 1 | Yes | Influence of current sun color on lit ground. |
| `skyFillStrength` | number | `0.12` | 0 – 1 | Yes | Influence of current sky color on shaded ground. |
| `rimStrength` | number | `0.06` | 0 – 1 | Yes | View-dependent grazing-angle color lift. |

### Ground shader profile: Weather Response

How ground responds to current wetness and snow coverage.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `wetDarkening` | number | `0.24` | 0 – 1 | Yes | Maximum albedo darkening at full wetness. |
| `wetDesaturation` | number | `0.08` | 0 – 1 | Yes | Maximum color desaturation at full wetness. |
| `wetRoughness` | number | `0.38` | 0 – 1 | Yes | Roughness approached at full wetness. |
| `snowTint` | color | `[0.92, 0.96, 1]` (#ebf5ff) | — | Yes | Ground snow tint. |
| `snowStrength` | number | `0.92` | 0 – 1 | Yes | Maximum visible snow coverage response. |
| `snowSlopeStart` | number | `0.62` | -1 – 1 | Yes | Upward-normal threshold where snow begins to remain. |
| `snowSoftness` | number | `0.22` | 0.001 – 1 | Yes | Softness of the snow slope transition. |

### Ground shader profile: Print Response

How printable dirt, sand, and snow respond to transient footprint and track stamps.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `strength` | number | `1` | 0 – 1 | Yes | Master visibility of the transient Ground Print Layer. |
| `dirtStrength` | number | `0.7` | 0 – 1 | Yes | Printability of the painted dirt layer. |
| `sandStrength` | number | `1` | 0 – 1 | Yes | Printability of the painted sand layer. |
| `snowStrength` | number | `1` | 0 – 1 | Yes | Printability of current snow once scene snow depth is sufficient. |
| `depressionDarkening` | number | `0.28` | 0 – 1 | Yes | Albedo darkening inside compressed or displaced material. |
| `rimLightening` | number | `0.22` | 0 – 1 | Yes | Graphic lift on the raised edge around a print. |
| `normalStrength` | number | `1.4` | 0 – 6 | Yes | World-space normal relief derived from the print field. |
| `compactedRoughness` | number | `0.5` | 0 – 1 | Yes | Roughness approached inside compacted prints. |

### Ground shader profile: Distance Treatment

Atmospheric recession and detail simplification over viewing distance.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `start` | number | `500` | 0 – 10000 | Yes | Distance in meters where atmospheric ground tint begins. |
| `end` | number | `15000` | 1 – 50000 | Yes | Distance in meters where atmospheric tint reaches full strength. |
| `color` | color | `[0.59375, 0.59375, 0.59375]` (#979797) | — | Yes | Atmospheric ground color at long distance. |
| `strength` | number | `0.5` | 0 – 1 | Yes | Maximum blend toward the far-distance color. |
| `detailFade` | number | `1` | 0 – 1 | Yes | Amount of high-frequency texture and macro detail removed at range. |

## Water

Module: `toonlab/water` — 7 groups, 82 fields.

Flat authored settings for `WaterSurface`; live sun/sky and Weather wave energy compose through transient scene layers without changing portable `water.settings`. Quality is a construction-time graph policy.

### Water: Waves

Gerstner swell and detail ripple shaping.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `waveIntensity` | number | `0.25` | 0 – 1 | Yes | Authored baseline from glassy mirror (0) to storm swell (1); scene weather can transiently modulate it without changing the preset. |
| `waterLevel` | number | `0.36` | 0 – 4 | Yes | World-space rest height of the surface; waves and run-up displace around it. |
| `waveAmplitude` | number | `0.3` | 0 – 5 | Yes | Largest wave amplitude in meters at full intensity; 5 gives a 10 m crest-to-trough swell. |
| `shoalingDepth` | number | `1.4` | 0.05 – 12 | Yes | Column depth in meters at which waves reach full height; shallower water shrinks them (needs a bed height sampler). |
| `shorelineWaves` | number | `0.35` | 0 – 1 | Yes | Fraction of wave height that keeps rolling through the shallows as surf before dying at the waterline. |
| `shorelineRunup` | number | `0.6` | 0 – 3 | Yes | How far incoming waves wash a thin foam film up the beach; reach scales with wave energy. |
| `runupDistance` | number | `0` | 0 – 15 | Yes | Maximum horizontal reach in meters. Wave groups vary each event from 80–100%, and each backwash hands its endpoint into the next uprush. 0 lets wave energy decide. |
| `breakerEnabled` | boolean | `true` | — | Yes | Master switch for the breaker system; off removes the mesh and skips all breaker work (for perf A/B). |
| `breakerAmount` | number | `0` | 0 – 1 | Yes | Dedicated curling breaker shells along the break line; 0 disables the system (needs a bed height sampler). |
| `breakerCurl` | number | `0.8` | 0 – 1 | Yes | Lip pitch: 0 spills down the face, 1 curls a full surfable tunnel. |
| `breakerScale` | number | `1` | 0.25 – 3 | Yes | Shell height multiplier over the physical breaking height (0.72x column depth). |
| `breakerPeel` | number | `1` | 0 – 4 | Yes | How fast the barrel section travels sideways along the crest line. |
| `waveLength` | number | `7.5` | 1 – 120 | Yes | Longest wavelength in meters; smaller waves are derived from it. Big swells need long wavelengths to stay stable. |
| `waveSteepness` | number | `0.75` | 0 – 1.4 | Yes | Gerstner chop; higher values pinch crests sharper. |
| `waveSpeed` | number | `1` | 0 – 4 | Yes | Phase speed multiplier over the deep-water dispersion. |
| `waveDirection` | vector2 | `[1, 0.35]` | — | Yes | Main travel direction of the swell in the XZ plane. |
| `waveDirectionSpread` | number | `0.65` | 0 – 1 | Yes | 0 keeps all waves aligned (river); 1 spreads them omnidirectionally (open sea). The primary swell always follows Wave Direction exactly. |
| `waveSetPeriod` | number | `60` | 8 – 600 | Yes | Seconds between wave-set peaks at a fixed point; big waves arrive in groups, not every period. |
| `waveSetStrength` | number | `0.5` | 0 – 1 | Yes | Depth of the set/lull cycle: 0 = constant swell, 1 = the swell dies completely between sets. |
| `detailNormalStrength` | number | `0.32` | 0 – 2 | Yes | Strength of the procedural micro-ripple normal detail. |
| `detailScale` | number | `1.15` | 0.05 – 8 | Yes | Spatial frequency of the micro-ripple detail. |
| `flowDirection` | vector2 | `[0.72, -0.18]` | — | Yes | Scroll direction for detail ripples, foam noise, and sparkles. |
| `flowSpeed` | number | `0.3` | 0 – 4 | Yes | Scroll speed for surface detail; high values read as a river current. |

### Water: Surface

Water body color, refraction, and caustics.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `colorTone` | select | `'classic'` | `classic` \| `anime` \| `teal` \| `caribbean` \| `lagoon` \| `deepOcean` | Yes | Named body-color palette forced over the preset colors; classic returns control to the preset. |
| `shallowColor` | color | `[0.42, 0.85, 0.88]` (#6bd9e0) | — | Yes | Water tint right at the shoreline. |
| `midColor` | color | `[0.2, 0.62, 0.8]` (#339ecc) | — | Yes | Water tint at moderate depth. |
| `deepColor` | color | `[0.1, 0.38, 0.6]` (#1a6199) | — | Yes | Water tint where the bottom is no longer visible. |
| `depthFadeDistance` | number | `1` | 0.05 – 12 | Yes | Water column depth where the shallow tint gives way to mid. |
| `deepFadeDistance` | number | `2.2` | 0.05 – 24 | Yes | Additional depth where mid fades to the deep tint. |
| `opacity` | number | `0.8` | 0 – 1 | Yes | Base transparency when no scene color grab pass is bound. |
| `refractionStrength` | number | `0.35` | 0 – 2 | Yes | Screen-space distortion of the underwater scene. |
| `indexOfRefraction` | number | `1.333` | 1.0001 – 1.8 | Yes | Index of refraction used by the underwater Snell window and total internal reflection. |
| `underwaterTransmission` | number | `1` | 0 – 1 | Yes | Visibility of the real above-water scene through the surface from below. |
| `underwaterTintStrength` | number | `0.35` | 0 – 1 | Yes | Stylized water-color tint applied to the view through the surface. |
| `causticsStrength` | number | `0.55` | 0 – 3 | Yes | Brightness of the procedural voronoi caustics on the bottom. |
| `causticsScale` | number | `0.8` | 0.05 – 8 | Yes | Spatial frequency of the caustic web. |
| `causticsSpeed` | number | `0.6` | 0 – 4 | Yes | Animation speed of the caustic web. |

### Water: Foam

Shoreline foam, whitecaps, and wake foam.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `foamColor` | color | `[0.94, 1, 0.99]` (#f0fffc) | — | Yes | Color of all foam: shoreline, whitecaps, wakes, and splashes. |
| `foamAmount` | number | `1` | 0 – 2 | Yes | Offshore contact foam, whitecap, and wake gain. |
| `swashFoamAmount` | number | `1.15` | 0 – 2 | Yes | Independent gain for torn foam carried up and back down the beach. |
| `swashFoamLifetime` | number | `4` | 0.25 – 30 | Yes | Seconds fresh aerated swash foam remains before thinning into residue. |
| `swashFoamResidueLifetime` | number | `10` | 0.5 – 60 | Yes | Seconds fragmented beach foam persists and drifts after the active front passes. |
| `wetSandDryTime` | number | `120` | 2 – 600 | Yes | Seconds saturated sand takes to return to its dry color after the water retreats. |
| `wetSandDarkening` | number | `0.58` | 0 – 1 | Yes | How strongly remembered moisture darkens exposed sand. |
| `wetSandSheen` | number | `0.78` | 0 – 1 | Yes | Strength of the short-lived glossy water film left on freshly exposed sand. |
| `foamContactDistance` | number | `0.4` | 0.02 – 4 | Yes | Depth difference covered by the solid contact foam band. |
| `foamLineSpacing` | number | `0.55` | 0.05 – 4 | Yes | Spacing of the animated lapping foam lines off the shore. |
| `foamNoiseScale` | number | `0.6` | 0.05 – 8 | Yes | Breakup noise frequency for foam edges. |
| `whitecapAmount` | number | `0.05` | 0 – 1 | Yes | Coverage of breaking crests on open water. |
| `rippleFoamStrength` | number | `0.8` | 0 – 3 | Yes | Foam intensity left behind by interactive ripples and wakes. |

### Water: Lighting

Authored fallback sun/sky plus water-specific glint, fresnel, and reflection response.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sunDirection` | vector3 | `[0.35, 0.8, 0.45]` | — | Yes | Authored fallback direction toward the sun when no live scene-light override is connected. |
| `sunColor` | color | `[1, 0.96, 0.86]` (#fff5db) | — | Yes | Authored fallback sun tint for glints, sparkles, and caustics; a live scene rig may replace it transiently. |
| `specularStrength` | number | `0.8` | 0 – 3 | Yes | Toon sun-glint intensity. |
| `specularShininess` | number | `150` | 4 – 2000 | Yes | Glint tightness; higher is smaller and sharper. |
| `specularStretch` | number | `0.35` | 0 – 0.95 | Yes | Elongates glints along the sun azimuth into a sparkling sun path. |
| `sparkleStrength` | number | `0.5` | 0 – 3 | Yes | Twinkling star-glint intensity. |
| `sparkleScale` | number | `1.5` | 0.1 – 16 | Yes | Density of the sparkle field. |
| `sparkleSpeed` | number | `1` | 0 – 6 | Yes | How quickly sparkles twinkle in and out. |
| `sunGlowStrength` | number | `0.85` | 0 – 3 | Yes | Sun disk glow in the procedural sky reflection. |
| `sceneShadowStrength` | number | `0.6` | 0 – 1 | Yes | How strongly cast shadows from rocks, trees, and the character darken the surface. |
| `fresnelStrength` | number | `0.9` | 0 – 2 | Yes | Grazing-angle reflectivity boost. |
| `fresnelPower` | number | `4.5` | 0.5 – 12 | Yes | Falloff of the fresnel band toward the horizon. |
| `fresnelBias` | number | `0.16` | 0 – 0.6 | Yes | Sky-tint floor at steep angles; higher reads more anime-blue. |
| `fresnelColor` | color | `[0.68, 0.9, 1]` (#ade6ff) | — | Yes | Additive rim tint at grazing angles. |
| `skyZenithColor` | color | `[0.5, 0.74, 0.98]` (#80bdfa) | — | Yes | Authored fallback procedural sky-reflection color overhead when no live scene sky is connected. |
| `skyHorizonColor` | color | `[0.86, 0.95, 1]` (#dbf2ff) | — | Yes | Authored fallback procedural sky-reflection color at the horizon when no live scene sky is connected. |
| `reflectionStrength` | number | `0.62` | 0 – 1.5 | Yes | Planar/sky reflection mix, weighted by fresnel. |
| `reflectionDistortion` | number | `0.04` | 0 – 0.3 | Yes | How much waves shatter the reflection. |
| `reflectionSoftness` | number | `0.55` | 0 – 1 | Yes | Blends sharp planar reflections toward the soft procedural sky (milky anime look). |

### Water: Ripples

Interactive ripple simulation response.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `rippleStrength` | number | `1` | 0 – 6 | Yes | Global multiplier for splash and wake impulses. |
| `rippleDamping` | number | `0.985` | 0.9 – 0.999 | Yes | Energy retained per frame; higher rings travel farther. |
| `ripplePropagation` | number | `11` | 1 – 40 | Yes | Travel speed of interactive rings across the surface. |
| `rippleHeightScale` | number | `1` | 0 – 4 | Yes | Vertical displacement of the interactive ripples. |
| `rippleFoamDecay` | number | `0.94` | 0.5 – 0.999 | Yes | How long wake foam lingers. |
| `rippleFoamGain` | number | `2.4` | 0 – 12 | Yes | How quickly motion generates wake foam. |

### Water: Splashes

Procedural splash droplets, spray, and rings.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `splashStrength` | number | `1` | 0 – 3 | Yes | Global multiplier for splash particle counts and energy. |
| `splashScale` | number | `1` | 0.1 – 4 | Yes | Physical size multiplier for droplets, spray, and rings. |
| `splashDropletCount` | number | `26` | 0 – 120 | Yes | Droplets emitted by a strength-1 splash. |
| `splashRingCount` | number | `2` | 0 – 4 | Yes | Expanding foam rings emitted per splash. |
| `splashColor` | color | `[0.97, 1, 1]` (#f7ffff) | — | Yes | Bright tone of droplets and spray. |
| `splashShadeColor` | color | `[0.62, 0.86, 0.95]` (#9edbf2) | — | Yes | Shadow tone of the two-tone splash shading. |

### Water: Quality

Shader quality tier gating caustics, sparkles, and noise octaves.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `quality` | select | `'high'` | `low` \| `medium` \| `high` | Yes | Named quality tier: low drops caustics and sparkles, high adds chromatic caustics and extra detail octaves. |

## Post-processing

Module: `toonlab/post` — 2 groups, 44 fields.

Settings are `{ features, parameters }`: `createPostProcessingSettings({ preset: "softAnime" })`.

### Post-processing: Features

Toggles for each optional screen-space effect in the final composite pass.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `atmosphere` | boolean | `false` | — | Yes | Two-layer stylized atmosphere: distance/height mix fog plus an additive sun/moon glow halo, colored by the scene environment state. |
| `bloom` | boolean | `false` | — | Yes | Adds glow around pixels brighter than the bloom threshold. |
| `colorGrade` | boolean | `false` | — | Yes | Applies exposure, contrast, saturation, and warmth grading. |
| `depthCue` | boolean | `false` | — | Yes | Fades distant pixels toward the depth cue color for atmospheric depth. |
| `enabled` | boolean | `false` | — | Yes | Forces the post-processing composite pass on, even with no individual effect active. |
| `motionBlur` | boolean | `false` | — | Yes | Blurs camera movement by reprojecting the previous frame (camera motion only). |
| `screenOutline` | boolean | `false` | — | Yes | Draws screen-space outlines from depth and luminance edges. |
| `vignette` | boolean | `false` | — | Yes | Darkens the frame toward the corners. |
| `verticalGrade` | boolean | `false` | — | Yes | Adds warm light at the top of the frame and darkening at the bottom. |

### Post-processing: Parameters

Tuning values used by the post-processing effects when their feature toggles are on.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `bloomBackgroundSuppress` | number | `1` | 0 – 2 | Yes | Scales bloom gathered from non-character pixels when a character mask is connected. |
| `bloomCharacterBoost` | number | `1` | 0 – 4 | Yes | Scales bloom gathered from character pixels when a character mask is connected. |
| `bloomLevels` | number | `5` | 2 – 8 | Yes | Number of mip levels in the pyramid bloom chain (pyramid mode only). |
| `bloomMode` | select | `'single'` | `single` \| `pyramid` | Yes | Selects the one-pass 9-tap bloom or the wider multi-pass pyramid bloom. |
| `bloomRadius` | number | `0.16` | 0 – 1 | Yes | Controls how far the bloom glow spreads from bright pixels. |
| `bloomStrength` | number | `0` | 0 – 2 | Yes | Controls how strongly bloom is added to the image. |
| `bloomThreshold` | number | `0.995` | 0 – 1 | Yes | Sets the luminance above which pixels start to bloom. |
| `bottomDark` | number | `0` | 0 – 1 | Yes | Darkens the lower part of the frame in the vertical grade. |
| `atmosphereBaseHeight` | number | `0` | -100 – 500 | Yes | World height where atmosphere fog is densest; fog thins above it. |
| `atmosphereFar` | number | `900` | 10 – 4000 | Yes | View distance in meters where atmosphere fog reaches full strength. |
| `atmosphereGlowStrength` | number | `1` | 0 – 3 | Yes | Multiplier on the environment-state sun/moon glow fog. |
| `atmosphereHeightFalloff` | number | `0.012` | 0 – 0.2 | Yes | How quickly atmosphere fog thins with altitude above the base height. |
| `atmosphereNear` | number | `60` | 0 – 1000 | Yes | View distance in meters where atmosphere fog starts. |
| `atmosphereStrength` | number | `0.55` | 0 – 1 | Yes | Maximum blend of the atmospheric mix fog. |
| `contrast` | number | `1` | 0 – 2 | Yes | Scales contrast around mid gray in the color grade. |
| `depthCueColor` | color | `[0.3371636150376657, 0.4735314961384573, 0.6866853124288864]` (#5679af) | — | Yes | Sets the color distant pixels fade toward. |
| `depthCueFar` | number | `24` | 0 – 200 | Yes | Sets the depth at which the depth cue reaches full strength. |
| `depthCueNear` | number | `1` | 0 – 50 | Yes | Sets the depth at which the depth cue starts to appear. |
| `depthCueStrength` | number | `0` | 0 – 1 | Yes | Controls how strongly distant pixels blend toward the depth cue color. |
| `exposure` | number | `1` | 0 – 4 | Yes | Multiplies overall image brightness in the color grade. |
| `lutMap` | texture | — | — | No — local/runtime | Optional 2D-strip color LUT texture (runtime only, not serialized). |
| `lutSize` | number | `0` | 0 – 64 | Yes | Slice size of the LUT strip; 0 derives it from the texture height. |
| `lutStrength` | number | `0` | 0 – 1 | Yes | Controls how strongly the LUT recolors the graded image. |
| `motionBlurStrength` | number | `0.55` | 0 – 2 | Yes | Scales the camera-reprojection blur distance along the motion vector. |
| `outlineColor` | color | `[0.005181516700061659, 0.006512090790025684, 0.010329823026364548]` (#010203) | — | Yes | Sets the color drawn on detected screen-space edges. |
| `outlineDepthStrength` | number | `0.16` | 0 – 2 | Yes | Controls how strongly depth discontinuities contribute to outlines. |
| `outlineLumaStrength` | number | `0.04` | 0 – 2 | Yes | Controls how strongly luminance edges contribute to outlines. |
| `outlineStrength` | number | `0` | 0 – 2 | Yes | Controls the overall opacity of screen-space outlines. |
| `saturation` | number | `1` | 0 – 2 | Yes | Scales color saturation in the color grade. |
| `strength` | number | `1` | 0 – 1 | Yes | Blends between the raw render and the full post-processing result. |
| `topLight` | number | `0` | 0 – 1 | Yes | Adds warm light to the upper part of the frame in the vertical grade. |
| `vignetteRadius` | number | `0.55` | 0 – 1 | Yes | Sets the distance from the frame center where the vignette starts. |
| `vignetteSoftness` | number | `0.34` | 0 – 1 | Yes | Controls the falloff width of the vignette edge. |
| `vignetteStrength` | number | `0` | 0 – 1 | Yes | Controls how strongly the vignette darkens the frame edges. |
| `warmth` | number | `0` | -1 – 1 | Yes | Shifts the color grade warmer (positive) or cooler (negative). |

## Vegetation shader family

Module: `toonlab/vegetation-shaders` — 8 groups, 104 fields.

Shared field registry for three independent portable profiles: Tree uses Shared/Foliage/Bark groups, Grass uses Shared/Grass groups, and Flower uses Shared/Foliage/Flower/Stem groups. Asset geometry, species, albedo, and current scene weather remain separate.

### Vegetation shader family: Shared Lighting

IP-wide light and shadow treatment shared by every vegetation surface.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `shadowTint` | color | `[0.36, 0.4, 0.58]` (#5c6694) | — | Yes | Cool treatment tint mixed into shadowed vegetation without replacing its albedo. |
| `shadowTintStrength` | number | `1` | 0 – 1 | Yes | Strength of the shared shadow tint treatment. |
| `sunTintStrength` | number | `0.25` | 0 – 1 | Yes | How strongly the active sun color tints lit vegetation. |
| `skyFillStrength` | number | `0.08` | 0 – 0.5 | Yes | Shared sky-color fill in unlit vegetation regions. |
| `rimStrength` | number | `0.12` | 0 – 1 | Yes | View-dependent silhouette fill shared by vegetation surfaces. |
| `rimPower` | number | `3` | 0.5 – 12 | Yes | Falloff exponent of the shared vegetation rim. |

### Vegetation shader family: Thin Surfaces

Lighting shared by thin blades, leaf cards, and petals.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `diffuseWrap` | number | `0.5` | 0 – 1 | Yes | Wraps direct light around thin surfaces so back faces remain readable. |
| `transmissionStrength` | number | `0.35` | 0 – 2 | Yes | Shared sunlight transmission through blades, leaves, and petals. |
| `transmissionPower` | number | `3.5` | 0.5 – 12 | Yes | Angular concentration of thin-surface transmission. |
| `transmissionShadowFloor` | number | `0.35` | 0 – 1 | Yes | Minimum transmission that remains inside cast or cloud shadow. |
| `normalUpBias` | number | `0` | 0 – 1 | Yes | Biases thin-surface shading normals toward world up. |
| `twoSidedLighting` | number | `1` | 0 – 1 | Yes | Blends back-face normals into the shared thin-surface lighting model. |

### Vegetation shader family: Weather Response

How the IP shades wetness and snow; current weather amounts remain scene-owned.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `wetDarkening` | number | `0.15` | 0 – 1 | Yes | Maximum albedo darkening applied by wetness. |
| `wetDesaturation` | number | `0.05` | 0 – 1 | Yes | Maximum desaturation applied by wetness. |
| `wetHighlightStrength` | number | `0.2` | 0 – 1 | Yes | Stylized highlight added to wet vegetation. |
| `snowTint` | color | `[0.92, 0.96, 1]` (#ebf5ff) | — | Yes | Vegetation-domain multiplier over the selected shared Snow Surface profile. The Snow Surface shader owns the base powder and shadow colors. |
| `snowShadowStrength` | number | `0.65` | 0 – 1 | Yes | Vegetation-domain light visibility retained over the shared Snow Surface shadow body. |
| `snowEdgeSoftness` | number | `0.2` | 0 – 1 | Yes | Softness of snow coverage transitions. |

### Vegetation shader family: Grass

Grass-only color, surface, lighting, dense-field, gust, and bend treatment.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `styleColorStrength` | number | `0` | 0 – 1 | Yes | Blend from asset-authored blade color to the style-owned root and tip treatment. |
| `baseColor` | color | `[0.16, 0.34, 0.08]` (#295714) | — | Yes | Style-owned anime grass-root color. |
| `tipBrightness` | number | `0.1` | -1 – 1 | Yes | Brightness added to root color before the blade-tip saturation and hue treatment. |
| `tipDesaturation` | number | `-0.35` | -1 – 1 | Yes | Tip desaturation. Negative values increase saturation for a graphic anime gradient. |
| `tipHueShift` | number | `-0.06` | -1 – 1 | Yes | Normalized HSV hue rotation applied to blade tips. |
| `roughness` | number | `0.5` | 0 – 1 | Yes | Grass surface roughness used by the stylized highlight response. |
| `specularStrength` | number | `0.04` | 0 – 1 | Yes | Grass direct-light highlight strength. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Albedo-relative emission before scene exposure. |
| `backlitStrength` | number | `0.4` | 0 – 1.5 | Yes | Grass transmission multiplier. |
| `sceneShadowResponse` | number | `0.7` | 0 – 1 | Yes | Grass response to renderer shadow visibility. |
| `cloudShadowResponse` | number | `0.35` | 0 – 1 | Yes | Grass response to the scene cloud-shadow field. |
| `bandThreshold` | number | `0.49` | 0 – 1 | Yes | Center of the grass direct-light toon transition. |
| `bandSoftness` | number | `0.1` | 0 – 0.5 | Yes | Width of the grass direct-light toon transition. |
| `shadowFloor` | number | `0.35` | 0 – 1 | Yes | Minimum grass brightness in full shadow. |
| `rootOcclusionStrength` | number | `0.36` | 0 – 1 | Yes | Dense-field darkening at blade roots. |
| `rootOcclusionHeight` | number | `0.62` | 0.01 – 1 | Yes | Blade height over which root occlusion fades. |
| `tipGradientStart` | number | `0.1` | 0 – 1 | Yes | Blade fraction where the root-to-tip material gradient begins. |
| `tipGradientEnd` | number | `0.95` | 0 – 1 | Yes | Blade fraction where the root-to-tip material gradient completes. |
| `colorVariationStrength` | number | `0.2` | 0 – 1 | Yes | Seeded blade luminance variation. |
| `gustSheenThreshold` | number | `0.78` | 0 – 1 | Yes | Gust value where the blade-tip sheen begins. |
| `gustSheenStrength` | number | `0.22` | 0 – 1 | Yes | Strength of the moving gust sheen. |
| `bendExponent` | number | `2` | 0.5 – 6 | Yes | Root-to-tip curve used by wind and interaction deformation. |
| `interactionResponse` | number | `1` | 0 – 2 | Yes | Grass deformation response to a scene-owned interaction field. |

### Vegetation shader family: Foliage

Leaf-card gradient shaping, surface, subsurface, and canopy-volume treatment over the asset-authored foliage palette.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `styleColorStrength` | number | `0` | 0 – 1 | Yes | Legacy aggregate-only blend into a global replacement palette. Canonical Tree and Flower Shader profiles preserve asset-authored foliage colors. |
| `mainColor` | color | `[0.040915, 0.135633, 0.015209]` (#0a2304) | — | Yes | Legacy aggregate-only replacement color. Canonical profiles read the primary foliage color from the asset or species recipe. |
| `gradientColor` | color | `[0.076185, 0.198069, 0.016807]` (#133304) | — | Yes | Legacy aggregate-only replacement color. Canonical profiles read the secondary foliage color from the asset or species recipe. |
| `gradientOffset` | number | `0.088` | -1 – 1 | Yes | Offsets the normalized height transfer applied over the asset-authored foliage palette. |
| `gradientContrast` | number | `0.821665` | -1 – 4 | Yes | Shapes the normalized height transfer applied over the asset-authored foliage palette. |
| `hueVariation` | number | `0.1` | 0 – 1 | Yes | Style-owned hue-variation amplitude; the stable per-card seed remains asset or instance data. |
| `hueShift` | number | `0` | -1 – 1 | Yes | Style-wide normalized HSV rotation applied after resolving the asset-authored foliage palette. |
| `roughness` | number | `0.75` | 0 – 1 | Yes | Roughness of the stylized leaf highlight response over any asset-authored surface inputs. |
| `specularStrength` | number | `0.1` | 0 – 1 | Yes | Leaf direct-light highlight strength. |
| `emissiveStrength` | number | `0.25` | 0 – 2 | Yes | Albedo-relative leaf emission before scene exposure. |
| `subsurfaceStrength` | number | `0.8` | 0 – 2 | Yes | Strength of foliage back-light transmission. |
| `subsurfaceOpacity` | number | `0.3` | 0 – 1 | Yes | Opacity retained by foliage transmission. |
| `backlitStrength` | number | `0.35` | 0 – 1.5 | Yes | Foliage transmission multiplier. |
| `sceneShadowResponse` | number | `0.55` | 0 – 1 | Yes | Foliage response to renderer shadow visibility. |
| `cloudShadowResponse` | number | `0` | 0 – 1 | Yes | Foliage response to the scene cloud-shadow field. |
| `bandThreshold` | number | `0.47` | 0 – 1 | Yes | Center of the foliage direct-light toon transition. |
| `bandSoftness` | number | `0.18` | 0 – 0.5 | Yes | Width of the foliage direct-light toon transition. |
| `crestThreshold` | number | `0.72` | 0 – 1 | Yes | Center of the high crown-color crest band. |
| `crestSoftness` | number | `0.12` | 0 – 0.5 | Yes | Width of the high crown-color crest band. |
| `crownOcclusionStrength` | number | `0.2` | 0 – 1 | Yes | Additional darkening inside renderer-shadowed crowns. |
| `spriteLuminanceStrength` | number | `0.36` | 0 – 1 | Yes | Influence of painted leaf-sprite luminance. |
| `cardVariationStrength` | number | `0.16` | 0 – 1 | Yes | Seeded per-card luminance variation. |
| `transmissionPowerMultiplier` | number | `1` | 0.25 – 3 | Yes | Foliage multiplier over the shared thin-surface transmission concentration. |

### Vegetation shader family: Flower

Shared petal/center cutout, surface, lighting, and subsurface treatment across flower variants.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `textureTint` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Legacy aggregate-only replacement tint. Canonical Flower Shader profiles preserve the asset/species petal and center palette. |
| `tintStrength` | number | `1` | 0 – 1 | Yes | Legacy aggregate-only strength for the replacement flower tint. |
| `roughness` | number | `0.5` | 0 – 1 | Yes | Flower surface roughness used by the stylized highlight response. |
| `specularStrength` | number | `0.05` | 0 – 1 | Yes | Flower direct-light highlight strength. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Albedo-relative flower emission before scene exposure. |
| `subsurfaceStrength` | number | `0.3` | 0 – 2 | Yes | Strength of petal back-light transmission. |
| `subsurfaceOpacity` | number | `0.08` | 0 – 1 | Yes | Opacity retained by petal transmission. |
| `backlitStrength` | number | `0.35` | 0 – 1.5 | Yes | Petal transmission multiplier. |
| `sceneShadowResponse` | number | `0.85` | 0 – 1 | Yes | Flower response to renderer shadow visibility. |
| `bandThreshold` | number | `0.5` | 0 – 1 | Yes | Center of the flower direct-light toon transition. |
| `bandSoftness` | number | `0.1` | 0 – 0.5 | Yes | Width of the flower direct-light toon transition. |
| `unlitPetalLift` | number | `0.35` | 0 – 1 | Yes | Petal-tinted floor for unlit petal faces. |
| `cupDarkeningStrength` | number | `0.1` | 0 – 1 | Yes | Stylized darkening toward curved petal edges. |
| `petalTransmissionMultiplier` | number | `1` | 0 – 2 | Yes | Flower-family multiplier over shared thin-surface transmission. |
| `centerLightResponse` | number | `0.8` | 0 – 2 | Yes | Direct-light response of flower centers relative to petals. |
| `centerShadowResponse` | number | `1` | 0 – 2 | Yes | Shadow response of flower centers relative to petals. |

### Vegetation shader family: Bark / Woody Surface

Opaque woody color, texture projection, surface, and lighting treatment for trunks, branches, and roots.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `tint` | color | `[0.938, 0.3752, 0]` (#ef6000) | — | Yes | Style tint mixed over the asset-authored bark color. |
| `tintStrength` | number | `0` | 0 – 1 | Yes | Strength of the bark style tint. |
| `roughness` | number | `1` | 0 – 1 | Yes | Bark roughness used by the stylized highlight response. |
| `normalFlatness` | number | `0` | 0 – 1 | Yes | Amount of asset-authored bark normal detail flattened by the style. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Albedo-relative bark emission before scene exposure. |
| `bandCount` | number | `3` | 2 – 6 | Yes | Cel bands across the woody light-to-shadow ramp. |
| `bandSoftness` | number | `0` | 0 – 1 | Yes | Continuous softness of woody toon-band transitions. |
| `shadowFloor` | number | `0.35` | 0 – 0.9 | Yes | Minimum brightness of a fully shadowed woody surface. |
| `sunTintStrength` | number | `0.15` | 0 – 1 | Yes | Sun-color tint applied to lit bark. |
| `skyFillStrength` | number | `0.04` | 0 – 0.5 | Yes | Sky-color fill applied to shaded bark. |
| `rimStrength` | number | `0` | 0 – 1 | Yes | View-dependent woody silhouette fill. |
| `specularStrength` | number | `0` | 0 – 1 | Yes | Stylized bark highlight strength. |
| `verticalShadeStrength` | number | `0` | 0 – 1 | Yes | World-up gradient used to ground trunks without changing their albedo. |

### Vegetation shader family: Herbaceous Stem

Smooth herbaceous stem surface and lighting treatment, intentionally separate from woody bark.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `color` | color | `[0.155926, 0.332452, 0.066626]` (#285511) | — | Yes | Legacy aggregate-only replacement color. Canonical Flower Shader profiles read herbaceous stem color from the plant asset/species recipe. |
| `colorStrength` | number | `0` | 0 – 1 | Yes | Legacy aggregate-only blend into the replacement stem color. |
| `roughness` | number | `0.5` | 0 – 1 | Yes | Stem surface roughness used by the stylized highlight response. |
| `specularStrength` | number | `0.05` | 0 – 1 | Yes | Stem direct-light highlight strength. |
| `emissiveStrength` | number | `0` | 0 – 2 | Yes | Albedo-relative stem emission before scene exposure. |
| `bandCount` | number | `3` | 2 – 6 | Yes | Cel bands across herbaceous stems. |
| `bandSoftness` | number | `0.08` | 0 – 1 | Yes | Softness of herbaceous stem toon bands. |
| `shadowFloor` | number | `0.42` | 0 – 0.9 | Yes | Minimum brightness of a fully shadowed stem. |
| `transmissionStrength` | number | `0.08` | 0 – 1 | Yes | Subtle light transmission through green stems. |
| `skyFillStrength` | number | `0.06` | 0 – 0.5 | Yes | Additional stem sky-color fill over the shared vegetation fill. |
| `rimStrength` | number | `0.02` | 0 – 1 | Yes | View-dependent stem silhouette fill. |

## Grass

Module: `toonlab/vegetation` — 9 groups, 30 fields.

Flat settings consumed by `new StylizedGrassField(options)` and `grass.applySettings(options)`. Portable grass preset v2 stores asset geometry, palette/material, and `windResponse` / `gustResponse`; current light, wind/gust field, cloud field, and push radius are scene/runtime inputs.

### Grass: Blades

Random blade dimensions baked into the instance attributes when the field is built. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `bladeHeightRange` | vector2 | `[0.16, 0.42]` | — | Yes | Min/max blade height in meters for placements without an explicit height. Construction-only: baked into instance attributes. |
| `bladeWidthRange` | vector2 | `[0.05, 0.085]` | — | Yes | Min/max blade width in meters for placements without an explicit width. Construction-only: baked into instance attributes. |
| `bladesPerClump` | number | `1` | 1 – 64 | Yes | Blades grown from each placement or authored into each paintable clump mesh. 1 keeps the classic lone-blade field; the first-party meadow clump uses 40. Construction-only. |
| `clumpRadius` | number | `0.055` | 0 – 1 | Yes | Base scatter radius in meters for the extra blades of a clump. Small values read as one tuft; larger values loosen the clump. Construction-only. |
| `leanStrength` | number | `1` | 0 – 2 | Yes | Authored static splay of each blade before live wind and interaction. Low values form clean upright meadow strokes; high values form wild bent grass. |

### Grass: Motion

Asset-level flexibility: how this grass responds when a scene supplies wind and gusts.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `windResponse` | number | `1` | 0 – 8 | Yes | Asset flexibility multiplier applied to the current scene wind strength. 1 preserves the authored baseline; 0 keeps blades still. |
| `gustResponse` | number | `1` | 0 – 4 | Yes | How strongly this grass follows gust bands relative to its regular wind sway. |

### Grass: Palette

The blades' coordinated base, tip, and material shadow colors — the grass's identity, whatever the scene lighting does. Magical blue grass welcome.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `baseColor` | color | `[0.42, 0.68, 0.24]` (#6bad3d) | — | Yes | Blade color at the root. |
| `tipColor` | color | `[0.74, 0.9, 0.42]` (#bde66b) | — | Yes | Blade color at the tip; blades gradient from base to tip. |
| `groundAdoptStrength` | number | `0` | 0 – 1 | Yes | How strongly blades adopt the terrain color under them from the scene ground field (0 keeps the authored palette). Needs a world running the ground-field pass. |
| `groundAdoptHeight` | number | `0.85` | 0.01 – 1 | Yes | Blade fraction the adopted ground color reaches before fading back to the palette tips. |
| `groundAdoptTint` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Multiplier applied to the adopted ground color — lift or warm the sampled terrain albedo before it colors the blades. |
| `washLift` | number | `0` | 0 – 1 | Yes | Procedural watercolor wash lift. Irregularly pulls blade strokes toward the active sun color without requiring a texture. |
| `washOpacity` | number | `1` | 0.1 – 1 | Yes | Layer opacity of the procedural watercolor blade strokes. Values below 1 soften each stroke against the terrain and sky. |

### Grass: Lighting

How the blades RESPOND to scene light — e.g. the backlit glow on blades between the camera and the sun.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `backlitStrength` | number | `0.3` | 0 – 2 | Yes | Translucent backlight boost when the camera looks toward the sun through the blades. |

### Grass: Shadows

Grass-material shadow strength and palette tint. The renderer and cloud-shadow fields themselves come from the scene.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `shadowStrength` | number | `0.9` | 0 – 1 | Yes | How strongly renderer shadow maps (trees, rocks, the character) darken blades. |
| `shadowTint` | color | `[0.42, 0.47, 0.62]` (#6b789e) | — | Yes | Grass material color approached in full scene or cloud shadow. Palette presets set it with base/tip colors; the IP-wide vegetation shadow treatment still layers over it. |

### Grass: Scene Light

Current sun direction/color and sky color supplied by the scene at runtime.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sunDirection` | vector3 | `[0.35, 0.72, 0.42]` | — | No — scene/runtime | World-space direction toward the sun (normalized on apply). Match your main directional light. |
| `sunColor` | color | `[1, 0.96, 0.84]` (#fff5d6) | — | No — scene/runtime | Sunlight tint applied to lit blades. |
| `skyColor` | color | `[0.62, 0.78, 0.95]` (#9ec7f2) | — | No — scene/runtime | Ambient sky tint mixed into shaded blades. |

### Grass: Scene Wind

Current world wind and gust field supplied by weather or another scene system.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `windDirection` | vector2 | `[1, 0.3]` | — | No — scene/runtime | Current horizontal (XZ) heading the world wind blows toward. |
| `windSpeed` | number | `1` | 0 – 4 | No — scene/runtime | Current temporal speed of the world wind. |
| `windStrength` | number | `0.16` | 0 – 1 | No — scene/runtime | Current world wind amplitude before the asset response multiplier. |
| `gustFrequency` | number | `0.35` | 0 – 2 | No — scene/runtime | Current spatial frequency of the world gust bands. |
| `gustSpeed` | number | `1.6` | 0 – 6 | No — scene/runtime | Current travel speed of the world gust bands. |

### Grass: Cloud Field

Current drifting cloud-shadow field shared across terrain, water, and vegetation.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `cloudShadowStrength` | number | `0` | 0 – 1 | No — scene/runtime | Current strength of the shared procedural cloud-shadow field. 0 disables it. |
| `cloudShadowCoverage` | number | `0.45` | 0 – 1 | No — scene/runtime | Current fraction of the world covered by cloud shadow. |
| `cloudShadowScale` | number | `0.012` | 0.001 – 0.1 | No — scene/runtime | Current world-to-noise scale of the shared cloud pattern. |
| `cloudShadowVelocity` | vector2 | `[0.02, 0.006]` | — | No — scene/runtime | Current cloud-shadow drift in noise-space units per second. |

### Grass: Interaction

Current push target and influence radius supplied per scene or grass instance.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `pushRadius` | number | `0.9` | 0 – 3 | No — scene/runtime | Current radius in meters around the scene push target. |

## Flowers

Module: `toonlab/vegetation` — 3 groups, 7 fields.

Flat settings consumed by `new StylizedFlowerField(options)` and `flowers.applySettings(options)`.

### Flowers: Heads

Random head sizes baked into the instance attributes when the field is built. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sizeRange` | vector2 | `[0.045, 0.08]` | — | Yes | Min/max head size in meters for placements without an explicit size. Construction-only: baked into instance attributes. |

### Flowers: Wind

Wind sway shared with the surrounding grass so heads and blades move together.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `windDirection` | vector2 | `[1, 0.3]` | — | Yes | Horizontal (XZ) heading the wind blows toward. Magnitude does not matter; use wind strength for amplitude. |
| `windSpeed` | number | `1` | 0 – 4 | Yes | How fast the head sway oscillates. |
| `windStrength` | number | `0.16` | 0 – 1 | Yes | How far flower heads bob with the wind. |

### Flowers: Appearance

Petal/center palette and scene-shadow darkening.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `petalColor` | color | `[1, 0.98, 0.92]` (#fffaeb) | — | Yes | Petal color of the procedural daisies. |
| `centerColor` | color | `[0.98, 0.8, 0.34]` (#facc57) | — | Yes | Center-disc color of the procedural daisies. |
| `shadowStrength` | number | `0.85` | 0 – 1 | Yes | How strongly renderer shadow maps darken flower heads. |

## Trees

Module: `toonlab/vegetation` — 5 groups, 77 fields.

Grouped settings consumed by `new StylizedTree(options)` and `tree.applySettings(options)`.

### Trees: Tree

Overall scale, seed, crown reach, leaf coverage, and canopy palette. Everything except the palette and trunk shadow flag bakes geometry at construction.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `size` | number | `1` | 0.2 – 6 | Yes | Overall tree multiplier (1 ≈ 3 m tree, 2 ≈ 6 m, 3+ large). Construction-only: also densifies canopy cards so leaves stay leaf-sized. |
| `seed` | number | `1` | 1 – 999 | Yes | Deterministic generation seed; the same options and seed always grow the same tree. Construction-only. |
| `canopyColor` | color | `[0.30196078431372547, 0.6352941176470588, 0.34509803921568627]` (#4da258) | — | Yes | Canopy base color; the lit/shadow/crown palette derives from it. Also accepts richer resolveCanopyColor specs (color lists, {from,to} blends, HSL ranges) resolved per seed. |
| `canopyPalette` | object | `'[object Object]'` | — | No — local/runtime | Optional explicit { lit, shadow, crown } tone overrides; unset tones derive from the canopy color. |
| `canopyWidth` | number | `1` | 0.3 – 2.5 | Yes | X-axis crown reach multiplier. Construction-only: shapes the blob layout. |
| `canopyDepth` | number | `1` | 0.3 – 2.5 | Yes | Z-axis crown reach multiplier. Construction-only: shapes the blob layout. |
| `canopyLayout` | object | `'[object Object]'` | — | No — local/construction | Optional createCanopyBlobs overrides (lobeCount, spread, flatten, coreRadius, ...). Construction-only. |
| `leafDensity` | number | `1` | 0.05 – 2 | Yes | Crown leaf coverage. Below ~0.9 see-through gap pockets open and branches read through; above 1 packs extra cards (and fatter tufts) for lush crowns. Construction-only. |
| `canopyScale` | number | `1` | 0.2 – 3 | Yes | Canopy-only scale relative to the trunk. Construction-only. |
| `leafPlacement` | select | `'canopy'` | `canopy` \| `tips` | Yes | canopy: solid leaf mass hiding interior wood. tips: bushes only at branch ends with bare limbs between them (Sumeru silhouette). Construction-only. |
| `trunkReceiveShadow` | boolean | `true` | — | Yes | Whether the bark receives shadow maps. Massive pale-limbed trees read better with this off. |
| `trunkColor` | color | `[0.788235294117647, 0.6705882352941176, 0.5411764705882353]` (#c9ab8a) | — | Yes | Warm bark base color used by the generated trunk, branches, and roots. |

### Trees: Trunk

Trunk silhouette (bend, lean, twist, gnarl) shared by the skeleton grower and the classic curved-trunk generator. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `height` | number | `1.55` | 0.4 – 3 | Yes | Trunk height in meters (before the overall size multiplier). Construction-only. |
| `radiusBottom` | number | `0.19` | 0.05 – 0.6 | Yes | Trunk radius at the root flare in meters. Construction-only. |
| `radiusTop` | number | `0.085` | 0.02 – 0.3 | Yes | Trunk radius at the top in meters. Classic trunk generator (createTreeTrunkGeometry) only. Construction-only. |
| `bend` | number | `0.12` | 0 – 0.8 | Yes | Mid-trunk bow amplitude that returns toward center (S-curve) in meters. Construction-only. |
| `lean` | number | `0.16` | 0 – 1.2 | Yes | Off-vertical drift that accumulates toward the top, in meters. Construction-only. |
| `twist` | number | `0` | -4 – 4 | Yes | Y-rotation of the cross-section over the full height in radians; spirals the bark like wrung wood. Construction-only. |
| `gnarl` | number | `0` | 0 – 2 | Yes | High-frequency wiggle and radius bulges: 0 is a clean park tree, 1+ reads like an old bonsai. Construction-only. |
| `gnarlFrequencyXRange` | vector2 | `[4.2, 7.6]` | — | Yes | Seeded min/max wave count of the gnarl wiggle over the trunk height on the X axis. Classic trunk generator only. Construction-only. |
| `gnarlFrequencyZRange` | vector2 | `[3.1, 6.7]` | — | Yes | Seeded min/max wave count of the gnarl wiggle over the trunk height on the Z axis. Classic trunk generator only. Construction-only. |
| `gnarlAmplitude` | number | `0.16` | 0 – 0.5 | Yes | Meters of gnarl wiggle (and radius bulge fraction) per unit of gnarl. Classic trunk generator only. Construction-only. |
| `radialGnarlFrequency` | number | `9.3` | 0 – 20 | Yes | Wave count of the gnarl radius bulges (old-wood knuckles) over the trunk height. Classic trunk generator only. Construction-only. |
| `bendDirection` | number | — | -6.283 – 6.283 | Yes | World heading of the bow in radians; null/unset picks a seeded heading. Construction-only. |
| `leanOffset` | number | — | -6.283 – 6.283 | Yes | Lean heading relative to the bow in radians (PI pins a serpentine S-trunk); null/unset picks a seeded offset. Construction-only. |
| `radialSegments` | number | `10` | 3 – 16 | Yes | Cross-section segment count of the trunk tube. Classic trunk generator only. Construction-only. |
| `heightSegments` | number | `14` | 2 – 24 | Yes | Vertical segment count of the trunk tube. Classic trunk generator only. Construction-only. |
| `branchCount` | number | `2` | 0 – 6 | Yes | Number of stub branches near the top. Classic trunk generator only. Construction-only. |
| `branchLength` | number | `0.55` | 0 – 1.5 | Yes | Base branch length in meters. Classic trunk generator only. Construction-only. |
| `branchRadius` | number | `0.055` | 0 – 0.2 | Yes | Base branch radius in meters. Classic trunk generator only. Construction-only. |

### Trees: Skeleton

Space-colonization limb growth and bark mesh controls. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `generator` | select | `'limbs'` | `limbs` \| `branching` \| `drawn` | Yes | limbs: space-colonization growth toward the crown blobs (solid anime-style crowns). branching: recursive central-leader branching (open, realistic broadleaf/conifer silhouettes). drawn: no procedural wood at all — the tree is exactly the hand-drawn branchSpines (Tree Lab sketch mode). Construction-only. |
| `levels` | number | `3` | 1 – 4 | Yes | Recursion depth of the branching generator; each level subdivides into thinner children. Branching generator only. Construction-only. |
| `childrenCount` | number | `6` | 1 – 90 | Yes | Lateral child branches sprouting along the trunk (deeper levels derive from them). The central leader continues separately, so children=1 forms one lateral limb plus the leader. Conifers use high counts (60-90) for dense whorled fronds. Branching generator only. Construction-only. |
| `branchAngle` | number | `55` | 10 – 130 | Yes | Child pitch away from the parent axis, in degrees. Past 90 points branches below horizontal (conifer fronds ~110). Branching generator only. Construction-only. |
| `branchStart` | number | `0.4` | 0 – 0.9 | Yes | Fraction of the trunk kept bare before children begin — real trees hold their crown off the ground. Branching generator only. Construction-only. |
| `lengthRatio` | number | `0.45` | 0.15 – 0.95 | Yes | Child branch length as a fraction of the trunk (deeper levels shorten from it). Branching generator only. Construction-only. |
| `radiusRatio` | number | `0.7` | 0.3 – 0.9 | Yes | Child radius as a fraction of the parent\u2019s radius at the attach point — radius continuity is what makes forks read as one tree. Branching generator only. Construction-only. |
| `gnarliness` | number | `0.15` | 0 – 0.6 | Yes | Random-walk curvature per growth section, amplified as branches thin: trunks stay stately, twigs wander. Branching generator only. Construction-only. |
| `forceStrength` | number | `0.02` | -0.08 – 0.15 | Yes | Growth force: every section steers toward vertical with 1/radius compliance. Positive sweeps tips skyward (broadleaf crowns); negative droops them (pines, willows). Branching generator only. Construction-only. |
| `conifer` | boolean | `false` | — | Yes | Evergreen behavior: branches taper fully and children shorten toward the top \u2014 the layered cone silhouette. Pair with high Children, Branch Angle ~110, negative Growth Force. Branching generator only. Construction-only. |
| `attractionCount` | number | `90` | 10 – 200 | Yes | Number of crown attraction points the limbs grow toward; more points grow more, finer limbs. Construction-only. |
| `segmentLength` | number | `0.3` | 0.1 – 0.8 | Yes | Growth step length in meters; shorter steps grow smoother, curvier limbs. Construction-only. |
| `influenceRadius` | number | `1.2` | 0.3 – 2.5 | Yes | How far an attraction point can pull on a growing limb, in meters. Construction-only. |
| `killRadius` | number | `0.42` | 0.1 – 1 | Yes | Distance at which a limb consumes an attraction point and stops growing toward it. Construction-only. |
| `maxSteps` | number | `48` | 4 – 96 | Yes | Growth iteration cap. Construction-only. |
| `maxNodes` | number | `140` | 20 – 400 | Yes | Skeleton node cap; lower keeps trees to a few clean limbs. Construction-only. |
| `radialSegments` | number | `8` | 3 – 16 | Yes | Cross-section segment count of each bark tube. Construction-only. |
| `tipRadius` | number | `0.03` | 0.005 – 0.15 | Yes | Radius of the thinnest twigs in meters; pipe-model radii grow from here toward the root. Construction-only. |
| `minLimbRadius` | number | `0.028` | 0 – 0.15 | Yes | Limbs thinner than this get no bark tube and are left to the leaves. Construction-only. |
| `attachmentTwigRadius` | number | `0.09` | 0 – 0.3 | Yes | Wood thinner than this sprouts leaf tufts in canopy mode. Construction-only. |
| `attractionReach` | number | — | 0 – 1 | Yes | How deep into each crown blob attraction points sample (fraction of blob radius); null/unset is automatic (0.65 canopy mode, 0.92 tips mode). Construction-only. |

### Trees: Canopy Cards

Leaf-card canopy geometry: card counts, tuft clusters, and shell fill. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `architecture` | select | `'cloud-cards'` | `cloud-cards` \| `layered-sprays` \| `needle-whorls` \| `radial-fronds` | Yes | Branch-attached foliage layout: historical round clouds, stacked sprays, conifer whorls, or palm-like radial fronds. Construction-only. |
| `cardCount` | number | `170` | 20 – 600 | Yes | Base leaf-card count before density and coverage scaling; few LARGE overlapping cards keep the crown one fluffy mass. Construction-only. |
| `cardSizeRange` | vector2 | `[1, 1.6]` | — | Yes | Min/max leaf-cluster card size in meters. Construction-only. |
| `cardsPerCluster` | number | `5` | 1 – 20 | Yes | Cards per leaf tuft around each branch attachment. Construction-only. (In tips placement the built-in default becomes 9.) |
| `clusterRadius` | number | `0.48` | 0.1 – 1.5 | Yes | Radius in meters of each leaf tuft around its branch end. Construction-only. (In tips placement the built-in default becomes 0.62.) |
| `sprayLayers` | number | `3` | 1 – 12 | Yes | Number of stacked foliage planes at each layered-spray attachment. Construction-only. |
| `spraySpread` | number | `0.8` | 0.05 – 4 | Yes | Branch-local radius of each layered spray in meters. Construction-only. |
| `sprayThickness` | number | `0.18` | 0 – 2 | Yes | Separation between the stacked spray planes in meters. Construction-only. |
| `whorlArms` | number | `6` | 3 – 24 | Yes | Radial arm count around a conifer foliage attachment. Construction-only. |
| `whorlRadius` | number | `0.48` | 0.05 – 3 | Yes | Radius of each conifer foliage whorl in meters. Construction-only. |
| `frondCount` | number | `7` | 3 – 24 | Yes | Number of radial frond directions at each attachment. Construction-only. |
| `frondLength` | number | `1.25` | 0.1 – 4 | Yes | Maximum radial frond reach in meters. Construction-only. |
| `shellFill` | boolean | `true` | — | Yes | Fill the blob shells between tufts so the crown reads as one solid mass; off leaves bare wood between end bushes. Construction-only. (Tips placement turns this off by default.) |

### Trees: Foliage Material

Leaf material response: wind, sun, alpha cutout, scene and cloud shadows. Applies at runtime via applySettings.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `alphaCutoff` | number | `0.3` | 0 – 1 | Yes | Alpha-cutout threshold for the leaf sprite; low enough that mipmap-averaged alpha does not erode distant crowns. |
| `windDirection` | vector2 | `[1, 0.3]` | — | Yes | Horizontal (XZ) heading the canopy flutter drifts toward. |
| `windSpeed` | number | `1` | 0 – 4 | Yes | How fast the leaf-card flutter oscillates. |
| `windStrength` | number | `0.05` | 0 – 0.5 | Yes | How far leaf cards sway with the wind. |
| `sunDirection` | vector3 | `[0.35, 0.72, 0.42]` | — | Yes | World-space direction toward the sun. Match your main directional light. |
| `sunColor` | color | `[1, 0.96, 0.84]` (#fff5d6) | — | Yes | Sunlight tint applied to lit leaf cards. |
| `skyColor` | color | `[0.62, 0.78, 0.95]` (#9ec7f2) | — | Yes | Ambient sky tint mixed into shaded leaf cards. |
| `sceneShadowStrength` | number | `0.55` | 0 – 1 | Yes | How strongly renderer shadow maps shift the crown toward its shadow palette. 0 disables. |
| `backlitStrength` | number | `0.35` | 0 – 2 | Yes | Translucent glow on leaves between the camera and the sun. |
| `cloudShadowStrength` | number | `0` | 0 – 1 | Yes | How strongly drifting procedural cloud shadows darken the crown. 0 disables the effect. |
| `cloudShadowCoverage` | number | `0.45` | 0 – 1 | Yes | Fraction of the world covered by cloud shadow at any moment. |
| `cloudShadowScale` | number | `0.012` | 0.001 – 0.1 | Yes | World-to-noise scale of the cloud shadow pattern; smaller values give larger cloud shapes. |
| `cloudShadowVelocity` | vector2 | `[0.02, 0.006]` | — | Yes | Cloud shadow drift in noise-space units per second (world drift = velocity / scale). |

## Sky

Module: `toonlab/sky` — 5 groups, 47 fields.

47 schema fields: 46 portable Sky art settings plus non-portable compatibility `radius`. Lighting, Weather, and manual state compose through ordered runtime layers; deployment quality is a separate compile-time tier.

### Sky: Dome

Sky dome geometry. Construction-only.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `radius` | number | `100` | 10 – 1000 | No — local/construction | Sphere radius of the sky dome in meters. Construction-only: baked into the dome geometry; applySettings stores but does not rebuild it. |

### Sky: Gradient

Vertical zenith-to-horizon-to-ground gradient and horizon scattering.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `zenithColor` | color | `[0.28, 0.56, 0.92]` (#478feb) | — | Yes | Sky color straight up at the top of the dome. |
| `horizonColor` | color | `[0.78, 0.92, 1]` (#c7ebff) | — | Yes | Sky color at the horizon band. |
| `groundColor` | color | `[0.42, 0.48, 0.55]` (#6b7a8c) | — | Yes | Dome color below the horizon. |
| `zenithExponent` | number | `0.48` | 0.1 – 4 | Yes | Shape of the horizon-to-zenith gradient. Lower values bring the zenith color farther toward the horizon. |
| `groundExponent` | number | `0.55` | 0.1 – 4 | Yes | Shape of the mirrored below-horizon fade into the ground color. |
| `horizonBandSize` | number | `0.42` | 0.02 – 1 | Yes | Vertical size of the sun-side atmospheric scattering band around the horizon. |
| `horizonSunPower` | number | `5` | 0.5 – 20 | Yes | How tightly horizon scattering concentrates toward the sun direction. |
| `horizonScattering` | number | `0.5` | 0 – 1 | Yes | Strength of the bright sun-side atmospheric wedge at the horizon. |

### Sky: Sun

Sun disc position, size, tint, and glow halo.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `sunDirection` | vector3 | `[0.35, 0.8, 0.45]` | — | Yes | World-space direction toward the sun (normalized on apply). Match your main directional light. |
| `sunColor` | color | `[1, 0.95, 0.82]` (#fff2d1) | — | Yes | Tint of the sun disc and its glow. |
| `sunSize` | number | `0.026` | 0 – 0.2 | Yes | Angular size of the sun disc. |
| `sunDiscSoftness` | number | `0.5` | 0.01 – 1 | Yes | Fraction of the disc radius used for its anti-aliased painterly edge. |
| `sunDiscIntensity` | number | `2.4` | 0 – 8 | Yes | Brightness multiplier of the solid sun disc before the renderer tone map. |
| `sunGlowStrength` | number | `1` | 0 – 4 | Yes | Master intensity of the broad and core sun glow terms. |
| `sunGlowSpread` | number | `5` | 1 – 20 | Yes | Falloff power of the broad halo. Lower values spread the glow across more sky. |
| `sunGlowCoreSharpness` | number | `60` | 5 – 200 | Yes | Falloff power of the tight inner halo. Higher values make a smaller, sharper core. |
| `sunGlowBroadStrength` | number | `0.16` | 0 – 2 | Yes | Contribution of the broad halo inside the master glow strength. |
| `sunGlowCoreStrength` | number | `0.5` | 0 – 2 | Yes | Contribution of the tight inner halo inside the master glow strength. |
| `sunCloudOcclusionStrength` | number | `1` | 0 – 1 | Yes | How strongly dense cloud coverage hides the sun disc. 0 keeps the disc visible through cloud. |

### Sky: Clouds

Painterly two-tone procedural clouds.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `cloudCoverage` | number | `0.42` | 0 – 1 | Yes | Fraction of the sky filled by clouds. 0 clears the sky. |
| `cloudScale` | number | `1.6` | 0.1 – 6 | Yes | Noise scale of the cloud shapes; higher gives smaller, busier clouds. |
| `cloudSoftness` | number | `0.1` | 0.01 – 0.3 | Yes | Width of the painterly cloud silhouette transition. |
| `cloudProjection` | number | `0.22` | 0.05 – 0.8 | Yes | Perspective offset of the virtual cloud plane; higher values flatten clouds toward the horizon. |
| `cloudOpacity` | number | `1` | 0 – 1 | Yes | Overall blend opacity of the procedural cloud layer. |
| `cloudEdgeOpacity` | number | `0.65` | 0 – 1 | Yes | Opacity of the soft outer silhouette relative to the solid cloud core. |
| `cloudSpeed` | number | `1` | 0 – 4 | Yes | How fast the authored cloud layer drifts across the dome. |
| `cloudDirection` | vector2 | `[0.9615239476, 0.2747211279]` | — | Yes | Normalized horizontal drift direction of the authored cloud layer; speed is controlled separately. |
| `cloudSeed` | number | `0` | 0 – 1000 | Yes | Offsets the procedural cloud field to produce a different deterministic composition. |
| `cloudColor` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Lit tone of the two-tone painterly clouds. |
| `cloudShadeColor` | color | `[0.68, 0.78, 0.92]` (#adc7eb) | — | Yes | Shaded underside tone of the two-tone painterly clouds. |
| `cloudShadeStrength` | number | `0.85` | 0 – 1 | Yes | Strength of the two-tone shaded underside. |
| `cloudShadeThreshold` | number | `0.02` | -0.3 – 0.3 | Yes | Noise-difference threshold that separates the lit and shaded cloud tones. |
| `cloudShadeSoftness` | number | `0.06` | 0.001 – 0.3 | Yes | Softness of the transition between the two cloud tones. |
| `cloudLightOffset` | number | `0.4` | 0 – 2 | Yes | Distance of the secondary noise sample toward the sun; controls the depth and directionality of cloud shading. |
| `cloudSilverLiningStrength` | number | `0.3` | 0 – 2 | Yes | Warm sun-colored lining added to cloud edges facing the sun. |
| `cloudSunPower` | number | `10` | 1 – 40 | Yes | Angular focus of the sun-colored cloud lining. |
| `cloudHorizonFade` | number | `0.16` | 0.02 – 0.8 | Yes | Altitude at which the cloud layer reaches full opacity above the horizon. |

### Sky: Stars

Procedural star field for night skies.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `starsStrength` | number | `0` | 0 – 2 | Yes | Brightness of the procedural star field. 0 (default) hides stars for daytime skies. |
| `starsColor` | color | `[1, 0.98, 0.92]` (#fffaeb) | — | Yes | Tint of the procedural star glints. |
| `starsSeed` | number | `0` | 0 – 1000 | Yes | Offsets the deterministic star pattern without changing density or size. |
| `starsDensity` | number | `0.28` | 0 – 1 | Yes | Fraction of candidate cells allowed to contain a visible star. |
| `starsScale` | number | `14` | 2 – 64 | Yes | Density scale of the projected star grid; higher values produce more, smaller cells. |
| `starsSize` | number | `0.06` | 0.005 – 0.2 | Yes | Size of each procedural star glint inside its cell. |
| `starsTwinkleStrength` | number | `0.8` | 0 – 1 | Yes | Depth of per-star brightness animation. 0 disables twinkle without hiding stars. |
| `starsTwinkleSpeed` | number | `1` | 0 – 4 | Yes | Speed multiplier of the seeded per-star twinkle animation. |
| `starsHorizonFade` | number | `0.24` | 0.04 – 1 | Yes | Altitude at which the star field reaches full brightness above the horizon. |

## Paths, roads & bridges

Module: `toonlab/pathgen` — 4 groups, 22 fields.

Grouped settings consumed by `createStylizedPaths({ settings })` and serialized in path recipes.

### Paths, roads & bridges: Routing

Cost-field router: how strongly slope and water repel routes, and how much existing paths attract reuse (forks and junctions).

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `pointCount` | number | `4` | 2 – 8 | Yes | Auto mode: number of destinations probed from the terrain and connected into a network. |
| `slopeCost` | number | `26` | 0 – 80 | Yes | How expensive climbing is for the router. Higher values hug contours and produce switchbacks instead of straight climbs. |
| `waterCost` | number | `14` | 2 – 60 | Yes | Cost multiplier for crossing water. High enough that routes only cross where a bridge is worth it, low enough that crossings still happen. |
| `reuseBonus` | number | `0.45` | 0 – 0.9 | Yes | Cost discount (0..1) on cells an earlier route already walks — the source of natural forks and shared trunk roads. |
| `gridStep` | number | `8` | 3 – 24 | Yes | Router grid resolution in meters. Smaller steps find finer detours and cost more to solve. |
| `shoreMargin` | number | `0.6` | 0 – 2 | Yes | Meters above the waterline a cell must be to count as dry land. |
| `loopChance` | number | `0.35` | 0 – 1 | Yes | Auto mode: chance to add one extra ring road beyond the spanning network. |

### Paths, roads & bridges: Ribbon

The walkable strip: width, hand-drawn wobble, edge skirts that tuck into the terrain, and the height-profile smoothing that flattens the walk.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `width` | number | `2.6` | 1 – 6 | Yes | Walkable ribbon width in meters (dirt trail 2–3, stone road 3–4). |
| `widthWobble` | number | `0.22` | 0 – 0.6 | Yes | Low-frequency width variation (0..1) for the hand-drawn look. 0 is a survey-straight road. |
| `edgeSkirt` | number | `1.1` | 0.2 – 2.5 | Yes | Extra meters each side that slope down and tuck under the terrain so the ribbon never floats on side slopes. |
| `lift` | number | `0.07` | 0.02 – 0.25 | Yes | Meters the ribbon rides above the height profile — the true-overlay offset that prevents z-fighting. |
| `smoothing` | number | `16` | 0 – 40 | Yes | Moving-average window in meters applied to the terrain height along the route; the flattened profile is what paths.heightAt reports. |
| `stepLength` | number | `2` | 1 – 5 | Yes | Meters between ribbon cross-sections. Smaller steps follow curves tighter and spend more triangles. |
| `edgeFade` | number | `1.4` | 0.2 – 4 | Yes | Meters past the ribbon edge over which maskAt falls from 1 to 0 — the band where grass and flowers thin out. |

### Paths, roads & bridges: Bridges

Arched plank bridges generated where a route crosses open water.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `arc` | number | `0.1` | 0 – 0.18 | Yes | Deck rise as a fraction of span length. 0 is a flat causeway, 0.14 a strong arched footbridge. |
| `railStyle` | select | `'posts'` | `posts` \| `beams` \| `none` | Yes | Bridge railing construction. |
| `postSpacing` | number | `2.2` | 1.2 – 4 | Yes | Meters between railing posts. |
| `minSpan` | number | `4` | 2 – 12 | Yes | Meters of open water a route must cross before a bridge is generated (shorter crossings ford instead). |
| `pierSpacing` | number | `7` | 4 – 16 | Yes | Long crossings get support piers to the bed every this many meters. |
| `deckClearance` | number | `1.1` | 0.3 – 3 | Yes | Minimum meters between the water level and the deck at mid-span. |

### Paths, roads & bridges: Stairs

Stepped stone segments swapped in where the route climbs steeply. Visual only — paths.heightAt stays a smooth ramp.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `slopeThreshold` | number | `0.45` | 0.2 – 0.9 | Yes | Rise-over-run along the route beyond which the ribbon switches to stepped stone segments. |
| `stepHeight` | number | `0.19` | 0.12 – 0.3 | Yes | Riser height of generated steps in meters. |

## Ambient VFX

Module: `toonlab/ambientfx` — 6 groups, 54 fields.

Settings are nested per group: `createAmbientFx({ settings: { fireflies: { blinkSpeed: 0.8 } } })`. Effect entries in `effects` override their group; `densityScale` multiplies the authored per-m³ density (`density` remains a compatibility alias). Call `emitNow(camera)` when build-time stats or a settled first capture are required before the first update.

### Ambient VFX: Shared

Wind, sun, and the follow-window every effect emits into. Match windDirection/windSpeed/windStrength with the grass and tree wind so the whole world blows the same way.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `windDirection` | vector2 | `[1, 0.3]` | — | Yes | Horizontal (XZ) heading the wind blows toward — share with grass/trees. Magnitude is ignored. |
| `windSpeed` | number | `1` | 0 – 4 | Yes | How fast wind-driven motion oscillates and mist scrolls. |
| `windStrength` | number | `0.16` | 0 – 1 | Yes | How far particles drift downwind. |
| `sunDirection` | vector3 | `[0.35, 0.72, 0.42]` | — | Yes | World-space direction toward the sun (normalized on apply); drives the pollen backlight and petal sheen. |
| `windowRadius` | number | `45` | 15 – 120 | Yes | Meters of the follow window particles exist in around the follow target. Construction-only. |
| `maxParticles` | number | `20000` | 1000 – 40000 | Yes | Hard budget; effect densities are scaled down proportionally when their sum would exceed it. Construction-only. |

### Ambient VFX: Petals

Flutter-falling blossom petals. Emit from registered bloom volumes (flowering canopies) when any exist, otherwise from the open air above the ground.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `density` | number | `0.03` | 0 – 0.15 | Yes | Petals per m³ of the emission volume. |
| `canopyDensity` | number | `4.5` | 0 – 20 | Yes | Petals per m³ inside registered bloom volumes (crowns shed far more than open air). |
| `sizeRange` | vector2 | `[0.06, 0.11]` | — | Yes | Min/max petal size in meters. |
| `colorA` | color | `[1, 0.52, 0.68]` (#ff85ad) | — | Yes | Primary petal color. |
| `colorB` | color | `[1, 0.75, 0.84]` (#ffbfd6) | — | Yes | Secondary petal color; each petal picks between the two. |
| `emitHeight` | vector2 | `[2, 9]` | — | Yes | Min/max meters above ground petals spawn at when not bound to canopies. Construction-only. |
| `flutter` | number | `1` | 0 – 3 | Yes | Side-to-side rocking amplitude while falling. |
| `windResponse` | number | `1` | 0 – 3 | Yes | Multiplier on the shared wind drift for this effect. |
| `gate` | select | `'day'` | `day` \| `night` \| `duskNight` \| `dawnDusk` \| `any` | Yes | When the effect is visible; weights follow the environmentTimeOfDay hour. |

### Ambient VFX: Falling Leaves

Tumble-falling leaves with strong gust response. Emit from bloom volumes tagged effect:"leaves", otherwise globally.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `density` | number | `0.022` | 0 – 0.15 | Yes | Leaves per m³ of the emission volume. |
| `canopyDensity` | number | `3.2` | 0 – 20 | Yes | Leaves per m³ inside bloom volumes tagged effect:"leaves". |
| `sizeRange` | vector2 | `[0.09, 0.16]` | — | Yes | Min/max leaf size in meters. |
| `colorA` | color | `[0.93, 0.64, 0.2]` (#eda333) | — | Yes | Primary leaf color. |
| `colorB` | color | `[0.78, 0.4, 0.13]` (#c76621) | — | Yes | Secondary leaf color; each leaf picks between the two. |
| `emitHeight` | vector2 | `[2, 10]` | — | Yes | Min/max meters above ground leaves spawn at when not bound to canopies. Construction-only. |
| `tumble` | number | `1` | 0 – 3 | Yes | Rotational tumbling speed while falling. |
| `windResponse` | number | `1.35` | 0 – 3 | Yes | Multiplier on the shared wind drift for this effect. |
| `gate` | select | `'any'` | `day` \| `night` \| `duskNight` \| `dawnDusk` \| `any` | Yes | When the effect is visible; weights follow the environmentTimeOfDay hour. |

### Ambient VFX: Fireflies

Hovering, blinking emissive motes over grass and shore margins. Unlit by design; they ramp with the time-of-day dusk.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `density` | number | `0.045` | 0 – 0.2 | Yes | Fireflies per m³ of the near-ground hover band. |
| `sizeRange` | vector2 | `[0.13, 0.2]` | — | Yes | Min/max glow-sprite size in meters. |
| `color` | color | `[1, 0.87, 0.42]` (#ffde6b) | — | Yes | Emissive glow color (unlit; never touched by scene lights). |
| `hoverHeight` | vector2 | `[0.25, 2.2]` | — | Yes | Min/max meters above ground fireflies hover at. Construction-only. |
| `hoverRadius` | number | `0.9` | 0 – 4 | Yes | Meters of wander around each spawn point. |
| `blinkSpeed` | number | `1` | 0 – 4 | Yes | How fast the blink program pulses. |
| `intensity` | number | `1` | 0 – 4 | Yes | Emissive brightness multiplier. |
| `windResponse` | number | `0.1` | 0 – 3 | Yes | Multiplier on the shared wind drift for this effect. |
| `gate` | select | `'duskNight'` | `day` \| `night` \| `duskNight` \| `dawnDusk` \| `any` | Yes | When the effect is visible; weights follow the environmentTimeOfDay hour. |

### Ambient VFX: Pollen Motes

Slow curl-drifting dust motes, brightest looking toward the sun (backlit). Bind to flower masks via the effects config.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `density` | number | `0.06` | 0 – 0.3 | Yes | Motes per m³ of the near-ground drift band. |
| `sizeRange` | vector2 | `[0.045, 0.085]` | — | Yes | Min/max mote size in meters. |
| `color` | color | `[1, 0.93, 0.72]` (#ffedb8) | — | Yes | Mote color (additive, so it reads as light). |
| `hoverHeight` | vector2 | `[0.3, 2.6]` | — | Yes | Min/max meters above ground motes drift at. Construction-only. |
| `driftRadius` | number | `1.3` | 0 – 5 | Yes | Meters of curl-drift wander around each spawn point. |
| `backlitStrength` | number | `1` | 0 – 3 | Yes | Brightness boost when the camera looks toward the sun through the motes. |
| `windResponse` | number | `0.5` | 0 – 3 | Yes | Multiplier on the shared wind drift for this effect. |
| `gate` | select | `'day'` | `day` \| `night` \| `duskNight` \| `dawnDusk` \| `any` | Yes | When the effect is visible; weights follow the environmentTimeOfDay hour. |

### Ambient VFX: Ground Mist

Soft horizontal wisps scrolling with the wind, hugging water margins and low ground at dawn/dusk.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `density` | number | `0.0045` | 0 – 0.02 | Yes | Wisps per m³ of the ground-hugging band — a few dozen quads, not thousands. |
| `sizeRange` | vector2 | `[1.6, 3]` | — | Yes | Min/max wisp height in meters (width is ~3–5× the height). |
| `color` | color | `[0.84, 0.9, 0.97]` (#d6e6f7) | — | Yes | Wisp color. |
| `opacity` | number | `0.34` | 0 – 0.6 | Yes | Peak alpha at a wisp center; the sprite falls off softly from there. |
| `scrollSpan` | number | `26` | 5 – 60 | Yes | Meters a wisp travels downwind before wrapping (fades at both ends). |
| `marginWidth` | number | `7` | 1 – 20 | Yes | Meters of \|ground − waterLevel\| that count as the water-margin emission band. Construction-only. |
| `windResponse` | number | `1` | 0 – 3 | Yes | Multiplier on the shared wind drift for this effect. |
| `gate` | select | `'dawnDusk'` | `day` \| `night` \| `duskNight` \| `dawnDusk` \| `any` | Yes | When the effect is visible; weights follow the environmentTimeOfDay hour. |

## Gameplay VFX

Module: `toonlab/vfxgen` — 7 groups, 80 fields.

Settings are nested per group: `createVfxSystem({ settings: { impact: { sparkCount: 40 } } })`. Per-spawn `look` overrides re-tint one spawn without touching settings.

### Gameplay VFX: Shared

Budgets and global pacing for every effect. The one-shot backbone renders all bursts in two draw calls; these bound its ring buffers and the pooled trail/projectile meshes.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `maxParticles` | number | `4096` | 256 – 32768 | Yes | Ring-buffer capacity of the one-shot backbone (sparks, embers, puffs, rings, flashes). Oldest instances are overwritten first. Construction-only. |
| `maxProjectiles` | number | `8` | 1 – 32 | Yes | Pooled legacy billboard projectile cores (fireballs in flight). Spawns beyond this reuse the oldest. Construction-only. |
| `maxLayeredProjectiles` | number | `8` | 1 – 32 | Yes | Pooled template-backed layered projectile roots. Spawns beyond this reuse the oldest. Construction-only. |
| `maxTrails` | number | `8` | 1 – 32 | Yes | Pooled slash-trail ribbons live at once. Spawns beyond this reuse the oldest. Construction-only. |
| `timeScale` | number | `1` | 0 – 2 | Yes | Global VFX clock multiplier — hit-stop and slow-motion hooks feed this. |

### Gameplay VFX: Slash Trail

Weapon-swing ribbon sampled from a followed blade (base + tip anchors), with a stepped toon fade and edge sparkle. The anime arc smear.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `color` | color | `[0.55, 0.8, 1]` (#8cccff) | — | Yes | The solid body of the arc — the flat saturated fill. |
| `coreColor` | color | `[1, 1, 1]` (#ffffff) | — | Yes | Leading-edge band color along the blade-tip side; white body+edge banding is the reference action-RPG read. |
| `lifetime` | number | `0.28` | 0.05 – 1.5 | Yes | Seconds a ribbon segment persists before the tail erodes over it. |
| `bands` | number | `3` | 1 – 8 | Yes | Cel quantization of the tail erosion sweep — fewer bands, chunkier stepped tail. |
| `intensity` | number | `1` | 0 – 4 | Yes | Emissive brightness multiplier on the glow parts. |
| `sparkle` | number | `60` | 0 – 300 | Yes | Sparks per second shed from the blade tip while the trail is active. |
| `segments` | number | `96` | 8 – 256 | Yes | Ribbon history capacity in spline points — longer fast swings need more. Construction-only. |

### Gameplay VFX: Impact Burst

Hit feedback: a radial star flash plus ballistic sparks with gravity. `power` at spawn scales count, speed, and flash size.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `sparkColor` | color | `[1, 0.85, 0.45]` (#ffd973) | — | Yes | Ballistic spark color (additive). |
| `flashColor` | color | `[1, 0.97, 0.88]` (#fff7e0) | — | Yes | Radial star-flash color at the hit point. |
| `sparkCount` | number | `26` | 0 – 120 | Yes | Sparks per burst at power 1; spawn `power` scales this. |
| `sparkSpeed` | number | `7` | 0 – 30 | Yes | Initial spark speed in m/s, biased along the hit normal. |
| `gravity` | number | `18` | 0 – 60 | Yes | Downward pull on sparks in m/s² — high values read as metal chips. |
| `flashSize` | number | `0.9` | 0 – 4 | Yes | Star-flash quad size in meters at power 1. |
| `spikes` | number | `6` | 3 – 12 | Yes | Point count of the star flash — 4 reads as an action-RPG glint, 6–8 as an anime hit star. |
| `shockwave` | boolean | `true` | — | Yes | Camera-facing expanding ring at the hit point — the action-RPG hit circle. Tinted by Flash Color. |
| `lifetime` | number | `0.5` | 0.05 – 2 | Yes | Seconds sparks live (the flash pops in about a quarter of this). |
| `intensity` | number | `1` | 0 – 4 | Yes | Emissive brightness multiplier on the glow parts. |

### Gameplay VFX: Fireball

Projectile: a flame-shaded core billboard shedding embers in flight; explodes into an impact burst, smoke puffs, and an expanding scorch ring.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `coreSize` | number | `0.42` | 0.05 – 2 | Yes | Flame-core billboard radius in meters. |
| `coreColor` | color | `[1, 0.95, 0.6]` (#fff299) | — | Yes | Hot center of the flame shader. |
| `flameColor` | color | `[1, 0.45, 0.12]` (#ff731f) | — | Yes | Outer flame licks and ember tint. |
| `emberRate` | number | `90` | 0 – 400 | Yes | Embers shed per second while the projectile flies. |
| `emberSize` | vector2 | `[0.05, 0.12]` | — | Yes | Min/max ember size in meters. |
| `emberLifetime` | number | `0.55` | 0.05 – 2 | Yes | Seconds each shed ember lives. |
| `intensity` | number | `1.2` | 0 – 4 | Yes | Emissive brightness multiplier on the glow parts. |
| `explosionPower` | number | `1.6` | 0 – 5 | Yes | `power` handed to the impact burst + smoke on detonation. |
| `scorchRing` | boolean | `true` | — | Yes | Expanding ground ring on detonation. |
| `ringColor` | color | `[1, 0.55, 0.2]` (#ff8c33) | — | Yes | Scorch-ring glow color. |

### Gameplay VFX: Charged Energy Shot

Template-backed layered projectile: directional mesh core, animated energy shell and filaments, internal motes, boundary sparks, travel trail, local light, and impact presentation.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `length` | number | `1.8` | 0.6 – 4 | Yes | Projectile length in meters at full charge. |
| `radius` | number | `0.46` | 0.12 – 1.2 | Yes | Projectile radius in meters at full charge. |
| `coreIntensity` | number | `2.4` | 0 – 5 | Yes | Emission multiplier for the directional inner body. |
| `shellIntensity` | number | `1.35` | 0 – 4 | Yes | Emission multiplier for the outer energy volume. |
| `filamentDensity` | number | `1.25` | 0.25 – 3 | Yes | Density of animated veins across the outer shell. |
| `filamentSpeed` | number | `1.2` | 0 – 4 | Yes | Flow speed of shell veins and internal streaks. |
| `circulationEnabled` | boolean | `true` | — | Yes | Procedural seeded energy arcs that move over the projectile volume. |
| `energyMotionTheme` | text | `'electric-orbit'` | — | Yes | Authored starting theme or custom parameter set. |
| `circulationCount` | number | `6` | 1 – 12 | Yes | Primary surface arcs before branch forks. |
| `circulationSpeed` | number | `1.6` | 0 – 4 | Yes | Cycles per authored motion unit. |
| `circulationDirection` | text | `'alternating'` | — | Yes | Clockwise, counter-clockwise, or alternating per arc. |
| `circulationCoverage` | number | `0.3` | 0.08 – 1 | Yes | Fraction of a full orbit covered by each arc. |
| `circulationIrregularity` | number | `0.72` | 0 – 1 | Yes | Seeded angular and axial deviation from a uniform orbit. |
| `circulationBranching` | number | `0.42` | 0 – 1 | Yes | Frequency and reach of connected lightning forks. |
| `circulationThickness` | number | `0.022` | 0.006 – 0.08 | Yes | Normalized width of the bright surface ribbon. |
| `circulationSurfaceOffset` | number | `1.68` | 1.05 – 2.4 | Yes | Visible gap between the main projectile body and the circulating lightning. |
| `circulationAxialWander` | number | `0.52` | 0 – 1 | Yes | How far an arc travels between nose and tail. |
| `circulationPlaneVariation` | number | `0.78` | 0 – 1 | Yes | Tilts arcs onto different seeded planes and adds non-planar depth wobble. |
| `circulationFlicker` | number | `0.68` | 0 – 1 | Yes | Seeded disappearance and reformation instead of continuous uniform bands. |
| `releaseDepth` | number | `0.28` | 0.05 – 0.65 | Yes | Out-of-plane depth along the firing axis. |
| `releaseIrregularity` | number | `0.38` | 0 – 0.75 | Yes | Restrained seeded variation around the loop. |
| `releaseLobes` | number | `3` | 2 – 7 | Yes | Gentle undulations around the closed loop. |
| `turbulence` | number | `0.7` | 0 – 2 | Yes | Internal-particle motion and boundary instability. |
| `trailLength` | number | `1.15` | 0 – 3 | Yes | Lifetime and visual reach of particles shed behind the projectile. |
| `particleRate` | number | `160` | 0 – 500 | Yes | Internal motes and boundary sparks emitted per second. |
| `impactPower` | number | `2.2` | 0 – 5 | Yes | Presentation power of the contact flash, shockwave, sparks, and smoke. |
| `coreColor` | color | `[0.9, 0.98, 1]` (#e6faff) | — | Yes | Hot inner energy color. |
| `edgeColor` | color | `[0.28, 0.62, 1]` (#479eff) | — | Yes | Outer shell and travel-trail color. |
| `accentColor` | color | `[0.55, 0.82, 1]` (#8cd1ff) | — | Yes | Filament, compression-ring, and impact accent color. |
| `lightIntensity` | number | `2.4` | 0 – 8 | Yes | Optional local point-light intensity at full charge. |
| `bloomContribution` | number | `0.8` | 0 – 2 | Yes | Authored bloom recommendation exposed to compatible host post stacks. |

### Gameplay VFX: Footstep Dust

Small chunky dust puffs kicked up at a footfall. Cheap enough to fire every step.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `puffCount` | number | `5` | 0 – 20 | Yes | Dust puffs per footfall. |
| `sizeRange` | vector2 | `[0.1, 0.22]` | — | Yes | Min/max puff size in meters (puffs grow ~2× over life). |
| `color` | color | `[0.78, 0.72, 0.62]` (#c7b89e) | — | Yes | Dust color — sample the ground palette. |
| `lifetime` | number | `0.55` | 0.05 – 2 | Yes | Seconds a puff lives. |
| `rise` | number | `0.5` | 0 – 2 | Yes | Upward drift in m/s — heavier dust settles faster. |
| `spread` | number | `0.22` | 0 – 1 | Yes | Horizontal scatter radius in meters around the footfall. |

### Gameplay VFX: Landing Ring

The classic landing hit: a radial ring of dust puffs expanding outward from the touch-down point. `power` at spawn scales radius and count.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Master toggle for the effect. |
| `puffCount` | number | `14` | 0 – 40 | Yes | Puffs around the ring at power 1; spawn `power` scales this. |
| `ringRadius` | number | `1.1` | 0.2 – 5 | Yes | Meters the dust ring expands to at power 1. |
| `sizeRange` | vector2 | `[0.18, 0.38]` | — | Yes | Min/max puff size in meters. |
| `color` | color | `[0.78, 0.72, 0.62]` (#c7b89e) | — | Yes | Dust color — sample the ground palette. |
| `lifetime` | number | `0.7` | 0.05 – 2 | Yes | Seconds the ring takes to expand and fade. |

## Fauna

Module: `toonlab/fauna` — 5 groups, 48 fields.

Settings are nested per species group: `createFauna({ settings: { birds: { fleeRadius: 15 } } })`. Populations are passed separately: `createFauna({ species: { birds: 40, fish: 80 } })`.

### Fauna: Shared

Cross-species simulation budgets: the staggered steering-tick share and the distance beyond which agents degrade to scripted loops.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `tickShare` | number | `0.25` | 0.05 – 0.5 | Yes | Fraction of all agents that receive a full steering tick per update; the rest integrate their last velocity. 0.25 = every agent steers at ~15 Hz on a 60 Hz host. |
| `farDistance` | number | `150` | 40 – 400 | Yes | Meters from the follow target beyond which agents stop steering entirely and fly scripted circles (fish keep their depth clamps). |

### Fauna: Birds

Flocking boids in a roaming altitude band; perch on registered points (or terrain) and flush when the follow target approaches.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `altitudeMin` | number | `7` | 1 – 40 | Yes | Bottom of the preferred flight band, meters above the local terrain. |
| `altitudeMax` | number | `26` | 2 – 80 | Yes | Top of the preferred flight band, meters above the local terrain. |
| `cruiseSpeed` | number | `7` | 1 – 20 | Yes | Relaxed flight speed in m/s; flocks settle around it. |
| `maxSpeed` | number | `12` | 2 – 30 | Yes | Hard speed cap in m/s, reached when fleeing. |
| `neighborRadius` | number | `14` | 2 – 30 | Yes | Meters within which flockmates influence cohesion and alignment. |
| `separationRadius` | number | `2.6` | 0.5 – 8 | Yes | Personal-space radius in meters; closer neighbors are pushed away. |
| `cohesion` | number | `0.9` | 0 – 2 | Yes | Pull toward the local flock center — the flock-tightness knob. |
| `alignment` | number | `0.8` | 0 – 2 | Yes | Pull toward the local average heading. |
| `separation` | number | `1.3` | 0 – 3 | Yes | Push away from neighbors inside the separation radius. |
| `wander` | number | `0.45` | 0 – 2 | Yes | Per-bird sinusoidal drift so flocks meander instead of orbiting. |
| `fleeRadius` | number | `12` | 0 – 40 | Yes | Meters from the follow target at which flying birds scatter and perched birds flush. |
| `perchChance` | number | `0.5` | 0 – 1 | Yes | Appetite for landing: expected perch attempts scale with this per ~10 s of flight. |
| `perchDuration` | number | `11` | 2 – 40 | Yes | Mean seconds a bird stays perched (each stay jitters ±40%). |
| `flapHz` | number | `3.4` | 0.5 – 8 | Yes | Wingbeats per second; the GPU flap phase/speed attributes derive from it. Birds glide (near-zero amplitude) when descending. |
| `scale` | number | `1` | 0.4 – 2.5 | Yes | Uniform body scale multiplier (±12% per-bird jitter on top). |
| `palette` | select | `'swallow'` | `swallow` \| `egret` \| `finch` | Yes | Named body palette; each palette carries 2–4 vertex-colored variants. |

### Fauna: Butterflies

Individual noise-wanderers anchored to flower-mask points, hovering just above the terrain.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `hoverMin` | number | `0.5` | 0.1 – 3 | Yes | Bottom of the flutter band, meters above the local terrain. |
| `hoverMax` | number | `1.7` | 0.2 – 5 | Yes | Top of the flutter band, meters above the local terrain. |
| `speed` | number | `1.3` | 0.2 – 4 | Yes | Typical flutter speed in m/s. |
| `wanderRadius` | number | `6` | 2 – 30 | Yes | Meters a butterfly may drift from its flower-mask anchor before being pulled back. |
| `fleeRadius` | number | `3.5` | 0 – 15 | Yes | Meters from the follow target at which butterflies scatter upward. |
| `flapHz` | number | `8.5` | 2 – 16 | Yes | Wingbeats per second for the GPU wing fold. |
| `scale` | number | `1` | 0.4 – 2.5 | Yes | Uniform body scale multiplier (±20% per-agent jitter on top). |
| `palette` | select | `'meadow'` | `meadow` \| `twilight` | Yes | Named wing palette; each palette carries up to 4 vertex-colored variants. |

### Fauna: Dragonflies

Hover-and-dart flyers anchored to the water margin, holding a fixed height above the water surface.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `hoverHeight` | number | `0.6` | 0.2 – 3 | Yes | Meters above the water surface dragonflies hold. |
| `hoverRadius` | number | `5` | 1 – 20 | Yes | Meters of drift allowed around the current hover anchor. |
| `dartSpeed` | number | `7` | 1 – 16 | Yes | Straight-line speed in m/s when relocating to a new anchor. |
| `dartChance` | number | `0.5` | 0 – 1 | Yes | Appetite for relocating: expected darts scale with this per ~8 s of hovering. |
| `flapHz` | number | `36` | 10 – 60 | Yes | Wing oscillations per second; high rates read as the classic wing shimmer. |
| `scale` | number | `1` | 0.4 – 2.5 | Yes | Uniform body scale multiplier. |
| `palette` | select | `'pond'` | `pond` \| `ember` | Yes | Named body palette; each palette carries 2–3 vertex-colored variants. |

### Fauna: Fish

Schooling boids clamped between the water surface and the bed; visible from above through the water refraction pass.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `surfaceMargin` | number | `0.3` | 0.1 – 2 | Yes | Minimum meters a fish stays below the water surface (never breaches). |
| `bedMargin` | number | `0.35` | 0.1 – 2 | Yes | Minimum meters a fish stays above the terrain bed. |
| `minSpawnDepth` | number | `1.1` | 0.3 – 5 | Yes | Meters of water column required for a fish spawn point; shallower bounds simply hold fewer fish. |
| `cruiseSpeed` | number | `1.5` | 0.2 – 5 | Yes | Relaxed swim speed in m/s. |
| `maxSpeed` | number | `3.2` | 0.5 – 8 | Yes | Hard speed cap in m/s, reached when fleeing. |
| `neighborRadius` | number | `4` | 1 – 12 | Yes | Meters within which schoolmates influence cohesion and alignment. |
| `separationRadius` | number | `0.8` | 0.2 – 4 | Yes | Personal-space radius in meters. |
| `cohesion` | number | `0.9` | 0 – 2 | Yes | Pull toward the local school center — schooling tightness. |
| `alignment` | number | `0.85` | 0 – 2 | Yes | Pull toward the local average heading. |
| `separation` | number | `1.1` | 0 – 3 | Yes | Push away from neighbors inside the separation radius. |
| `wander` | number | `0.5` | 0 – 2 | Yes | Per-fish sinusoidal drift so schools roam the basin. |
| `fleeRadius` | number | `7` | 0 – 25 | Yes | Meters from the follow target (a swimmer, a bridge walker) at which fish scatter. |
| `swayHz` | number | `2.8` | 0.5 – 8 | Yes | Tail-sway cycles per second for the GPU body flex. |
| `scale` | number | `1` | 0.3 – 3 | Yes | Uniform body scale multiplier (±25% per-fish jitter on top). |
| `palette` | select | `'koi'` | `koi` \| `silver` | Yes | Named body palette: koi for ponds and lakes, silver for open water. |


## Procedural textures

Module: `toonlab/texgen` — 10 groups, 166 fields.

Grouped settings consumed by `evaluateTextureMaps(settings)` and serialized in texture recipes (`createTextureSettings`).

### Procedural textures: Seed

Deterministic seed shared by every layer.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `seed` | number | `1337` | 0 – 99999 | Yes | Deterministic seed — every value is a different texture with the same recipe. |

### Procedural textures: Base pattern

The primary structure: pattern, frequency, warp.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `generator` | select | `'fbm'` | `fbm` \| `billow` \| `ridged` \| `turbulence` \| `value` \| `perlin` \| `worley` \| `worleyF2` \| `cells` \| `cracks` \| `caustics` \| `speckle` \| `bricks` \| `tiles` \| `hex` \| `checker` \| `grid` \| `stripes` \| `chevron` \| `weave` \| `basketWeave` \| `scales` \| `dots` \| `marble` \| `woodGrain` \| `flat` | Yes | Primary structure of the material: this drives height, color banding, and pattern cells. |
| `contrast` | number | `0` | -1 – 1 | Yes | Sharpens (+) or flattens (-) the base pattern. |
| `bias` | number | `0` | -0.5 – 0.5 | Yes | Shifts the whole pattern up or down the ramp. |
| `invert` | boolean | `false` | — | Yes | Flips the base pattern (crevices become ridges). |
| `scale` | number | `6` | 1 – 64 | Yes | Feature cells across the tile. Higher = finer features. |
| `rotate90` | boolean | `false` | — | Yes | Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact. |
| `detail` | number | `4` | 1 – 8 | Yes | Fractal octaves layered into the noise. |
| `detailGain` | number | `0.5` | 0.15 – 0.85 | Yes | How much each finer octave contributes. |
| `stretchX` | number | `1` | 0.25 – 8 | Yes | Horizontal anisotropy (brushed metal, wood planks). |
| `stretchY` | number | `1` | 0.25 – 8 | Yes | Vertical anisotropy (drips, strata, fibers). |
| `warp` | number | `0` | 0 – 1 | Yes | Domain warp: melts straight features into organic meanders. |
| `warpScale` | number | `3` | 1 – 32 | Yes | Frequency of the warp field. |
| `columns` | number | `4` | 1 – 64 | Yes | Pattern cells across the tile. |
| `rows` | number | `8` | 1 – 64 | Yes | Pattern cells down the tile. |
| `gap` | number | `0.06` | 0 – 0.4 | Yes | Mortar/groove width between pattern cells. |
| `bevel` | number | `0.12` | 0 – 0.5 | Yes | Edge ramp from groove up to the cell face. |
| `cellJitter` | number | `1` | 0 – 1 | Yes | Randomizes cell centers: 0 = perfect grid, 1 = organic. |
| `cellVariation` | number | `0.35` | 0 – 1 | Yes | Per-cell brightness variance (brick tint shifts). |
| `edgeWidth` | number | `0.12` | 0.01 – 0.6 | Yes | Width of cracks / caustic filaments / speckle chips. |
| `rings` | number | `6` | 1 – 32 | Yes | Ring or vein count across the tile (wood, marble). |
| `grain` | number | `0.5` | 0 – 1 | Yes | Streak amount (wood) or vein sharpness (marble). |

### Procedural textures: Detail layer A

Mid-frequency relief blended over the base.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `true` | — | Yes | Toggles this detail layer. |
| `generator` | select | `'fbm'` | `fbm` \| `billow` \| `ridged` \| `turbulence` \| `value` \| `perlin` \| `worley` \| `worleyF2` \| `cells` \| `cracks` \| `caustics` \| `speckle` \| `bricks` \| `tiles` \| `hex` \| `checker` \| `grid` \| `stripes` \| `chevron` \| `weave` \| `basketWeave` \| `scales` \| `dots` \| `marble` \| `woodGrain` \| `flat` | Yes | Pattern blended over the base height. |
| `blend` | select | `'overlay'` | `overlay` \| `add` \| `multiply` \| `screen` \| `min` \| `max` \| `mix` | Yes | How this layer combines with the height underneath. |
| `amount` | number | `0.35` | 0 – 1 | Yes | Blend strength of this layer. |
| `invert` | boolean | `false` | — | Yes | Flips the layer before blending. |
| `contrast` | number | `0` | -1 – 1 | Yes | Sharpens (+) or flattens (-) the layer. |
| `scale` | number | `18` | 1 – 64 | Yes | Feature cells across the tile. Higher = finer features. |
| `rotate90` | boolean | `false` | — | Yes | Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact. |
| `detail` | number | `4` | 1 – 8 | Yes | Fractal octaves layered into the noise. |
| `detailGain` | number | `0.5` | 0.15 – 0.85 | Yes | How much each finer octave contributes. |
| `stretchX` | number | `1` | 0.25 – 8 | Yes | Horizontal anisotropy (brushed metal, wood planks). |
| `stretchY` | number | `1` | 0.25 – 8 | Yes | Vertical anisotropy (drips, strata, fibers). |
| `warp` | number | `0` | 0 – 1 | Yes | Domain warp: melts straight features into organic meanders. |
| `warpScale` | number | `3` | 1 – 32 | Yes | Frequency of the warp field. |
| `columns` | number | `4` | 1 – 64 | Yes | Pattern cells across the tile. |
| `rows` | number | `8` | 1 – 64 | Yes | Pattern cells down the tile. |
| `gap` | number | `0.06` | 0 – 0.4 | Yes | Mortar/groove width between pattern cells. |
| `bevel` | number | `0.12` | 0 – 0.5 | Yes | Edge ramp from groove up to the cell face. |
| `cellJitter` | number | `1` | 0 – 1 | Yes | Randomizes cell centers: 0 = perfect grid, 1 = organic. |
| `cellVariation` | number | `0.35` | 0 – 1 | Yes | Per-cell brightness variance (brick tint shifts). |
| `edgeWidth` | number | `0.12` | 0.01 – 0.6 | Yes | Width of cracks / caustic filaments / speckle chips. |
| `rings` | number | `6` | 1 – 32 | Yes | Ring or vein count across the tile (wood, marble). |
| `grain` | number | `0.5` | 0 – 1 | Yes | Streak amount (wood) or vein sharpness (marble). |

### Procedural textures: Detail layer B

Fine grain, pores, chips.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Toggles this detail layer. |
| `generator` | select | `'speckle'` | `fbm` \| `billow` \| `ridged` \| `turbulence` \| `value` \| `perlin` \| `worley` \| `worleyF2` \| `cells` \| `cracks` \| `caustics` \| `speckle` \| `bricks` \| `tiles` \| `hex` \| `checker` \| `grid` \| `stripes` \| `chevron` \| `weave` \| `basketWeave` \| `scales` \| `dots` \| `marble` \| `woodGrain` \| `flat` | Yes | Pattern blended over the base height. |
| `blend` | select | `'add'` | `overlay` \| `add` \| `multiply` \| `screen` \| `min` \| `max` \| `mix` | Yes | How this layer combines with the height underneath. |
| `amount` | number | `0.2` | 0 – 1 | Yes | Blend strength of this layer. |
| `invert` | boolean | `false` | — | Yes | Flips the layer before blending. |
| `contrast` | number | `0` | -1 – 1 | Yes | Sharpens (+) or flattens (-) the layer. |
| `scale` | number | `24` | 1 – 64 | Yes | Feature cells across the tile. Higher = finer features. |
| `rotate90` | boolean | `false` | — | Yes | Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact. |
| `detail` | number | `4` | 1 – 8 | Yes | Fractal octaves layered into the noise. |
| `detailGain` | number | `0.5` | 0.15 – 0.85 | Yes | How much each finer octave contributes. |
| `stretchX` | number | `1` | 0.25 – 8 | Yes | Horizontal anisotropy (brushed metal, wood planks). |
| `stretchY` | number | `1` | 0.25 – 8 | Yes | Vertical anisotropy (drips, strata, fibers). |
| `warp` | number | `0` | 0 – 1 | Yes | Domain warp: melts straight features into organic meanders. |
| `warpScale` | number | `3` | 1 – 32 | Yes | Frequency of the warp field. |
| `columns` | number | `4` | 1 – 64 | Yes | Pattern cells across the tile. |
| `rows` | number | `8` | 1 – 64 | Yes | Pattern cells down the tile. |
| `gap` | number | `0.06` | 0 – 0.4 | Yes | Mortar/groove width between pattern cells. |
| `bevel` | number | `0.12` | 0 – 0.5 | Yes | Edge ramp from groove up to the cell face. |
| `cellJitter` | number | `1` | 0 – 1 | Yes | Randomizes cell centers: 0 = perfect grid, 1 = organic. |
| `cellVariation` | number | `0.35` | 0 – 1 | Yes | Per-cell brightness variance (brick tint shifts). |
| `edgeWidth` | number | `0.12` | 0.01 – 0.6 | Yes | Width of cracks / caustic filaments / speckle chips. |
| `rings` | number | `6` | 1 – 32 | Yes | Ring or vein count across the tile (wood, marble). |
| `grain` | number | `0.5` | 0 – 1 | Yes | Streak amount (wood) or vein sharpness (marble). |

### Procedural textures: Color

Five-stop height ramp, painterly jitter, cavity & sheen, final grade.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `color0` | color | `[0.16, 0.14, 0.13]` (#292421) | — | Yes | Ramp stop at the darkest crevices. |
| `color1` | color | `[0.35, 0.31, 0.28]` (#594f47) | — | Yes | Ramp stop between crevices and the mid tone. |
| `color2` | color | `[0.55, 0.5, 0.45]` (#8c8073) | — | Yes | Ramp stop for the average surface. |
| `color3` | color | `[0.72, 0.68, 0.62]` (#b8ad9e) | — | Yes | Ramp stop approaching the ridges. |
| `color4` | color | `[0.88, 0.85, 0.79]` (#e0d9c9) | — | Yes | Ramp stop at the highest ridges. |
| `pos1` | number | `0.25` | 0.02 – 0.98 | Yes | Where the Low stop sits on the height ramp. |
| `pos2` | number | `0.5` | 0.02 – 0.98 | Yes | Where the Mid stop sits on the height ramp. |
| `pos3` | number | `0.75` | 0.02 – 0.98 | Yes | Where the High stop sits on the height ramp. |
| `rampSmooth` | number | `1` | 0 – 1 | Yes | 1 = smooth gradient, 0 = hard cel bands between the five stops. |
| `jitterHue` | number | `0.04` | 0 – 0.5 | Yes | Painterly hue drift across the surface. |
| `jitterValue` | number | `0.08` | 0 – 0.5 | Yes | Painterly brightness drift across the surface. |
| `jitterScale` | number | `24` | 2 – 64 | Yes | Frequency of the painterly drift. |
| `jitterCells` | boolean | `false` | — | Yes | Applies drift per pattern cell (per brick / plank / scale) instead of smoothly. |
| `cavity` | number | `0.35` | 0 – 1 | Yes | Darkens crevices toward the cavity tint — the hand-painted occlusion read. |
| `cavityTint` | color | `[0.13, 0.09, 0.08]` (#211714) | — | Yes | Color the crevices sink toward. |
| `sheen` | number | `0.18` | 0 – 1 | Yes | Screens the sheen tint over ridges and edges — worn highlight. |
| `sheenTint` | color | `[1, 0.97, 0.88]` (#fff7e0) | — | Yes | Color of the ridge highlight. |
| `hueShift` | number | `0` | -0.5 – 0.5 | Yes | Rotates the final palette hue. |
| `saturation` | number | `1` | 0 – 2 | Yes | Final color saturation. |
| `brightness` | number | `1` | 0.25 – 1.75 | Yes | Final brightness multiplier. |
| `contrast` | number | `0` | -1 – 1 | Yes | Final color contrast. |
| `gamma` | number | `1` | 0.4 – 2.5 | Yes | Final gamma on the albedo. |

### Procedural textures: Wear & tear

One-knob damage and dirt macros layered over everything.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `damage` | number | `0` | 0 – 1 | Yes | Universal wear macro: carves seeded scratches and chips into the surface and roughens them. One knob, many parameters. |
| `dirt` | number | `0` | 0 – 1 | Yes | Grime macro: darkens crevices with pooled dirt and raises their roughness, independent of the overlay slots. |

### Procedural textures: Overlay A

Masked colored overlay: moss, rust, dirt, snow, lichen…

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Toggles this overlay. |
| `generator` | select | `'fbm'` | `fbm` \| `billow` \| `ridged` \| `turbulence` \| `value` \| `perlin` \| `worley` \| `worleyF2` \| `cells` \| `cracks` \| `caustics` \| `speckle` \| `bricks` \| `tiles` \| `hex` \| `checker` \| `grid` \| `stripes` \| `chevron` \| `weave` \| `basketWeave` \| `scales` \| `dots` \| `marble` \| `woodGrain` \| `flat` | Yes | Mask pattern deciding where the overlay lands. |
| `color` | color | `[0.35, 0.48, 0.22]` (#597a38) | — | Yes | Overlay color where the mask is strongest. |
| `colorB` | color | `[0.52, 0.62, 0.28]` (#859e47) | — | Yes | Secondary overlay color for variation within the mask. |
| `coverage` | number | `0.35` | 0 – 1 | Yes | How much of the surface the overlay claims. |
| `softness` | number | `0.18` | 0.01 – 0.6 | Yes | Feather width of the overlay border. |
| `creviceBias` | number | `0.5` | -1 – 1 | Yes | +1 pools into crevices (moss, grime); -1 caps ridges and peaks (snow, wear). |
| `blend` | select | `'normal'` | `normal` \| `multiply` \| `overlay` \| `screen` | Yes | How the overlay color mixes into the albedo. |
| `roughnessShift` | number | `0.25` | -1 – 1 | Yes | Overlay area gets rougher (+) or glossier (-). |
| `heightShift` | number | `0.05` | -0.5 – 0.5 | Yes | Overlay area rises (+) or sinks (-) in the height map. |
| `metalShift` | number | `0` | -1 – 1 | Yes | Overlay area gains (+) or loses (-) metalness — rust strips metal. |
| `contrast` | number | `0` | -1 – 1 | Yes | Sharpens (+) or flattens (-) the mask pattern. |
| `invert` | boolean | `false` | — | Yes | Flips the mask before thresholding. |
| `scale` | number | `5` | 1 – 64 | Yes | Feature cells across the tile. Higher = finer features. |
| `rotate90` | boolean | `false` | — | Yes | Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact. |
| `detail` | number | `4` | 1 – 8 | Yes | Fractal octaves layered into the noise. |
| `detailGain` | number | `0.5` | 0.15 – 0.85 | Yes | How much each finer octave contributes. |
| `stretchX` | number | `1` | 0.25 – 8 | Yes | Horizontal anisotropy (brushed metal, wood planks). |
| `stretchY` | number | `1` | 0.25 – 8 | Yes | Vertical anisotropy (drips, strata, fibers). |
| `warp` | number | `0.3` | 0 – 1 | Yes | Domain warp: melts straight features into organic meanders. |
| `warpScale` | number | `3` | 1 – 32 | Yes | Frequency of the warp field. |
| `columns` | number | `4` | 1 – 64 | Yes | Pattern cells across the tile. |
| `rows` | number | `8` | 1 – 64 | Yes | Pattern cells down the tile. |
| `gap` | number | `0.06` | 0 – 0.4 | Yes | Mortar/groove width between pattern cells. |
| `bevel` | number | `0.12` | 0 – 0.5 | Yes | Edge ramp from groove up to the cell face. |
| `cellJitter` | number | `1` | 0 – 1 | Yes | Randomizes cell centers: 0 = perfect grid, 1 = organic. |
| `cellVariation` | number | `0.35` | 0 – 1 | Yes | Per-cell brightness variance (brick tint shifts). |
| `edgeWidth` | number | `0.12` | 0.01 – 0.6 | Yes | Width of cracks / caustic filaments / speckle chips. |
| `rings` | number | `6` | 1 – 32 | Yes | Ring or vein count across the tile (wood, marble). |
| `grain` | number | `0.5` | 0 – 1 | Yes | Streak amount (wood) or vein sharpness (marble). |

### Procedural textures: Overlay B

Second masked overlay: grime, stains, scorch, drips…

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Toggles this overlay. |
| `generator` | select | `'turbulence'` | `fbm` \| `billow` \| `ridged` \| `turbulence` \| `value` \| `perlin` \| `worley` \| `worleyF2` \| `cells` \| `cracks` \| `caustics` \| `speckle` \| `bricks` \| `tiles` \| `hex` \| `checker` \| `grid` \| `stripes` \| `chevron` \| `weave` \| `basketWeave` \| `scales` \| `dots` \| `marble` \| `woodGrain` \| `flat` | Yes | Mask pattern deciding where the overlay lands. |
| `color` | color | `[0.16, 0.12, 0.09]` (#291f17) | — | Yes | Overlay color where the mask is strongest. |
| `colorB` | color | `[0.3, 0.24, 0.18]` (#4d3d2e) | — | Yes | Secondary overlay color for variation within the mask. |
| `coverage` | number | `0.3` | 0 – 1 | Yes | How much of the surface the overlay claims. |
| `softness` | number | `0.22` | 0.01 – 0.6 | Yes | Feather width of the overlay border. |
| `creviceBias` | number | `0.6` | -1 – 1 | Yes | +1 pools into crevices (moss, grime); -1 caps ridges and peaks (snow, wear). |
| `blend` | select | `'multiply'` | `normal` \| `multiply` \| `overlay` \| `screen` | Yes | How the overlay color mixes into the albedo. |
| `roughnessShift` | number | `0.2` | -1 – 1 | Yes | Overlay area gets rougher (+) or glossier (-). |
| `heightShift` | number | `-0.03` | -0.5 – 0.5 | Yes | Overlay area rises (+) or sinks (-) in the height map. |
| `metalShift` | number | `0` | -1 – 1 | Yes | Overlay area gains (+) or loses (-) metalness — rust strips metal. |
| `contrast` | number | `0` | -1 – 1 | Yes | Sharpens (+) or flattens (-) the mask pattern. |
| `invert` | boolean | `false` | — | Yes | Flips the mask before thresholding. |
| `scale` | number | `4` | 1 – 64 | Yes | Feature cells across the tile. Higher = finer features. |
| `rotate90` | boolean | `false` | — | Yes | Turns the pattern a quarter turn (planks run vertical, strata run horizontal). Tiling stays exact. |
| `detail` | number | `4` | 1 – 8 | Yes | Fractal octaves layered into the noise. |
| `detailGain` | number | `0.5` | 0.15 – 0.85 | Yes | How much each finer octave contributes. |
| `stretchX` | number | `1` | 0.25 – 8 | Yes | Horizontal anisotropy (brushed metal, wood planks). |
| `stretchY` | number | `1` | 0.25 – 8 | Yes | Vertical anisotropy (drips, strata, fibers). |
| `warp` | number | `0.25` | 0 – 1 | Yes | Domain warp: melts straight features into organic meanders. |
| `warpScale` | number | `3` | 1 – 32 | Yes | Frequency of the warp field. |
| `columns` | number | `4` | 1 – 64 | Yes | Pattern cells across the tile. |
| `rows` | number | `8` | 1 – 64 | Yes | Pattern cells down the tile. |
| `gap` | number | `0.06` | 0 – 0.4 | Yes | Mortar/groove width between pattern cells. |
| `bevel` | number | `0.12` | 0 – 0.5 | Yes | Edge ramp from groove up to the cell face. |
| `cellJitter` | number | `1` | 0 – 1 | Yes | Randomizes cell centers: 0 = perfect grid, 1 = organic. |
| `cellVariation` | number | `0.35` | 0 – 1 | Yes | Per-cell brightness variance (brick tint shifts). |
| `edgeWidth` | number | `0.12` | 0.01 – 0.6 | Yes | Width of cracks / caustic filaments / speckle chips. |
| `rings` | number | `6` | 1 – 32 | Yes | Ring or vein count across the tile (wood, marble). |
| `grain` | number | `0.5` | 0 – 1 | Yes | Streak amount (wood) or vein sharpness (marble). |

### Procedural textures: Surface

PBR response: relief, occlusion, roughness, metalness.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `heightScale` | number | `0.5` | 0 – 1 | Yes | Overall relief strength — feeds the normal map, AO, and displacement. |
| `normalStrength` | number | `1` | 0 – 3 | Yes | Extra multiplier on the derived normal map. |
| `invertHeight` | boolean | `false` | — | Yes | Flips the height map (grooves become ridges). |
| `aoStrength` | number | `0.55` | 0 – 1 | Yes | Baked ambient occlusion depth in the crevices. |
| `roughness` | number | `0.75` | 0 – 1 | Yes | Base roughness: 0 = mirror gloss, 1 = fully matte. |
| `roughnessContrast` | number | `0.35` | -1 – 1 | Yes | +1 = crevices rough & ridges polished; -1 = the reverse. |
| `metalness` | number | `0` | 0 – 1 | Yes | Base metalness of the material. |

### Procedural textures: Glow

Optional emissive map.

| Field | Type | Default | Range / options | Portable | Description |
|---|---|---|---|---|---|
| `enabled` | boolean | `false` | — | Yes | Adds a glow map (lava cracks, sci-fi circuits, embers). |
| `color` | color | `[1, 0.45, 0.12]` (#ff731f) | — | Yes | Emissive color. |
| `intensity` | number | `2` | 0 – 8 | Yes | Emissive brightness (preview material intensity). |
| `source` | select | `'crevices'` | `crevices` \| `peaks` \| `band` \| `accentA` \| `accentB` \| `everywhere` | Yes | Which part of the surface glows. |
| `threshold` | number | `0.5` | 0 – 1 | Yes | Height level the glow hugs (band / crevices / peaks). |
| `width` | number | `0.25` | 0.02 – 0.8 | Yes | Thickness of the glowing region. |
| `softness` | number | `0.2` | 0.01 – 0.6 | Yes | Feather on the glow border. |