Import an Unreal Map into GripForge Map Studio: Native Extraction Guide
How to run a local UE 5.7 export of an existing Unreal map, upload it, and review what actually survives in Map Studio.
GripForge Map Studio cannot open a .umap file directly, and the hosted MCP endpoint cannot read files sitting on your local disk. To bring an existing Unreal map in, you run a local native extraction against a real Unreal Engine 5.7 install on your machine, which writes a persistent, checkpointed job folder at the location you specify without touching the source map. You then upload that export, which creates a new private work scene in the browser scene editor for visual review — not an automatically validated, guaranteed-accurate copy of your level.
What actually crosses over is PBR static props, foliage patches, and editable Landscape (heights, holes, baked terrain color). Blueprint logic, Niagara effects, animated water, and procedural sky systems do not travel through this path — they need separate adapters, and nothing here should be read as a promise of full engine fidelity.
Prerequisites, exactly
Before you start, confirm these four things — each one is a real precondition, not a nice-to-have:
- Unreal Engine 5.7 installed locally. The extraction runs a commandlet against your own editor build; there is no cloud-side UE instance doing this for you.
- The local MCP client,
@gripforgeai/mcp, connected to your coding agent or workflow. The hostedhttps://gripforge.ai/mcpendpoint returns tool results but has no access to your local project folder, so map extraction has to go through the local client. - An absolute
.uprojectpath for the project containing the map. - The map's asset path in
/Game/...form (the way Unreal itself references the level), plus the path to your local editor executable and a persistent job directory.
If any of these four are missing or wrong, the job will not start correctly — see Troubleshooting below.
Export the map and review the imported scene
1. Point the export at your project and level
Use gripforge_map_unreal_export_local with project_file (the absolute .uproject path), source_level (the /Game/... asset path), editor_executable and a persistent job_directory. Inspect gripforge_map_import_unreal_schema for the current portable-scene contract and limits.
Acceptance check: the job accepts the inputs and reports a job directory path back to you. If it errors immediately, read the returned error and check paths, permissions, engine version and project requirements before retrying.
2. Let the commandlet run against a persistent job folder
Extraction runs as a separate commandlet process, not inside your interactive editor session. It writes to a persistent job directory and checkpoints its progress as it goes. Two things matter here:
- Your source map is preserved. The commandlet reads and exports; it does not modify or resave the original
.umap. - The job folder survives interruptions. Because progress is checkpointed, you can check status later rather than re-running the whole extraction from scratch.
Acceptance check: the job directory exists on disk and grows over time. If it's empty after a reasonable wait, check that the editor executable actually launched (look for a hung or crashed UE process).
3. Check status, resume, or cancel
Use the status tool to see whether the job is running, finished, or stalled. If you need to stop it — wrong level selected, wrong project — cancel rather than killing the editor process directly, so the job folder stays in a consistent state for a later retry.
Acceptance check: status reporting matches what you'd expect (running → complete, or a clear failure reason). If progress stops, inspect the job status and commandlet logs. A large Landscape can take time, but an unchanged checkpoint can also indicate a failure.
4. Upload the completed export
Once the job reports complete, upload it. This step creates a new private work scene — it does not overwrite anything and it is not shared by default.
Acceptance check: a new scene appears in your workspace, distinct from any existing scenes.
5. Review visually in the scene editor
Open the new work scene in Map Studio's scene editor. This is the real acceptance gate — upload success only means the transfer worked, not that the level is faithfully represented.
Walk the scene and check:
- Static props and foliage patches are present and roughly positioned.
- Landscape terrain shows the expected heights, holes, and baked color.
- Compare unsupported gameplay and effects systems against the export report. A Blueprint actor may contain exportable static components, but transferring geometry does not transfer its behavior. Record which parts need adapters or rebuilding.
What travels vs. what doesn't
| Comes through | Does not come through |
|---|---|
| Static meshes with PBR materials | Blueprint gameplay logic |
| Foliage patches | Niagara particle systems |
| Landscape heights and holes | Animated/dynamic water |
| Baked Landscape terrain color | Procedural sky and atmosphere systems |
Anything in the right column needs a separate adapter or manual rebuild — plan for that before you promise a client or teammate a one-to-one level port.
Troubleshooting
- Job won't start: re-check the
.uprojectabsolute path and that the editor executable version matches the project's engine association (5.7). - Job starts but produces nothing: confirm the
/Game/...level path is exact — a renamed or moved level asset is a common cause. - Upload succeeds but the scene looks sparse: compare the export report with the source level. Distinguish unsupported effects or behavior from missing static components that should have transferred.
- Terrain looks flattened or holes are wrong: compare the exported height and hole data, scale and job logs with the source Landscape. Baked color is a separate output and does not prove height or hole fidelity.
FAQ
Does this modify my original Unreal map?
No. The commandlet reads and exports; your source .umap is preserved.
Can I run this through the hosted MCP server instead of installing anything locally?
No. The hosted endpoint cannot read local .umap files — extraction requires the local MCP client and a local UE 5.7 install.
Does upload mean the map is validated and ready to ship?
No. Upload creates a new private work scene for review; you still need to visually confirm props, foliage, and terrain before treating it as usable.
For the underlying tool names and parameters, see the MCP documentation and general product docs. If you're assembling a level from reusable pieces rather than porting an existing one, the greybox-to-playable workflow is a related starting point, and once assets land you'll want a consistent way to organize meshes, textures, and bindings across both pipelines.