Eve library

Isis 3D output → Unreal import and cook (audit F.2)

Other

Revision 1

On this page

@bellona/unreal may not depend on Isis, and Isis may not depend on Bellona, so the mapping between them lives here: import-and-cook.ts takes an Isis 3D output (a GLB, glTF or FBX with its recorded sha256), refuses bytes that don't match, maps the file to a Bellona HeadlessImportTask, and runs Bellona's own CookOrchestrator:

  • the import job drives HeadlessImporter: UnrealEditor-Cmd running a generated Python commandlet, with success read from the editor's marker lines;
  • the cook job drives UnrealCookRunner: RunUAT BuildCookRun, cook only.

Then it lists the .uasset files on disk under the destination, in Content/ and in Saved/Cooked/, and exits non-zero if either is missing.

Unreal refuses to run as root. When the tool runs as root, every engine process is started through sudo -u ueagent.

The probe project#

A content-only project in ueagent's home, with PythonScriptPlugin and EditorScriptingUtilities enabled. Config/DefaultGame.ini lists the destination in DirectoriesToAlwaysCook:

ini
[/Script/UnrealEd.ProjectPackagingSettings]
+DirectoriesToAlwaysCook=(Path="/Game/Isis")

Without that setting, the cooker cooks only maps and what they reference. The first cook here finished with UAT reporting success and not one Isis asset cooked (452 engine assets, nothing under /Game/Isis). That is why the tool checks the cooked files instead of trusting the job status.

Run it#

bash
npx tsx --tsconfig tools/isis-unreal-import/tsconfig.json tools/isis-unreal-import/import-and-cook.ts \
  --mesh tools/presentations/tests/fixtures/recorded-glb/study-room-t0602.glb \
  --sha256 d929316dcd09e614897dc7914591331312a62a07fa6e99b21b78d7fca53d5133 \
  --engine /root/workspace/UnrealEngine-5.5 \
  --project /home/ueagent/isis-import-probe/IsisImportProbe.uproject \
  --destination /Game/Isis/StudyRoom --cook
npx vitest run --config tools/isis-unreal-import/vitest.config.ts   # the mapping spec

Recorded run, 2026-09-21 (Unreal 5.5.4 source build on the dev server)#

The input was T.06.02's study room, an Isis scene-assembly output whose provenance is in tools/presentations/tests/fixtures/recorded-glb/sources.json.

  • Import. 18 objects (16 static meshes and the oak and plaster materials) were imported into /Game/Isis/StudyRoom in 35 s on the first run, and saved as 18 .uasset files of 45–54 KB.
  • Cook. 18 cooked .uasset files and their .uexp payloads were written to Saved/Cooked/Linux/IsisImportProbe/Content/Isis/StudyRoom/. The meshes are about 1.5 KB plus 4–6 KB each, and the materials 1.1 KB plus 17 KB. The first cook took 578 s (engine content and global shaders); the second, iterative with the cook directory set, took 26 s.

evidence/study-room-2026-09-21.json records the job outcomes and the size and sha256 of every imported and cooked file.