@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/bridge-plugins/helix.bridge.unreal/bridge-plugin.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": "helix.bridge-plugin/1",
+  "id": "helix.bridge.unreal",
+  "name": "HELIX Unreal Bridge",
+  "version": "1.0.0",
+  "trust": "helix-verified",
+  "description": "Official Unreal Engine skeletal-mesh extraction adapter for HELIX Bridge.",
+  "permissions": [
+    "filesystem.read-source",
+    "filesystem.write-output",
+    "spawn-process",
+    "unrestricted-host-execution",
+    "unreal-editor"
+  ],
+  "capabilities": [
+    {
+      "id": "unreal.project.extract",
+      "stage": "extract",
+      "accepts": ["unreal.project"],
+      "produces": ["format.fbx"],
+      "targets": ["web", "unreal", "canonical"],
+      "permissions": [
+        "filesystem.read-source",
+        "filesystem.write-output",
+        "spawn-process",
+        "unrestricted-host-execution",
+        "unreal-editor"
+      ],
+      "requires": [
+        "tool:unreal-editor-commandlet",
+        "input:unrealAsset"
+      ],
+      "description": "Open the snapshotted Unreal project in the full editor and export one configured Skeletal Mesh to FBX.",
+      "command": {
+        "executable": "bin/unreal-skeletal-mesh-extract.js",
+        "timeoutSeconds": 3600
+      }
+    }
+  ]
+}

package/bridge-plugins/helix.bridge.unreal/test/exporter.test.js

@@ -0,0 +1,418 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } = require('node:fs');
+const { tmpdir } = require('node:os');
+const { join, resolve } = require('node:path');
+const test = require('node:test');
+
+const exporter = resolve(__dirname, '..', 'unreal', 'export_skeletal_mesh.py');
+
+const fakeUnrealModule = String.raw`
+import json
+import os
+
+def _record(kind, **values):
+    with open(os.environ['HELIX_FAKE_UNREAL_EVENTS'], 'a', encoding='utf-8') as stream:
+        stream.write(json.dumps({'kind': kind, **values}) + '\n')
+
+class _AssetClass:
+    def __init__(self, name):
+        self.name = name
+
+    def get_name(self):
+        return self.name
+
+class _EditorObject:
+    def __init__(self, path, class_name, **properties):
+        self.path = path
+        self.class_name = class_name
+        self.properties = properties
+
+    def get_path_name(self):
+        return self.path
+
+    def get_class(self):
+        return _AssetClass(self.class_name)
+
+    def get_editor_property(self, name):
+        if name not in self.properties:
+            raise RuntimeError('missing property ' + name)
+        return self.properties[name]
+
+class _Vector:
+    def __init__(self, r, g, b, a):
+        self.r = r
+        self.g = g
+        self.b = b
+        self.a = a
+
+class Texture2D(_EditorObject):
+    def __init__(self, path):
+        super().__init__(path, 'Texture2D', srgb=True, compression_settings='TC_Default', flip_green_channel=False)
+
+class _UnsupportedTexture(_EditorObject):
+    def __init__(self, path):
+        super().__init__(path, 'TextureCube')
+
+class _Material(_EditorObject):
+    def __init__(self, path, parent=None):
+        super().__init__(path, 'MaterialInstanceConstant' if parent else 'Material', parent=parent)
+
+class _SkeletalMaterial:
+    def __init__(self, material):
+        self.properties = {
+            'material_interface': material,
+            'material_slot_name': 'Body',
+            'imported_material_slot_name': 'Body_skin00',
+        }
+
+    def get_editor_property(self, name):
+        return self.properties[name]
+
+class SkeletalMesh:
+    def __init__(self, path=''):
+        self.path = path
+        root = _Material('/Game/Materials/M_Body.M_Body')
+        self.material = _Material('/Game/Materials/MI_Body.MI_Body', root)
+        self.texture = (_UnsupportedTexture('/Game/Textures/T_Unsupported.T_Unsupported')
+                        if os.environ.get('HELIX_FAKE_UNREAL_UNSUPPORTED_TEXTURE') == '1'
+                        else Texture2D('/Game/Textures/T_Body+EV1.T_Body+EV1'))
+        self.properties = {'materials': [_SkeletalMaterial(self.material)]}
+
+    def get_class(self):
+        return _AssetClass('SkeletalMesh')
+
+    def get_editor_property(self, name):
+        return self.properties[name]
+
+class _WrongAsset:
+    def get_class(self):
+        return _AssetClass('StaticMesh')
+
+class EditorAssetLibrary:
+    @staticmethod
+    def load_asset(path):
+        _record('load_asset', path=path)
+        if os.environ.get('HELIX_FAKE_UNREAL_MISSING') == '1':
+            return None
+        if os.environ.get('HELIX_FAKE_UNREAL_WRONG_TYPE') == '1':
+            return _WrongAsset()
+        if path == os.environ.get('HELIX_FAKE_UNREAL_WRONG_TYPE_PATH'):
+            return _WrongAsset()
+        return SkeletalMesh(path)
+
+class FbxExportOption:
+    def __init__(self):
+        self.properties = {}
+
+    def set_editor_property(self, name, value):
+        self.properties[name] = value
+        _record('option', name=name, value=value)
+
+class AssetExportTask:
+    def __init__(self):
+        self.properties = {}
+
+    def set_editor_property(self, name, value):
+        self.properties[name] = value
+
+class Exporter:
+    @staticmethod
+    def run_asset_export_task(task):
+        asset = task.properties['object']
+        filename = task.properties['filename']
+        if isinstance(asset, Texture2D):
+            _record('texture_export', asset=asset.path, filename=filename)
+            if os.environ.get('HELIX_FAKE_UNREAL_TEXTURE_EXPORT_FAIL') == '1':
+                return False
+            with open(filename, 'wb') as stream:
+                stream.write(b'\x89PNG\r\n\x1a\n' + b'fake-png-' + asset.path.encode('utf-8'))
+            return True
+        options = task.properties['options']
+        _record(
+            'export',
+            asset=asset.path,
+            filename=filename,
+            morphs=options.properties['export_morph_targets'],
+            automated=task.properties['automated'],
+            prompt=task.properties['prompt'],
+            replace_identical=task.properties['replace_identical'],
+            write_empty_files=task.properties['write_empty_files'],
+        )
+        if os.environ.get('HELIX_FAKE_UNREAL_EXPORT_FAIL') == '1':
+            return False
+        with open(filename, 'wb') as stream:
+            stream.write(b'Kaydara FBX Binary  \x00\x1a\x00' + bytes(32))
+        return True
+
+class MaterialEditingLibrary:
+    @staticmethod
+    def get_scalar_parameter_names(material):
+        return ['Roughness']
+
+    @staticmethod
+    def get_vector_parameter_names(material):
+        return ['Tint']
+
+    @staticmethod
+    def get_texture_parameter_names(material):
+        return ['BaseColor']
+
+    @staticmethod
+    def get_material_instance_scalar_parameter_value(material, name):
+        return 0.5
+
+    @staticmethod
+    def get_material_instance_vector_parameter_value(material, name):
+        return _Vector(1.0, 0.5, 0.25, 1.0)
+
+    @staticmethod
+    def get_material_instance_texture_parameter_value(material, name):
+        return _current_mesh.texture
+
+class SystemLibrary:
+    @staticmethod
+    def quit_editor():
+        _record('quit_editor')
+
+def log(message):
+    _record('log', message=message)
+
+def log_error(message):
+    _record('log_error', message=message)
+
+_current_mesh = SkeletalMesh('/Game/Current')
+`;
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'helix-unreal-exporter-'));
+  const fakeModuleDir = join(root, 'fake-unreal');
+  const outputDir = join(root, 'output');
+  const eventsPath = join(root, 'events.jsonl');
+  mkdirSync(fakeModuleDir);
+  mkdirSync(outputDir);
+  writeFileSync(join(fakeModuleDir, 'unreal.py'), fakeUnrealModule);
+  return { root, fakeModuleDir, outputDir, eventsPath };
+}
+
+function run(entry, environment) {
+  return spawnSync('python3', [exporter], {
+    encoding: 'utf8',
+    env: {
+      PATH: process.env.PATH,
+      PYTHONPATH: entry.fakeModuleDir,
+      HELIX_FAKE_UNREAL_EVENTS: entry.eventsPath,
+      ...environment,
+    },
+  });
+}
+
+function events(entry) {
+  return readFileSync(entry.eventsPath, 'utf8')
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+test('exports every batch job with reviewed FBX task options and morph settings', () => {
+  const entry = fixture();
+  const outputs = [join(entry.outputDir, 'body.fbx'), join(entry.outputDir, 'top.fbx')];
+  const jobs = [
+    { slug: 'body', assetPath: '/Game/Body', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'top', assetPath: '/Game/Top', outputPath: outputs[1], exportMorphTargets: false },
+  ];
+  const result = run(entry, { HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs) });
+  assert.equal(result.status, 0, result.stderr);
+
+  const observed = events(entry);
+  assert.deepEqual(observed.filter((event) => event.kind === 'load_asset').map((event) => event.path), [
+    '/Game/Body',
+    '/Game/Top',
+  ]);
+  assert.deepEqual(observed.filter((event) => event.kind === 'export').map((event) => ({
+    asset: event.asset,
+    morphs: event.morphs,
+    automated: event.automated,
+    prompt: event.prompt,
+    replaceIdentical: event.replace_identical,
+    writeEmptyFiles: event.write_empty_files,
+  })), [
+    { asset: '/Game/Body', morphs: true, automated: true, prompt: false, replaceIdentical: true, writeEmptyFiles: false },
+    { asset: '/Game/Top', morphs: false, automated: true, prompt: false, replaceIdentical: true, writeEmptyFiles: false },
+  ]);
+  assert.equal(observed.at(-1).kind, 'quit_editor');
+  for (const output of outputs) {
+    assert.match(readFileSync(output, 'binary'), /^Kaydara FBX Binary/);
+  }
+  const bodySidecar = JSON.parse(readFileSync(join(entry.outputDir, 'body.materials.json'), 'utf8'));
+  assert.equal(bodySidecar.schemaVersion, 'helix.bridge.unreal-material-sidecar/1');
+  assert.deepEqual(bodySidecar.asset, { slug: 'body', sourceMeshAssetPath: '/Game/Body' });
+  assert.equal(bodySidecar.materials[0].slotIndex, 0);
+  assert.equal(bodySidecar.materials[0].sourceRootMaterialAssetPath, '/Game/Materials/M_Body.M_Body');
+  assert.equal(bodySidecar.materials[0].parameters.scalars.Roughness, 0.5);
+  assert.deepEqual(bodySidecar.materials[0].parameters.vectors.Tint, { a: 1, b: 0.25, g: 0.5, r: 1 });
+  const texture = bodySidecar.materials[0].parameters.textures.BaseColor;
+  assert.match(texture.path, /^textures\/[a-f0-9]{64}\.png$/);
+  assert.deepEqual(texture.colorSpace, { compressionSettings: 'TC_Default', flipGreenChannel: false, srgb: true });
+  assert.match(readFileSync(join(entry.outputDir, texture.path), 'binary'), /^\x89PNG\r\n\x1a\nfake-png-\/Game\/Textures\/T_Body\+EV1\.T_Body\+EV1$/);
+  const topSidecar = JSON.parse(readFileSync(join(entry.outputDir, 'top.materials.json'), 'utf8'));
+  assert.equal(topSidecar.materials[0].parameters.textures.BaseColor.path, texture.path);
+  assert.equal(observed.filter((event) => event.kind === 'texture_export').length, 1);
+});
+
+test('supports the single-export compatibility environment', () => {
+  const entry = fixture();
+  const output = join(entry.outputDir, 'single.fbx');
+  const result = run(entry, {
+    HELIX_UNREAL_ASSET_PATH: '/Game/Single',
+    HELIX_UNREAL_OUTPUT_FBX: output,
+    HELIX_UNREAL_EXPORT_MORPH_TARGETS: '0',
+  });
+  assert.equal(result.status, 0, result.stderr);
+  const exportEvent = events(entry).find((event) => event.kind === 'export');
+  assert.equal(exportEvent.asset, '/Game/Single');
+  assert.equal(exportEvent.morphs, false);
+});
+
+test('logs export failures, exits nonzero, and still requests editor shutdown', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify([
+      { slug: 'body', assetPath: '/Game/Body', outputPath: join(entry.outputDir, 'body.fbx'), exportMorphTargets: true },
+    ]),
+    HELIX_FAKE_UNREAL_EXPORT_FAIL: '1',
+  });
+  assert.notEqual(result.status, 0);
+  const observed = events(entry);
+  assert.ok(observed.some((event) => event.kind === 'log_error' && /Unreal failed to export/.test(event.message)));
+  assert.equal(observed.at(-1).kind, 'quit_editor');
+});
+
+test('rejects malformed batch jobs and still requests editor shutdown', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify([
+      { slug: 'body', assetPath: '/Game/Body', outputPath: join(entry.outputDir, 'body.fbx'), exportMorphTargets: 'yes' },
+    ]),
+  });
+  assert.notEqual(result.status, 0);
+  const observed = events(entry);
+  assert.ok(observed.some((event) => event.kind === 'log_error' && /boolean exportMorphTargets/.test(event.message)));
+  assert.equal(observed.at(-1).kind, 'quit_editor');
+});
+
+test('omits non-Texture2D material parameters while preserving portable Texture2D-only sidecars', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify([
+      { slug: 'body', assetPath: '/Game/Body', outputPath: join(entry.outputDir, 'body.fbx'), exportMorphTargets: true },
+    ]),
+    HELIX_FAKE_UNREAL_UNSUPPORTED_TEXTURE: '1',
+  });
+  assert.equal(result.status, 0, result.stderr);
+  const sidecar = JSON.parse(readFileSync(join(entry.outputDir, 'body.materials.json'), 'utf8'));
+  assert.deepEqual(sidecar.materials[0].parameters.textures, {});
+  const observed = events(entry);
+  assert.equal(observed.at(-1).kind, 'quit_editor');
+});
+
+test('isolates a per-asset failure: the rest of the batch still exports and a results manifest records both outcomes', () => {
+  // Regression for batch-backlog.md item 13: `SKM_M_Denim_Jacket` (a MaterialInstanceConstant,
+  // not a SkeletalMesh) used to throw out of the batch loop and abort the whole UnrealEditor
+  // process, so `Combat Boots` right after it in the same batch was never even attempted.
+  const entry = fixture();
+  const outputs = [
+    join(entry.outputDir, 'denim-jacket.fbx'),
+    join(entry.outputDir, 'combat-boots.fbx'),
+  ];
+  const jobs = [
+    { slug: 'denim-jacket', assetPath: '/Game/Characters/SKM_M_Denim_Jacket', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'combat-boots', assetPath: '/Game/Characters/SKM_M_Combat_Boots', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE_PATH: '/Game/Characters/SKM_M_Denim_Jacket',
+  });
+  // The exporter itself exits zero: something usable came out of this batch, so it is up to
+  // the Node handler (see handler.test.js) to decide how to report the mixed outcome upward,
+  // not for the exporter to make the whole run look like a hard failure.
+  assert.equal(result.status, 0, result.stderr);
+
+  const observed = events(entry);
+  assert.deepEqual(observed.filter((event) => event.kind === 'load_asset').map((event) => event.path), [
+    '/Game/Characters/SKM_M_Denim_Jacket',
+    '/Game/Characters/SKM_M_Combat_Boots',
+  ], 'combat-boots must still be attempted after denim-jacket fails');
+  assert.ok(
+    observed.some((event) => event.kind === 'log_error' && /SKM_M_Denim_Jacket/.test(event.message) && /not a SkeletalMesh/.test(event.message)),
+  );
+
+  assert.equal(existsSync(join(entry.outputDir, 'denim-jacket.fbx')), false);
+  assert.match(readFileSync(join(entry.outputDir, 'combat-boots.fbx'), 'binary'), /^Kaydara FBX Binary/);
+  const bootsSidecar = JSON.parse(readFileSync(join(entry.outputDir, 'combat-boots.materials.json'), 'utf8'));
+  assert.equal(bootsSidecar.asset.slug, 'combat-boots');
+
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  assert.equal(manifest.schemaVersion, 'helix.bridge.unreal-export-results/1');
+  const bySlug = Object.fromEntries(manifest.results.map((entryResult) => [entryResult.slug, entryResult]));
+  assert.equal(bySlug['denim-jacket'].status, 'failed');
+  assert.match(bySlug['denim-jacket'].error, /not a SkeletalMesh/);
+  assert.equal(bySlug['combat-boots'].status, 'succeeded');
+  assert.equal(observed.at(-1).kind, 'quit_editor', 'the editor must still shut down cleanly after a partial batch');
+});
+
+test('exits zero when a batch fully succeeds despite an earlier asset in the same batch failing', () => {
+  // The overall process exit code should reflect whether the batch produced anything usable
+  // at all, not merely whether the FIRST asset happened to succeed — this is what lets the
+  // Node handler treat a partial batch as a deliverable result rather than a hard failure.
+  const entry = fixture();
+  const outputs = [join(entry.outputDir, 'body.fbx'), join(entry.outputDir, 'top.fbx')];
+  const jobs = [
+    { slug: 'body', assetPath: '/Game/Broken', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'top', assetPath: '/Game/Top', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE_PATH: '/Game/Broken',
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(readFileSync(outputs[1], 'binary'), /^Kaydara FBX Binary/);
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  const bySlug = Object.fromEntries(manifest.results.map((entryResult) => [entryResult.slug, entryResult]));
+  assert.equal(bySlug.body.status, 'failed', 'the manifest still records the real failure even though the batch exits zero');
+  assert.equal(bySlug.top.status, 'succeeded');
+});
+
+test('reports every asset failed, with no partial output, when an entire batch fails', () => {
+  const entry = fixture();
+  const outputs = [join(entry.outputDir, 'body.fbx'), join(entry.outputDir, 'top.fbx')];
+  const jobs = [
+    { slug: 'body', assetPath: '/Game/Body', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'top', assetPath: '/Game/Top', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE: '1',
+  });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Every asset in this batch failed to export/);
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  assert.ok(manifest.results.every((entryResult) => entryResult.status === 'failed'));
+});
+
+test('fails atomically when Unreal cannot export a referenced Texture2D', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify([
+      { slug: 'body', assetPath: '/Game/Body', outputPath: join(entry.outputDir, 'body.fbx'), exportMorphTargets: true },
+    ]),
+    HELIX_FAKE_UNREAL_TEXTURE_EXPORT_FAIL: '1',
+  });
+  assert.notEqual(result.status, 0);
+  const observed = events(entry);
+  assert.ok(observed.some((event) => event.kind === 'log_error' && /failed to export Texture2D/.test(event.message)));
+  assert.equal(observed.at(-1).kind, 'quit_editor');
+});