@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/docs/characters.md

@@ -0,0 +1,144 @@
+# Characters and animation
+
+Bring-your-own-model is a first-class feature: any humanoid character in a
+common format gets loaded, toon-shaded, and animated — without code changes
+in the labs, with rig helpers in `@call-me-sensei/toonlab/character` and optional loader
+helpers in `@call-me-sensei/toonlab/loaders` for your own app.
+
+## Loading models
+
+```js
+import { loadModelAsset, SUPPORTED_MODEL_FORMATS } from '@call-me-sensei/toonlab/loaders';
+
+const asset = await loadModelAsset('models/hero.vrm');
+// asset: { root, clips, format, url, resourcePath, vrm? }
+scene.add(asset.root);
+```
+
+(Inside this repo the labs import from `../../src/character/...`.)
+
+Supported formats (`SUPPORTED_MODEL_FORMATS`): `pmx`, `pmd`, `fbx`, `glb`,
+`gltf`, `vrm` (0 and 1), `obj` (pass `materialUrl` for the MTL), and
+text-based `usdz`. VRM models are detected automatically on glTF load,
+rotated to the +Z convention, and returned with the `vrm` instance.
+
+Draco or KTX2-compressed glTF assets need an explicit decoder directory:
+
+```js
+await loadModelAsset('models/compressed.glb', {
+  decoderBasePath: '/vendor/three-decoders/',
+  renderer,
+});
+```
+
+In the labs, use the HUD **Model URL** input or `?model=` — local paths and
+hosted URLs both work (hosted URLs need CORS headers on the server; load
+failures surface in a HUD banner). Private test models go in the gitignored
+`assets-local/models/` drop-in folder: after `npm run assets:local` they
+surface in every model-aware lab's Model select, no code changes. See
+[getting-started.md](getting-started.md#loading-your-own-models) for the
+folder shapes the scanner recognizes.
+
+## Bone-role adapters (`characterRig`)
+
+Animation is rig-agnostic because bone *names* are resolved to canonical
+humanoid *roles* (VRM humanoid naming, `HUMANOID_ROLES`) once, up front:
+
+```js
+import { resolveCharacterRig, targetBoneNameForRole } from '@call-me-sensei/toonlab/character';
+
+const rig = resolveCharacterRig(skinnedMesh, { vrm: asset.vrm });
+// rig: { type, targetToMixamo, mixamoToTarget, hipCarrierName } — or null
+targetBoneNameForRole(rig, 'head'); // the model's actual head bone name
+```
+
+`resolveCharacterRig` tries each convention adapter in order:
+
+1. **VRM** — the humanoid bone map from the VRM extension (spec'd, exact).
+2. **MMD/PMX** — Japanese bone names (`頭`, `下半身`, ...), including the
+   center-bone hip carrier.
+3. **Mixamo-named** — skeletons already using `mixamorig` names (normalized
+   for the common prefix variants).
+4. **Rigify** — Blender Rigify `DEF-` deform bones, matched loosely
+   (heuristic name matching handles export renaming).
+
+If no adapter matches, retargeting is impossible and models fall back to
+their embedded clips. Everything downstream (retargeting, the procedural
+swim clip, head tracking) works through roles, so a new rig convention is
+one name table, not a new pipeline.
+
+## Native-clip fast path
+
+Models that ship their own locomotion clips skip retargeting entirely. A
+model qualifies when at least idle + walk resolve against these clip-name
+conventions (`NATIVE_LOCOMOTION_CLIP_NAMES` in
+`labs/playground/animationPipeline.js`; first match per role wins):
+
+| Role | Accepted clip names |
+|---|---|
+| idle | `Idle_Loop`, `Idle` |
+| walk | `Walk_Loop`, `Walking`, `Walk` |
+| run | `Sprint_Loop`, `Jog_Fwd_Loop`, `Running`, `Run` |
+| jump | `Jump_Start`, `Jump_Loop`, `Jump` |
+| swim | `Swim_Fwd_Loop`, `Swimming`, `Swim` |
+| tread | `Swim_Idle_Loop`, `Treading_Water`, `TreadingWater` |
+
+The bundled CC0 mannequin (Quaternius Universal Animation Library, 45
+embedded clips) qualifies out of the box — that is why a fresh clone
+animates with zero downloads. Author your own GLBs to these names and they
+play natively too.
+
+## Mixamo retarget pipeline
+
+For models without native clips, the Playground retargets Mixamo FBX clips
+onto the resolved rig with a world-space bake: only the role mapping comes
+from `characterRig`; rest-pose differences (T-pose vs. A-pose) and hierarchy
+mismatches are solved numerically. This is how a PMX character, a VRM
+avatar, and a Rigify export all play the same `Walking.fbx`.
+
+Adobe's terms do not permit redistributing Mixamo clips, so the repo ships
+none. Download clips with your own Adobe account from
+[mixamo.com](https://www.mixamo.com) and drop them into
+`assets-local/animations/` (`Idle.fbx`, `Walking.fbx`, `Running.fbx`,
+`Jump.fbx`, `Swimming.fbx`, `Treading_Water.fbx`, ...). Override individual
+clips per URL: `?swimAnim=`, `?treadAnim=`, `?diveAnim=`, `?anim=`. See
+[ATTRIBUTION.md](../ATTRIBUTION.md).
+
+When a swim/tread retarget source is missing, the pipeline falls back to the
+model's native swim clips if it has them.
+
+## Procedural freestyle swim
+
+`createFreestyleSwimClip(targetMesh, rig, options)` generates a freestyle
+(front crawl) swim clip with no FBX source: windmilling catch-up arm
+strokes, flutter kick, body roll, and a breath every fourth stroke. Motion
+is authored as world-space rotation deltas against the bind pose, so the
+same code bakes onto any supported skeleton (VRM, MMD, Mixamo-named,
+Rigify).
+
+```js
+import { createFreestyleSwimClip } from '@call-me-sensei/toonlab/character';
+
+// Skeleton must be in bind pose when you call this.
+const clip = createFreestyleSwimClip(targetMesh, rig, {
+  clipName: 'FreestyleSwim',
+  trackNameStyle: 'skeleton', // 'skeleton' for retarget-style mixers, 'node' for native-clip mixers
+});
+mixer.clipAction(clip).play();
+```
+
+The Playground uses it as the default swim style (`?freestyleAnim=none`
+disables it).
+
+## swimVisualLift
+
+Swim physics floats every model at the same capsule depth below the wave
+surface — the whole swim backend (vertical control, clamps, ray geometry,
+wave exposure) is tuned as a package around one value, and giving models
+different physics floats re-exposes tuning bugs. Models that need to *look*
+higher or lower in the water get `swimVisualLift`: a visual-only vertical
+offset applied to the model group while swimming, which the physics never
+sees. The compact mannequin uses `0.18` to read as surface freestyle; a
+character with tall hair volume needs none. Per-model values live in the
+lab's character options (`labs/shared/sceneHub.js`); override for testing
+with `?swimVisualLift=`.

package/docs/debug-panel.md

@@ -0,0 +1,126 @@
+# Debug panel
+
+`@call-me-sensei/toonlab/debug` is an optional, DOM-dependent tuning GUI: it turns any
+settings module's group/field schema into live controls. One call gives you
+the same panel the labs use — ship it behind a debug flag, or not at all
+(nothing else imports it).
+
+The labs now expose one TSL renderer stack: native WebGPU by default and
+`?renderer=webgl` for the WebGL2 fallback. The panel writes the same settings
+surface on both backends.
+
+## createSettingsPanel
+
+```js
+import { createSettingsPanel } from '@call-me-sensei/toonlab/debug';
+import { readFieldValueFromSettings } from '@call-me-sensei/toonlab/debug';
+import {
+  TOON_SETTING_GROUPS,
+  TOON_SETTING_FIELD_SCHEMA,
+  applyToonSettingsToMaterial,
+} from '@call-me-sensei/toonlab/toon';
+
+const panel = createSettingsPanel({
+  container: document.getElementById('toonSettingGroups'),
+  groups: TOON_SETTING_GROUPS,
+  fieldSchema: TOON_SETTING_FIELD_SCHEMA,
+  getValue: (field) => readFieldValueFromSettings(settings, field),
+  onChange: (field, value) => {
+    settings[field.group][field.key] = value;
+    applyToonSettingsToMaterial(characterRoot, settings);
+  },
+});
+
+panel.refresh(); // re-pull every control value via getValue (e.g. after a preset switch)
+```
+
+(Inside this repo the labs import from `../../src/debug/...`.)
+
+The panel renders one collapsible `<details>` group per schema group, with a
+typed control per field — checkbox for `boolean`, `<select>` for `select`
+(using the schema's `options`/`optionLabels`), color input for `color`,
+range slider for `number` (using the schema's `range`), text input
+otherwise — each with a label, tooltip description, and live `<output>`
+readout.
+
+The host owns the settings state: the panel only reads through `getValue`
+and reports edits through `onChange`. It never mutates settings itself,
+which is what makes it schema-generic.
+
+### Options
+
+Beyond the required five, `createSettingsPanel` accepts:
+
+- `fieldFilter(field)` — hide fields (e.g. non-serializable texture slots).
+- `isDisabled(field)` — gray controls out (re-evaluated on `refresh()`).
+- `formatValue(value, field)` — custom `<output>` formatting.
+- `isGroupOpen(group)` — which groups start expanded.
+- `prepend` — DOM nodes to insert before the groups (preset pickers, etc.).
+- `dataAttribute`, `idPrefix`, `rowClassName`, `groupClassName`,
+  `fieldsClassName` — styling/data hooks.
+
+### It works with every schema
+
+Any module following the groups + field-schema convention plugs in — this is
+the full list (see the generated
+[settings reference](settings-reference.md) for their contents):
+
+| Module | groups / fieldSchema |
+|---|---|
+| `@call-me-sensei/toonlab/toon` | `TOON_SETTING_GROUPS` / `TOON_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/environment` | `ENVIRONMENT_SETTING_GROUPS` / `ENVIRONMENT_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/water` | `WATER_SETTING_GROUPS` / `WATER_SETTING_FIELD_SCHEMA_BY_GROUP` |
+| `@call-me-sensei/toonlab/post` | `POST_PROCESSING_SETTING_GROUPS` / `POST_PROCESSING_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (grass) | `GRASS_SETTING_GROUPS` / `GRASS_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (flowers) | `FLOWER_SETTING_GROUPS` / `FLOWER_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (trees) | `STYLIZED_TREE_SETTING_GROUPS` / `STYLIZED_TREE_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/sky` | `SKY_SETTING_GROUPS` / `SKY_SETTING_FIELD_SCHEMA` |
+
+Note the value-read difference: toon/environment/post/tree settings are
+nested (`settings[field.group][field.key]`), water/grass/flower/sky settings
+are flat (`settings[field.key]`). `readFieldValueFromSettings` handles the
+nested case; for flat settings pass
+`getValue: (field) => settings[field.key]`.
+
+## createSelectRow
+
+A plain labeled `<select>` row for the controls that live alongside the
+schema-generated groups (preset pickers, debug-view selectors):
+
+```js
+import { createSelectRow } from '@call-me-sensei/toonlab/debug';
+
+const row = createSelectRow({
+  id: 'toonPreset',
+  label: 'Preset',
+  options: getToonPresetOptions().map((p) => ({ value: p.id, label: p.label })),
+  value: currentPreset,
+  onChange: (value) => setLabParams({ toonPreset: value }),
+});
+panelHeader.append(row);
+```
+
+## Field value helpers (`fieldValues.js`)
+
+The coercion layer between schema-typed values and DOM control values, used
+by the panel and exported for custom UIs:
+
+- `readFieldValueFromSettings(settings, field)` — nested group/key read.
+- `readFieldValueFromControl(control, field)` — checkbox/range/color/select
+  → typed value (colors become `[r, g, b]` arrays, numbers parse, etc.).
+- `writeFieldControlValue(control, output, field, value)` — push a value
+  into a control and its `<output>`.
+- `formatFieldValue(value, field)` — display formatting.
+- `colorToHex(value)` / `hexToColorArray(value)` — `[r, g, b]` ↔ `#rrggbb`.
+- `vectorToArray(value)` — vector-ish → plain array.
+
+## How the labs use it
+
+Character Shader Lab and Environment Shader Lab consume their respective
+schemas independently. Each lab's panel is a thin consumer that wires
+`getValue`/`onChange` to its preset store and to
+`applyToonSettingsToMaterial` or `applyEnvironmentSettingsToMaterial` for
+live uniform-safe edits. Preset switching refreshes the controls from the
+normalized package settings. The same schema-consumer pattern drives Water,
+Sky, Grass, Tree, and Flower Labs; no lab keeps a private copy of its runtime
+parameter contract.