---
name: ferret-unreal-porting
description: Use to port an Unreal Engine 5 level or game to Ferret with tools/ue-export: what maps, the order of the work (census, spike, export, postprocess, Blueprints, viewer, parity), how to run the Unreal side so the output is complete, and the traps of real ports.
---

# Porting from Unreal Engine 5

## When to use
Bringing a UE5 level into Ferret, planning a port, or deciding what a UE feature becomes. For a level that loads but looks wrong use `ferret-unreal-level-look`; for characters and animation `ferret-unreal-characters`.

## Through Caroline's tools
With UE on the person's own Windows computer, use `ue_places`, `ue_import`, `ue_export`, `ue_status`, `ue_cancel`: the importer app there does the work (`tools/ue-export.md`, "The importer app"). No app online: give the installer link from that page. No UE on their computer: no import or export.

## What maps
Level to a level and travel; Actor/Blueprint to entity + behaviour by name (a mapping file the game keeps); Character Movement to `character` with the same numbers; Animation Blueprint to an `animation` graph; NavMesh to `ai`; collision to `physics` layers; Enhanced Input to actions; UMG rewritten per widget. Lumen, Nanite, Chaos destruction and MetaHuman rigs have no equivalent (`reference/ue-export.md`).

## Steps
1. **Census** (headless, seconds): classes, unique meshes and instances, textures and sizes, Blueprint instances with their variables. Check every column for empty values before trusting it.
2. **Spike**: the stock exporter on the whole level, opened in the viewer as is.
3. **Export** with rendering on, the real project open (the game's C++ module), a short path; then environment, collision, landscape, physics, Blueprints, material parameters (`reference/ue-export-runs.md`).
4. **Postprocess**: `postprocess.mjs level.glb out/ --tier all --environment ... --collision ... --nav ...`; `--no-lights` for a level whose lamps were baked, `--world-aligned` for world-aligned materials.
5. **Blueprints**: read each class's graph as a spec, map it in the game's mapping file, rewrite as behaviours with tests. Unknown classes are reported, never dropped.
6. **Viewer**, then **parity** with the original from the same cameras (`ferret-unreal-level-look`).
7. Write what was found and what still differs into the level's port plan after each step.

## Check afterwards
The level validates and loads; spawns, doors and triggers work by the original's names; the parity shots match or each difference is recorded.

## What usually goes wrong
- Baked textures empty or grey: rendering off, materials not compiled.
- Actors silently missing: the scratch project lacks the game's C++ classes.
- A door's target is a loader level with an options string; spawn names are the `PlayerStart`s' tags (`PS_MAIN`), not their labels.
- A trigger's size lives in a per-instance box extent the export does not carry: read it, do not guess a radius.
- `-game` runs the real game with its network; stop your own editor processes when done.
- Guessing a fix for a wrong look before finding its cause (see `ferret-unreal-level-look`).
- Game-specific data (presets, which meshes make a character, the mapping) belongs to the game, not the exporter.

## Files

- `reference/ue-export.md` — The export pipeline that turns a UE5 level into a Ferret level package, and how UE concepts map to Ferret's.
- `reference/ue-export-runs.md` — How to run the export scripts in Unreal 5.8 so they give complete output, and the traps found in real ports: rendering, paths, missing C++ classes, scratch levels, live servers.
- `reference/levels.md` — The level manifest, the level registry and travel, environment, and the .ferret package format.