@series-inc/stowkit-cli 0.1.29 → 0.1.31

package/dist/app/state.d.ts

@@ -39,4 +39,6 @@ export interface ProjectAsset {
     processedSize: number;
     parentId?: string;
     locked?: boolean;
+    /** Processing warnings (e.g. animation bone mismatches). */
+    warnings?: string[];
 }

package/dist/cli.js

@@ -38,7 +38,9 @@ checkForUpdate();
 function printUsage() {
     console.log(`
 Usage:
-  stowkit init [dir]              Initialize a StowKit project
+  stowkit init [dir]              Initialize a StowKit project (interactive menu)
+  stowkit init --with-engine      Initialize with 3D engine included
+  stowkit init --no-engine        Initialize without 3D engine (skip prompt)
   stowkit init --update [dir]     Update AI skill files to match installed CLI version
   stowkit build [dir]             Full build: scan + process + pack
   stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
@@ -105,7 +107,11 @@ async function main() {
     try {
         switch (command) {
             case 'init':
-                await initProject(projectDir, { update: args.includes('--update') });
+                await initProject(projectDir, {
+                    update: args.includes('--update'),
+                    withEngine: args.includes('--with-engine'),
+                    noEngine: args.includes('--no-engine'),
+                });
                 break;
             case 'update': {
                 const currentVersion = getVersion();
@@ -226,7 +232,7 @@ async function main() {
                     process.exit(1);
                 }
                 const resolvedProject = path.resolve(projectDir);
-                await startServer({ port, projectDir: resolvedProject, staticApps: { '/': packerDir } });
+                await startServer({ port, projectDir: resolvedProject, force, staticApps: { '/': packerDir } });
                 console.log(`\n  Packer: http://localhost:${port}\n`);
                 openBrowser(`http://localhost:${port}`);
                 break;
@@ -240,11 +246,11 @@ async function main() {
                 const resolvedProject = path.resolve(projectDir);
                 const packerPort = port + 1;
                 // Start editor server
-                await startServer({ port, projectDir: resolvedProject, staticApps: { '/': editorDir } });
+                await startServer({ port, projectDir: resolvedProject, force, staticApps: { '/': editorDir } });
                 // Start packer on next port if installed
                 const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
                 if (packerDir) {
-                    await startServer({ port: packerPort, projectDir: resolvedProject, staticApps: { '/': packerDir } });
+                    await startServer({ port: packerPort, projectDir: resolvedProject, force, staticApps: { '/': packerDir } });
                     console.log(`\n  Editor: http://localhost:${port}`);
                     console.log(`  Packer: http://localhost:${packerPort}\n`);
                 }
@@ -255,7 +261,7 @@ async function main() {
                 break;
             }
             case 'serve':
-                await startServer({ port, projectDir: projectDir !== '.' ? path.resolve(projectDir) : undefined });
+                await startServer({ port, force, projectDir: projectDir !== '.' ? path.resolve(projectDir) : undefined });
                 break;
             default:
                 console.error(`Unknown command: ${command}`);

package/dist/core/constants.d.ts

@@ -50,10 +50,15 @@ export declare const SKINNED_MESH_GEOMETRY_INFO_SIZE = 72;
 export declare const SKINNED_MESH_METADATA_FIXED_SIZE = 144;
 /** Size of Bone on disk (bytes): name[64] + parent_index(4) + offset_matrix[64] */
 export declare const BONE_SIZE = 132;
-/** Size of VertexWeights on disk (bytes): bone_indices[16] + weights[16] */
+/** Size of VertexWeights on disk (bytes) — legacy: bone_indices[4*u32] + weights[4*f32] */
 export declare const VERTEX_WEIGHTS_SIZE = 32;
+/** Size of compact VertexWeights on disk: bone_indices[4*u16] + weights[4*u8] = 12 bytes */
+export declare const COMPACT_VERTEX_WEIGHTS_SIZE = 12;
 /** Interleaved vertex size for skinned meshes: pos[3] + normal[3] + uv[2] = 8 floats */
 export declare const SKINNED_VERTEX_STRIDE = 32;
+/** SkinnedMeshGeometryInfo flags */
+export declare const SKINNED_INDEX16_FLAG = 1;
+export declare const SKINNED_COMPACT_WEIGHTS_FLAG = 2;
 /** Size of AnimationTrackDescriptor on disk (bytes) */
 export declare const ANIMATION_TRACK_DESCRIPTOR_SIZE = 88;
 /** Size of AnimationClipMetadata fixed portion on disk (bytes) */

package/dist/core/constants.js

@@ -50,10 +50,15 @@ export const SKINNED_MESH_GEOMETRY_INFO_SIZE = 72;
 export const SKINNED_MESH_METADATA_FIXED_SIZE = 144;
 /** Size of Bone on disk (bytes): name[64] + parent_index(4) + offset_matrix[64] */
 export const BONE_SIZE = 132;
-/** Size of VertexWeights on disk (bytes): bone_indices[16] + weights[16] */
+/** Size of VertexWeights on disk (bytes) — legacy: bone_indices[4*u32] + weights[4*f32] */
 export const VERTEX_WEIGHTS_SIZE = 32;
+/** Size of compact VertexWeights on disk: bone_indices[4*u16] + weights[4*u8] = 12 bytes */
+export const COMPACT_VERTEX_WEIGHTS_SIZE = 12;
 /** Interleaved vertex size for skinned meshes: pos[3] + normal[3] + uv[2] = 8 floats */
 export const SKINNED_VERTEX_STRIDE = 32;
+/** SkinnedMeshGeometryInfo flags */
+export const SKINNED_INDEX16_FLAG = 0x1;
+export const SKINNED_COMPACT_WEIGHTS_FLAG = 0x2;
 // ─── Animation V2 Constants ─────────────────────────────────────────────────
 /** Size of AnimationTrackDescriptor on disk (bytes) */
 export const ANIMATION_TRACK_DESCRIPTOR_SIZE = 88;

package/dist/core/types.d.ts

@@ -159,7 +159,8 @@ export interface SkinnedMeshGeometryInfo {
     weightsOffset: number;
     weightsSize: number;
     materialIndex: number;
-    _padding: number;
+    /** Bit flags: 0x1 = index16, 0x2 = compact weights (u16 bone indices + u8 weights) */
+    flags: number;
 }
 export interface Bone {
     name: string;

package/dist/encoders/fbx-loader.js

@@ -63,6 +63,14 @@ export class NodeFbxImporter {
             return mesh;
         }
         catch (err) {
+            // Animation-only FBX files often crash Three.js's FBXLoader (missing skeleton connections).
+            // Fall back to extracting animations directly via fbx-parser.
+            const animations = parseFbxAnimations(data);
+            if (animations.length > 0) {
+                const mesh = emptyMesh();
+                mesh.animations = animations;
+                return mesh;
+            }
             console.error('[NodeFbxImporter] Failed:', err);
             return emptyMesh();
         }
@@ -189,54 +197,57 @@ function extractMeshFromGroup(group) {
         if (!posAttr)
             continue;
         const vertCount = posAttr.count;
-        const positions = new Float32Array(vertCount * 3);
+        // Pre-compute full-mesh vertex data (shared across groups)
+        const worldMatrix = mesh.matrixWorld;
+        const fullPositions = new Float32Array(vertCount * 3);
         {
-            const worldMatrix = mesh.matrixWorld;
             const v = new THREE.Vector3();
             for (let vi = 0; vi < vertCount; vi++) {
                 v.fromBufferAttribute(posAttr, vi);
                 v.applyMatrix4(worldMatrix);
-                positions[vi * 3] = v.x;
-                positions[vi * 3 + 1] = v.y;
-                positions[vi * 3 + 2] = v.z;
+                fullPositions[vi * 3] = v.x;
+                fullPositions[vi * 3 + 1] = v.y;
+                fullPositions[vi * 3 + 2] = v.z;
             }
         }
-        let normals = null;
+        let fullNormals = null;
         const normAttr = geometry.getAttribute('normal');
         if (normAttr && normAttr.count === vertCount) {
-            normals = new Float32Array(vertCount * 3);
+            fullNormals = new Float32Array(vertCount * 3);
             const normalMatrix = new THREE.Matrix3().getNormalMatrix(mesh.matrixWorld);
             const n = new THREE.Vector3();
             for (let vi = 0; vi < vertCount; vi++) {
                 n.fromBufferAttribute(normAttr, vi);
                 n.applyMatrix3(normalMatrix).normalize();
-                normals[vi * 3] = n.x;
-                normals[vi * 3 + 1] = n.y;
-                normals[vi * 3 + 2] = n.z;
+                fullNormals[vi * 3] = n.x;
+                fullNormals[vi * 3 + 1] = n.y;
+                fullNormals[vi * 3 + 2] = n.z;
             }
         }
-        let uvs = null;
+        let fullUvs = null;
         const uvAttr = geometry.getAttribute('uv');
         if (uvAttr && uvAttr.count === vertCount) {
-            uvs = new Float32Array(vertCount * 2);
+            fullUvs = new Float32Array(vertCount * 2);
             for (let vi = 0; vi < vertCount; vi++) {
-                uvs[vi * 2] = uvAttr.getX(vi);
-                uvs[vi * 2 + 1] = uvAttr.getY(vi);
+                fullUvs[vi * 2] = uvAttr.getX(vi);
+                fullUvs[vi * 2 + 1] = uvAttr.getY(vi);
             }
         }
         const indexAttr = geometry.getIndex();
-        let indices;
+        let fullIndices;
         if (indexAttr) {
-            indices = new Uint32Array(indexAttr.count);
+            fullIndices = new Uint32Array(indexAttr.count);
             for (let ii = 0; ii < indexAttr.count; ii++)
-                indices[ii] = indexAttr.getX(ii);
+                fullIndices[ii] = indexAttr.getX(ii);
         }
         else {
-            indices = new Uint32Array(vertCount);
+            fullIndices = new Uint32Array(vertCount);
             for (let ii = 0; ii < vertCount; ii++)
-                indices[ii] = ii;
+                fullIndices[ii] = ii;
         }
-        let skinData;
+        // Pre-compute full skin data
+        let fullSkinBoneIndices;
+        let fullSkinBoneWeights;
         if (mesh.isSkinnedMesh) {
             const skinIndexAttr = geometry.getAttribute('skinIndex');
             const skinWeightAttr = geometry.getAttribute('skinWeight');
@@ -250,44 +261,125 @@ function extractMeshFromGroup(group) {
                         remap[si] = idx >= 0 ? idx : 0;
                     }
                 }
-                const boneIndices = new Uint32Array(vertCount * 4);
-                const boneWeights = new Float32Array(vertCount * 4);
+                fullSkinBoneIndices = new Uint32Array(vertCount * 4);
+                fullSkinBoneWeights = new Float32Array(vertCount * 4);
                 for (let vi = 0; vi < vertCount; vi++) {
                     const si0 = skinIndexAttr.getX(vi);
                     const si1 = skinIndexAttr.getY(vi);
                     const si2 = skinIndexAttr.getZ(vi);
                     const si3 = skinIndexAttr.getW(vi);
-                    boneIndices[vi * 4] = remap && si0 < remap.length ? remap[si0] : si0;
-                    boneIndices[vi * 4 + 1] = remap && si1 < remap.length ? remap[si1] : si1;
-                    boneIndices[vi * 4 + 2] = remap && si2 < remap.length ? remap[si2] : si2;
-                    boneIndices[vi * 4 + 3] = remap && si3 < remap.length ? remap[si3] : si3;
-                    boneWeights[vi * 4] = skinWeightAttr.getX(vi);
-                    boneWeights[vi * 4 + 1] = skinWeightAttr.getY(vi);
-                    boneWeights[vi * 4 + 2] = skinWeightAttr.getZ(vi);
-                    boneWeights[vi * 4 + 3] = skinWeightAttr.getW(vi);
+                    fullSkinBoneIndices[vi * 4] = remap && si0 < remap.length ? remap[si0] : si0;
+                    fullSkinBoneIndices[vi * 4 + 1] = remap && si1 < remap.length ? remap[si1] : si1;
+                    fullSkinBoneIndices[vi * 4 + 2] = remap && si2 < remap.length ? remap[si2] : si2;
+                    fullSkinBoneIndices[vi * 4 + 3] = remap && si3 < remap.length ? remap[si3] : si3;
+                    fullSkinBoneWeights[vi * 4] = skinWeightAttr.getX(vi);
+                    fullSkinBoneWeights[vi * 4 + 1] = skinWeightAttr.getY(vi);
+                    fullSkinBoneWeights[vi * 4 + 2] = skinWeightAttr.getZ(vi);
+                    fullSkinBoneWeights[vi * 4 + 3] = skinWeightAttr.getW(vi);
                 }
-                skinData = { boneIndices, boneWeights };
             }
         }
-        const meshMaterial = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
-        const matName = meshMaterial?.name || 'default';
-        let matIndex;
-        if (materialSet.has(matName)) {
-            matIndex = materialSet.get(matName);
+        // Determine groups: multi-material meshes have geometry.groups
+        const matArray = Array.isArray(mesh.material) ? mesh.material : null;
+        const groups = geometry.groups.length > 0 && matArray && matArray.length > 1
+            ? geometry.groups
+            : null;
+        const meshSubMeshIndices = [];
+        if (groups) {
+            // Multi-material: split into one submesh per group
+            for (const group of groups) {
+                const groupMat = matArray[group.materialIndex ?? 0] ?? matArray[0];
+                const matName = groupMat?.name || 'default';
+                let matIndex;
+                if (materialSet.has(matName)) {
+                    matIndex = materialSet.get(matName);
+                }
+                else {
+                    matIndex = materials.length;
+                    materialSet.set(matName, matIndex);
+                    materials.push({ name: matName });
+                }
+                // Extract the index slice for this group and remap vertices
+                const groupIndexStart = group.start;
+                const groupIndexCount = group.count;
+                const usedVerts = new Map(); // old vertex index → new vertex index
+                const groupIndicesRaw = [];
+                for (let ii = 0; ii < groupIndexCount; ii++) {
+                    const oldVi = fullIndices[groupIndexStart + ii];
+                    if (!usedVerts.has(oldVi)) {
+                        usedVerts.set(oldVi, usedVerts.size);
+                    }
+                    groupIndicesRaw.push(usedVerts.get(oldVi));
+                }
+                const gVertCount = usedVerts.size;
+                const positions = new Float32Array(gVertCount * 3);
+                const normals = fullNormals ? new Float32Array(gVertCount * 3) : null;
+                const uvs = fullUvs ? new Float32Array(gVertCount * 2) : null;
+                let skinData;
+                let gBoneIndices;
+                let gBoneWeights;
+                if (fullSkinBoneIndices && fullSkinBoneWeights) {
+                    gBoneIndices = new Uint32Array(gVertCount * 4);
+                    gBoneWeights = new Float32Array(gVertCount * 4);
+                }
+                for (const [oldVi, newVi] of usedVerts) {
+                    positions[newVi * 3] = fullPositions[oldVi * 3];
+                    positions[newVi * 3 + 1] = fullPositions[oldVi * 3 + 1];
+                    positions[newVi * 3 + 2] = fullPositions[oldVi * 3 + 2];
+                    if (normals && fullNormals) {
+                        normals[newVi * 3] = fullNormals[oldVi * 3];
+                        normals[newVi * 3 + 1] = fullNormals[oldVi * 3 + 1];
+                        normals[newVi * 3 + 2] = fullNormals[oldVi * 3 + 2];
+                    }
+                    if (uvs && fullUvs) {
+                        uvs[newVi * 2] = fullUvs[oldVi * 2];
+                        uvs[newVi * 2 + 1] = fullUvs[oldVi * 2 + 1];
+                    }
+                    if (gBoneIndices && gBoneWeights && fullSkinBoneIndices && fullSkinBoneWeights) {
+                        gBoneIndices[newVi * 4] = fullSkinBoneIndices[oldVi * 4];
+                        gBoneIndices[newVi * 4 + 1] = fullSkinBoneIndices[oldVi * 4 + 1];
+                        gBoneIndices[newVi * 4 + 2] = fullSkinBoneIndices[oldVi * 4 + 2];
+                        gBoneIndices[newVi * 4 + 3] = fullSkinBoneIndices[oldVi * 4 + 3];
+                        gBoneWeights[newVi * 4] = fullSkinBoneWeights[oldVi * 4];
+                        gBoneWeights[newVi * 4 + 1] = fullSkinBoneWeights[oldVi * 4 + 1];
+                        gBoneWeights[newVi * 4 + 2] = fullSkinBoneWeights[oldVi * 4 + 2];
+                        gBoneWeights[newVi * 4 + 3] = fullSkinBoneWeights[oldVi * 4 + 3];
+                    }
+                }
+                if (gBoneIndices && gBoneWeights) {
+                    skinData = { boneIndices: gBoneIndices, boneWeights: gBoneWeights };
+                }
+                meshSubMeshIndices.push(subMeshes.length);
+                subMeshes.push({ skinData, positions, normals, uvs, indices: new Uint32Array(groupIndicesRaw), materialIndex: matIndex });
+            }
         }
         else {
-            matIndex = materials.length;
-            materialSet.set(matName, matIndex);
-            materials.push({ name: matName });
+            // Single material
+            const meshMaterial = matArray ? matArray[0] : mesh.material;
+            const matName = meshMaterial?.name || 'default';
+            let matIndex;
+            if (materialSet.has(matName)) {
+                matIndex = materialSet.get(matName);
+            }
+            else {
+                matIndex = materials.length;
+                materialSet.set(matName, matIndex);
+                materials.push({ name: matName });
+            }
+            let skinData;
+            if (fullSkinBoneIndices && fullSkinBoneWeights) {
+                skinData = { boneIndices: fullSkinBoneIndices, boneWeights: fullSkinBoneWeights };
+            }
+            meshSubMeshIndices.push(subMeshes.length);
+            subMeshes.push({ skinData, positions: fullPositions, normals: fullNormals, uvs: fullUvs, indices: fullIndices, materialIndex: matIndex });
         }
-        subMeshes.push({ skinData, positions, normals, uvs, indices, materialIndex: matIndex });
         nodes.push({
             name: mesh.name || `mesh_${mi}`,
             parentIndex: -1,
             position: [0, 0, 0],
             rotation: [0, 0, 0, 1],
             scale: [1, 1, 1],
-            meshIndices: [mi],
+            meshIndices: meshSubMeshIndices,
         });
     }
     if (materials.length === 0)

package/dist/encoders/skinned-mesh-builder.js

@@ -1,12 +1,16 @@
-import { SKINNED_VERTEX_STRIDE, VERTEX_WEIGHTS_SIZE } from '../core/constants.js';
+import { SKINNED_VERTEX_STRIDE, COMPACT_VERTEX_WEIGHTS_SIZE, SKINNED_INDEX16_FLAG, SKINNED_COMPACT_WEIGHTS_FLAG, } from '../core/constants.js';
 export function buildSkinnedMeshData(imported, scaleFactor = 1.0) {
     const geometries = [];
     let totalDataSize = 0;
     for (const sub of imported.subMeshes) {
         const vertCount = sub.positions.length / 3;
+        const useIndex16 = vertCount < 65536;
         const vertexBufSize = vertCount * SKINNED_VERTEX_STRIDE;
-        const indexBufSize = sub.indices.length * 4;
-        const weightsBufSize = vertCount * VERTEX_WEIGHTS_SIZE;
+        const indexBufSize = sub.indices.length * (useIndex16 ? 2 : 4);
+        const weightsBufSize = vertCount * COMPACT_VERTEX_WEIGHTS_SIZE;
+        let flags = SKINNED_COMPACT_WEIGHTS_FLAG;
+        if (useIndex16)
+            flags |= SKINNED_INDEX16_FLAG;
         geometries.push({
             vertexCount: vertCount,
             indexCount: sub.indices.length,
@@ -19,15 +23,19 @@ export function buildSkinnedMeshData(imported, scaleFactor = 1.0) {
             weightsOffset: totalDataSize + vertexBufSize + indexBufSize,
             weightsSize: weightsBufSize,
             materialIndex: sub.materialIndex,
-            _padding: 0,
+            flags,
         });
         totalDataSize += vertexBufSize + indexBufSize + weightsBufSize;
     }
     const data = new Uint8Array(totalDataSize);
     const view = new DataView(data.buffer);
     let offset = 0;
-    for (const sub of imported.subMeshes) {
+    for (let si = 0; si < imported.subMeshes.length; si++) {
+        const sub = imported.subMeshes[si];
+        const geo = geometries[si];
         const vertCount = sub.positions.length / 3;
+        const useIndex16 = (geo.flags & SKINNED_INDEX16_FLAG) !== 0;
+        // Vertex buffer (32 bytes per vert: pos[3] + normal[3] + uv[2])
         for (let v = 0; v < vertCount; v++) {
             view.setFloat32(offset, sub.positions[v * 3] * scaleFactor, true);
             offset += 4;
@@ -64,25 +72,37 @@ export function buildSkinnedMeshData(imported, scaleFactor = 1.0) {
                 offset += 4;
             }
         }
-        for (let i = 0; i < sub.indices.length; i++) {
-            view.setUint32(offset, sub.indices[i], true);
-            offset += 4;
+        // Index buffer — uint16 or uint32
+        if (useIndex16) {
+            for (let i = 0; i < sub.indices.length; i++) {
+                view.setUint16(offset, sub.indices[i], true);
+                offset += 2;
+            }
+        }
+        else {
+            for (let i = 0; i < sub.indices.length; i++) {
+                view.setUint32(offset, sub.indices[i], true);
+                offset += 4;
+            }
         }
+        // Compact weights: bone_indices[4*u16] + weights[4*u8] = 12 bytes per vert
         for (let v = 0; v < vertCount; v++) {
             if (sub.skinData) {
                 for (let w = 0; w < 4; w++) {
-                    view.setUint32(offset, sub.skinData.boneIndices[v * 4 + w], true);
-                    offset += 4;
+                    view.setUint16(offset, sub.skinData.boneIndices[v * 4 + w], true);
+                    offset += 2;
                 }
                 for (let w = 0; w < 4; w++) {
-                    view.setFloat32(offset, sub.skinData.boneWeights[v * 4 + w], true);
-                    offset += 4;
+                    // Quantize float weight [0,1] to uint8 [0,255]
+                    view.setUint8(offset, Math.round(sub.skinData.boneWeights[v * 4 + w] * 255));
+                    offset += 1;
                 }
             }
             else {
-                for (let w = 0; w < 8; w++) {
-                    view.setUint32(offset, 0, true);
-                    offset += 4;
+                // 8 bytes zero indices + 4 bytes zero weights
+                for (let w = 0; w < 12; w++) {
+                    view.setUint8(offset, 0);
+                    offset += 1;
                 }
             }
         }

package/dist/format/metadata.js

@@ -262,7 +262,7 @@ function serializeSkinnedGeometryInfo(w, g) {
     w.writeUint64FromNumber(g.weightsOffset);
     w.writeUint64FromNumber(g.weightsSize);
     w.writeUint32(g.materialIndex);
-    w.writeUint32(g._padding);
+    w.writeUint32(g.flags);
 }
 function deserializeSkinnedGeometryInfo(r) {
     return {
@@ -277,7 +277,7 @@ function deserializeSkinnedGeometryInfo(r) {
         weightsOffset: r.readUint64AsNumber(),
         weightsSize: r.readUint64AsNumber(),
         materialIndex: r.readUint32(),
-        _padding: r.readUint32(),
+        flags: r.readUint32(),
     };
 }
 function serializeBone(w, bone) {

package/dist/init.d.ts

@@ -1,4 +1,6 @@
 export interface InitOptions {
     update?: boolean;
+    withEngine?: boolean;
+    noEngine?: boolean;
 }
 export declare function initProject(projectDir: string, opts?: InitOptions): Promise<void>;

package/dist/init.js

@@ -1,6 +1,36 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import * as readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
+async function promptMenu(question, choices) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        console.log(`\n${question}\n`);
+        for (let i = 0; i < choices.length; i++) {
+            console.log(`  ${i + 1}) ${choices[i]}`);
+        }
+        console.log('');
+        const ask = () => {
+            rl.question('Choose [1]: ', (answer) => {
+                const trimmed = answer.trim();
+                if (trimmed === '') {
+                    rl.close();
+                    resolve(0);
+                    return;
+                }
+                const num = parseInt(trimmed, 10);
+                if (num >= 1 && num <= choices.length) {
+                    rl.close();
+                    resolve(num - 1);
+                    return;
+                }
+                console.log(`  Please enter 1-${choices.length}`);
+                ask();
+            });
+        };
+        ask();
+    });
+}
 export async function initProject(projectDir, opts) {
     const absDir = path.resolve(projectDir);
     const configPath = path.join(absDir, '.felicityproject');
@@ -15,6 +45,7 @@ export async function initProject(projectDir, opts) {
             process.exit(1);
         }
         await copySkillFiles(absDir);
+        await copyEngineSkillFiles(absDir);
         console.log('Updated AI skill files:');
         console.log('  .claude/skills/stowkit/SKILL.md');
         console.log('  .cursor/rules/stowkit.mdc');
@@ -29,6 +60,16 @@ export async function initProject(projectDir, opts) {
     catch {
         // Does not exist — create it
     }
+    // Prompt for engine setup unless explicitly set via flag
+    let withEngine = opts?.withEngine ?? false;
+    const noEngine = opts?.noEngine ?? false;
+    if (!withEngine && !noEngine && process.stdin.isTTY) {
+        const choice = await promptMenu('What would you like to set up?', [
+            'StowKit (asset pipeline only)',
+            'StowKit + 3D Engine (includes @series-inc/rundot-3d-engine)',
+        ]);
+        withEngine = choice === 1;
+    }
     // Create srcArtDir with .gitignore for cache files
     const srcArtDir = 'assets';
     await fs.mkdir(path.join(absDir, srcArtDir), { recursive: true });
@@ -72,10 +113,36 @@ export async function initProject(projectDir, opts) {
     console.log(`  Output dir:     public/cdn-assets/`);
     console.log(`  Config:         .felicityproject`);
     console.log(`  AI skills:      .claude/skills/stowkit/SKILL.md, .cursor/rules/stowkit.mdc`);
+    // Install engine if selected
+    if (withEngine) {
+        await installEngine(absDir);
+    }
     console.log('');
     console.log('Drop your assets (PNG, JPG, FBX, WAV, etc.) into assets/');
     console.log('Then run: stowkit build');
 }
+async function installEngine(absDir) {
+    console.log('');
+    console.log('Installing @series-inc/rundot-3d-engine and three...');
+    const { execSync } = await import('node:child_process');
+    try {
+        execSync('npm install @series-inc/rundot-3d-engine three', {
+            cwd: absDir,
+            stdio: 'inherit',
+        });
+    }
+    catch {
+        console.error('Failed to install engine packages. You can install manually:');
+        console.error('  npm install @series-inc/rundot-3d-engine three');
+        return;
+    }
+    await copyEngineSkillFiles(absDir);
+    console.log('');
+    console.log('  3D Engine installed:');
+    console.log('    @series-inc/rundot-3d-engine');
+    console.log('    three');
+    console.log('  AI skills: .claude/skills/stowkit-engine/SKILL.md, .cursor/rules/stowkit-engine.mdc');
+}
 async function copySkillFiles(absDir) {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     const skillSrc = path.resolve(thisDir, '../skill.md');
@@ -92,3 +159,34 @@ async function copySkillFiles(absDir) {
         // Skill file not found in package — skip silently
     }
 }
+async function copyEngineSkillFiles(absDir) {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Monorepo dev: sibling folder
+        path.resolve(thisDir, '../../stowkit-engine/SKILL.md'),
+        // Installed in project's node_modules
+        path.join(absDir, 'node_modules/@series-inc/rundot-3d-engine/SKILL.md'),
+        // Installed as dep of CLI: nested node_modules
+        path.resolve(thisDir, '../node_modules/@series-inc/rundot-3d-engine/SKILL.md'),
+        // Hoisted in global node_modules
+        path.resolve(thisDir, '../../../@series-inc/rundot-3d-engine/SKILL.md'),
+    ];
+    let skillContent = null;
+    for (const candidate of candidates) {
+        try {
+            skillContent = await fs.readFile(candidate, 'utf-8');
+            break;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    if (!skillContent)
+        return;
+    const claudeDir = path.join(absDir, '.claude', 'skills', 'stowkit-engine');
+    await fs.mkdir(claudeDir, { recursive: true });
+    await fs.writeFile(path.join(claudeDir, 'SKILL.md'), skillContent);
+    const cursorDir = path.join(absDir, '.cursor', 'rules');
+    await fs.mkdir(cursorDir, { recursive: true });
+    await fs.writeFile(path.join(cursorDir, 'stowkit-engine.mdc'), `---\ndescription: Rundot 3D Engine — VenusGame, GameObject, Component, physics, animations, StowKit asset loading\nalwaysApply: true\n---\n\n${skillContent}`);
+}

package/dist/orchestrator.js

@@ -263,10 +263,10 @@ export async function fullBuild(projectDir, opts) {
                 for (let si = 0; si < mesh.imported.subMeshes.length; si++) {
                     const matIdx = mesh.imported.subMeshes[si].materialIndex;
                     const matName = mesh.imported.materials[matIdx]?.name;
-                    if (matName) {
+                    if (matName && overrides[matIdx] === undefined) {
                         const matChildId = `${container.id}/${matName}.stowmat`;
                         if (assetsById.has(matChildId)) {
-                            overrides[si] = matChildId;
+                            overrides[matIdx] = matChildId;
                         }
                     }
                 }

package/dist/pipeline.d.ts

@@ -22,6 +22,7 @@ export interface ProcessResult {
     processedSize: number;
     glbChildren?: GlbChildDescriptor[];
     glbExtract?: GlbExtractResult;
+    warnings?: string[];
 }
 export declare function processAsset(id: string, sourceData: Uint8Array, type: AssetType, stringId: string, settings: AssetSettings, ctx: ProcessingContext): Promise<ProcessResult>;
 export declare function processExtractedMesh(childId: string, imported: ImportedMesh, hasSkeleton: boolean, stringId: string, settings: AssetSettings, ctx: ProcessingContext): Promise<ProcessResult>;
@@ -40,3 +41,4 @@ export declare function buildAnimationDataBlobsV2(imported: ImportedMesh): {
     data: Uint8Array;
     metadata: AnimationClipMetadata;
 }[];
+export declare function generateAnimationWarnings(imported: ImportedMesh): string[];

package/dist/pipeline.js

@@ -99,6 +99,7 @@ export async function processAsset(id, sourceData, type, stringId, settings, ctx
         log('importing FBX...');
         const imported = await ctx.meshImporter.import(sourceData, id);
         const animCount = imported.animations?.length ?? 0;
+        const animWarnings = generateAnimationWarnings(imported);
         if (animCount === 0)
             throw new Error('No animation clips found in FBX file');
         const animBlobs = buildAnimationDataBlobsV2(imported);
@@ -117,7 +118,9 @@ export async function processAsset(id, sourceData, type, stringId, settings, ctx
         BlobStore.setProcessed(`${id}:animCount`, new Uint8Array([animBlobs.length]));
         const totalAnimBytes = animBlobs.reduce((s, a) => s + a.data.length, 0);
         log(`animation serialized (${(totalAnimBytes / 1024).toFixed(0)} KB, ${animBlobs.length} clips)`);
-        return { metadata: primary.metadata, processedSize: totalAnimBytes };
+        if (animWarnings.length > 0)
+            log(`warnings: ${animWarnings.join('; ')}`);
+        return { metadata: primary.metadata, processedSize: totalAnimBytes, warnings: animWarnings.length > 0 ? animWarnings : undefined };
     }
     if (type === AssetType.Audio) {
         log('decoding audio...');
@@ -494,3 +497,51 @@ export function buildAnimationDataBlobsV2(imported) {
     }
     return results;
 }
+// ─── Animation Diagnostics ──────────────────────────────────────────────────
+export function generateAnimationWarnings(imported) {
+    const warnings = [];
+    if (!imported.animations || imported.animations.length === 0) {
+        warnings.push('No animation clips found in FBX');
+        return warnings;
+    }
+    const boneNames = new Set((imported.bones ?? []).map(b => b.name));
+    for (const clip of imported.animations) {
+        const prefix = imported.animations.length > 1 ? `Clip "${clip.name}": ` : '';
+        if (!clip.tracks || clip.tracks.length === 0) {
+            warnings.push(`${prefix}No animation tracks`);
+            continue;
+        }
+        if (clip.duration <= 0) {
+            warnings.push(`${prefix}Duration is 0`);
+        }
+        // Check for bone name mismatches
+        const trackBoneNames = new Set();
+        let singleKeyframeTracks = 0;
+        for (const track of clip.tracks) {
+            if (track.name.endsWith('.scale'))
+                continue;
+            const boneName = track.name.split('.')[0];
+            trackBoneNames.add(boneName);
+            if (track.times.length <= 1)
+                singleKeyframeTracks++;
+        }
+        if (boneNames.size > 0 && trackBoneNames.size > 0) {
+            const unmatched = [];
+            for (const tn of trackBoneNames) {
+                if (!boneNames.has(tn))
+                    unmatched.push(tn);
+            }
+            if (unmatched.length > 0 && unmatched.length === trackBoneNames.size) {
+                warnings.push(`${prefix}No track bone names match skeleton (${unmatched.length} unmatched: ${unmatched.slice(0, 3).join(', ')}${unmatched.length > 3 ? '...' : ''})`);
+            }
+            else if (unmatched.length > 0) {
+                warnings.push(`${prefix}${unmatched.length}/${trackBoneNames.size} track bones not in skeleton: ${unmatched.slice(0, 3).join(', ')}${unmatched.length > 3 ? '...' : ''}`);
+            }
+        }
+        const nonScaleTracks = clip.tracks.filter(t => !t.name.endsWith('.scale'));
+        if (singleKeyframeTracks > 0 && singleKeyframeTracks === nonScaleTracks.length) {
+            warnings.push(`${prefix}All ${singleKeyframeTracks} tracks have only 1 keyframe (static pose)`);
+        }
+    }
+    return warnings;
+}

package/dist/server.d.ts

@@ -3,6 +3,8 @@ export interface ServerOptions {
     port?: number;
     projectDir?: string;
     wasmDir?: string;
+    /** Force reprocess all assets on startup, ignoring cache. */
+    force?: boolean;
     /** Static apps to serve. Key = URL prefix (e.g. '/packer'), value = directory path. Use '/' for root. */
     staticApps?: Record<string, string>;
 }

package/dist/server.js

@@ -327,10 +327,10 @@ async function processGlbContainer(containerId) {
                     for (let si = 0; si < mesh.imported.subMeshes.length; si++) {
                         const matIdx = mesh.imported.subMeshes[si].materialIndex;
                         const matName = mesh.imported.materials[matIdx]?.name;
-                        if (matName) {
+                        if (matName && overrides[matIdx] === undefined) {
                             const matChildId = `${containerId}/${matName}.stowmat`;
                             if (childAssets.some(a => a.id === matChildId)) {
-                                overrides[si] = matChildId;
+                                overrides[matIdx] = matChildId;
                             }
                         }
                     }
@@ -735,6 +735,7 @@ async function processOneAsset(id) {
             asset.metadata = result.metadata;
             asset.processedSize = result.processedSize;
             asset.sourceSize = sourceData.length;
+            asset.warnings = result.warnings;
             broadcast({
                 type: 'asset-update', id,
                 updates: {
@@ -742,6 +743,7 @@ async function processOneAsset(id) {
                     metadata: result.metadata,
                     processedSize: result.processedSize,
                     sourceSize: sourceData.length,
+                    warnings: result.warnings,
                 },
             });
         }
@@ -1576,7 +1578,7 @@ export async function startServer(opts = {}) {
     // Open project if specified (skip if already loaded — e.g. stowkit editor starts two servers)
     if (opts.projectDir && (!projectConfig || projectConfig.projectDir !== opts.projectDir)) {
         await openProject(opts.projectDir);
-        queueProcessing();
+        queueProcessing({ force: opts.force });
     }
     return new Promise((resolve) => {
         server.listen(port, () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,8 +17,8 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.16",
-    "@series-inc/stowkit-editor": "^0.1.2",
+    "@series-inc/stowkit-packer-gui": "^0.1.17",
+    "@series-inc/stowkit-editor": "^0.1.3",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",

package/skill.md

@@ -36,7 +36,8 @@ A StowKit project has a `.felicityproject` JSON file at its root:
 ## CLI Commands
 
 ```bash
-stowkit init [dir]              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
+stowkit init [dir]              # Scaffold a new project (interactive menu: pipeline only or with 3D engine)
+stowkit init --with-engine      # Scaffold with 3D engine pre-installed
 stowkit init --update [dir]     # Update AI skill files to match installed CLI version
 stowkit update                  # Update CLI to latest version and refresh skill files
 stowkit version                 # Show installed version