FERRETGame engine over Babylon.js
Ferret

Porting from Unreal Engine 5

Skill ferret-unreal-porting · download all skills · SKILL.md

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 PlayerStarts' 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.