incanto 0.1.0

package/bin/incanto-model.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/**
+ * incanto-model — inspect a GLB/glTF/VRM file and report what an agent cannot
+ * guess from the file name: node hierarchy, mesh stats, the TRANSFORMED scene
+ * bounding box (size/center), animations, materials, and VRM meta/humanoid.
+ *
+ *   npx incanto-model character.vrm          # human summary
+ *   npx incanto-model level.glb --json       # full machine-readable report
+ *
+ * Bounding boxes come from glTF POSITION accessor min/max transformed through
+ * each node's TRS chain — for skinned meshes that is the BIND pose.
+ */
+import { readFileSync } from 'node:fs';
+
+function parseArgs(argv) {
+  const args = { file: undefined, json: false };
+  for (const a of argv) {
+    if (a === '--json') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (!a.startsWith('-') && !args.file) args.file = a;
+    else {
+      console.error(`unknown argument: ${a}`);
+      args.error = true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.error || !args.file) {
+  console.log(`Usage: npx incanto-model <file.glb|.gltf|.vrm> [--json]
+
+Reports hierarchy, mesh stats, scene bounding box, animations, and VRM meta —
+the numbers you need to size and place a model in a scene.`);
+  process.exit(args.help && !args.error ? 0 : 1);
+}
+
+// ---- container parsing --------------------------------------------------------------
+
+function readGltfJson(file) {
+  const data = readFileSync(file);
+  if (data.length >= 12 && data.readUInt32LE(0) === 0x46546c67) {
+    // GLB container: header(12) then chunks [len][type][payload]
+    let offset = 12;
+    while (offset + 8 <= data.length) {
+      const len = data.readUInt32LE(offset);
+      const type = data.readUInt32LE(offset + 4);
+      if (type === 0x4e4f534a) {
+        return JSON.parse(data.subarray(offset + 8, offset + 8 + len).toString('utf-8'));
+      }
+      offset += 8 + len + ((4 - (len % 4)) % 4);
+    }
+    throw new Error('GLB has no JSON chunk');
+  }
+  return JSON.parse(data.toString('utf-8')); // raw .gltf
+}
+
+// ---- minimal mat4 (column-major, like glTF) -------------------------------------------
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+
+function composeTrs(node) {
+  if (node.matrix) return node.matrix;
+  const [tx, ty, tz] = node.translation ?? [0, 0, 0];
+  const [qx, qy, qz, qw] = node.rotation ?? [0, 0, 0, 1];
+  const [sx, sy, sz] = node.scale ?? [1, 1, 1];
+  const x2 = qx + qx,
+    y2 = qy + qy,
+    z2 = qz + qz;
+  const xx = qx * x2,
+    xy = qx * y2,
+    xz = qx * z2;
+  const yy = qy * y2,
+    yz = qy * z2,
+    zz = qz * z2;
+  const wx = qw * x2,
+    wy = qw * y2,
+    wz = qw * z2;
+  return [
+    (1 - (yy + zz)) * sx,
+    (xy + wz) * sx,
+    (xz - wy) * sx,
+    0,
+    (xy - wz) * sy,
+    (1 - (xx + zz)) * sy,
+    (yz + wx) * sy,
+    0,
+    (xz + wy) * sz,
+    (yz - wx) * sz,
+    (1 - (xx + yy)) * sz,
+    0,
+    tx,
+    ty,
+    tz,
+    1,
+  ];
+}
+
+function mulMat4(a, b) {
+  const out = new Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      out[c * 4 + r] =
+        a[r] * b[c * 4] +
+        a[4 + r] * b[c * 4 + 1] +
+        a[8 + r] * b[c * 4 + 2] +
+        a[12 + r] * b[c * 4 + 3];
+    }
+  }
+  return out;
+}
+
+function transformPoint(m, [x, y, z]) {
+  return [
+    m[0] * x + m[4] * y + m[8] * z + m[12],
+    m[1] * x + m[5] * y + m[9] * z + m[13],
+    m[2] * x + m[6] * y + m[10] * z + m[14],
+  ];
+}
+
+// ---- analysis ------------------------------------------------------------------------
+
+function round(n) {
+  return Math.round(n * 1000) / 1000;
+}
+
+function bboxOf(min, max) {
+  return {
+    min: min.map(round),
+    max: max.map(round),
+    size: max.map((v, i) => round(v - min[i])),
+    center: max.map((v, i) => round((v + min[i]) / 2)),
+  };
+}
+
+function analyze(json) {
+  const meshes = (json.meshes ?? []).map((mesh) => {
+    let vertices = 0;
+    let triangles = 0;
+    let min = null;
+    let max = null;
+    for (const prim of mesh.primitives ?? []) {
+      const pos = json.accessors?.[prim.attributes?.POSITION];
+      if (pos) {
+        vertices += pos.count ?? 0;
+        if (pos.min && pos.max) {
+          min = min ? min.map((v, i) => Math.min(v, pos.min[i])) : [...pos.min];
+          max = max ? max.map((v, i) => Math.max(v, pos.max[i])) : [...pos.max];
+        }
+      }
+      const idx = json.accessors?.[prim.indices];
+      const drawn = idx?.count ?? pos?.count ?? 0;
+      const mode = prim.mode ?? 4; // TRIANGLES default
+      if (mode === 4) triangles += Math.floor(drawn / 3);
+      else if (mode === 5 || mode === 6) triangles += Math.max(0, drawn - 2); // strip/fan
+    }
+    return {
+      name: mesh.name ?? '(unnamed mesh)',
+      primitives: (mesh.primitives ?? []).length,
+      vertices,
+      triangles,
+      bbox: min && max ? bboxOf(min, max) : null,
+      localMin: min,
+      localMax: max,
+    };
+  });
+
+  // hierarchy + scene bbox (transform each mesh's 8 corners through the TRS chain)
+  const nodes = [];
+  let sceneMin = null;
+  let sceneMax = null;
+  const seen = new Set(); // corrupt files can contain cycles — never recurse forever
+  const visit = (index, depth, parentMat) => {
+    if (seen.has(index) || depth > 256) return;
+    seen.add(index);
+    const node = json.nodes?.[index];
+    if (!node) return;
+    const mat = mulMat4(parentMat, composeTrs(node));
+    const entry = {
+      name: node.name ?? `(node ${index})`,
+      depth,
+      children: (node.children ?? []).length,
+    };
+    if (node.mesh !== undefined)
+      entry.mesh = meshes[node.mesh]?.name ?? `(missing mesh #${node.mesh})`;
+    if (node.skin !== undefined) entry.skinned = true;
+    nodes.push(entry);
+    const mesh = node.mesh !== undefined ? meshes[node.mesh] : null;
+    if (mesh?.localMin && mesh.localMax) {
+      for (const x of [mesh.localMin[0], mesh.localMax[0]]) {
+        for (const y of [mesh.localMin[1], mesh.localMax[1]]) {
+          for (const z of [mesh.localMin[2], mesh.localMax[2]]) {
+            const p = transformPoint(mat, [x, y, z]);
+            sceneMin = sceneMin ? sceneMin.map((v, i) => Math.min(v, p[i])) : [...p];
+            sceneMax = sceneMax ? sceneMax.map((v, i) => Math.max(v, p[i])) : [...p];
+          }
+        }
+      }
+    }
+    for (const child of node.children ?? []) visit(child, depth + 1, mat);
+  };
+  const sceneIndex = json.scene ?? 0;
+  for (const rootIndex of json.scenes?.[sceneIndex]?.nodes ?? []) visit(rootIndex, 0, IDENTITY);
+
+  const animations = (json.animations ?? []).map((anim) => {
+    let duration = 0;
+    for (const sampler of anim.samplers ?? []) {
+      const input = json.accessors?.[sampler.input];
+      if (input?.max?.[0] !== undefined) duration = Math.max(duration, input.max[0]);
+    }
+    return { name: anim.name ?? '(unnamed)', duration: round(duration) };
+  });
+
+  let vrm = null;
+  if (json.extensions?.VRM) {
+    const v = json.extensions.VRM;
+    vrm = {
+      spec: '0.x',
+      name: v.meta?.title ?? null,
+      authors: v.meta?.author ? [v.meta.author] : [],
+      humanBones: (v.humanoid?.humanBones ?? []).length,
+    };
+  } else if (json.extensions?.VRMC_vrm) {
+    const v = json.extensions.VRMC_vrm;
+    vrm = {
+      spec: '1.0',
+      name: v.meta?.name ?? null,
+      authors: v.meta?.authors ?? [],
+      humanBones: Object.keys(v.humanoid?.humanBones ?? {}).length,
+    };
+  }
+
+  return {
+    generator: json.asset?.generator ?? null,
+    nodes,
+    meshes: meshes.map(({ localMin, localMax, ...rest }) => rest),
+    bbox: sceneMin && sceneMax ? bboxOf(sceneMin, sceneMax) : null,
+    animations,
+    materials: (json.materials ?? []).map((m, i) => m.name ?? `(material ${i})`),
+    textures: (json.textures ?? []).length,
+    skins: (json.skins ?? []).length,
+    vrm,
+  };
+}
+
+// ---- output --------------------------------------------------------------------------
+
+let report;
+try {
+  const json = readGltfJson(args.file);
+  if (!json.asset?.version) throw new Error('missing glTF asset header');
+  report = {
+    file: args.file,
+    format: readFileSync(args.file).readUInt32LE(0) === 0x46546c67 ? 'glb' : 'gltf',
+    ...analyze(json),
+  };
+} catch (error) {
+  console.error(`not a glTF/GLB/VRM file: ${String(error.message ?? error)}`);
+  process.exit(1);
+}
+
+if (args.json) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  const out = [];
+  out.push(`${report.file} (${report.format}${report.vrm ? ` · VRM ${report.vrm.spec}` : ''})`);
+  if (report.vrm) {
+    out.push(
+      `  avatar: ${report.vrm.name ?? '?'} by ${report.vrm.authors.join(', ') || '?'} · ${report.vrm.humanBones} humanoid bones`,
+    );
+  }
+  if (report.bbox) {
+    out.push(
+      `  size:   ${report.bbox.size.join(' × ')}  center: [${report.bbox.center.join(', ')}]`,
+    );
+    out.push(`  bounds: [${report.bbox.min.join(', ')}] → [${report.bbox.max.join(', ')}]`);
+  }
+  out.push(
+    `  nodes:  ${report.nodes.length} · skins: ${report.skins} · materials: ${report.materials.length} · textures: ${report.textures}`,
+  );
+  for (const node of report.nodes.slice(0, 40)) {
+    out.push(
+      `    ${'  '.repeat(node.depth)}${node.name}${node.mesh ? ` ▸ ${node.mesh}` : ''}${node.skinned ? ' (skinned)' : ''}`,
+    );
+  }
+  if (report.nodes.length > 40) out.push(`    … ${report.nodes.length - 40} more`);
+  for (const mesh of report.meshes) {
+    out.push(
+      `  mesh ${mesh.name}: ${mesh.vertices} verts · ${mesh.triangles} tris${mesh.bbox ? ` · size ${mesh.bbox.size.join('×')}` : ''}`,
+    );
+  }
+  for (const anim of report.animations) {
+    out.push(`  anim ${anim.name}: ${anim.duration}s`);
+  }
+  console.log(out.join('\n'));
+}

package/bin/incanto-play.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * incanto-play — play a scene HEADLESSLY from bash. The agent's gamepad:
+ * feed inputs over stdin, advance simulated time, and capture the CURRENT
+ * state as scene JSON — the same format as a saved *.scene.json, so reading
+ * a capture is reading the screen.
+ *
+ *   bunx incanto-play src/game.scene.json --behaviors src/behaviors.ts
+ *
+ * stdin protocol (one command per line; every response is one JSON line):
+ *   step <ms>                advance the simulation
+ *   press <action>           hold a button action      release <action>
+ *   vector <action> <x> <y>  analog direction ((0 0) clears)
+ *   key <code> down|up       raw KeyboardEvent.code    mouse <0|1|2> down|up
+ *   pointer <dx> <dy>        look deltas               wheel <dy>
+ *   capture [file]           current state as scene JSON (stdout or file)
+ *   describe                 one line per node, non-default props only
+ *   logs                     engine.log entries since the last call
+ *   quit
+ *
+ * Without --behaviors, unregistered scripts are stubbed (structure-only play).
+ * --behaviors accepts .ts directly (node 23.6+ type stripping / bun).
+ */
+import { createInterface } from 'node:readline';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function parseArgs(argv) {
+  const args = {
+    scene: undefined,
+    behaviors: undefined,
+    seed: undefined,
+    fixedHz: undefined,
+    commands: undefined,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--behaviors') args.behaviors = argv[++i];
+    else if (a === '--seed') args.seed = Number(argv[++i]);
+    else if (a === '--fixed-hz') args.fixedHz = Number(argv[++i]);
+    else if (a === '--commands') args.commands = argv[++i];
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) {
+      console.error(`unknown flag: ${a}`);
+      args.help = true;
+    } else if (!args.scene) args.scene = a;
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !args.scene) {
+  console.error(`Usage: incanto-play <scene.json> [--behaviors <file.ts|.js>] [--seed N] [--fixed-hz 60] [--commands <file>]
+
+Headless play: stdin commands (step/press/release/vector/key/mouse/pointer/
+wheel/capture/describe/logs/quit), JSON-line responses on stdout.`);
+  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+}
+
+const out = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+const fail = (cmd, e) =>
+  out({ ok: false, cmd, error: { code: e?.code ?? 'ERROR', message: e?.message ?? String(e) } });
+
+const { createPlaySession } = await import(pathToFileURL(join(PKG, 'dist', 'test.js')).href);
+const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+// --behaviors: import the consumer module (TS works on node >= 23.6 / bun)
+// and register every exported Behavior subclass under its export name.
+const behaviors = {};
+if (args.behaviors) {
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+  } catch (e) {
+    const reason =
+      e?.code === 'ERR_MODULE_NOT_FOUND' && String(e.message).includes(resolve(args.behaviors))
+        ? 'file not found'
+        : (e?.message ?? String(e));
+    out({
+      ok: false,
+      cmd: 'behaviors',
+      error: {
+        code: e?.code ?? 'BEHAVIORS_LOAD_FAILED',
+        message: `could not load --behaviors '${args.behaviors}' (${reason}). Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.`,
+      },
+    });
+    process.exit(1);
+  }
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === 'function' && value.prototype instanceof incanto.Behavior) {
+      behaviors[name] = value;
+    }
+  }
+  if (Object.keys(behaviors).length === 0) {
+    console.error(`warning: no Behavior subclasses exported from ${args.behaviors}`);
+  }
+}
+
+const sceneJson = JSON.parse(readFileSync(resolve(args.scene), 'utf-8'));
+let session;
+try {
+  session = await createPlaySession(sceneJson, {
+    behaviors,
+    stubMissingBehaviors: !args.behaviors, // structure-only play without code
+    seed: args.seed,
+    fixedHz: args.fixedHz,
+    resolveScene: (p) =>
+      JSON.parse(readFileSync(resolve(dirname(resolve(args.scene)), p), 'utf-8')),
+  });
+} catch (e) {
+  fail('load', e);
+  process.exit(1);
+}
+
+out({
+  ok: true,
+  ready: true,
+  scene: session.scene.name,
+  dimension: session.scene.dimension ?? null,
+  behaviors: Object.keys(behaviors),
+  stubbed: !args.behaviors,
+});
+
+function handle(line) {
+  const [cmd, ...parts] = line.trim().split(/\s+/);
+  if (!cmd) return true;
+  try {
+    switch (cmd) {
+      case 'step': {
+        session.step(Number(parts[0] ?? 16.7));
+        out({ ok: true, cmd, t: Math.round(session.timeMs) });
+        break;
+      }
+      case 'press':
+        session.engine.input.pressAction(parts[0]);
+        out({ ok: true, cmd, action: parts[0] });
+        break;
+      case 'release':
+        session.engine.input.releaseAction(parts[0]);
+        out({ ok: true, cmd, action: parts[0] });
+        break;
+      case 'vector':
+        session.engine.input.setActionVector(parts[0], Number(parts[1]), Number(parts[2]));
+        out({ ok: true, cmd, action: parts[0] });
+        break;
+      case 'key':
+        session.engine.input.handleKey(parts[0], parts[1] !== 'up');
+        out({ ok: true, cmd, code: parts[0] });
+        break;
+      case 'mouse':
+        session.engine.input.handleMouseButton(Number(parts[0]), parts[1] !== 'up');
+        out({ ok: true, cmd });
+        break;
+      case 'pointer':
+        session.engine.input.handlePointerMove(Number(parts[0]), Number(parts[1]));
+        out({ ok: true, cmd });
+        break;
+      case 'wheel':
+        session.engine.input.handleWheel(Number(parts[0]));
+        out({ ok: true, cmd });
+        break;
+      case 'capture': {
+        const scene = session.capture();
+        if (parts[0]) {
+          writeFileSync(resolve(parts[0]), `${JSON.stringify(scene, null, 2)}\n`);
+          out({ ok: true, cmd, t: Math.round(session.timeMs), file: resolve(parts[0]) });
+        } else {
+          out({ ok: true, cmd, t: Math.round(session.timeMs), scene });
+        }
+        break;
+      }
+      case 'describe':
+        out({ ok: true, cmd, text: session.describe() });
+        break;
+      case 'logs':
+        out({ ok: true, cmd, entries: session.drainLogs() });
+        break;
+      case 'quit':
+        session.dispose();
+        out({ ok: true, cmd });
+        return false;
+      default:
+        out({
+          ok: false,
+          cmd,
+          error: {
+            code: 'UNKNOWN_COMMAND',
+            message: `unknown command '${cmd}'. Commands: step press release vector key mouse pointer wheel capture describe logs quit`,
+          },
+        });
+    }
+  } catch (e) {
+    fail(cmd, e);
+  }
+  return true;
+}
+
+if (args.commands) {
+  for (const line of readFileSync(resolve(args.commands), 'utf-8').split('\n')) {
+    if (!handle(line)) process.exit(0);
+  }
+  session.dispose();
+  process.exit(0);
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  if (!handle(line)) {
+    rl.close();
+    process.exit(0);
+  }
+});
+rl.on('close', () => {
+  session.dispose();
+  process.exit(0);
+});

package/bin/incanto-skills.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * incanto-skills — install this package's agent skills into your project so an
+ * AI agent launched there can vibe-code games with the INSTALLED engine version.
+ *
+ *   npx incanto-skills --format claude     → .claude/skills/<name>/SKILL.md
+ *   npx incanto-skills --format opencode   → skills/<name>.md (flat)
+ *   npx incanto-skills --format claude --out custom/dir
+ *
+ * Skills are copied from the installed package (node_modules/incanto/skills),
+ * so they always match the engine version your project depends on.
+ */
+import { copyFileSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+
+function parseArgs(argv) {
+  const args = { format: 'claude', out: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--format') args.format = argv[++i];
+    else if (argv[i] === '--out') args.out = argv[++i];
+    else if (argv[i] === '--help' || argv[i] === '-h') args.help = true;
+    else {
+      console.error(`unknown argument: ${argv[i]}`);
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || !['claude', 'opencode'].includes(args.format)) {
+  console.log(`Usage: npx incanto-skills [--format claude|opencode] [--out <dir>]
+
+  claude    (default) Claude Code project skills:
+            <out>/<skill-name>/SKILL.md          (default out: .claude/skills)
+  opencode  flat markdown files:
+            <out>/<skill-name>.md                (default out: skills)
+
+Skills are read from the installed incanto package and match its version.`);
+  process.exit(args.help ? 0 : 1);
+}
+
+const outRoot = resolve(args.out ?? (args.format === 'claude' ? '.claude/skills' : 'skills'));
+const files = readdirSync(SKILLS_DIR).filter((f) => f.startsWith('incanto-') && f.endsWith('.md'));
+if (files.length === 0) {
+  console.error(`no incanto-*.md skills found in ${SKILLS_DIR}`);
+  process.exit(1);
+}
+
+for (const file of files) {
+  const name = basename(file, '.md');
+  if (args.format === 'claude') {
+    const dir = join(outRoot, name);
+    mkdirSync(dir, { recursive: true });
+    copyFileSync(join(SKILLS_DIR, file), join(dir, 'SKILL.md'));
+  } else {
+    mkdirSync(outRoot, { recursive: true });
+    copyFileSync(join(SKILLS_DIR, file), join(outRoot, file));
+  }
+}
+
+// A tiny manifest so tooling (and humans) can see what was installed from where.
+writeFileSync(
+  join(outRoot, 'incanto-skills.json'),
+  `${JSON.stringify({ source: 'incanto', format: args.format, skills: files.map((f) => basename(f, '.md')) }, null, 2)}\n`,
+);
+
+console.log(`installed ${files.length} incanto skills (${args.format} format) → ${outRoot}`);