@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/character/src/customization.js

@@ -0,0 +1,464 @@
+// ============================================================================
+// Character customization — variant catalogs + selection resolution for
+// modular character kits.
+//
+// Kits like the builtin Aisha/Robin/Humanling packs ship every outfit, hair
+// style, beard, and accessory as sibling mesh nodes named `slot.NNN` (with
+// Blender `_ptN` splits folding into their canonical variant). The destructive
+// selectVariantMeshes/filterOptionalMeshes pipeline picks one variant per
+// group at load time; this module instead builds a catalog of every variant
+// and resolves a JSON-serializable CharacterCustomization into the mesh
+// subset to upload — the model-viewer's selectedPartIndices contract applied
+// to characters.
+//
+// Group classification:
+//   internal   — /collider/ meshes: never listed, never rendered.
+//   defaultOff — DEFAULT_OPTIONAL_MESH_PATTERNS (backpack, mask, vest,
+//                headgear/headwear/headphone, legpouch, *_acc): hidden by
+//                default (parity with filterOptionalMeshes) but equipable.
+//   required   — body groups (head/torso/leg(s)/feet/hand(s)/eye(s)): must
+//                always render a variant — "None" is not offered.
+//   optional   — everything else (hair, beard, facewear, …): defaults to the
+//                first variant, may be hidden or re-picked.
+// ============================================================================
+import { DEFAULT_OPTIONAL_MESH_PATTERNS } from "./loader.js";
+const DEFAULT_REQUIRED_SUFFIXES = [
+    "head", "torso", "leg", "legs", "feet", "foot", "hand", "hands", "eye", "eyes",
+];
+const DEFAULT_INTERNAL_PATTERNS = [/collider/i];
+/** Strip a Blender mesh-split `_ptN` suffix (shared with loader.selectVariantMeshes). */
+function variantPartKey(name) {
+    return name.replace(/_pt\d+$/i, "");
+}
+/** Strip the trailing `.NNN` / `_NNN` variant suffix (shared with loader). */
+function variantGroupKey(name) {
+    return variantPartKey(name).replace(/[._]\d+$/, "");
+}
+/** Group suffix used for required classification: "ash_torso" → "torso". */
+function groupSuffix(key) {
+    return key.replace(/^[a-z]+_/i, "").toLowerCase();
+}
+/** "ash_upperTorso" → "Upper Torso"; "rb_headwear" → "Headwear". */
+export function slotLabel(groupKey) {
+    const suffix = groupKey.replace(/^[a-z]+_/i, "");
+    return suffix
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/_/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** Short variant label for UI: "ash_torso.007" → "7"; unnumbered base → "Base". */
+export function variantLabel(variantKey) {
+    const m = /[._](\d+)$/.exec(variantKey);
+    return m ? String(parseInt(m[1], 10)) : "Base";
+}
+/**
+ * Build the variant catalog for a fully-loaded model (i.e. loaded WITHOUT the
+ * destructive filterOptionalMeshes/selectVariantMeshes passes).
+ */
+export function buildVariantCatalog(model, opts = {}) {
+    const requiredSuffixes = opts.requiredSuffixes ?? DEFAULT_REQUIRED_SUFFIXES;
+    const defaultOffPatterns = opts.defaultOffPatterns ?? DEFAULT_OPTIONAL_MESH_PATTERNS;
+    const internalPatterns = opts.internalPatterns ?? DEFAULT_INTERNAL_PATTERNS;
+    const requiredSet = opts.requiredGroups ? new Set(opts.requiredGroups) : null;
+    // Collect mesh-bearing nodes into groups, keyed by variantGroupKey.
+    // Within a group, variants are keyed by variantPartKey (canonical node name)
+    // so a variant split across `rb_headwear.005`, `.005_pt1`, `.005_pt2` nodes
+    // counts once and keeps every split mesh.
+    const groupMap = new Map();
+    const nodes = model.nodes ?? [];
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const idxs = [];
+        if (node.meshes) {
+            for (let _j = 0, _it = node.meshes, _m = _it.length; _j < _m; _j++) {
+                const mi = _it[_j];
+                if (mi < model.meshes.length)
+                    idxs.push(mi);
+            }
+        }
+        else if (node.mesh !== undefined && node.mesh < model.meshes.length) {
+            idxs.push(node.mesh);
+        }
+        if (idxs.length === 0)
+            continue;
+        const gkey = variantGroupKey(node.name);
+        const pkey = variantPartKey(node.name);
+        let g = groupMap.get(gkey);
+        if (!g) {
+            g = { key: gkey, parts: new Map() };
+            groupMap.set(gkey, g);
+        }
+        let part = g.parts.get(pkey);
+        if (!part) {
+            part = [];
+            g.parts.set(pkey, part);
+        }
+        for (let _j = 0, _n = idxs.length; _j < _n; _j++)
+            part.push(idxs[_j]);
+    }
+    const groups = [];
+    const byKey = new Map();
+    for (const g of groupMap.values()) {
+        const variants = [];
+        for (const [pkey, meshIndices] of g.parts.entries()) {
+            variants.push({ key: pkey, meshIndices });
+        }
+        let kind;
+        if (internalPatterns.some((p) => p.test(g.key)))
+            kind = "internal";
+        else if (requiredSet ? requiredSet.has(g.key) : requiredSuffixes.includes(groupSuffix(g.key)))
+            kind = "required";
+        else if (defaultOffPatterns.some((p) => p.test(g.key)))
+            kind = "defaultOff";
+        else
+            kind = "optional";
+        const group = { key: g.key, label: slotLabel(g.key), variants, kind };
+        groups.push(group);
+        byKey.set(g.key, group);
+    }
+    return { groups, byKey };
+}
+/**
+ * The kit default — reproduces the legacy filterOptionalMeshes +
+ * selectVariantMeshes pipeline exactly: required and optional groups keep
+ * their first variant; defaultOff groups are hidden; internal groups render
+ * nothing.
+ */
+export function defaultCustomization(catalog) {
+    const variants = {};
+    for (let _i = 0, _it = catalog.groups, _n = _it.length; _i < _n; _i++) {
+        const g = _it[_i];
+        if (g.kind === "internal")
+            continue;
+        variants[g.key] = g.kind === "defaultOff" ? null : (g.variants[0]?.key ?? null);
+    }
+    return { variants, textures: {}, tints: {} };
+}
+/** Groups the UI should list: everything except internal groups and
+ *  required groups with a single variant (nothing to choose). */
+export function customizableGroups(catalog) {
+    const out = [];
+    for (let _i = 0, _it = catalog.groups, _n = _it.length; _i < _n; _i++) {
+        const g = _it[_i];
+        if (g.kind === "internal")
+            continue;
+        if (g.kind === "required" && g.variants.length <= 1)
+            continue;
+        out.push(g);
+    }
+    return out;
+}
+/** Validate a saved variant pick: returns the variant key, or the group's
+ *  default when the saved value is missing/stale. */
+export function effectiveVariantKey(group, cust) {
+    const saved = cust.variants[group.key];
+    if (saved !== undefined) {
+        if (saved === null)
+            return group.kind === "required" ? (group.variants[0]?.key ?? null) : null;
+        for (let _i = 0, _it = group.variants, _n = _it.length; _i < _n; _i++) {
+            const v = _it[_i];
+            if (v.key === saved)
+                return saved;
+        }
+    }
+    return group.kind === "defaultOff" ? null : (group.variants[0]?.key ?? null);
+}
+const DEFAULT_INNER_SUFFIXES = [
+    "leg", "legs", "hand", "hands", "torso", "uppertorso", "foot", "feet",
+];
+const DEFAULT_INNER_MATERIALS = [/skin/i];
+const DEFAULT_INNER_OFFSET = 0.01;
+/** UE-style bone names → girth region weight. Ordered — first match wins. */
+const DEFAULT_GIRTH_BONES = [
+    [/pelvis|spine/i, 1.0],
+    [/thigh/i, 0.8],
+    [/clavicle/i, 0.7],
+    [/upperarm/i, 0.5],
+    [/calf/i, 0.4],
+    [/lowerarm/i, 0.3],
+    [/neck|head/i, 0],
+    [/foot|ball|toe/i, 0.15],
+    [/hand|thumb|index|middle|ring|pinky|metacarpal/i, 0.15],
+];
+const DEFAULT_GIRTH_UNSKINNED = 0.7;
+const GIRTH_FALLBACK = 0.5;
+const DEFAULT_GIRTH_WINDOW = [0.72, 0.88, 0.3];
+function boneGirthFactor(name, table) {
+    for (let i = 0; i < table.length; i++)
+        if (table[i][0].test(name))
+            return table[i][1];
+    return GIRTH_FALLBACK;
+}
+/** Per-mesh girth weights — cached so repeat resolves don't rescan skin
+ *  weights. Keyed on the factors table + height window the field derives
+ *  from (the window shifts if the selected mesh set's bounds change). */
+const girthWeightCache = new WeakMap();
+function girthWeightsFor(model, mesh, table, unskinned, up, uFull, uCap, topMul) {
+    const hit = girthWeightCache.get(mesh);
+    if (hit && hit.src === table && hit.uF === uFull && hit.uC === uCap && hit.tm === topMul)
+        return hit.weights;
+    const out = new Float32Array(mesh.vertexCount);
+    if (mesh.joints && mesh.weights && mesh.joints.length >= mesh.vertexCount * 4 && model.skin) {
+        const bones = model.skin.bones;
+        const jf = new Float32Array(bones.length);
+        for (let i = 0; i < bones.length; i++)
+            jf[i] = boneGirthFactor(bones[i].name, table);
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const b = v * 4;
+            out[v] =
+                jf[mesh.joints[b]] * mesh.weights[b] +
+                    jf[mesh.joints[b + 1]] * mesh.weights[b + 1] +
+                    jf[mesh.joints[b + 2]] * mesh.weights[b + 2] +
+                    jf[mesh.joints[b + 3]] * mesh.weights[b + 3];
+        }
+    }
+    else {
+        out.fill(unskinned);
+    }
+    // Height taper — weight gain lives in the torso/legs; ease toward
+    // topMul approaching the head so collars don't out-widen the face.
+    const span = uCap - uFull;
+    for (let v = 0; v < mesh.vertexCount; v++) {
+        const u = mesh.vertices[v * 6 + up];
+        if (u <= uFull || span <= 0)
+            continue;
+        if (u >= uCap) {
+            out[v] *= topMul;
+            continue;
+        }
+        const t = (u - uFull) / span;
+        out[v] *= 1 + (topMul - 1) * t * t * (3 - 2 * t);
+    }
+    girthWeightCache.set(mesh, { src: table, uF: uFull, uC: uCap, tm: topMul, weights: out });
+    return out;
+}
+/**
+ * Resolve a customization into the mesh subset to upload. Internal groups
+ * never contribute meshes; `null` selections contribute none. Required groups
+ * fall back to their first variant when the saved pick is stale.
+ *
+ * Skin-material meshes in "inner" groups are shallow-cloned with a
+ * `surfaceOffset` — modular kits author bare-skin shells that sit fractions
+ * of a millimeter under garments; without the offset the skin z-fights or
+ * pokes through where a garment variant doesn't fully cover it. The offset
+ * only applies to skin meshes substantially enclosed by a non-skin mesh in
+ * the same variant: a bare-skin pick (or one whose only non-skin meshes are
+ * small accessories like nails or partially-overlapping cuffs) must keep its
+ * authored surface, since a uniform inward offset on a limb-radius mesh
+ * collapses it to the bone.
+ */
+export function resolveCustomizationMeshes(model, catalog, cust, opts = {}) {
+    const innerSuffixes = opts.innerLayerSuffixes ?? DEFAULT_INNER_SUFFIXES;
+    const innerMats = opts.innerMaterials ?? DEFAULT_INNER_MATERIALS;
+    const innerOffset = opts.innerLayerOffset ?? DEFAULT_INNER_OFFSET;
+    const isSkin = (meshIdx) => {
+        const name = model.materials?.[model.meshes[meshIdx].materialIndex ?? -1]?.name;
+        return name !== undefined && innerMats.some((p) => (typeof p === "string" ? p === name : p.test(name)));
+    };
+    const meshIndices = new Set();
+    const innerIndices = new Set();
+    const boundsCache = new Map();
+    for (let _i = 0, _it = catalog.groups, _n = _it.length; _i < _n; _i++) {
+        const g = _it[_i];
+        if (g.kind === "internal")
+            continue;
+        const pick = effectiveVariantKey(g, cust);
+        if (pick === null)
+            continue;
+        const inner = innerOffset !== 0 && innerSuffixes.includes(groupSuffix(g.key));
+        for (let _j = 0, _jt = g.variants, _m = _jt.length; _j < _m; _j++) {
+            const v = _jt[_j];
+            if (v.key !== pick)
+                continue;
+            for (let _k = 0, _kt = v.meshIndices, _l = _kt.length; _k < _l; _k++) {
+                meshIndices.add(_kt[_k]);
+            }
+            if (!inner)
+                continue;
+            for (let _k = 0, _kt = v.meshIndices, _l = _kt.length; _k < _l; _k++) {
+                const mi = _kt[_k];
+                if (!isSkin(mi))
+                    continue;
+                const covered = v.meshIndices.some((j) => {
+                    if (j === mi || isSkin(j))
+                        return false;
+                    const sb = meshBoundsCached(model.meshes, mi, boundsCache);
+                    const gb = meshBoundsCached(model.meshes, j, boundsCache);
+                    // ≥90% enclosed: the shell sits under the garment. Lower overlaps
+                    // are exposed surfaces (bare picks, crease slivers) that must keep
+                    // their authored shape — recessing them opens a gap at the seam.
+                    return sb !== null && gb !== null && boxOverlapFraction(sb, gb) >= 0.9;
+                });
+                if (covered)
+                    innerIndices.add(mi);
+            }
+        }
+    }
+    // Girth: scale the two horizontal axes about the body-center line.
+    // Loaded vertex data is always engine y-up (normalizeModel bakes the
+    // source up-axis conversion into the verts — do NOT use sourceUpAxis
+    // here, it describes the file, not the stored data). Pivot on each
+    // scaled axis is its bounds midpoint.
+    const girth = cust.girth ?? 0;
+    let gAxes = null;
+    let gCenters = null;
+    let gUp = 1, gUFull = 0, gUCap = 0, gUTop = 0;
+    const gTable = opts.girthBoneFactors ?? DEFAULT_GIRTH_BONES;
+    const gUnskinned = opts.girthUnskinned ?? DEFAULT_GIRTH_UNSKINNED;
+    const gWindow = opts.girthUpWindow ?? DEFAULT_GIRTH_WINDOW;
+    if (girth !== 0) {
+        const b = computeMeshBounds(model.meshes, meshIndices);
+        if (b) {
+            const ext = [b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]];
+            const up = 1;
+            const h = [0, 1, 2].filter((a) => a !== up);
+            gAxes = h;
+            gCenters = [(b.min[h[0]] + b.max[h[0]]) / 2, (b.min[h[1]] + b.max[h[1]]) / 2];
+            gUp = up;
+            const uSpan = Math.max(1e-6, ext[up]);
+            gUFull = b.min[up] + uSpan * Math.min(gWindow[0], gWindow[1]);
+            gUCap = b.min[up] + uSpan * Math.max(gWindow[0], gWindow[1]);
+            gUTop = gWindow[2];
+        }
+    }
+    const meshes = [];
+    for (let i = 0; i < model.meshes.length; i++) {
+        if (!meshIndices.has(i))
+            continue;
+        const m = model.meshes[i];
+        const inner = innerIndices.has(i);
+        if (!inner && !gAxes) {
+            meshes.push(m);
+            continue;
+        }
+        meshes.push({
+            ...m,
+            ...(inner ? { surfaceOffset: innerOffset } : {}),
+            ...(gAxes ? { surfaceGirth: { factor: girth, weights: girthWeightsFor(model, m, gTable, gUnskinned, gUp, gUFull, gUCap, gUTop), axes: gAxes, centers: gCenters } } : {}),
+        });
+    }
+    return { meshes, meshIndices };
+}
+/** Mesh indices of visible *required* groups — the body used for scale fit
+ *  (outfits/hats shouldn't change how the avatar fits the 1.8m capsule). */
+export function requiredMeshIndices(catalog, cust) {
+    const out = new Set();
+    for (let _i = 0, _it = catalog.groups, _n = _it.length; _i < _n; _i++) {
+        const g = _it[_i];
+        if (g.kind !== "required")
+            continue;
+        const pick = effectiveVariantKey(g, cust);
+        if (pick === null)
+            continue;
+        for (let _j = 0, _jt = g.variants, _m = _jt.length; _j < _m; _j++) {
+            const v = _jt[_j];
+            if (v.key !== pick)
+                continue;
+            for (let _k = 0, _kt = v.meshIndices, _l = _kt.length; _k < _l; _k++)
+                out.add(_kt[_k]);
+        }
+    }
+    return out;
+}
+/** Per-mesh axis-aligned bounds (pos stride: xyz + normal xyz), or null for
+ *  a mesh with no usable position data. */
+function singleMeshBounds(mesh) {
+    const verts = mesh.vertices;
+    const stride = mesh.vertexCount > 0 ? Math.floor(verts.length / mesh.vertexCount) : 0;
+    if (stride < 3)
+        return null;
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (let v = 0; v < mesh.vertexCount; v++) {
+        const x = verts[v * stride], y = verts[v * stride + 1], z = verts[v * stride + 2];
+        if (x < min[0])
+            min[0] = x;
+        if (x > max[0])
+            max[0] = x;
+        if (y < min[1])
+            min[1] = y;
+        if (y > max[1])
+            max[1] = y;
+        if (z < min[2])
+            min[2] = z;
+        if (z > max[2])
+            max[2] = z;
+    }
+    return { min, max };
+}
+function meshBoundsCached(meshes, i, cache) {
+    let b = cache.get(i);
+    if (b === undefined) {
+        b = singleMeshBounds(meshes[i]);
+        cache.set(i, b);
+    }
+    return b;
+}
+/** Fraction of box `a`'s volume overlapped by box `b` (0–1). */
+function boxOverlapFraction(a, b) {
+    let f = 1;
+    for (let i = 0; i < 3; i++) {
+        const ext = Math.max(1e-9, a.max[i] - a.min[i]);
+        f *= Math.max(0, Math.min(a.max[i], b.max[i]) - Math.max(a.min[i], b.min[i])) / ext;
+    }
+    return f;
+}
+/** Axis-aligned bounds over vertex positions (pos stride: xyz + normal xyz). */
+export function computeMeshBounds(meshes, meshIndices) {
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let any = false;
+    for (let i = 0; i < meshes.length; i++) {
+        if (meshIndices && !meshIndices.has(i))
+            continue;
+        const mesh = meshes[i];
+        const verts = mesh.vertices;
+        const stride = mesh.vertexCount > 0 ? Math.floor(verts.length / mesh.vertexCount) : 0;
+        if (stride < 3)
+            continue;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const x = verts[v * stride], y = verts[v * stride + 1], z = verts[v * stride + 2];
+            if (x < min[0])
+                min[0] = x;
+            if (x > max[0])
+                max[0] = x;
+            if (y < min[1])
+                min[1] = y;
+            if (y > max[1])
+                max[1] = y;
+            if (z < min[2])
+                min[2] = z;
+            if (z > max[2])
+                max[2] = z;
+            any = true;
+        }
+    }
+    return any ? { min, max } : null;
+}
+/** Clone the materials array and apply a texture swap (bytes already fetched)
+ *  and/or tint on the named material. Indices are preserved so mesh
+ *  materialIndex lookups stay valid. Returns the ORIGINAL array untouched
+ *  when no override applies. */
+export function withMaterialOverrides(materials, overrides) {
+    if (!materials || overrides.length === 0)
+        return materials;
+    let out = null;
+    for (let _i = 0, _it = overrides, _n = _it.length; _i < _n; _i++) {
+        const ov = _it[_i];
+        for (let mi = 0; mi < materials.length; mi++) {
+            if (materials[mi].name !== ov.material)
+                continue;
+            if (!out)
+                out = materials.slice();
+            const m = { ...out[mi] };
+            if (ov.textureData !== undefined) {
+                m.textureData = ov.textureData;
+                m.textureUri = undefined;
+            }
+            if (ov.tint)
+                m.baseColor = [ov.tint[0], ov.tint[1], ov.tint[2], m.baseColor[3]];
+            out[mi] = m;
+        }
+    }
+    return out ?? materials;
+}

package/dist/libraries/character/src/index.js

@@ -0,0 +1,19 @@
+// ============================================================================
+// @downdraft/engine/libraries/character — skinned character plumbing
+//
+// The character pipeline every rigged-model game needs:
+//  - `createCharacterModelLoader` — fetch + parse + external texture
+//    resolution + accessory-mesh filtering + animation-file merging, cached.
+//  - `LocomotionAnimator` — Idle/Walk/Run/airborne state machine with
+//    hysteresis, driven by {grounded, speed, override}.
+//  - `CharacterAnimator` — SkeletonAnimator → skin matrices with the model's
+//    normalization conjugation, for ModelRenderer.updateSkinMatrices.
+//  - `CharacterPreview` — self-contained orbiting model preview canvas.
+//  - Humanoid bone-name resolver + procedural locomotion clip builders.
+// ============================================================================
+export { buildLocomotionClips, CharacterAnimator, findBoneIndex, positionTrack, resolveHumanoidBones, rotationTrack } from "./character-animator.js";
+export { buildVariantCatalog, computeMeshBounds, customizableGroups, defaultCustomization, effectiveVariantKey, requiredMeshIndices, resolveCustomizationMeshes, slotLabel, variantLabel, withMaterialOverrides } from "./customization.js";
+export { characterCustomizationNodes, CUSTOMIZATION_NONE } from "./inspectable.js";
+export { createCharacterModelLoader, DEFAULT_OPTIONAL_MESH_PATTERNS, filterOptionalMeshes, isDecodableImage, loadExternalTextures, selectVariantMeshes } from "./loader.js";
+export { LocomotionAnimator } from "./locomotion.js";
+export { CharacterPreview } from "./preview.js";

package/dist/libraries/character/src/inspectable.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// inspectable.ts — characterCustomizationNodes(): InspectableNode[] exposing
+// a CharacterCustomization to automation (MCP inspectable_* tools, devtools).
+//
+// The nodes write through the game's `apply` callback — the SAME function the
+// customization UI calls (store update → resolveCustomizationMeshes → mesh
+// re-upload → sim dispatch) — so an agent setting `player.customization.
+// variants.ash_torso` produces exactly the in-game effect of a user picking
+// that variant.
+//
+// Group coverage is captured at call time: re-run the helper and re-register
+// (the previous registerAll() unsubscribe makes this one line) after a model
+// swap changes the group set. Option lists stay fresh within a fixed set —
+// `enum` and `get` re-resolve the catalog lazily.
+// ============================================================================
+import { customizableGroups, effectiveVariantKey, slotLabel, } from "./customization.js";
+/** Sentinel enum value standing in for a `null` variant pick (hidden group). */
+export const CUSTOMIZATION_NONE = "<none>";
+export function characterCustomizationNodes(opts) {
+    const prefix = opts.prefix ?? "player.customization";
+    const catalog = () => (typeof opts.catalog === "function" ? opts.catalog() : opts.catalog);
+    const patch = (update) => opts.apply({ ...opts.get(), ...update });
+    const nodes = [
+        {
+            path: `${prefix}.girth`,
+            label: "Body girth",
+            description: "Horizontal body-width scale delta; 0 = authored shape.",
+            type: "number",
+            min: -1,
+            max: 1,
+            get: () => opts.get().girth ?? 0,
+            set: (v) => patch({ girth: v }),
+        },
+        {
+            path: `${prefix}.tints`,
+            label: "Material tints",
+            description: "Whole tint map (material name → linear RGB 0-1 triple).",
+            type: "json",
+            get: () => opts.get().tints,
+            set: (v) => patch({ tints: v }),
+        },
+        {
+            path: `${prefix}.textures`,
+            label: "Material textures",
+            description: "Whole texture map (material name → texture asset path).",
+            type: "json",
+            get: () => opts.get().textures,
+            set: (v) => patch({ textures: v }),
+        },
+    ];
+    for (const group of customizableGroups(catalog() ?? { groups: [], byKey: new Map() })) {
+        nodes.push(variantNode(prefix, group, catalog, opts.get, patch));
+    }
+    return nodes;
+}
+function variantNode(prefix, groupAtEmit, catalog, get, patch) {
+    // Group lookups re-resolve the catalog so a rebuilt catalog (same group
+    // set, refreshed variants) is honored without re-registration.
+    const group = () => catalog()?.byKey.get(groupAtEmit.key) ?? groupAtEmit;
+    const allowsNone = () => group().kind !== "required";
+    const options = () => {
+        const keys = group().variants.map((v) => v.key);
+        return allowsNone() ? [...keys, CUSTOMIZATION_NONE] : keys;
+    };
+    return {
+        path: `${prefix}.variants.${groupAtEmit.key}`,
+        label: groupAtEmit.label,
+        description: `Variant pick for the ${slotLabel(groupAtEmit.key)} slot`,
+        type: "enum",
+        enum: options,
+        get: () => effectiveVariantKey(group(), get()) ?? CUSTOMIZATION_NONE,
+        set: (v) => {
+            const cust = get();
+            patch({ variants: { ...cust.variants, [groupAtEmit.key]: v === CUSTOMIZATION_NONE ? null : v } });
+        },
+    };
+}