incanto 0.1.0

package/assets/characters/goblin.json

@@ -0,0 +1,40 @@
+{
+  "frame": {
+    "width": 192,
+    "height": 192
+  },
+  "origin": {
+    "x": 0.5,
+    "y": 0.6
+  },
+  "body": {
+    "size": {
+      "width": 60,
+      "height": 60
+    },
+    "offset": {
+      "x": 66,
+      "y": 76
+    }
+  },
+  "animations": {
+    "idle": {
+      "start": 0,
+      "end": 6,
+      "frameRate": 10,
+      "repeat": -1
+    },
+    "move": {
+      "start": 7,
+      "end": 12,
+      "frameRate": 10,
+      "repeat": -1
+    },
+    "attack": {
+      "start": 14,
+      "end": 19,
+      "frameRate": 10,
+      "repeat": 0
+    }
+  }
+}

package/assets/characters/medieval-knight.json

@@ -0,0 +1,41 @@
+{
+  "frame": {
+    "width": 192,
+    "height": 192
+  },
+  "direction": "right",
+  "origin": {
+    "x": 0.5,
+    "y": 0.61
+  },
+  "body": {
+    "size": {
+      "width": 60,
+      "height": 60
+    },
+    "offset": {
+      "x": 66,
+      "y": 76
+    }
+  },
+  "animations": {
+    "idle": {
+      "start": 0,
+      "end": 5,
+      "frameRate": 10,
+      "repeat": -1
+    },
+    "move": {
+      "start": 6,
+      "end": 11,
+      "frameRate": 10,
+      "repeat": -1
+    },
+    "attack": {
+      "start": 12,
+      "end": 17,
+      "frameRate": 10,
+      "repeat": 0
+    }
+  }
+}

package/bin/incanto-assets.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * incanto-assets — the built-in asset catalog (shipped IN the package, no
+ * network, owner-licensed). Find art, copy it into your project, and get the
+ * ready-to-paste scene JSON.
+ *
+ *   npx incanto-assets list [--json]        what ships (characters/tiles/items/effects)
+ *   npx incanto-assets info <name>          description + animation details
+ *   npx incanto-assets copy <name> --out public/assets
+ *                                           copy the file(s) + print the scene snippet
+ *
+ * External art still works the usual way (any URL in scene assets{}) — this
+ * is the zero-setup starting set.
+ */
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const ASSETS = join(PKG, 'assets');
+
+function catalog() {
+  return JSON.parse(readFileSync(join(ASSETS, 'catalog.json'), 'utf-8'));
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`Usage:
+  incanto-assets list [--json]
+  incanto-assets info <name>
+  incanto-assets copy <name> --out <dir>`);
+  process.exit(command ? 0 : 1);
+}
+
+if (command === 'list') {
+  const entries = catalog();
+  if (rest.includes('--json')) {
+    console.log(JSON.stringify(entries, null, 2));
+  } else {
+    for (const e of entries) {
+      const anim = e.animation ? ' [animated]' : '';
+      console.log(
+        `${e.name.padEnd(20)} ${e.kind.padEnd(10)}${anim.padEnd(11)} ${e.description.slice(0, 80)}`,
+      );
+    }
+    console.log(`\n${entries.length} built-in asset(s) — incanto-assets info <name> for details`);
+  }
+  // NO process.exit() here: piped stdout flushes asynchronously on POSIX, so
+  // exit() truncates any output past one ~8 KB pipe buffer (the catalog
+  // crossed that line when the bark/ground textures joined it). Falling off
+  // the end of the script lets node drain stdout before exiting.
+  process.exitCode = 0;
+} else {
+  const name = rest.find((a) => !a.startsWith('--'));
+  const entry = catalog().find((e) => e.name === name);
+  if (!entry) {
+    const names = catalog().map((e) => e.name);
+    console.error(`unknown asset '${name ?? ''}'. Available: [${names.join(', ')}]`);
+    process.exit(1);
+  }
+
+  if (command === 'info') {
+    console.log(JSON.stringify(entry, null, 2));
+    if (entry.animation) {
+      const meta = JSON.parse(readFileSync(join(ASSETS, entry.animation), 'utf-8'));
+      console.log('\nanimations:', Object.keys(meta.animations ?? {}).join(', '));
+    }
+    process.exitCode = 0; // see the list note — exit() truncates piped stdout
+  } else if (command === 'copy') {
+    const outFlag = rest.indexOf('--out');
+    const outDir = resolve(outFlag !== -1 ? rest[outFlag + 1] : 'public/assets');
+    mkdirSync(outDir, { recursive: true });
+    const copied = [];
+    for (const file of [entry.file, entry.animation].filter(Boolean)) {
+      const target = join(outDir, basename(file));
+      copyFileSync(join(ASSETS, file), target);
+      copied.push(target);
+    }
+    for (const t of copied) console.log(`copied ${t}`);
+
+    // Ready-to-paste scene JSON (sheet assets get full animation wiring).
+    const url = `assets/${basename(entry.file)}`;
+    if (entry.animation) {
+      const { spriteFromLibraryMeta } = await import(
+        pathToFileURL(join(PKG, 'dist', '2d.js')).href
+      );
+      const meta = JSON.parse(readFileSync(join(ASSETS, entry.animation), 'utf-8'));
+      const { asset, props } = spriteFromLibraryMeta(meta, { url, assetKey: entry.name });
+      console.log(`\nscene assets entry:\n  "${entry.name}": ${JSON.stringify(asset)}`);
+      console.log(
+        `\nnode:\n  ${JSON.stringify({ name: entry.name, type: 'AnimatedSprite2D', props }, null, 2)}`,
+      );
+    } else {
+      console.log(
+        `\nscene assets entry:\n  "${entry.name}": ${JSON.stringify({ type: 'texture', url })}`,
+      );
+      console.log(
+        `\nnode:\n  ${JSON.stringify({ name: entry.name, type: 'Sprite2D', props: { texture: `$${entry.name}` } })}`,
+      );
+    }
+    process.exitCode = 0;
+  } else {
+    console.error(`unknown command '${command}'`);
+    process.exit(1);
+  }
+}

package/bin/incanto-check.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * incanto-check — headless scene validation. Every hard load error the engine
+ * would throw in the browser, on the command line instead (the agent's
+ * after-every-edit check; production VMs have no browser).
+ *
+ *   npx incanto-check                       → validates every *.scene.json under cwd
+ *   npx incanto-check src/game.scene.json   → specific files (or directories)
+ *   npx incanto-check --json                → machine-readable report
+ *   npx incanto-check --strict-behaviors    → unregistered script names fail too
+ *
+ * Unregistered behaviors are STUBBED by default: structure-only validation
+ * that needs no TypeScript. Sub-scene `instance` paths resolve relative to
+ * each scene file.
+ */
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DIST = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist');
+
+function parseArgs(argv) {
+  const args = { files: [], json: false, strict: false, help: false, invalid: false };
+  for (const a of argv) {
+    if (a === '--json') args.json = true;
+    else if (a === '--strict-behaviors') args.strict = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) {
+      console.error(`unknown flag: ${a}`);
+      args.invalid = true;
+    } else args.files.push(a);
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.invalid) {
+  console.log(`Usage: npx incanto-check [files|dirs...] [--json] [--strict-behaviors]
+
+Validates *.scene.json files headlessly with the installed engine.
+With no arguments, scans the current directory recursively
+(skipping node_modules and dist).`);
+  process.exit(args.invalid ? 1 : 0);
+}
+
+function collectScenes(entry) {
+  const stat = statSync(entry);
+  if (stat.isFile()) return entry.endsWith('.scene.json') ? [entry] : [];
+  const out = [];
+  for (const item of readdirSync(entry, { withFileTypes: true })) {
+    if (item.name === 'node_modules' || item.name === 'dist' || item.name.startsWith('.')) {
+      continue;
+    }
+    const full = join(entry, item.name);
+    if (lstatSync(full).isSymbolicLink()) continue; // no symlink-loop recursion
+    out.push(...collectScenes(full));
+  }
+  return out;
+}
+
+const roots = args.files.length > 0 ? args.files : ['.'];
+for (const r of roots) {
+  if (!existsSync(resolve(r))) {
+    console.error(`no such file or directory: ${r}`);
+    process.exit(1);
+  }
+}
+const files = roots.flatMap((r) => collectScenes(resolve(r)));
+if (files.length === 0) {
+  console.error('no *.scene.json files found');
+  process.exit(1);
+}
+
+const { validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
+
+const results = files.map((file) => {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return { file, ok: false, code: 'BAD_JSON', message: String(e?.message ?? e) };
+  }
+  const res = validateScene(json, {
+    strictBehaviors: args.strict,
+    resolveScene: (p) => JSON.parse(readFileSync(resolve(dirname(file), p), 'utf-8')),
+  });
+  if (res.ok) return { file, ok: true };
+  return {
+    file,
+    ok: false,
+    code: res.error?.code,
+    message: res.error?.message,
+    details: res.error?.details,
+  };
+});
+
+const failed = results.filter((r) => !r.ok);
+if (args.json) {
+  console.log(JSON.stringify({ ok: failed.length === 0, results }, null, 2));
+} else {
+  for (const r of results) {
+    if (r.ok) console.log(`  ok  ${r.file}`);
+    else console.log(`FAIL  ${r.file}\n      [${r.code}] ${r.message}`);
+  }
+  console.log(`\n${results.length - failed.length}/${results.length} scene(s) valid`);
+}
+process.exit(failed.length === 0 ? 0 : 1);