@idajs/create-mod 0.2.11 → 0.2.15-dev.37

package/README.md

@@ -24,6 +24,12 @@ npx @idajs/create-mod
 
 The tool will guide you through the setup process with interactive prompts.
 
+Refresh scaffolder-managed files in an existing mod project:
+
+```pwsh
+npx @idajs/create-mod --update
+```
+
 ## Usage
 
 ```pwsh

package/_project.config/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## What is IdaJS
+
+IdaJS is a JavaScript-powered modding engine for Little Big Adventure 2 (LBA2). It lets you create mods for the classic LBA2 game using JavaScript or TypeScript — modifying scenes, characters, behaviors, dialogs, and more through a modern scripting API.
+
+## API Reference
+
+The full IdaJS TypeScript API with JSDoc documentation is available in `./node_modules/@idajs/types/`, structured by entities. The global objects (such as `scene`, `ida`, `text`, `object`, etc.) are defined in `global.d.ts`. Always consult these type definitions when implementing any feature.
+
+## Mod Execution Phases
+
+Different phases of mod execution allow different APIs. Be aware which phase you are in:
+
+- **Scene setup phase** (`scene.Events.afterLoadScene` handler): Configure the scene before gameplay starts. Use `scene`, `object`, `text`, zone and waypoint APIs to add/modify objects, zones, waypoints, register life script handlers, register coroutines, and set initial state. Do **not** call life or move script commands here.
+- **Life script handler** (`handleLifeScript`): Runs every frame per actor. Use `ida.life()` and `ida.lifef()` for life script commands/functions (conditions, dialogs, state changes). Can start/pause/stop coroutines from here.
+- **Coroutine (move script)** (generator function registered via `registerCoroutine`): Runs across multiple frames. Use `yield doMove()` for move commands (animations, movement, timing) and other `yield do...()` helpers (`doSceneStore`, `doGameStore`, etc.). Cannot check game conditions directly — that logic belongs in life scripts.
+
+## Mod Examples
+
+For examples of working mods, look at `Ida/Samples` in the IdaJS installation folder. The path to the installation folder is written in a JSON file either in the user's home directory: `~/.idajs.json` or in the root directory of this project.
+
+## Web Documentation
+
+Full readme, API reference, and guides are available at: https://ida.innerbytes.com

package/_project.config/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/_project.config/archive.js

@@ -0,0 +1,107 @@
+const fs = require("fs");
+const path = require("path");
+const yazl = require("yazl");
+
+function normalizeZipPath(value) {
+  return String(value || "")
+    .split(path.sep)
+    .join("/")
+    .replace(/\/+/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+}
+
+async function collectDirectoryEntries(sourceDir, zipRoot) {
+  const dirents = await fs.promises.readdir(sourceDir, { withFileTypes: true });
+  const sortedDirents = dirents.slice().sort((a, b) => a.name.localeCompare(b.name));
+  const entries = [];
+
+  if (sortedDirents.length === 0 && zipRoot) {
+    entries.push({
+      type: "directory",
+      metadataPath: normalizeZipPath(zipRoot),
+    });
+  }
+
+  for (const dirent of sortedDirents) {
+    const sourcePath = path.join(sourceDir, dirent.name);
+    const metadataPath = normalizeZipPath(path.posix.join(zipRoot, dirent.name));
+
+    if (dirent.isDirectory()) {
+      entries.push(...(await collectDirectoryEntries(sourcePath, metadataPath)));
+      continue;
+    }
+
+    if (dirent.isFile()) {
+      entries.push({
+        type: "file",
+        sourcePath,
+        metadataPath,
+      });
+      continue;
+    }
+
+    throw new Error(`Unsupported entry type in archive source: ${sourcePath}`);
+  }
+
+  return entries;
+}
+
+async function createZipFromDirectories(zipPath, mappings, options = {}) {
+  const zipfile = new yazl.ZipFile();
+  const output = fs.createWriteStream(zipPath);
+  const zipOptions = {};
+
+  if (typeof options.compressionLevel === "number") {
+    zipOptions.compressionLevel = options.compressionLevel;
+  }
+
+  const collectedEntries = [];
+  for (const mapping of mappings) {
+    if (!fs.existsSync(mapping.sourceDir)) {
+      throw new Error(`Source directory not found: ${mapping.sourceDir}`);
+    }
+
+    collectedEntries.push(...(await collectDirectoryEntries(mapping.sourceDir, mapping.zipRoot)));
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    function finish(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    }
+
+    output.on("close", () => finish());
+    output.on("error", finish);
+    zipfile.outputStream.on("error", finish);
+
+    zipfile.outputStream.pipe(output);
+
+    try {
+      for (const entry of collectedEntries) {
+        if (entry.type === "directory") {
+          zipfile.addEmptyDirectory(entry.metadataPath);
+        } else {
+          zipfile.addFile(entry.sourcePath, entry.metadataPath, zipOptions);
+        }
+      }
+
+      zipfile.end();
+    } catch (error) {
+      finish(error);
+    }
+  });
+}
+
+module.exports = {
+  createZipFromDirectories,
+};

package/_project.config/build.js

@@ -1,14 +1,15 @@
 const { execSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
-const archiver = require("archiver");
+const { createZipFromDirectories } = require("./archive");
+const { getPackageName } = require("./project");
 
 // Get mod name from command line argument
-const modName = process.argv[2];
+const modName = process.argv[2] || getPackageName();
 
 if (!modName) {
   console.error("Error: Mod name is required as an argument");
-  console.error("Usage: node build.js <mod-name>");
+  console.error("Usage: node build.js [mod-name]");
   process.exit(1);
 }
 
@@ -61,47 +62,31 @@ if (!fs.existsSync(buildFolder)) {
 
 // Create zip file
 const zipPath = path.join(buildFolder, `${modName}.zip`);
-const output = fs.createWriteStream(zipPath);
-const archive = archiver("zip", {
-  zlib: { level: 9 }, // Maximum compression
-});
 
-console.log(`Creating ${zipPath}...`);
+async function main() {
+  console.log(`Creating ${zipPath}...`);
 
-// Handle archive events
-output.on("close", () => {
-  const sizeInKB = (archive.pointer() / 1024).toFixed(2);
-  console.log(`✓ Build complete: ${zipPath} (${sizeInKB} KB)`);
-});
+  const mappings = [{ sourceDir: sourceFolder, zipRoot: modName }];
 
-archive.on("error", (err) => {
-  console.error("Error creating archive:", err);
-  process.exit(1);
-});
+  console.log(`Adding ${sourceFolder}/ → ${modName}/`);
 
-archive.on("warning", (err) => {
-  if (err.code === "ENOENT") {
-    console.warn("Warning:", err);
+  const mediaFolder = "media";
+  if (fs.existsSync(mediaFolder)) {
+    console.log(`Adding ${mediaFolder}/ → ${modName}/media/`);
+    mappings.push({ sourceDir: mediaFolder, zipRoot: `${modName}/media` });
   } else {
-    throw err;
+    console.log("No media folder found, skipping");
   }
-});
-
-// Pipe archive data to the file
-archive.pipe(output);
 
-// Add source folder contents to zip under modName directory
-console.log(`Adding ${sourceFolder}/ → ${modName}/`);
-archive.directory(sourceFolder, modName);
+  await createZipFromDirectories(zipPath, mappings, {
+    compressionLevel: 9,
+  });
 
-// Add media folder if it exists
-const mediaFolder = "media";
-if (fs.existsSync(mediaFolder)) {
-  console.log(`Adding ${mediaFolder}/ → ${modName}/media/`);
-  archive.directory(mediaFolder, `${modName}/media`);
-} else {
-  console.log("No media folder found, skipping");
+  const sizeInKB = (fs.statSync(zipPath).size / 1024).toFixed(2);
+  console.log(`✓ Build complete: ${zipPath} (${sizeInKB} KB)`);
 }
 
-// Finalize the archive
-archive.finalize();
+main().catch((error) => {
+  console.error("Error creating archive:", error);
+  process.exit(1);
+});

package/_project.config/package.template.json

@@ -1,19 +1,19 @@
 {
   "author": "Andriy Tevelyev",
-  "private": true,
-  "scripts": {
-    "setup": "node ../install.js",
-    "watch": "node watch.js",
-    "sync": "node sync.js %npm_package_name%",
-    "start": "powershell -ExecutionPolicy Bypass -File run.ps1 %npm_package_name%",
-    "build": "node build.js %npm_package_name%",
-    "update:types": "npm update @idajs/types"
-  },
-  "devDependencies": {
-    "archiver": "^7.0.1",
-    "chokidar-cli": "^3.0.0",
-    "@idajs/types": "^0.2.0",
-    "@idajs/sync": "^1.1.0",
+  "private": true,
+  "scripts": {
+    "setup": "node ../install.js",
+    "watch": "node watch.js",
+    "sync": "node sync.js",
+    "start": "node start.js",
+    "build": "node build.js",
+    "update:types": "npm update @idajs/types"
+  },
+  "devDependencies": {
+    "yazl": "^3.3.1",
+    "chokidar-cli": "^3.0.0",
+    "@idajs/types": "^0.2.0",
+    "@idajs/sync": "^1.1.0",
     "typescript": "^5.9.3"
   }
 }

package/_project.config/project.js

@@ -0,0 +1,120 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DEFAULT_PORT = 7770;
+
+function getArgs(argv = process.argv.slice(2)) {
+  return argv;
+}
+
+function getArgValue(name, argv = getArgs()) {
+  const index = argv.findIndex((arg) => arg === name || arg.startsWith(`${name}=`));
+  if (index === -1) {
+    return null;
+  }
+
+  const arg = argv[index];
+  if (arg.includes("=")) {
+    return arg.split("=").slice(1).join("=");
+  }
+
+  return argv[index + 1] || null;
+}
+
+function getPackageName(projectDir = process.cwd()) {
+  const packagePath = path.join(projectDir, "package.json");
+
+  if (!fs.existsSync(packagePath)) {
+    throw new Error(`package.json not found in ${projectDir}`);
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  if (!packageJson.name) {
+    throw new Error("package.json is missing the 'name' field");
+  }
+
+  return packageJson.name;
+}
+
+function getIdaJsPath(projectDir = process.cwd()) {
+  const configPaths = [path.join(projectDir, ".idajs.json"), path.join(os.homedir(), ".idajs.json")];
+
+  for (const configPath of configPaths) {
+    if (!fs.existsSync(configPath)) {
+      continue;
+    }
+
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      if (config.installDir) {
+        return config.installDir;
+      }
+    } catch (error) {
+      // Ignore parse failures and keep looking.
+    }
+  }
+
+  return null;
+}
+
+function getIdaJsServer(projectDir = process.cwd()) {
+  const configPaths = [path.join(projectDir, ".idajs.json"), path.join(os.homedir(), ".idajs.json")];
+
+  for (const configPath of configPaths) {
+    if (!fs.existsSync(configPath)) {
+      continue;
+    }
+
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      if (config.server) {
+        return config.server;
+      }
+    } catch (error) {
+      // Ignore parse failures and keep looking.
+    }
+  }
+
+  return null;
+}
+
+function isTypeScriptProject(projectDir = process.cwd()) {
+  const tsConfigPath = path.join(projectDir, "tsconfig.json");
+  const srcDir = path.join(projectDir, "src");
+
+  if (!fs.existsSync(tsConfigPath) || !fs.existsSync(srcDir)) {
+    return false;
+  }
+
+  const files = fs.readdirSync(srcDir);
+  return files.some((file) => file.endsWith(".ts"));
+}
+
+function parseServerAddress(serverInput) {
+  if (!serverInput) {
+    throw new Error("Server address is required. Use --server <host[:port]>.");
+  }
+
+  const trimmedInput = String(serverInput).trim();
+  const withProtocol = trimmedInput.includes("://") ? trimmedInput : `http://${trimmedInput}`;
+  const url = new URL(withProtocol);
+
+  return {
+    host: url.hostname,
+    port: Number(url.port || DEFAULT_PORT),
+    origin: `${url.protocol}//${url.hostname}:${url.port || DEFAULT_PORT}`,
+    value: `${url.hostname}:${url.port || DEFAULT_PORT}`,
+  };
+}
+
+module.exports = {
+  DEFAULT_PORT,
+  getArgValue,
+  getArgs,
+  getIdaJsPath,
+  getIdaJsServer,
+  getPackageName,
+  isTypeScriptProject,
+  parseServerAddress,
+};

package/_project.config/remote.js

@@ -0,0 +1,157 @@
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const { createZipFromDirectories } = require("./archive");
+const { getPackageName } = require("./project");
+
+function runNodeScript(scriptName, args = []) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [path.join(__dirname, scriptName), ...args], {
+      cwd: process.cwd(),
+      stdio: "inherit",
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`${scriptName} exited with code ${code}`));
+    });
+  });
+}
+
+function createZip(zipPath, sourceDir, rootName) {
+  return createZipFromDirectories(
+    zipPath,
+    [{ sourceDir, zipRoot: rootName }],
+    { compressionLevel: 0 }
+  );
+}
+
+function request(server, method, requestPath, body, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const client = server.origin.startsWith("https://") ? https : http;
+    const options = {
+      method,
+      hostname: server.host,
+      port: server.port,
+      path: requestPath,
+      headers,
+    };
+
+    const req = client.request(options, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const responseBody = Buffer.concat(chunks).toString("utf8");
+
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          if (!responseBody) {
+            resolve(null);
+            return;
+          }
+
+          try {
+            resolve(JSON.parse(responseBody));
+          } catch (error) {
+            resolve(responseBody);
+          }
+          return;
+        }
+
+        reject(
+          new Error(
+            `${method} ${requestPath} failed with ${res.statusCode}: ${responseBody || "no body"}`
+          )
+        );
+      });
+    });
+
+    req.on("error", (error) => {
+      if (error.code === "EHOSTUNREACH" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+        reject(
+          new Error(
+            `Cannot reach remote Ida listener at ${server.host}:${server.port}. ` +
+              `Start it on the Windows machine with 'npm run listen' in the Ida folder and verify the host/port is reachable. ` +
+              `Original error: ${error.code}`
+          )
+        );
+        return;
+      }
+
+      reject(error);
+    });
+
+    if (body) {
+      req.write(body);
+    }
+
+    req.end();
+  });
+}
+
+async function stageMod(targetRoot) {
+  const args = [];
+  if (targetRoot) {
+    args.push("--target-root", targetRoot);
+  }
+
+  await runNodeScript("sync.js", args);
+}
+
+async function stageAndZip(targetRoot) {
+  const modName = getPackageName();
+  const stagedModDir = path.join(targetRoot, modName);
+  const zipPath = path.join(targetRoot, `${modName}.zip`);
+
+  await stageMod(targetRoot);
+  if (fs.existsSync(zipPath)) {
+    fs.rmSync(zipPath, { force: true });
+  }
+  await createZip(zipPath, stagedModDir, modName);
+
+  return { modName, stagedModDir, zipPath };
+}
+
+async function uploadMod(server, modName, zipPath) {
+  const body = fs.readFileSync(zipPath);
+  return request(server, "POST", `/sync?modName=${encodeURIComponent(modName)}`, body, {
+    "Content-Type": "application/zip",
+    "Content-Length": Buffer.byteLength(body),
+  });
+}
+
+async function startRemoteGame(server, modName) {
+  return request(
+    server,
+    "POST",
+    "/game/start",
+    Buffer.from(JSON.stringify({ modName }), "utf8"),
+    {
+      "Content-Type": "application/json",
+    }
+  );
+}
+
+async function killRemoteGame(server) {
+  return request(server, "POST", "/game/kill");
+}
+
+async function getRemoteGameStatus(server) {
+  return request(server, "GET", "/game/status");
+}
+
+module.exports = {
+  getRemoteGameStatus,
+  killRemoteGame,
+  stageMod,
+  stageAndZip,
+  startRemoteGame,
+  uploadMod,
+};

package/_project.config/run-remote.js

@@ -0,0 +1,75 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const { getArgValue, parseServerAddress } = require("./project");
+const { getRemoteGameStatus, stageAndZip, startRemoteGame, uploadMod } = require("./remote");
+
+async function main() {
+  const args = process.argv.slice(2);
+  const server = parseServerAddress(getArgValue("--server", args));
+  const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "idajs-remote-"));
+  let cleanedUp = false;
+
+  const cleanup = () => {
+    if (cleanedUp) {
+      return;
+    }
+
+    cleanedUp = true;
+    fs.rmSync(sessionRoot, { recursive: true, force: true });
+  };
+
+  try {
+    console.log(`Checking remote Ida listener at ${server.origin}...`);
+    await getRemoteGameStatus(server);
+
+    console.log(`Using remote staging directory: ${sessionRoot}`);
+    const { modName, zipPath } = await stageAndZip(sessionRoot);
+    await uploadMod(server, modName, zipPath);
+    await startRemoteGame(server, modName);
+
+    const child = spawn(
+      process.execPath,
+      [
+        path.join(__dirname, "watch.js"),
+        "--server",
+        server.value,
+        "--session-root",
+        sessionRoot,
+      ],
+      {
+        cwd: process.cwd(),
+        stdio: "inherit",
+      }
+    );
+
+    child.on("exit", (code) => {
+      cleanup();
+      process.exit(code ?? 0);
+    });
+
+    child.on("error", (error) => {
+      cleanup();
+      console.error(error.message);
+      process.exit(1);
+    });
+
+    process.on("SIGINT", () => {
+      child.kill("SIGINT");
+    });
+
+    process.on("SIGTERM", () => {
+      child.kill("SIGTERM");
+    });
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/_project.config/start.js

@@ -0,0 +1,60 @@
+const path = require("path");
+const { execFileSync, spawn } = require("child_process");
+
+const { getArgValue, getIdaJsPath, getIdaJsServer, getPackageName } = require("./project");
+
+function runRemote(args) {
+  const child = spawn(process.execPath, [path.join(__dirname, "run-remote.js"), ...args], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+
+  child.on("error", (error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}
+
+function runLocal() {
+  try {
+    execFileSync(
+      "powershell",
+      [
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        path.join(__dirname, "run.ps1"),
+        getPackageName(),
+      ],
+      {
+        cwd: process.cwd(),
+        stdio: "inherit",
+      }
+    );
+    process.exit(0);
+  } catch (error) {
+    if (typeof error.status === "number") {
+      process.exit(error.status);
+    }
+
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+const args = process.argv.slice(2);
+const explicitServer = getArgValue("--server", args);
+const installDir = getIdaJsPath();
+const configuredServer = getIdaJsServer();
+
+if (explicitServer) {
+  runRemote(args);
+} else if (!installDir && configuredServer) {
+  runRemote(["--server", configuredServer]);
+} else {
+  runLocal();
+}