@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/motion/motionSettings.js

@@ -0,0 +1,222 @@
+// Runtime-safe motion style settings. These settings deliberately describe
+// playback and presentation, not a catalog of animations: behavior topology
+// and clip-slot bindings live in separate serializable documents.
+
+export const MOTION_CADENCE_MODES = Object.freeze(['smooth', 'stepped']);
+export const MOTION_ROOT_POLICIES = Object.freeze(['ignore', 'inPlace', 'extract', 'apply']);
+export const MOTION_EASING_MODES = Object.freeze(['linear', 'smoothstep', 'easeInOutCubic']);
+
+export const DEFAULT_MOTION_SETTINGS = Object.freeze({
+  playback: Object.freeze({
+    cadence: 'smooth',
+    sampleRate: 24,
+    speed: 1,
+    maxDelta: 0.1,
+  }),
+  transitions: Object.freeze({
+    duration: 0.18,
+    easing: 'smoothstep',
+    allowInterrupt: true,
+    syncPhase: true,
+  }),
+  lean: Object.freeze({
+    enabled: true,
+    maxAngle: 0.2,
+    response: 10,
+    turnParameter: 'turn',
+    forwardParameter: 'speed',
+  }),
+  bob: Object.freeze({
+    enabled: true,
+    amplitude: 0.035,
+    frequency: 1.8,
+    lateral: 0.012,
+    speedParameter: 'speed',
+  }),
+  squash: Object.freeze({
+    enabled: true,
+    amount: 0.08,
+    response: 14,
+    verticalParameter: 'verticalSpeed',
+  }),
+  rootMotion: Object.freeze({
+    policy: 'inPlace',
+    axes: Object.freeze([true, false, true]),
+    scale: 1,
+    applyYaw: false,
+  }),
+  events: Object.freeze({
+    maxPerUpdate: 32,
+    fireOnLoop: true,
+    minimumWeight: 0.05,
+  }),
+});
+
+export const MOTION_SETTING_GROUPS = Object.freeze([
+  Object.freeze({ id: 'playback', label: 'Playback', description: 'Global timing and frame cadence. Stepped cadence creates deliberately held animation frames without slowing simulation.' }),
+  Object.freeze({ id: 'transitions', label: 'Transitions', description: 'Default cross-fade behavior for graph edges that do not provide their own values.' }),
+  Object.freeze({ id: 'lean', label: 'Lean', description: 'Procedural directional lean driven by arbitrary named graph parameters.' }),
+  Object.freeze({ id: 'bob', label: 'Bob', description: 'A subtle locomotion presentation layer applied after clip and graph blending.' }),
+  Object.freeze({ id: 'squash', label: 'Squash', description: 'Velocity-driven squash and stretch with volume-preserving horizontal compensation.' }),
+  Object.freeze({ id: 'rootMotion', label: 'Root Motion', description: 'Whether authored root travel is ignored, removed in place, extracted for gameplay, or applied through the rig adapter.' }),
+  Object.freeze({ id: 'events', label: 'Events', description: 'Per-frame safety limits and filtering for arbitrary clip event tracks.' }),
+]);
+
+const FIELDS = Object.freeze({
+  playback: Object.freeze({
+    cadence: { label: 'Cadence', type: 'select', options: MOTION_CADENCE_MODES },
+    sampleRate: { label: 'Held-frame rate', range: { min: 1, max: 120, step: 1 } },
+    speed: { label: 'Global speed', range: { min: 0, max: 4, step: 0.01 } },
+    maxDelta: { label: 'Maximum delta', range: { min: 0.016, max: 0.5, step: 0.001 } },
+  }),
+  transitions: Object.freeze({
+    duration: { label: 'Default duration', range: { min: 0, max: 2, step: 0.01 } },
+    easing: { label: 'Easing', type: 'select', options: MOTION_EASING_MODES },
+    allowInterrupt: { label: 'Allow interruption', type: 'boolean' },
+    syncPhase: { label: 'Synchronize phase', type: 'boolean' },
+  }),
+  lean: Object.freeze({
+    enabled: { label: 'Enabled', type: 'boolean' },
+    maxAngle: { label: 'Maximum angle', range: { min: 0, max: 0.8, step: 0.01 } },
+    response: { label: 'Response', range: { min: 0, max: 40, step: 0.1 } },
+    turnParameter: { label: 'Turn parameter', type: 'text' },
+    forwardParameter: { label: 'Forward parameter', type: 'text' },
+  }),
+  bob: Object.freeze({
+    enabled: { label: 'Enabled', type: 'boolean' },
+    amplitude: { label: 'Vertical amplitude', range: { min: 0, max: 0.4, step: 0.001 } },
+    frequency: { label: 'Frequency', range: { min: 0, max: 8, step: 0.01 } },
+    lateral: { label: 'Lateral amplitude', range: { min: 0, max: 0.25, step: 0.001 } },
+    speedParameter: { label: 'Speed parameter', type: 'text' },
+  }),
+  squash: Object.freeze({
+    enabled: { label: 'Enabled', type: 'boolean' },
+    amount: { label: 'Amount', range: { min: 0, max: 0.45, step: 0.001 } },
+    response: { label: 'Response', range: { min: 0, max: 40, step: 0.1 } },
+    verticalParameter: { label: 'Vertical parameter', type: 'text' },
+  }),
+  rootMotion: Object.freeze({
+    policy: { label: 'Policy', type: 'select', options: MOTION_ROOT_POLICIES },
+    axes: { label: 'Translation axes', type: 'boolean3' },
+    scale: { label: 'Scale', range: { min: 0, max: 8, step: 0.01 } },
+    applyYaw: { label: 'Apply yaw', type: 'boolean' },
+  }),
+  events: Object.freeze({
+    maxPerUpdate: { label: 'Maximum events/update', range: { min: 1, max: 512, step: 1 } },
+    fireOnLoop: { label: 'Fire across loops', type: 'boolean' },
+    minimumWeight: { label: 'Minimum blend weight', range: { min: 0, max: 1, step: 0.01 } },
+  }),
+});
+
+export const MOTION_SETTING_FIELD_SCHEMA = Object.freeze(Object.fromEntries(
+  MOTION_SETTING_GROUPS.map((group) => [group.id, Object.freeze(Object.fromEntries(
+    Object.entries(FIELDS[group.id]).map(([key, field]) => [key, Object.freeze({
+      ...field,
+      defaultValue: DEFAULT_MOTION_SETTINGS[group.id][key],
+      group: group.id,
+      id: `${group.id}.${key}`,
+      key,
+      type: field.type ?? 'number',
+    })]),
+  ))]),
+));
+
+const plain = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const finite = (value, fallback) => Number.isFinite(Number(value)) ? Number(value) : fallback;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const text = (value, fallback) => typeof value === 'string' && value.trim() ? value.trim() : fallback;
+
+function sourceGroup(options, id) {
+  return plain(options?.[id]) ? options[id] : {};
+}
+
+function boolean3(value, fallback) {
+  return Array.isArray(value) && value.length >= 3
+    ? value.slice(0, 3).map(Boolean)
+    : [...fallback];
+}
+
+/** Normalizes partial style settings into a complete mutable object. */
+export function createMotionSettings(options = {}) {
+  const p = sourceGroup(options, 'playback');
+  const t = sourceGroup(options, 'transitions');
+  const l = sourceGroup(options, 'lean');
+  const b = sourceGroup(options, 'bob');
+  const s = sourceGroup(options, 'squash');
+  const r = sourceGroup(options, 'rootMotion');
+  const e = sourceGroup(options, 'events');
+  const d = DEFAULT_MOTION_SETTINGS;
+  return {
+    playback: {
+      cadence: MOTION_CADENCE_MODES.includes(p.cadence) ? p.cadence : d.playback.cadence,
+      sampleRate: clamp(finite(p.sampleRate, d.playback.sampleRate), 1, 240),
+      speed: clamp(finite(p.speed, d.playback.speed), 0, 8),
+      maxDelta: clamp(finite(p.maxDelta, d.playback.maxDelta), 0.001, 1),
+    },
+    transitions: {
+      duration: clamp(finite(t.duration, d.transitions.duration), 0, 8),
+      easing: MOTION_EASING_MODES.includes(t.easing) ? t.easing : d.transitions.easing,
+      allowInterrupt: t.allowInterrupt === undefined ? d.transitions.allowInterrupt : Boolean(t.allowInterrupt),
+      syncPhase: t.syncPhase === undefined ? d.transitions.syncPhase : Boolean(t.syncPhase),
+    },
+    lean: {
+      enabled: l.enabled === undefined ? d.lean.enabled : Boolean(l.enabled),
+      maxAngle: clamp(finite(l.maxAngle, d.lean.maxAngle), 0, Math.PI / 2),
+      response: clamp(finite(l.response, d.lean.response), 0, 100),
+      turnParameter: text(l.turnParameter, d.lean.turnParameter),
+      forwardParameter: text(l.forwardParameter, d.lean.forwardParameter),
+    },
+    bob: {
+      enabled: b.enabled === undefined ? d.bob.enabled : Boolean(b.enabled),
+      amplitude: clamp(finite(b.amplitude, d.bob.amplitude), 0, 1),
+      frequency: clamp(finite(b.frequency, d.bob.frequency), 0, 20),
+      lateral: clamp(finite(b.lateral, d.bob.lateral), 0, 1),
+      speedParameter: text(b.speedParameter, d.bob.speedParameter),
+    },
+    squash: {
+      enabled: s.enabled === undefined ? d.squash.enabled : Boolean(s.enabled),
+      amount: clamp(finite(s.amount, d.squash.amount), 0, 0.8),
+      response: clamp(finite(s.response, d.squash.response), 0, 100),
+      verticalParameter: text(s.verticalParameter, d.squash.verticalParameter),
+    },
+    rootMotion: {
+      policy: MOTION_ROOT_POLICIES.includes(r.policy) ? r.policy : d.rootMotion.policy,
+      axes: boolean3(r.axes, d.rootMotion.axes),
+      scale: clamp(finite(r.scale, d.rootMotion.scale), 0, 20),
+      applyYaw: r.applyYaw === undefined ? d.rootMotion.applyYaw : Boolean(r.applyYaw),
+    },
+    events: {
+      maxPerUpdate: Math.round(clamp(finite(e.maxPerUpdate, d.events.maxPerUpdate), 1, 2048)),
+      fireOnLoop: e.fireOnLoop === undefined ? d.events.fireOnLoop : Boolean(e.fireOnLoop),
+      minimumWeight: clamp(finite(e.minimumWeight, d.events.minimumWeight), 0, 1),
+    },
+  };
+}
+
+/** Deep-merges grouped overrides and re-normalizes them. */
+export function mergeMotionSettings(base = {}, overrides = {}) {
+  const current = createMotionSettings(base);
+  return createMotionSettings(Object.fromEntries(
+    MOTION_SETTING_GROUPS.map(({ id }) => [id, {
+      ...current[id],
+      ...(plain(overrides?.[id]) ? overrides[id] : {}),
+    }]),
+  ));
+}
+
+export function interpolateMotionSettings(from, to, amount) {
+  const a = createMotionSettings(from);
+  const b = createMotionSettings(to);
+  const t = clamp(finite(amount, 0), 0, 1);
+  const output = {};
+  for (const { id } of MOTION_SETTING_GROUPS) {
+    output[id] = {};
+    for (const key of Object.keys(a[id])) {
+      const av = a[id][key];
+      const bv = b[id][key];
+      if (typeof av === 'number' && typeof bv === 'number') output[id][key] = av + (bv - av) * t;
+      else output[id][key] = t < 0.5 ? av : bv;
+    }
+  }
+  return createMotionSettings(output);
+}

package/src/pathgen/index.js

@@ -0,0 +1,7 @@
+export * from './pathSettings.js';
+export * from './pathRouter.js';
+export * from './pathRibbon.js';
+export * from './pathBridge.js';
+export * from './pathTextures.js';
+export * from './pathPresets.js';
+export * from './stylizedPaths.js';

package/src/pathgen/pathBridge.js

@@ -0,0 +1,232 @@
+// Parametric plank bridges for water crossings. Generated like a debrisgen
+// piece: deterministic, vertex-colored wood, one merged geometry per bridge
+// (a single draw call each), rails registered as collision circles so a
+// character crosses the deck and never strolls off the side.
+
+import * as THREE from 'three';
+
+import { hashCombine } from '../rockgen/noise/prng.js';
+import { valueNoise3 } from '../rockgen/noise/valueNoise3.js';
+import { mergePathGeometries } from './pathRibbon.js';
+
+const WOOD = Object.freeze({
+  dark: Object.freeze([0.3, 0.2, 0.12]),
+  base: Object.freeze([0.44, 0.3, 0.18]),
+  light: Object.freeze([0.56, 0.4, 0.24]),
+});
+
+function paintBox(geometry, rgb, shade) {
+  const count = geometry.attributes.position.count;
+  const colors = new Float32Array(count * 3);
+  for (let index = 0; index < count; index += 1) {
+    colors[index * 3] = Math.min(rgb[0] * shade, 1);
+    colors[index * 3 + 1] = Math.min(rgb[1] * shade, 1);
+    colors[index * 3 + 2] = Math.min(rgb[2] * shade, 1);
+  }
+  geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+  return geometry;
+}
+
+/**
+ * Builds one bridge over a crossing (bank sample to bank sample).
+ *
+ * @param {Object} options
+ * @param {Array} options.samples Route samples (from buildRouteProfile).
+ * @param {{startIndex: number, endIndex: number, span: number}} options.crossing
+ * @param {Object} options.settings Path settings (bridge group used).
+ * @param {Function} [options.heightAt] Bed sampler for pier depth.
+ * @param {number} [options.waterLevel]
+ * @param {number} [options.seed]
+ * @returns {{ geometry: THREE.BufferGeometry, blockers: Array<{x,z,radius}>,
+ *   deckWidth: number, span: number }}
+ */
+export function buildBridge({
+  samples,
+  crossing,
+  settings,
+  heightAt = null,
+  waterLevel = 0,
+  seed = 1,
+}) {
+  const { bridge } = settings;
+  const deck = samples.slice(crossing.startIndex, crossing.endIndex + 1);
+  const span = crossing.span;
+  const halfWidth = deck[0].half + 0.12;
+  const random = (value, salt = 0) => valueNoise3(hashCombine(seed, 419 + salt), value * 5.13, 0.3, 0.7);
+
+  const geometries = [];
+  const unitBox = new THREE.BoxGeometry(1, 1, 1);
+  const matrix = new THREE.Matrix4();
+  const quaternion = new THREE.Quaternion();
+  const scale = new THREE.Vector3();
+  const position = new THREE.Vector3();
+  const euler = new THREE.Euler();
+
+  // Deck position/heading at arclength t along the crossing.
+  const atLength = (target) => {
+    let index = 0;
+    while (index < deck.length - 2 && deck[index + 1].s - deck[0].s < target) index += 1;
+    const a = deck[index];
+    const b = deck[Math.min(index + 1, deck.length - 1)];
+    const t = (target - (a.s - deck[0].s)) / Math.max(b.s - a.s, 1e-6);
+    const clamped = Math.min(Math.max(t, 0), 1);
+    return {
+      heading: Math.atan2(b.x - a.x, b.z - a.z),
+      pitch: Math.atan2(b.profile - a.profile, Math.max(b.s - a.s, 1e-6)),
+      sideX: a.sideX + (b.sideX - a.sideX) * clamped,
+      sideZ: a.sideZ + (b.sideZ - a.sideZ) * clamped,
+      x: a.x + (b.x - a.x) * clamped,
+      y: a.profile + (b.profile - a.profile) * clamped,
+      z: a.z + (b.z - a.z) * clamped,
+    };
+  };
+
+  const addBox = (rgb, shade, px, py, pz, sx, sy, sz, yaw, pitch = 0) => {
+    const geometry = unitBox.clone();
+    euler.set(pitch, yaw, 0, 'YXZ');
+    quaternion.setFromEuler(euler);
+    position.set(px, py, pz);
+    scale.set(sx, sy, sz);
+    matrix.compose(position, quaternion, scale);
+    geometry.applyMatrix4(matrix);
+    paintBox(geometry, rgb, shade);
+    geometries.push(geometry);
+  };
+
+  // Planks across the walking direction, following the arc.
+  const plankPitchGap = 0.42;
+  const plankCount = Math.max(Math.round(span / plankPitchGap), 3);
+  for (let index = 0; index < plankCount; index += 1) {
+    const along = (index + 0.5) * (span / plankCount);
+    const at = atLength(along);
+    addBox(
+      WOOD.base, 0.9 + random(index) * 0.18,
+      at.x, at.y + 0.045, at.z,
+      halfWidth * 2, 0.09, span / plankCount * 0.82,
+      at.heading, -at.pitch,
+    );
+  }
+
+  // Two stringer beams under the planks, segment per deck sample pair.
+  for (let index = 0; index < deck.length - 1; index += 1) {
+    const a = deck[index];
+    const b = deck[index + 1];
+    const length = Math.hypot(b.x - a.x, b.z - a.z, b.profile - a.profile);
+    const heading = Math.atan2(b.x - a.x, b.z - a.z);
+    const pitch = Math.atan2(b.profile - a.profile, Math.hypot(b.x - a.x, b.z - a.z));
+    for (const side of [-1, 1]) {
+      const offset = halfWidth * 0.56 * side;
+      addBox(
+        WOOD.dark, 0.9,
+        (a.x + b.x) / 2 + a.sideX * offset,
+        (a.profile + b.profile) / 2 - 0.09,
+        (a.z + b.z) / 2 + a.sideZ * offset,
+        0.14, 0.16, length + 0.05,
+        heading, -pitch,
+      );
+    }
+  }
+
+  // Rails: posts + top rail (and a mid beam for the 'beams' style).
+  const blockers = [];
+  if (bridge.railStyle !== 'none') {
+    const postCount = Math.max(Math.round(span / bridge.postSpacing), 2);
+    const railHeight = 0.98;
+    for (const side of [-1, 1]) {
+      const posts = [];
+      for (let index = 0; index <= postCount; index += 1) {
+        const along = index * (span / postCount);
+        const at = atLength(along);
+        const px = at.x + at.sideX * (halfWidth - 0.05) * side;
+        const pz = at.z + at.sideZ * (halfWidth - 0.05) * side;
+        addBox(
+          WOOD.dark, 0.86 + random(index, side + 2) * 0.14,
+          px, at.y + railHeight / 2, pz,
+          0.11, railHeight, 0.11,
+          at.heading,
+        );
+        posts.push({ x: px, y: at.y, z: pz });
+      }
+      for (let index = 0; index < posts.length - 1; index += 1) {
+        const a = posts[index];
+        const b = posts[index + 1];
+        const length = Math.hypot(b.x - a.x, b.z - a.z, b.y - a.y);
+        const heading = Math.atan2(b.x - a.x, b.z - a.z);
+        const pitch = Math.atan2(b.y - a.y, Math.hypot(b.x - a.x, b.z - a.z));
+        addBox(
+          WOOD.light, 0.95,
+          (a.x + b.x) / 2, (a.y + b.y) / 2 + railHeight - 0.06, (a.z + b.z) / 2,
+          0.09, 0.09, length + 0.06,
+          heading, -pitch,
+        );
+        if (bridge.railStyle === 'beams') {
+          addBox(
+            WOOD.base, 0.92,
+            (a.x + b.x) / 2, (a.y + b.y) / 2 + railHeight * 0.5, (a.z + b.z) / 2,
+            0.07, 0.07, length + 0.06,
+            heading, -pitch,
+          );
+        }
+      }
+      // Collision: a fence of circles along the rail line keeps the
+      // character on the deck without blocking the deck itself.
+      const blockerSpacing = 0.7;
+      const blockerCount = Math.max(Math.round(span / blockerSpacing), 2);
+      for (let index = 0; index <= blockerCount; index += 1) {
+        const at = atLength(index * (span / blockerCount));
+        blockers.push({
+          radius: 0.3,
+          x: at.x + at.sideX * (halfWidth + 0.18) * side,
+          z: at.z + at.sideZ * (halfWidth + 0.18) * side,
+        });
+      }
+    }
+  }
+
+  // Abutments: a grounded block under each deck end, so the first planks
+  // never hover over the bank.
+  for (const endIndex of [0, deck.length - 1]) {
+    const at = deck[endIndex];
+    const bankY = typeof heightAt === 'function'
+      ? Number(heightAt(at.x, at.z)) || at.profile
+      : at.profile;
+    const top = at.profile + 0.02;
+    const bottom = Math.min(bankY, top) - 0.55;
+    addBox(
+      WOOD.dark, 0.85,
+      at.x, (top + bottom) / 2, at.z,
+      halfWidth * 2 - 0.06, top - bottom, 1.15,
+      Math.atan2(
+        deck[Math.min(endIndex + 1, deck.length - 1)].x - deck[Math.max(endIndex - 1, 0)].x,
+        deck[Math.min(endIndex + 1, deck.length - 1)].z - deck[Math.max(endIndex - 1, 0)].z,
+      ),
+    );
+  }
+
+  // Piers on long crossings: post pairs down to the bed.
+  if (span > bridge.pierSpacing * 1.4) {
+    const pierCount = Math.floor(span / bridge.pierSpacing);
+    const bed = typeof heightAt === 'function' ? heightAt : () => waterLevel - 2;
+    for (let index = 1; index <= pierCount; index += 1) {
+      const along = index * (span / (pierCount + 1));
+      const at = atLength(along);
+      for (const side of [-1, 1]) {
+        const px = at.x + at.sideX * halfWidth * 0.56 * side;
+        const pz = at.z + at.sideZ * halfWidth * 0.56 * side;
+        const bedY = Math.min(Number(bed(px, pz)) || waterLevel - 2, waterLevel - 0.2);
+        const top = at.y - 0.12;
+        addBox(
+          WOOD.dark, 0.82 + random(index, side + 7) * 0.1,
+          px, (top + bedY - 0.5) / 2, pz,
+          0.16, top - bedY + 0.5, 0.16,
+          at.heading,
+        );
+      }
+    }
+  }
+
+  unitBox.dispose();
+  const geometry = mergePathGeometries(geometries);
+  for (const piece of geometries) piece.dispose();
+  return { blockers, deckWidth: halfWidth * 2, geometry, span };
+}

package/src/pathgen/pathPresets.js

@@ -0,0 +1,35 @@
+// Built-in path network presets. Same convention as every cluster:
+// `default` is the neutral starting point, `call_me_sensei` is the
+// studio-managed look used across the reference worlds.
+
+import { createPathRecipeDocument } from './pathSettings.js';
+
+export const BUILT_IN_PATH_PRESETS = Object.freeze([
+  Object.freeze({
+    description: 'Neutral dirt trail network with plank bridges.',
+    id: 'default',
+    label: 'Default',
+    recipe: Object.freeze(createPathRecipeDocument({
+      auto: { count: 4, styles: ['dirt'] },
+      seed: 1,
+    })),
+  }),
+  Object.freeze({
+    description: 'The studio look: wandering dirt trails, a stone spine road, arched bridges with rails, stairs on the climbs.',
+    id: 'call_me_sensei',
+    label: 'Call Me Sensei',
+    recipe: Object.freeze(createPathRecipeDocument({
+      auto: { count: 5, styles: ['dirt', 'dirt', 'stone'] },
+      seed: 7,
+      settings: {
+        bridge: { arc: 0.11, railStyle: 'posts' },
+        ribbon: { edgeFade: 1.8, width: 2.8, widthWobble: 0.28 },
+        routing: { reuseBonus: 0.5, slopeCost: 30 },
+      },
+    })),
+  }),
+]);
+
+export function findPathPreset(id) {
+  return BUILT_IN_PATH_PRESETS.find((preset) => preset.id === id) ?? null;
+}