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

`@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.
