feat: engine plugin system for game-engine agnostic orchestration

CLAUDE.md

@@ -49,7 +49,7 @@ yarn game-ci --help   # Run CLI locally via ts-node
 - `.github/workflows/test.yml` — unit tests
 - `.github/workflows/ci.yml` — caller workflow for test + integrity
 - `.github/workflows/orchestrator-integrity.yml` — integration tests (AWS via LocalStack, K8s via k3d)
-- `.github/workflows/release-cli.yml` — CLI binary releases
+- `.github/workflows/release-cli.yml` — CLI binary releases (npm publish is not yet active — no `NPM_TOKEN` secret configured)
 
 ## Conventions
 

src/cli/commands/build.ts

@@ -227,6 +227,18 @@ const buildCommand: CommandModule<object, BuildArguments> = {
         description: 'Path to a directory containing SSH public keys to forward to the container',
         default: '',
       })
+      .option('engine', {
+        type: 'string',
+        description: 'Game engine name (unity, godot, unreal, etc.)',
+        default: 'unity',
+      })
+      .option('engine-plugin', {
+        alias: 'enginePlugin',
+        type: 'string',
+        description:
+          'Engine plugin source: module:<npm-pkg>, cli:<executable>, docker:<image>, or an npm package name',
+        default: '',
+      })
       .option('cache-unity-installation-on-mac', {
         alias: 'cacheUnityInstallationOnMac',
         type: 'boolean',

src/index.ts

@@ -31,6 +31,11 @@ export { Action } from './model/action';
 export { Platform } from './model/platform';
 export { StringKeyValuePair, DockerParameters } from './model/shared-types';
 
+// Engine plugin system
+export type { EnginePlugin } from './model/engine';
+export { getEngine, setEngine, initEngine, UnityPlugin } from './model/engine';
+export { loadEngineFromModule, loadEngineFromCli, loadEngineFromDocker } from './model/engine';
+
 // Re-export services for direct access
 export { BuildReliabilityService } from './model/orchestrator/services/reliability';
 export { TestWorkflowService } from './model/orchestrator/services/test-workflow';

src/model/build-parameters.ts

@@ -12,8 +12,13 @@
 import * as core from '@actions/core';
 import { Cli } from './cli/cli';
 import Input from './input';
+import { initEngine } from './engine';
 
 class BuildParameters {
+  // ── engine ─────────────────────────────────────────────────────────
+  engine!: string;
+  enginePlugin!: string;
+
   // ── identity ────────────────────────────────────────────────────────
   editorVersion!: string;
   customImage!: string;
@@ -220,6 +225,12 @@ class BuildParameters {
     p.dockerMemoryLimit = '';
     p.dockerIsolationMode = '';
     p.gitPrivateToken = Input.getInput('gitPrivateToken') || process.env.GIT_PRIVATE_TOKEN || '';
+    p.engine = Input.getInput('engine') || 'unity';
+    p.enginePlugin = Input.getInput('enginePlugin') || '';
+
+    // Initialize the engine plugin (Unity is built-in, others require enginePlugin source)
+    initEngine(p.engine, p.enginePlugin || undefined);
+
     p.orchestratorRepoName =
       Input.getInput('orchestratorRepoName') || process.env.GITHUB_REPOSITORY || 'game-ci/unity-builder';
     p.orchestratorBranch = Input.getInput('orchestratorBranch') || 'main';

src/model/engine/cli-engine-loader.ts

@@ -0,0 +1,70 @@
+import { spawnSync } from 'child_process';
+import { EnginePlugin } from './engine-plugin';
+import OrchestratorLogger from '../orchestrator/services/core/orchestrator-logger';
+
+/**
+ * Load an EnginePlugin from an external CLI executable.
+ *
+ * Protocol: the executable receives `{"command":"get-engine-config"}` on stdin
+ * and must print a JSON response on stdout:
+ *
+ *   { "name": "godot", "cacheFolders": [".godot/imported"], "preStopCommand": "..." }
+ *
+ * The executable can be any language (Go, Python, Rust, shell, etc.).
+ */
+export function loadEngineFromCli(executablePath: string): EnginePlugin {
+  const request = JSON.stringify({ command: 'get-engine-config' });
+
+  const result = spawnSync(executablePath, ['get-engine-config'], {
+    input: request,
+    encoding: 'utf-8',
+    timeout: 30_000,
+    shell: process.platform === 'win32',
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to spawn engine plugin executable '${executablePath}': ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim() || '';
+    throw new Error(
+      `Engine plugin executable '${executablePath}' exited with code ${result.status}${stderr ? ': ' + stderr : ''}`,
+    );
+  }
+
+  const stdout = result.stdout?.trim() || '';
+
+  // Find the last JSON object in stdout (skip any non-JSON preamble)
+  const lines = stdout.split('\n');
+  let config: any;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i].trim());
+      if (typeof parsed === 'object' && parsed !== null && parsed.name) {
+        config = parsed;
+        break;
+      }
+    } catch {
+      // Not JSON, skip
+    }
+  }
+
+  if (!config) {
+    throw new Error(`Engine plugin executable '${executablePath}' did not return valid JSON config. Output: ${stdout}`);
+  }
+
+  if (!config.name || !Array.isArray(config.cacheFolders)) {
+    throw new Error(
+      `Engine plugin config from '${executablePath}' missing required fields (name, cacheFolders). Got: ${JSON.stringify(config)}`,
+    );
+  }
+
+  OrchestratorLogger.log(`Loaded engine plugin '${config.name}' from CLI: ${executablePath}`);
+
+  return {
+    name: config.name,
+    cacheFolders: config.cacheFolders,
+    preStopCommand: config.preStopCommand || undefined,
+  };
+}

src/model/engine/docker-engine-loader.ts

@@ -0,0 +1,67 @@
+import { spawnSync } from 'child_process';
+import { EnginePlugin } from './engine-plugin';
+import OrchestratorLogger from '../orchestrator/services/core/orchestrator-logger';
+
+/**
+ * Load an EnginePlugin from a Docker image.
+ *
+ * The container is run with `docker run --rm <image> get-engine-config`
+ * and must print a JSON config on stdout:
+ *
+ *   { "name": "godot", "cacheFolders": [".godot/imported"], "preStopCommand": "..." }
+ *
+ * This allows community engine plugins to be distributed as Docker images.
+ */
+export function loadEngineFromDocker(image: string): EnginePlugin {
+  const result = spawnSync('docker', ['run', '--rm', image, 'get-engine-config'], {
+    encoding: 'utf-8',
+    timeout: 120_000,
+    shell: process.platform === 'win32',
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to run engine plugin Docker image '${image}': ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim() || '';
+    throw new Error(
+      `Engine plugin Docker image '${image}' exited with code ${result.status}${stderr ? ': ' + stderr : ''}`,
+    );
+  }
+
+  const stdout = result.stdout?.trim() || '';
+
+  // Find the last JSON object in stdout
+  const lines = stdout.split('\n');
+  let config: any;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i].trim());
+      if (typeof parsed === 'object' && parsed !== null && parsed.name) {
+        config = parsed;
+        break;
+      }
+    } catch {
+      // Not JSON, skip
+    }
+  }
+
+  if (!config) {
+    throw new Error(`Engine plugin Docker image '${image}' did not return valid JSON config. Output: ${stdout}`);
+  }
+
+  if (!config.name || !Array.isArray(config.cacheFolders)) {
+    throw new Error(
+      `Engine plugin config from Docker image '${image}' missing required fields (name, cacheFolders). Got: ${JSON.stringify(config)}`,
+    );
+  }
+
+  OrchestratorLogger.log(`Loaded engine plugin '${config.name}' from Docker: ${image}`);
+
+  return {
+    name: config.name,
+    cacheFolders: config.cacheFolders,
+    preStopCommand: config.preStopCommand || undefined,
+  };
+}

src/model/engine/engine-plugin.ts

@@ -0,0 +1,25 @@
+/**
+ * Engine plugin interface — allows the orchestrator to support
+ * different game engines (Unity, Godot, Unreal, etc.) without
+ * hardcoding engine-specific behavior.
+ *
+ * Each engine provides:
+ * - Cache folder names (e.g. 'Library' for Unity, '.godot/imported' for Godot)
+ * - Optional container preStop command (e.g. license cleanup for Unity)
+ */
+export interface EnginePlugin {
+  /** Engine identifier: 'unity', 'godot', 'unreal', etc. */
+  readonly name: string;
+
+  /**
+   * Folders to cache between builds, relative to projectPath.
+   * Examples: ['Library'] for Unity, ['.godot/imported', '.godot/shader_cache'] for Godot.
+   */
+  readonly cacheFolders: string[];
+
+  /**
+   * Shell command for container preStop hook (e.g. license cleanup).
+   * Undefined means no preStop hook.
+   */
+  readonly preStopCommand?: string;
+}

src/model/engine/index.ts

@@ -0,0 +1,68 @@
+export { EnginePlugin } from './engine-plugin';
+export { UnityPlugin } from './unity-plugin';
+export { loadEngineFromModule } from './module-engine-loader';
+export { loadEngineFromCli } from './cli-engine-loader';
+export { loadEngineFromDocker } from './docker-engine-loader';
+
+import { EnginePlugin } from './engine-plugin';
+import { UnityPlugin } from './unity-plugin';
+import { loadEngineFromModule } from './module-engine-loader';
+import { loadEngineFromCli } from './cli-engine-loader';
+import { loadEngineFromDocker } from './docker-engine-loader';
+import OrchestratorLogger from '../orchestrator/services/core/orchestrator-logger';
+
+/** Current engine plugin — defaults to Unity. */
+let currentEngine: EnginePlugin = UnityPlugin;
+
+/** Get the current engine plugin. */
+export function getEngine(): EnginePlugin {
+  return currentEngine;
+}
+
+/** Replace the engine plugin (e.g. for Godot, Unreal, or testing). */
+export function setEngine(engine: EnginePlugin): void {
+  currentEngine = engine;
+}
+
+/**
+ * Initialize the engine from a plugin source string.
+ *
+ * Source formats:
+ *   - `docker:<image>`  — load from a Docker image
+ *   - `cli:<path>`      — load from an external CLI executable
+ *   - `module:<id>`     — load from an npm package or local JS/TS file
+ *   - `<id>` (no prefix) — treated as a module (npm package or local path)
+ *
+ * When engine is 'unity' (or unset) with no enginePlugin, the built-in
+ * UnityPlugin is used — no loading needed.
+ */
+export function initEngine(engine: string, enginePlugin?: string): void {
+  if (!enginePlugin) {
+    if (engine === 'unity') {
+      currentEngine = UnityPlugin;
+      return;
+    }
+    throw new Error(
+      `Engine '${engine}' requires an enginePlugin source. ` +
+        `Use one of: module:<npm-package>, cli:<executable-path>, docker:<image>`,
+    );
+  }
+
+  OrchestratorLogger.log(`Loading engine plugin for '${engine}' from: ${enginePlugin}`);
+
+  let loaded: EnginePlugin;
+
+  if (enginePlugin.startsWith('docker:')) {
+    loaded = loadEngineFromDocker(enginePlugin.slice('docker:'.length));
+  } else if (enginePlugin.startsWith('cli:')) {
+    loaded = loadEngineFromCli(enginePlugin.slice('cli:'.length));
+  } else if (enginePlugin.startsWith('module:')) {
+    loaded = loadEngineFromModule(enginePlugin.slice('module:'.length));
+  } else {
+    // No prefix — default to module loader (npm package or local path)
+    loaded = loadEngineFromModule(enginePlugin);
+  }
+
+  currentEngine = loaded;
+  OrchestratorLogger.log(`Engine plugin '${loaded.name}' initialized successfully`);
+}

src/model/engine/module-engine-loader.ts

@@ -0,0 +1,47 @@
+import { EnginePlugin } from './engine-plugin';
+import OrchestratorLogger from '../orchestrator/services/core/orchestrator-logger';
+
+/**
+ * Load an EnginePlugin from a TypeScript/JavaScript module.
+ *
+ * Accepts:
+ * - npm package name: `@game-ci/godot-engine`
+ * - Local file path: `./my-engine-plugin.js` or `/absolute/path/plugin.js`
+ *
+ * The module must export an EnginePlugin-compatible object as default or named `plugin`:
+ *
+ *   // ES module
+ *   export default { name: 'godot', cacheFolders: ['.godot/imported'] };
+ *
+ *   // CommonJS
+ *   module.exports = { name: 'godot', cacheFolders: ['.godot/imported'] };
+ */
+export function loadEngineFromModule(moduleId: string): EnginePlugin {
+  let loaded: any;
+  try {
+    loaded = require(moduleId);
+  } catch (error: any) {
+    throw new Error(`Failed to load engine plugin module '${moduleId}': ${error.message}`);
+  }
+
+  // Support default export, named `plugin` export, or the module itself
+  const config = loaded.default || loaded.plugin || loaded;
+
+  if (!config || typeof config !== 'object') {
+    throw new Error(`Engine plugin module '${moduleId}' did not export a valid object`);
+  }
+
+  if (!config.name || !Array.isArray(config.cacheFolders)) {
+    throw new Error(
+      `Engine plugin from module '${moduleId}' missing required fields (name, cacheFolders). Got: ${JSON.stringify(config)}`,
+    );
+  }
+
+  OrchestratorLogger.log(`Loaded engine plugin '${config.name}' from module: ${moduleId}`);
+
+  return {
+    name: config.name,
+    cacheFolders: config.cacheFolders,
+    preStopCommand: config.preStopCommand || undefined,
+  };
+}

src/model/engine/unity-plugin.ts

@@ -0,0 +1,17 @@
+import { EnginePlugin } from './engine-plugin';
+
+/**
+ * Unity engine plugin — built-in.
+ *
+ * This is a plugin like any other, it just ships with the orchestrator.
+ * unity-builder owns everything else (image resolution, versioning, build
+ * scripts, licensing activation flow). This plugin only provides the
+ * minimal config the orchestrator needs to handle caching and container
+ * lifecycle generically.
+ */
+export const UnityPlugin: EnginePlugin = {
+  name: 'unity',
+  cacheFolders: ['Library'],
+  preStopCommand:
+    'cd /data/builder/action/steps && chmod +x /steps/return_license.sh 2>/dev/null || true; /steps/return_license.sh 2>/dev/null || true',
+};