@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/bridge-plugins/helix.bridge.unreal/unreal/export_skeletal_mesh.py

@@ -0,0 +1,384 @@
+"""Export reviewed Unreal Skeletal Meshes plus portable material sidecars."""
+
+import hashlib
+import json
+import math
+import os
+import re
+import traceback
+
+import unreal
+
+
+SIDECAR_SCHEMA = "helix.bridge.unreal-material-sidecar/1"
+UNREAL_OBJECT_PATH = re.compile(
+    r"^/[A-Za-z0-9_+]+/(?:[A-Za-z0-9_+]+/)*[A-Za-z0-9_+]+(?:\.[A-Za-z0-9_+]+)?$"
+)
+
+# Mirrors bin/unreal-skeletal-mesh-extract.js's EXPORT_RESULTS_FILENAME/EXPORT_RESULTS_SCHEMA
+# (kept in sync by hand: this plugin script runs standalone inside UnrealEditor's Python VM,
+# not through the built CLI, so it cannot import that module). This is the per-asset results
+# manifest that lets a batch survive one bad asset: each job's outcome is recorded here so the
+# Node wrapper can tell "this asset really failed" apart from "the editor crashed before
+# writing anything", and still deliver every other asset's FBX/sidecar/textures as usable
+# output instead of discarding the whole batch (see batch-backlog.md item 13).
+EXPORT_RESULTS_SCHEMA = "helix.bridge.unreal-export-results/1"
+EXPORT_RESULTS_FILENAME = "_export-results.json"
+
+
+def required_environment(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise RuntimeError(f"Missing required environment variable {name}")
+    return value
+
+
+def editor_property(value, name, default=None):
+    try:
+        return value.get_editor_property(name)
+    except Exception:
+        return default
+
+
+def object_path(value, label: str) -> str:
+    try:
+        path = str(value.get_path_name())
+    except Exception as exc:
+        raise RuntimeError(f"Unable to resolve {label} Unreal object path: {exc}") from exc
+    if not UNREAL_OBJECT_PATH.fullmatch(path) or "\\" in path or ".." in path:
+        raise RuntimeError(f"{label} has a non-portable Unreal object path: {path!r}")
+    return path
+
+
+def finite_number(value, label: str) -> float:
+    if isinstance(value, bool):
+        raise RuntimeError(f"{label} did not resolve to a finite number")
+    try:
+        number = float(value)
+    except Exception as exc:
+        raise RuntimeError(f"{label} did not resolve to a finite number: {exc}") from exc
+    if not math.isfinite(number):
+        raise RuntimeError(f"{label} did not resolve to a finite number")
+    return number
+
+
+def parameter_names(material, kind: str):
+    method = getattr(unreal.MaterialEditingLibrary, f"get_{kind}_parameter_names", None)
+    if method is None:
+        raise RuntimeError(f"Unreal does not expose resolved {kind} parameter names")
+    try:
+        names = method(material) or []
+    except Exception as exc:
+        raise RuntimeError(f"Unable to read resolved {kind} parameter names: {exc}") from exc
+    return sorted({str(name) for name in names}, key=lambda name: (name.casefold(), name))
+
+
+def resolved_parameter(material, kind: str, name: str):
+    method = getattr(
+        unreal.MaterialEditingLibrary,
+        f"get_material_instance_{kind}_parameter_value",
+        None,
+    )
+    if method is None:
+        raise RuntimeError(f"Unreal does not expose resolved {kind} parameter values")
+    try:
+        return method(material, name)
+    except Exception as exc:
+        raise RuntimeError(f"Unable to resolve {kind} parameter {name!r}: {exc}") from exc
+
+
+def root_material(material):
+    current = material
+    seen = set()
+    while current is not None:
+        path = object_path(current, "Material")
+        if path in seen:
+            raise RuntimeError(f"Material parent cycle encountered at {path!r}")
+        seen.add(path)
+        parent = editor_property(current, "parent")
+        if parent is None:
+            return current
+        current = parent
+    raise RuntimeError("Material has no root material")
+
+
+def sha256_file(path: str):
+    digest = hashlib.sha256()
+    size = 0
+    with open(path, "rb") as stream:
+        while True:
+            chunk = stream.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+            size += len(chunk)
+    return digest.hexdigest(), size
+
+
+def enum_text(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def texture_color_space(texture):
+    metadata = {}
+    srgb = editor_property(texture, "srgb")
+    if isinstance(srgb, bool):
+        metadata["srgb"] = srgb
+    compression = enum_text(editor_property(texture, "compression_settings"))
+    if compression is not None:
+        metadata["compressionSettings"] = compression
+    # The PNG export is the texture's source art; Unreal applies "Flip Green Channel" at build time.
+    # Recording it lets import convert only the normal maps that really are DirectX-convention.
+    flip_green = editor_property(texture, "flip_green_channel")
+    if isinstance(flip_green, bool):
+        metadata["flipGreenChannel"] = flip_green
+    return metadata
+
+
+def export_texture(texture, textures_dir: str, cache):
+    if not isinstance(texture, unreal.Texture2D):
+        return None
+
+    source_asset_path = object_path(texture, "Texture2D")
+    cached = cache.get(source_asset_path)
+    if cached is not None:
+        return cached
+
+    os.makedirs(textures_dir, exist_ok=True)
+    temporary_name = hashlib.sha256(source_asset_path.encode("utf-8")).hexdigest()
+    temporary_path = os.path.join(textures_dir, f".helix-texture-{temporary_name}.png")
+    if os.path.lexists(temporary_path):
+        raise RuntimeError(f"Texture export path already exists: {temporary_path}")
+
+    task = unreal.AssetExportTask()
+    task.set_editor_property("object", texture)
+    task.set_editor_property("filename", temporary_path)
+    task.set_editor_property("automated", True)
+    task.set_editor_property("prompt", False)
+    task.set_editor_property("replace_identical", False)
+    task.set_editor_property("write_empty_files", False)
+    if not unreal.Exporter.run_asset_export_task(task):
+        raise RuntimeError(f"Unreal failed to export Texture2D {source_asset_path!r} as PNG")
+    if not os.path.isfile(temporary_path) or os.path.islink(temporary_path):
+        raise RuntimeError(f"Unreal did not create a regular PNG for Texture2D {source_asset_path!r}")
+
+    digest, size = sha256_file(temporary_path)
+    if size == 0:
+        raise RuntimeError(f"Unreal created an empty PNG for Texture2D {source_asset_path!r}")
+    filename = f"{digest}.png"
+    final_path = os.path.join(textures_dir, filename)
+    if os.path.exists(final_path):
+        existing_digest, existing_size = sha256_file(final_path)
+        if existing_digest != digest or existing_size != size:
+            raise RuntimeError(f"Texture content-address collision for {digest}")
+        os.remove(temporary_path)
+    else:
+        os.replace(temporary_path, final_path)
+
+    record = {
+        "sourceAssetPath": source_asset_path,
+        "path": f"textures/{filename}",
+        "sha256": digest,
+        "sizeBytes": size,
+        "colorSpace": texture_color_space(texture),
+    }
+    cache[source_asset_path] = record
+    return record
+
+
+def resolved_material(material, output_dir: str, texture_cache):
+    scalars = {
+        name: finite_number(resolved_parameter(material, "scalar", name), f"Scalar {name!r}")
+        for name in parameter_names(material, "scalar")
+    }
+    vectors = {}
+    for name in parameter_names(material, "vector"):
+        value = resolved_parameter(material, "vector", name)
+        vectors[name] = {
+            channel: finite_number(getattr(value, channel, None), f"Vector {name!r}.{channel}")
+            for channel in ("r", "g", "b", "a")
+        }
+    textures = {}
+    for name in parameter_names(material, "texture"):
+        texture = resolved_parameter(material, "texture", name)
+        if texture is not None:
+            exported = export_texture(
+                texture,
+                os.path.join(output_dir, "textures"),
+                texture_cache,
+            )
+            if exported is not None:
+                textures[name] = exported
+    return {"scalars": scalars, "vectors": vectors, "textures": textures}
+
+
+def material_sidecar(asset, asset_path: str, slug: str, output_dir: str, texture_cache):
+    materials = []
+    for index, skeletal_material in enumerate(editor_property(asset, "materials", []) or []):
+        interface = editor_property(skeletal_material, "material_interface")
+        if interface is None:
+            raise RuntimeError(f"Skeletal Mesh material slot {index} has no material interface")
+        materials.append({
+            "slotIndex": index,
+            "slotName": str(editor_property(skeletal_material, "material_slot_name", "")),
+            "importedSlotName": str(
+                editor_property(skeletal_material, "imported_material_slot_name", "")
+            ),
+            "sourceMaterialAssetPath": object_path(interface, "Material"),
+            "sourceRootMaterialAssetPath": object_path(root_material(interface), "Root material"),
+            "parameters": resolved_material(interface, output_dir, texture_cache),
+        })
+    return {
+        "schemaVersion": SIDECAR_SCHEMA,
+        "asset": {"slug": slug, "sourceMeshAssetPath": asset_path},
+        "materials": materials,
+    }
+
+
+def export_asset(job, texture_cache) -> None:
+    asset_path = job["assetPath"]
+    output_path = job["outputPath"]
+    export_morph_targets = job["exportMorphTargets"]
+    slug = job["slug"]
+    unreal.log(f"HELIX Bridge exporting {asset_path!r} to {output_path!r}")
+    asset = unreal.EditorAssetLibrary.load_asset(asset_path)
+    if asset is None:
+        raise RuntimeError(f"Unable to load Unreal asset {asset_path!r}")
+    if not isinstance(asset, unreal.SkeletalMesh):
+        raise RuntimeError(
+            f"Unreal asset {asset_path!r} is {asset.get_class().get_name()}, not a SkeletalMesh"
+        )
+
+    output_dir = os.path.dirname(output_path)
+    sidecar = material_sidecar(asset, asset_path, slug, output_dir, texture_cache)
+
+    options = unreal.FbxExportOption()
+    options.set_editor_property("export_morph_targets", export_morph_targets)
+    task = unreal.AssetExportTask()
+    task.set_editor_property("object", asset)
+    task.set_editor_property("filename", output_path)
+    task.set_editor_property("automated", True)
+    task.set_editor_property("prompt", False)
+    task.set_editor_property("replace_identical", True)
+    task.set_editor_property("write_empty_files", False)
+    task.set_editor_property("options", options)
+
+    if not unreal.Exporter.run_asset_export_task(task):
+        raise RuntimeError(f"Unreal failed to export SkeletalMesh {asset_path!r} to {output_path!r}")
+    if not os.path.isfile(output_path) or os.path.getsize(output_path) == 0:
+        raise RuntimeError(
+            f"Unreal reported success but did not create a non-empty FBX at {output_path!r}"
+        )
+
+    sidecar_path = os.path.join(output_dir, f"{slug}.materials.json")
+    if os.path.lexists(sidecar_path):
+        raise RuntimeError(f"Material sidecar path already exists: {sidecar_path}")
+    with open(sidecar_path, "x", encoding="utf-8", newline="\n") as stream:
+        json.dump(sidecar, stream, indent=2, sort_keys=True, allow_nan=False)
+        stream.write("\n")
+    unreal.log(f"HELIX Bridge exported {asset_path!r} to {output_path!r}")
+
+
+def export_jobs():
+    raw = os.environ.get("HELIX_UNREAL_EXPORTS_JSON", "").strip()
+    if not raw:
+        output_path = required_environment("HELIX_UNREAL_OUTPUT_FBX")
+        return [{
+            "slug": os.path.splitext(os.path.basename(output_path))[0],
+            "assetPath": required_environment("HELIX_UNREAL_ASSET_PATH"),
+            "outputPath": output_path,
+            "exportMorphTargets": os.environ.get("HELIX_UNREAL_EXPORT_MORPH_TARGETS", "1") == "1",
+        }]
+    jobs = json.loads(raw)
+    if not isinstance(jobs, list) or not jobs:
+        raise RuntimeError("HELIX_UNREAL_EXPORTS_JSON must be a non-empty array")
+    return jobs
+
+
+def write_export_results(output_dir: str, results) -> None:
+    payload = {
+        "schemaVersion": EXPORT_RESULTS_SCHEMA,
+        "results": results,
+    }
+    results_path = os.path.join(output_dir, EXPORT_RESULTS_FILENAME)
+    with open(results_path, "w", encoding="utf-8", newline="\n") as stream:
+        json.dump(payload, stream, indent=2, sort_keys=True, allow_nan=False)
+        stream.write("\n")
+
+
+def main() -> None:
+    texture_cache = {}
+    results = []
+    output_dir = None
+    for job in export_jobs():
+        if not isinstance(job, dict):
+            raise RuntimeError("Each Unreal export job must be an object")
+        slug = str(job.get("slug", "")).strip()
+        asset_path = str(job.get("assetPath", "")).strip()
+        output_path = str(job.get("outputPath", "")).strip()
+        export_morph_targets = job.get("exportMorphTargets", True)
+        if (
+            not slug
+            or not asset_path
+            or not output_path
+            or not isinstance(export_morph_targets, bool)
+        ):
+            raise RuntimeError(
+                "Unreal export jobs require slug, assetPath, outputPath, and a boolean exportMorphTargets"
+            )
+        if output_dir is None:
+            output_dir = os.path.dirname(output_path)
+
+        # A single bad asset (wrong type, won't load, corrupt material, ...) must not discard
+        # every other asset already queued in this batch commandlet run: catch it, record it,
+        # and move on. See batch-backlog.md item 13 — this used to propagate straight out of
+        # the loop and abort the whole UnrealEditor process, silently dropping every
+        # not-yet-processed asset even when they had nothing wrong with them.
+        try:
+            export_asset({
+                "slug": slug,
+                "assetPath": asset_path,
+                "outputPath": output_path,
+                "exportMorphTargets": export_morph_targets,
+            }, texture_cache)
+        except Exception as exc:
+            message = str(exc) or exc.__class__.__name__
+            unreal.log_error(
+                f"HELIX Bridge failed to export {asset_path!r} (slug {slug!r}); skipping it and "
+                f"continuing with the rest of the batch: {message}\n" + traceback.format_exc()
+            )
+            results.append({
+                "slug": slug,
+                "assetPath": asset_path,
+                "outputPath": output_path,
+                "status": "failed",
+                "error": message,
+            })
+            continue
+        results.append({
+            "slug": slug,
+            "assetPath": asset_path,
+            "outputPath": output_path,
+            "status": "succeeded",
+        })
+
+    if output_dir is not None:
+        write_export_results(output_dir, results)
+
+    failed = [result for result in results if result["status"] == "failed"]
+    succeeded = [result for result in results if result["status"] == "succeeded"]
+    if failed and not succeeded:
+        summary = "; ".join(f"{result['slug']}: {result['error']}" for result in failed)
+        raise RuntimeError(f"Every asset in this batch failed to export ({summary})")
+
+
+try:
+    main()
+except Exception:
+    unreal.log_error("HELIX Unreal Bridge export failed:\n" + traceback.format_exc())
+    raise
+finally:
+    unreal.SystemLibrary.quit_editor()