fmodel-unpack
Skill159 starsChanged 2 days agoMITView on GitHub
documents how to use the fmodel-mcp toolkit (a CUE4Parse-based .NET CLI plus a thin Python MCP server) to inspect and export Unreal Engine game assets — pak files, textures, meshes, animations, materials, and raw package JSON. Use it when unpacking/extracting assets from a UE game (e.g. Duet Night Abyss), writing or troubleshooting config.json for a new title, or driving the fmodel-cli subcommands / fmodel_* MCP tools.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- admin-management-pageSkill
- build-creatorSkill
- bun-webview-testSkill
- charbuild-dps-ablationSkill
- db-styleSkill
- dob-skill-creatorSkill
- i18nSkill
- orchestrated-deliverySkill
- perf-hotspot-profilingSkill
- shuorenhuaSkill
- tauri-cdpSkill
- video-productionSkill
- wt-review-prSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
All asset knowledge lives in CUE4Parse.
- Very specific: line 44
Only needed if running the framework-dependent .dll via dotnet exec.
- Very specific: line 82
Run status first. If it errors, almost everything else will too.
- Very specific: line 148
Verify with list [prefix] (does not need the provider):
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
fmodel-unpack
Overview
fmodel-mcp is a minimal, headless alternative to the FModel GUI for ripping assets out of
Unreal Engine games. It is not a fork of FModel — it wraps the underlying CUE4Parse library
directly so an assistant (or a script) can search, read, and export UE assets without clicking
through the FModel window.
It is split into two layers on purpose:
Cli/— the only component that links to CUE4Parse. A single self-containedfmodel-cli.exeexposing subcommands (status,search,read,inspect,export-tex,export-mesh,export-mesh-uf,export-anim,export-raw,list) that all print one JSON object to stdout. Usable standalone for ad-hoc scripts.Server/— a thin FastMCP (Python, stdio) server that invokes the CLI as a subprocess and exposes each subcommand as an MCP tool (fmodel_*).
All asset knowledge lives in CUE4Parse; this toolkit only marshals arguments and parses JSON. That means the CLI can be evolved independently of any LLM integration.
The repo checkout used here is ..\fmodel-mcp. The CLI is already built at
..\fmodel-mcp\Cli\bin\publish\fmodel-cli.exe.
When to use this skill
Trigger this skill when any of the following appear:
- "Extract / unpack / rip assets from
<UE game>" (e.g. Duet Night Abyss, Expedition 33). - "Set up config.json for a game so I can read its paks."
- "Export this texture / mesh / animation / material from the game files."
- Driving the
fmodel_*MCP tools, or invokingfmodel-cli.exedirectly. - Troubleshooting "paks dir not found", mount-point mismatches, Oodle download, AES, or
.usmapmapping errors.
Prerequisites
- .NET runtime — not needed for the self-contained
fmodel-cli.exe(runtime is embedded). Only needed if running the framework-dependent.dllviadotnet exec. - Internet on first run —
fmodel-clidownloads the Oodle decompression DLL (oo2core_9_win64.dllon Windows) on demand from the OodleUE GitHub release. The DLL is not redistributable and is gitignored. After the first successful run it sits next to the exe and is reused. - For the MCP server: Python ≥ 3.11 and
uv(uv syncinServer/). - The game's paks present on disk (
.pak/.utoc/.ucas).
Note on versions:
Cli/FModelCli.csprojtargetsnet10.0. The README still mentionsnet9.0in places (andServer/src/server.pydefaults its fallback DLL path toDebug/net9.0/...). This mismatch is harmless — the server prefers the publishedbin/publish/fmodel-cli.exefirst. Always prefer the published exe; only fall back to a Debug.dllbuild if you deliberately made one.
Step 1 — Configure for the game (the central step)
Copy config.json.example to config.json next to the CLI binary
(Cli/bin/publish/config.json) or point the FMODEL_MCP_CONFIG env var at an absolute path.
Config lookup order inside the CLI: FMODEL_MCP_CONFIG → <baseDir>/config.json →
<repoRoot>/config.json → a fake <EDIT-ME> placeholder (which surfaces a "paks dir not found"
error if nothing is set).
Config keys:
| Key | Meaning | Nullable |
PaksDir | Directory holding the game's *.pak / *.utoc / *.ucas | No |
OutputDir | Where exports land (mirrors FModel's Output/Exports/ role) | No |
UeVersion | CUE4Parse enum, e.g. GAME_UE4_27, GAME_UE5_4 | No |
MappingsFile | Path to a .usmap file (often required for correct property names) | Yes |
AesKey | Encryption key as hex string (omit for unencrypted games) | Yes |
MountPoint | Content mount, e.g. EM for Duet Night Abyss, Sandfall for E33. Used to rewrite /Game/X → <MountPoint>/Content/X. Defaults to Sandfall if absent. | Yes |
Detailed, copy-paste configs (Duet Night Abyss, Expedition 33) and where each value comes
from (FModel AppSettings.json) are in references/game-configs.md.
Step 2 — Verify the provider
Run status first. If it errors, almost everything else will too.
# via the MCP tool
fmodel_status()
# or directly
..\fmodel-mcp\Cli\bin\publish\fmodel-cli.exe statusExpected shape:
{
"ok": true,
"paksDir": "...",
"outputDir": "...",
"ueVersion": "GAME_UE4_27",
"mappings": "....usmap",
"mappingsLoaded": true,
"files": 123456
}files is the number of indexed package entries — a non-zero count means paks mounted and
Oodle + AES + mappings all applied.
Step 3 — Locate the asset (search)
search takes a glob over package paths (the same keys CUE4Parse indexes). Rules:
** matches any number of path components, * matches a single component, ? matches one
character. Case-insensitive.
fmodel-cli.exe search "**/MI_*" # material instances
fmodel-cli.exe search "**/MI_Curator*" # exact-ish
fmodel-cli.exe search "EM/Content/Characters/**/*" 1000Returns { ok, pattern, count, truncated, matches:[...] }. truncated is true when the
optional limit (default 200) was hit.
Step 4 — Inspect before exporting (read / inspect)
read <path>→ full FModel-style JSON of every UObject in the package. Verbose; good for blueprints / mesh metadata.inspect <path>→ a compressed material view:parent,blendMode,twoSided,opacityMaskClipValue, plustextures/scalars/vectorsparameter lists. Use this to discover which texture assets a material wires up before exporting them.
Step 5 — Export
| Subcommand | Produces | Notes |
export-tex <path> | OutputDir/.../<name>.png | UTexture2D decoded via SkiaSharp |
export-mesh <path> | ...psk / ...pskx | Skeletal/StaticMesh as ActorX |
export-mesh-uf <path> | ....uemodel | UEFormat mesh |
export-anim <path> | ....ueanim | UEFormat anim (keeps per-bone scale) |
export-raw <path> | ....json | Full indented JSON dump to disk |
Export paths mirror the package path under OutputDir (slashes become separators). For
Blender rigging, pair export-mesh-uf (.uemodel) with export-anim (.ueanim) — both are
UEFormat and share a consistent bind pose when imported via the UEFormat Blender addon. The
plain export-mesh (PSK) + export-anim (UEFormat) combo can drift on bone-scale animations
(e.g. the giant Paintress in E33).
Verify with list [prefix] (does not need the provider):
fmodel-cli.exe list "EM/Content/Characters"Full subcommand signatures, return JSON shapes, and the path-normalization rules are in
references/cli-reference.md. A convenience wrapper (scripts/fmodel.py) locates the published
exe and runs any subcommand from a plain shell.
Step 6 — (Optional) Expose as MCP tools
cd ..\fmodel-mcp\Server
uv syncThen register the server in your MCP client config (WorkBuddy ~/.workbuddy/mcp.json or
Claude Code ~/.claude.json):
{
"mcpServers": {
"fmodel": {
"command": "uv",
"args": ["run", "--project", "D:\\dev\\fmodel-mcp\\Server", "python", "src/server.py"]
}
}
}Override the CLI binary with FMODEL_CLI_BIN=/abs/path/fmodel-cli.exe if needed. Tool names map
1:1: fmodel_status, fmodel_search, fmodel_read, fmodel_inspect_material,
fmodel_export_texture, fmodel_export_mesh, fmodel_export_mesh_uf, fmodel_export_anim,
fmodel_export_raw, fmodel_list_exports.
Path normalization (critical gotcha)
NormalizePath accepts several input forms and always returns a mount-relative package path
without extension and without the FModel .0 index:
EM/Content/Characters/Foo✔EM/Content/Characters/Foo.uasset✔ (extension stripped)EM/Content/Characters/Foo.0✔ (trailing index stripped)/Game/Characters/Foo→ rewrites to<MountPoint>/Content/Characters/Foo✔
So a /Game/... path only resolves correctly if MountPoint is set in config. For Duet
Night Abyss, MountPoint must be "EM" — without it, /Game/... paths wrongly resolve to
Sandfall/Content/... and read/export will fail to find the package.
Troubleshooting
- "paks dir not found" / 0 files →
PaksDirwrong, or noconfig.jsonresolved (setFMODEL_MCP_CONFIG). Checkstatusoutput. - Oodle error on first run → no internet to fetch
oo2core_9_win64.dll. Manually drop the matching Oodle DLL next tofmodel-cli.exe(from OodleUE). - Empty / wrong property names → game needs
MappingsFile(.usmap). PointMappingsFileat the correct version-specific usmap; confirmmappingsLoaded: trueinstatus. - Decryption failures → encrypted paks need
AesKey(hex). Duet Night Abyss ships one; leaveAesKey: nullonly for unencrypted titles. read/export"package not found" → path used the/Game/form butMountPointis wrong/unset, or the path still has an extension/.0index. Use the mount-relative form or fixMountPoint.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

