@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/src/rock-shader/rockMaterial.js

@@ -131,6 +131,8 @@ export const TOONLAB_ROCK_PROFILE_DEFAULTS = Object.freeze({
     distanceScale: 1,
   }),
   base: Object.freeze({
+    mode: 'triplanar',
+    upAxis: 'y',
     scale: 1,
     tint: Object.freeze([1, 1, 1]),
     saturation: 1,
@@ -335,6 +337,14 @@ function bool(value, fallback) {
   return fallback;
 }
 
+function projectionMode(value, fallback = 'triplanar') {
+  return value === 'directional-bedding' || value === 'triplanar' ? value : fallback;
+}
+
+function projectionUpAxis(value, fallback = 'y') {
+  return value === 'x' || value === 'y' || value === 'z' ? value : fallback;
+}
+
 function color3(value, fallback) {
   if (Array.isArray(value)) {
     return [
@@ -401,6 +411,8 @@ export function normalizeToonLabRockProfile(profile = {}) {
       ),
     },
     base: {
+      mode: projectionMode(base.mode, defaults.base.mode),
+      upAxis: projectionUpAxis(base.upAxis, defaults.base.upAxis),
       scale: finite(base.scale, defaults.base.scale),
       tint: color3(base.tint, defaults.base.tint),
       saturation: finite(base.saturation, defaults.base.saturation),
@@ -944,6 +956,87 @@ export function toonLabTriplanarColor(map, scale, blend = 1, coordinates = { zSi
     .add(mapNode.sample(projected.xy).rgb.mul(weights.z));
 }
 
+const DIRECTIONAL_BEDDING_AXES = Object.freeze({
+  x: Object.freeze({
+    lateral: Object.freeze([
+      Object.freeze({ faceAxis: 'y', uAxis: 'z', uv: 'zx' }),
+      Object.freeze({ faceAxis: 'z', uAxis: 'y', uv: 'yx' }),
+    ]),
+    suppressedProjectionAxis: 'x',
+    upAxis: 'x',
+  }),
+  y: Object.freeze({
+    lateral: Object.freeze([
+      Object.freeze({ faceAxis: 'x', uAxis: 'z', uv: 'zy' }),
+      Object.freeze({ faceAxis: 'z', uAxis: 'x', uv: 'xy' }),
+    ]),
+    suppressedProjectionAxis: 'y',
+    upAxis: 'y',
+  }),
+  z: Object.freeze({
+    lateral: Object.freeze([
+      Object.freeze({ faceAxis: 'x', uAxis: 'y', uv: 'yz' }),
+      Object.freeze({ faceAxis: 'y', uAxis: 'x', uv: 'xz' }),
+    ]),
+    suppressedProjectionAxis: 'z',
+    upAxis: 'z',
+  }),
+});
+
+/**
+ * Describes the compile-time directional-bedding graph. The returned data is
+ * deliberately plain CPU data so authoring tools and focused verifiers can
+ * prove which axis is suppressed without compiling a WebGPU pipeline.
+ */
+export function describeToonLabDirectionalBeddingProjection(upAxis = 'y') {
+  const resolved = projectionUpAxis(upAxis, 'y');
+  const descriptor = DIRECTIONAL_BEDDING_AXES[resolved];
+  return {
+    lateral: descriptor.lateral.map((entry) => ({ ...entry })),
+    suppressedProjectionAxis: descriptor.suppressedProjectionAxis,
+    upAxis: descriptor.upAxis,
+  };
+}
+
+function directionalBeddingState(scale, blend, coordinates, upAxis) {
+  const descriptor = DIRECTIONAL_BEDDING_AXES[projectionUpAxis(upAxis, 'y')];
+  const projected = toonLabSourcePosition(coordinates).div(safeScale(scale));
+  const geometryNormal = toonLabSourceGeometryNormal(coordinates);
+  const exponent = float(Math.max(finite(blend, 1), 0.000001));
+  const upWeight = pow(
+    max(abs(geometryNormal[descriptor.upAxis]), TOONLAB_FLOAT_EPSILON),
+    exponent,
+  );
+  const lateralWeights = descriptor.lateral.map(({ faceAxis }) => pow(
+    max(abs(geometryNormal[faceAxis]), TOONLAB_FLOAT_EPSILON),
+    exponent,
+  ).add(upWeight.mul(0.5)));
+  const denominator = max(lateralWeights[0].add(lateralWeights[1]), 0.000001);
+  return {
+    descriptor,
+    geometryNormal,
+    projected,
+    weights: lateralWeights.map((weight) => weight.div(denominator)),
+  };
+}
+
+export function toonLabDirectionalBeddingColor(
+  map,
+  scale,
+  blend = 1,
+  coordinates = { zSign: 1 },
+  upAxis = 'y',
+) {
+  const mapNode = texture(map);
+  const state = directionalBeddingState(scale, blend, coordinates, upAxis);
+  const sample = ({ uv: swizzle }) => mapNode.sample(vec2(
+    state.projected[swizzle[0]],
+    state.projected[swizzle[1]],
+  )).rgb;
+  return sample(state.descriptor.lateral[0]).mul(state.weights[0])
+    .add(sample(state.descriptor.lateral[1]).mul(state.weights[1]));
+}
+
 function toonLabSideProjection(map, scale, projectionContrast, {
   negativeScale = true,
   clampResult = true,
@@ -966,7 +1059,18 @@ function toonLabSideProjection(map, scale, projectionContrast, {
 }
 
 function toonLabRockProjection(map, profile) {
-  return profile.base.sideOnly
+  // Directional bedding has explicit precedence. `sideOnly` remains the exact
+  // legacy graph for old presets, but cannot re-enable the suppressed top-axis
+  // sample on a bedded C8 surface.
+  return profile.base.mode === 'directional-bedding'
+    ? toonLabDirectionalBeddingColor(
+      map,
+      profile.base.scale,
+      profile.base.projectionContrast,
+      profile.coordinates,
+      profile.base.upAxis,
+    )
+    : profile.base.sideOnly
     ? toonLabSideProjection(map, profile.base.scale, profile.base.projectionContrast, {
       coordinates: profile.coordinates,
     })
@@ -993,13 +1097,18 @@ function normalGreenSignForTexture(map, profileSign) {
   return finite(profileSign, 1) * importerSign;
 }
 
+function safeNormalizeDirection(direction, fallback = vec3(0, 0, 1)) {
+  const valid = step(float(1e-12), dot(direction, direction));
+  return normalize(mix(fallback, direction, valid));
+}
+
 function worldNormalToTangent(worldNormal) {
   const viewNormal = transformNormalByViewMatrix(worldNormal, cameraViewMatrix);
-  return normalize(transpose(TBNViewMatrix).mul(viewNormal));
+  return safeNormalizeDirection(transpose(TBNViewMatrix).mul(viewNormal));
 }
 
 export function tangentNormalToView(tangentNormal) {
-  return normalize(TBNViewMatrix.mul(tangentNormal));
+  return safeNormalizeDirection(TBNViewMatrix.mul(tangentNormal));
 }
 
 export function toonLabTriplanarNormal(map, scale, blend, greenSign, coordinates) {
@@ -1027,6 +1136,52 @@ export function toonLabTriplanarNormal(map, scale, blend, greenSign, coordinates
   return worldNormalToTangent(worldNormal);
 }
 
+function directionalBeddingNormalCandidate(decoded, geometryNormal, entry, upAxis) {
+  const components = {
+    x: geometryNormal.x,
+    y: geometryNormal.y,
+    z: geometryNormal.z,
+  };
+  components[entry.faceAxis] = abs(decoded.z).mul(geometryNormal[entry.faceAxis]);
+  components[entry.uAxis] = decoded.x.add(geometryNormal[entry.uAxis]);
+  components[upAxis] = decoded.y.add(geometryNormal[upAxis]);
+  return vec3(components.x, components.y, components.z);
+}
+
+export function toonLabDirectionalBeddingNormal(
+  map,
+  scale,
+  blend,
+  greenSign,
+  coordinates,
+  upAxis = 'y',
+) {
+  const state = directionalBeddingState(scale, blend, coordinates, upAxis);
+  const mapNode = texture(map);
+  const candidates = state.descriptor.lateral.map((entry) => {
+    const decoded = decodeToonLabNormal(mapNode.sample(vec2(
+      state.projected[entry.uv[0]],
+      state.projected[entry.uv[1]],
+    )).rgb, greenSign);
+    return directionalBeddingNormalCandidate(
+      decoded,
+      state.geometryNormal,
+      entry,
+      state.descriptor.upAxis,
+    );
+  });
+  const sourceWorldNormal = safeNormalizeDirection(
+    candidates[0].mul(state.weights[0]).add(candidates[1].mul(state.weights[1])),
+    state.geometryNormal,
+  );
+  const worldNormal = safeNormalizeDirection(vec3(
+    sourceWorldNormal.x,
+    sourceWorldNormal.y,
+    sourceWorldNormal.z.mul(coordinates.zSign),
+  ), state.geometryNormal);
+  return worldNormalToTangent(worldNormal);
+}
+
 function toonLabNormalBlend(a, b) {
   // S_Rock's Normal Blend node uses BlendMode.Default, not RNM.
   return normalize(vec3(a.xy.add(b.xy), a.z.mul(b.z)));
@@ -1286,12 +1441,14 @@ export function createToonRockMaterial({
   // The macro projection carries the authored silhouette-scale color breakup;
   // a second metre-scale octave preserves readable rock surface detail close
   // to the camera without changing that macro identity.
-  const nearDetailSample = toonLabTriplanarColor(
-    textures.rock,
-    resolvedProfile.base.nearDetailScale,
-    resolvedProfile.base.projectionContrast,
-    resolvedProfile.coordinates,
-  );
+  const nearDetailProfile = {
+    ...resolvedProfile,
+    base: {
+      ...resolvedProfile.base,
+      scale: resolvedProfile.base.nearDetailScale,
+    },
+  };
+  const nearDetailSample = toonLabRockProjection(textures.rock, nearDetailProfile);
   const nearDetailValue = dot(nearDetailSample, vec3(0.2126, 0.7152, 0.0722));
   const nearDetailFade = clamp(
     radialDistance.div(resolvedProfile.base.nearDetailDistance),
@@ -1320,16 +1477,24 @@ export function createToonRockMaterial({
   );
 
   if (resolvedProfile.base.striping.enabled) {
-    const stripeProjected = toonLabSideProjection(
-      textures.stripe,
-      resolvedProfile.base.striping.scale,
-      resolvedProfile.base.projectionContrast,
-      {
-        negativeScale: false,
-        clampResult: false,
-        coordinates: resolvedProfile.coordinates,
-      },
-    );
+    const stripeProjected = resolvedProfile.base.mode === 'directional-bedding'
+      ? toonLabDirectionalBeddingColor(
+        textures.stripe,
+        resolvedProfile.base.striping.scale,
+        resolvedProfile.base.projectionContrast,
+        resolvedProfile.coordinates,
+        resolvedProfile.base.upAxis,
+      )
+      : toonLabSideProjection(
+        textures.stripe,
+        resolvedProfile.base.striping.scale,
+        resolvedProfile.base.projectionContrast,
+        {
+          negativeScale: false,
+          clampResult: false,
+          coordinates: resolvedProfile.coordinates,
+        },
+      );
     const stripeOpacity = clamp(
       toonLabContrast(stripeProjected.r, resolvedProfile.base.striping.contrast),
       0,
@@ -1811,16 +1976,28 @@ export function createToonRockMaterial({
     : vec3(0, 0, 1);
   let combinedNormal = stylizedNormal;
   if (textures.rockNormal) {
-    const crackNormal = toonLabTriplanarNormal(
-      textures.rockNormal,
-      resolvedProfile.base.scale,
-      resolvedProfile.base.projectionContrast,
-      normalGreenSignForTexture(
+    const crackNormal = resolvedProfile.base.mode === 'directional-bedding'
+      ? toonLabDirectionalBeddingNormal(
         textures.rockNormal,
-        resolvedProfile.normals.normalGreenSign,
-      ),
-      resolvedProfile.coordinates,
-    );
+        resolvedProfile.base.scale,
+        resolvedProfile.base.projectionContrast,
+        normalGreenSignForTexture(
+          textures.rockNormal,
+          resolvedProfile.normals.normalGreenSign,
+        ),
+        resolvedProfile.coordinates,
+        resolvedProfile.base.upAxis,
+      )
+      : toonLabTriplanarNormal(
+        textures.rockNormal,
+        resolvedProfile.base.scale,
+        resolvedProfile.base.projectionContrast,
+        normalGreenSignForTexture(
+          textures.rockNormal,
+          resolvedProfile.normals.normalGreenSign,
+        ),
+        resolvedProfile.coordinates,
+      );
     const normalFade = clamp(
       radialDistance.div(Math.max(
         resolvedProfile.normals.distance * authoredDistanceScale,

package/src/rock-shader/rockShaderRuntime.js

@@ -226,6 +226,8 @@ export function rockShaderSettingsToProfile(input = {}) {
 
   return normalizeToonLabRockProfile({
     base: {
+      mode: projection.mode,
+      upAxis: projection.upAxis,
       scale: projection.scale,
       projectionContrast: projection.projectionContrast,
       sideOnly: projection.sideOnly,
@@ -373,6 +375,11 @@ function createMaterialForSource({
     materialProfile.shoreline = structuredClone(profile.shoreline);
     materialProfile.base = {
       ...materialProfile.base,
+      // Projection choice belongs to the edited C8 surface package/runtime
+      // binding, not to a shared semantic material set. These strings select
+      // a CPU-authored TSL graph; they are deliberately not shader uniforms.
+      mode: profile.base.mode,
+      upAxis: profile.base.upAxis,
       closeTintDistance: profile.base.closeTintDistance,
       distantTint: profile.base.distantTint,
       distantTintMix: profile.base.distantTintMix,
@@ -529,6 +536,12 @@ function createMaterialForSource({
     },
     sourceTextureCount: rockMaterial.userData.toonlabSourceTextureIds.length,
   };
+  rockMaterial.userData.toonlabRockProjectionContract = {
+    mapRoles: ['BaseColor', 'NearDetail', 'Smoothness', 'NormalGL', 'AO'],
+    mode: materialProfile.base.mode,
+    sideOnly: materialProfile.base.sideOnly,
+    upAxis: materialProfile.base.upAxis,
+  };
   if (semantic) {
     rockMaterial.userData.toonLabRockTextureComposition.materialSetId = semantic.materialSetId;
     rockMaterial.userData.toonLabRockTextureComposition.surfaceState = surfaceState;
@@ -560,8 +573,11 @@ function createMaterialForSource({
         : materialProfile.layers?.[activeLayer]?.roughness ?? null,
     };
     rockMaterial.userData.toonlabRockProjectionContract = {
+      ...rockMaterial.userData.toonlabRockProjectionContract,
       normalBlend: 'whiteout-world-to-tangent',
-      primary: 'world-space-triplanar',
+      primary: materialProfile.base.mode === 'directional-bedding'
+        ? 'world-space-directional-bedding'
+        : 'world-space-triplanar',
       scaleCompensation: 'absolute-world-position',
       texelDensityInvariantUnderNonUniformScale: true,
     };

package/src/rock-shader/rockShaderSettings.js

@@ -34,6 +34,20 @@ const GROUP_DEFINITIONS = Object.freeze({
     description: 'World-space base projection and graphic texture treatment.',
     label: 'Base Projection',
     fields: Object.freeze({
+      mode: field({
+        defaultValue: 'triplanar',
+        description: 'Compile-time texture graph: ordinary three-axis projection or coherent bedding that excludes the top-axis structural sample.',
+        label: 'Projection Mode',
+        options: ['triplanar', 'directional-bedding'],
+        type: 'select',
+      }),
+      upAxis: field({
+        defaultValue: 'y',
+        description: 'World-space geological up axis used by directional bedding.',
+        label: 'Bedding Up Axis',
+        options: ['x', 'y', 'z'],
+        type: 'select',
+      }),
       scale: field({
         defaultValue: 1.6,
         description: 'World-space size of the projected rock texture in meters.',
@@ -792,6 +806,8 @@ export const DEFAULT_ROCK_SHADER_SETTINGS = Object.freeze(Object.fromEntries(
 // visible, serializable, and independent from any preview fixture.
 export const CALL_ME_SENSEI_ROCK_SHADER_SETTINGS = Object.freeze({
   projection: Object.freeze({
+    mode: 'triplanar',
+    upAxis: 'y',
     scale: 48,
     // Geological maps already own lithology color and value structure. The
     // previous 0.72 saturation/contrast pair washed every family toward the

package/src/rockgen/index.js

@@ -14,3 +14,12 @@ export * from './mesh/meshDocument.js';
 export * from './lod/index.js';
 export * from './export/glbExport.js';
 export * from './surface/c7GeologySurface.js';
+
+// Public names for the realistic material library; stored schema IDs stay compatible.
+export {
+  C8_FIRST12_LITHOLOGY_PROFILES as NATURAL_ROCK_SURFACE_PROFILES,
+  C8_FIRST12_MAP_ROLES as NATURAL_ROCK_MAP_ROLES,
+  createC8First12GeologyMapData as createNaturalRockMapData,
+  createC8First12SurfaceSpecification as createNaturalRockSurfaceSpecification,
+  resolveC8First12Projection as resolveNaturalRockProjection,
+} from './surface/naturalRockSurface.js';

package/src/rockgen/lod/index.js

@@ -1,4 +1,5 @@
 export * from './rockLodMetrics.js';
+export * from './rockDenseFieldPolicy.js';
 export * from './rockLodPlanner.js';
 export * from './rockLodPolicy.js';
 export * from './rockLodRuntime.js';

package/src/rockgen/lod/rockDenseFieldPolicy.js

@@ -0,0 +1,143 @@
+import {
+  collectCatalogLodBindings,
+  createCatalogLodRuntime,
+} from '../../catalog/officialCatalogLod.js';
+
+export const DENSE_FIELD_ROCK_LOD_LEVELS = Object.freeze([
+  Object.freeze({ id: 'LOD0', level: 0, purpose: 'hero-close' }),
+  Object.freeze({ id: 'LOD1', level: 1, purpose: 'near-gameplay' }),
+  Object.freeze({ id: 'LOD2', level: 2, purpose: 'mid-gameplay' }),
+  Object.freeze({ id: 'LOD3', level: 3, purpose: 'far-simplified' }),
+  Object.freeze({ id: 'LOD4', level: 4, purpose: 'very-far-silhouette' }),
+]);
+
+export const DENSE_FIELD_ROCK_PIXEL_THRESHOLDS = Object.freeze([240, 110, 48, 16, 6]);
+export const DENSE_FIELD_ROCK_CULL_BELOW_PIXELS = 5;
+
+export const DENSE_FIELD_ROCK_TRIANGLE_CEILINGS = Object.freeze({
+  ordinary: Object.freeze({ LOD3: 1200, LOD4: 350 }),
+  formation: Object.freeze({ LOD3: 1800, LOD4: 600 }),
+  landmark: Object.freeze({ LOD3: 2500, LOD4: 800 }),
+});
+
+export const DENSE_FIELD_ROCK_PRODUCTION_RULE = Object.freeze({
+  cullBelowPixels: DENSE_FIELD_ROCK_CULL_BELOW_PIXELS,
+  farShadowLastLevel: 2,
+  levelCount: 5,
+  levels: DENSE_FIELD_ROCK_LOD_LEVELS,
+  pixelThresholds: DENSE_FIELD_ROCK_PIXEL_THRESHOLDS,
+  selectionBasis: 'projected-object-diameter-pixels',
+  triangleCeilings: DENSE_FIELD_ROCK_TRIANGLE_CEILINGS,
+  veryFar: Object.freeze({
+    allowedSurfaceChannels: Object.freeze(['baseColor', 'broadLighting']),
+    castShadow: false,
+    preserve: Object.freeze(['outerSilhouette', 'primaryMass', 'groundContact', 'broadBaseColor']),
+    remove: Object.freeze([
+      'cracks',
+      'strataRelief',
+      'cavities',
+      'secondaryLedges',
+      'normalMap',
+      'heightMap',
+      'aoMap',
+      'uniqueRoughness',
+    ]),
+    silhouetteOnly: true,
+  }),
+});
+
+export function inferDenseFieldRockClass({ scaleClass = null, targetHeightMetres = null } = {}) {
+  const named = String(scaleClass ?? '').trim().toLowerCase();
+  if (named === 'landmark' || named === 'hero' || named === 'backdrop') return 'landmark';
+  if (named === 'formation' || named === 'outcrop' || named === 'cliff') return 'formation';
+  if (named === 'ordinary' || named === 'boulder' || named === 'debris') return 'ordinary';
+  const height = Number(targetHeightMetres);
+  if (Number.isFinite(height) && height > 6) return 'landmark';
+  if (Number.isFinite(height) && height > 2) return 'formation';
+  return 'ordinary';
+}
+
+export function validateDenseFieldRockLodTargets(targets, {
+  assetClass = 'ordinary',
+} = {}) {
+  const classification = Object.hasOwn(DENSE_FIELD_ROCK_TRIANGLE_CEILINGS, assetClass)
+    ? assetClass
+    : 'ordinary';
+  const ceilings = DENSE_FIELD_ROCK_TRIANGLE_CEILINGS[classification];
+  const values = DENSE_FIELD_ROCK_LOD_LEVELS.map(({ id }) => Number(targets?.[id]));
+  const errors = [];
+  values.forEach((value, level) => {
+    if (!Number.isInteger(value) || value <= 0) {
+      errors.push(`${DENSE_FIELD_ROCK_LOD_LEVELS[level].id} must be a positive integer`);
+    }
+  });
+  for (let level = 1; level < values.length; level += 1) {
+    if (Number.isFinite(values[level]) && Number.isFinite(values[level - 1])
+      && values[level] >= values[level - 1]) {
+      errors.push(`LOD${level} must contain fewer triangles than LOD${level - 1}`);
+    }
+  }
+  if (Number.isFinite(values[3]) && values[3] > ceilings.LOD3) {
+    errors.push(`LOD3 exceeds the ${classification} ${ceilings.LOD3}-triangle ceiling`);
+  }
+  if (Number.isFinite(values[4]) && values[4] > ceilings.LOD4) {
+    errors.push(`LOD4 exceeds the ${classification} ${ceilings.LOD4}-triangle ceiling`);
+  }
+  return Object.freeze({
+    assetClass: classification,
+    ceilings,
+    errors: Object.freeze(errors),
+    valid: errors.length === 0,
+    values: Object.freeze(values),
+  });
+}
+
+/**
+ * Install the mandatory dense-field rock behavior on an authored LOD0-LOD4
+ * root. The final tier is geometry-only silhouette support; it never casts a
+ * shadow and the root is culled once its projected diameter drops below the
+ * production pixel threshold.
+ */
+export function createDenseFieldRockLodRuntime(root, {
+  cullBelowPixels = DENSE_FIELD_ROCK_CULL_BELOW_PIXELS,
+  hysteresis = 0.12,
+  maxLevel = Number.POSITIVE_INFINITY,
+  pixelThresholds = DENSE_FIELD_ROCK_PIXEL_THRESHOLDS,
+  referenceDiameter = null,
+  requireComplete = true,
+} = {}) {
+  const bindings = collectCatalogLodBindings(root);
+  const levels = [...new Set(bindings.map(({ level }) => level))].sort((a, b) => a - b);
+  const missing = DENSE_FIELD_ROCK_LOD_LEVELS
+    .map(({ level }) => level)
+    .filter((level) => !levels.includes(level));
+  if (requireComplete && missing.length > 0) {
+    throw new Error(`Dense-field rock is missing required visual tiers: ${missing.map((level) => `LOD${level}`).join(', ')}`);
+  }
+
+  const originalShadows = new Map(bindings.map(({ mesh }) => [mesh, mesh.castShadow]));
+  for (const { level, mesh } of bindings) {
+    if (level > DENSE_FIELD_ROCK_PRODUCTION_RULE.farShadowLastLevel) mesh.castShadow = false;
+    mesh.userData.toonlabDenseFieldRock = Object.freeze({
+      castShadow: mesh.castShadow,
+      silhouetteOnly: level === 4,
+      visualLevel: level,
+    });
+  }
+
+  const runtime = createCatalogLodRuntime(root, {
+    cullBelowPixels,
+    hysteresis,
+    maxLevel,
+    pixelThresholds,
+    referenceDiameter,
+  });
+  return Object.freeze({
+    ...runtime,
+    policy: DENSE_FIELD_ROCK_PRODUCTION_RULE,
+    dispose() {
+      runtime.dispose();
+      for (const [mesh, castShadow] of originalShadows) mesh.castShadow = castShadow;
+    },
+  });
+}