unreal-assets

Unreal Assets

A skill for reading and editing Unreal Engine binary assets (.uasset, .umap) without corrupting them. Works on any Unreal project on this machine.

What this skill gives you

Two tiers of tooling, picked per task:

Tier	Tool	Cost	Use when
1. Fast	scripts/inspect.py (stdlib Python)	~50 ms, no UE needed	Surface-level questions: what type is this? what does it reference?
2. Deep	scripts/run_ue.sh <uproject> <ue_script> [args] — runs Python inside headless Unreal Editor	~30–60 s cold start, ~5 s warm	Need the real parent class, variables, components, DataTable rows; any kind of edit

Tier 2 is authoritative because it uses Unreal's own APIs (unreal.EditorAssetLibrary, unreal.Blueprint, unreal.DataTable, etc.). It requires the Python Editor Script Plugin to be enabled in the UE editor — see references/setup.md if smoke tests fail.

When to use this skill

Triggers — if any of these apply, use the skill:

• File path ends in .uasset or .umap
• User mentions an asset by UE path like /Game/Bearships/App/BearshipsController_BP
• User references a Blueprint, DataTable, Widget, Material, or other UE asset concept
• .uproject file is in the working directory and the task touches content
• git status / git diff shows .uasset / .umap changes
• User asks "what does X do" where X is a Blueprint class name (*_BP, BP_*, *_C in logs)

Hard rules

1. Never Edit or Write a .uasset or .umap file directly. They are binary — you will corrupt them. Editing happens only through Tier 2 (UE Python).
2. Never Read a .uasset file as text. The output is garbage and wastes context. Use inspect.py first.
3. Before any edit, make sure the user has committed (or stashed) current changes. See references/workflow.md for the commit-first rule and why.
4. If the editor is currently open on this project, warn the user before running Tier 2. Tier 2 opens its own editor instance. Running two editors against the same project can lock or corrupt files. Ask the user to close the editor first.
5. If a task needs Blueprint graph-node surgery (editing event graphs, rewiring nodes), you cannot do it reliably via Python. Explain the change in human terms and defer to the user. See references/blueprints.md.

Decision tree

User mentions a .uasset or /Game/... asset
│
├─ Question is "what is this / what does it reference / what's its class?"
│     → Tier 1: python3 <skill>/scripts/inspect.py <path>
│
├─ Question is about a Blueprint's variables / components / parent class
│     → Tier 2: run_ue.sh <uproject> ue_scripts/dump_bp.py /Game/<path>
│
├─ Question is about a Blueprint's graph logic ("what does this function do?",
│  "why does X call Y?", "what's the control flow here?")
│     → Tier 2: run_ue.sh <uproject> ue_scripts/dump_graph.py /Game/<path> [GraphName]
│     → Requires ClaudeUnrealBridge UE plugin. Scope with a graph name on big BPs.
│
├─ Question is about a DataTable's rows
│     → Tier 2: run_ue.sh <uproject> ue_scripts/dump_dt.py /Game/<path>
│
├─ Need to edit a DataTable (add/update/delete rows)
│     → Build JSON patch → run_ue.sh ... ue_scripts/edit_dt.py /Game/<path> <patch.json>
│     → See references/datatables.md for patch schema
│
├─ Need to edit a Blueprint (var default, parent class, component)
│     → run_ue.sh ... ue_scripts/edit_bp.py /Game/<path> <op.json>
│     → Scope is LIMITED (no graph edits). See references/blueprints.md.
│
└─ Asset type not yet covered (Widget, Material, Map, …)
      → Fall back to Tier 1 for metadata. Tell the user what's missing and
        offer to extend the skill by adding a new ue_scripts/dump_<type>.py.

Paths on this machine

• Skill root: ~/.claude/skills/unreal-assets/ (symlink → ~/Developer/claude-unreal-tools/skills/unreal-assets/)
• UE editor binary (macOS default): /Users/Shared/Epic Games/UE_5.7/Engine/Binaries/Mac/UnrealEditor.app/Contents/MacOS/UnrealEditor — override by setting UE_EDITOR env var.

Path conventions

Unreal scripts take /Game/... paths, not filesystem paths. Rules:

• Content/Bearships/App/BearshipsController_BP.uasset → /Game/Bearships/App/BearshipsController_BP
• No .uasset / .umap extension in the UE path.
• Case-sensitive on all platforms.

inspect.py accepts filesystem paths. Tier 2 scripts accept /Game/... paths.

Quick recipes

Inspect any asset (fast)

python3 ~/.claude/skills/unreal-assets/scripts/inspect.py \
    Content/Bearships/App/BearshipsController_BP.uasset

Returns JSON with the file's class names, imports (things it depends on), and exports (things it defines). Good for 90% of "what is this?" questions.

Dump a Blueprint (deep)

~/.claude/skills/unreal-assets/scripts/run_ue.sh \
    ./BearGame.uproject \
    ~/.claude/skills/unreal-assets/scripts/ue_scripts/dump_bp.py \
    /Game/Bearships/App/BearshipsController_BP

Dump a Blueprint graph's topology (nodes + connections)

~/.claude/skills/unreal-assets/scripts/run_ue.sh \
    ./BearGame.uproject \
    ~/.claude/skills/unreal-assets/scripts/ue_scripts/dump_graph.py \
    /Game/Bearships/Systems/Bears/BearBase_BP TraceForItems

Pass a specific graph name (like TraceForItems or EventGraph) to scope big BPs. Omit to dump every graph. Requires the ClaudeUnrealBridge UE plugin. Output includes full control-flow (exec) and data-flow edges, with node titles and semantic references — enough to reconstruct what the graph actually does.

Dump a DataTable (deep)

~/.claude/skills/unreal-assets/scripts/run_ue.sh \
    ./BearGame.uproject \
    ~/.claude/skills/unreal-assets/scripts/ue_scripts/dump_dt.py \
    /Game/Bearships/Systems/Bears/Customization/SpeciesTypes

Patch a DataTable

1. Write the patch to a temp file (see references/datatables.md for schema).
2. Run edit_dt.py /Game/<dt> /tmp/patch.json.
3. Re-run dump_dt.py and diff to verify.
4. git status should show the DT's .uasset modified — commit it.

First-time smoke test for a new project

~/.claude/skills/unreal-assets/scripts/run_ue.sh \
    ./BearGame.uproject \
    ~/.claude/skills/unreal-assets/scripts/ue_scripts/smoke.py

Expected output: {"ok": true, "engine": "5.7.x", "project": "BearGame"}. If it fails, see references/setup.md.

References

Deeper material — load on demand, don't inline into SKILL.md:

• references/blueprints.md — what's readable/editable on a Blueprint, 5.7 API caveats, the graph-surgery limitation.
• references/datatables.md — row-struct model, discovering the struct class, patch schema.
• references/uasset-format.md — primer on the binary format Claude needs for interpreting inspect.py output.
• references/workflow.md — safety rules: commit-first, redirectors, when to defer to human.
• references/setup.md — one-time setup, enabling Python Editor Script Plugin, troubleshooting.

Extending this skill

Support for a new asset type (e.g. Widgets):

1. Drop scripts/ue_scripts/dump_wbp.py mirroring dump_bp.py.
2. Add a decision-tree branch above pointing at it.
3. Add references/widgets.md for the per-type detail.
4. Bump plugin version in .claude-plugin/plugin.json.

No changes needed to inspect.py or run_ue.sh — they are asset-type-agnostic.