Getting Started

Inspect a package

ue3-tools upk-header Game/CookedPCConsole/Interface.upk
ue3-tools list       Game/CookedPCConsole/Interface.upk

upk-header prints the parsed package summary — version, decoded flags, table counts, GUID, generations, compression chunks. list prints every export in UE notation:

#312 Texture2D UI_Menu.Backgrounds.MainMenu
#313 SwfMovie UI_Menu.Movies.hud

Extract

ue3-tools --game-root /path/to/Dishonored/DishonoredGame \
          extract Game/CookedPCConsole/Interface.upk

Always pass --game-root

Without it there is no schema database. Extraction still runs, but arrays and non-atomic structs degrade to @bytes(...) hex, enum values print as raw bytes, no class/struct/enum declaration files are produced, and textures stored in .tfc files cannot be resolved.

Extract a single object — the filter is a substring matched against both the UE full name and the derived filesystem path:

ue3-tools --game-root /path/to/game extract Interface.upk MainMenu output/

Skip all conversion and dump the raw serialized bytes:

ue3-tools extract Interface.upk MainMenu output/ --raw

What you get

Output is <output_dir>/<package stem>/ with the object's UE path mirrored underneath. Texture2D UI_Menu.Backgrounds.MainMenu becomes:

output/
└── Interface/
    └── UI_Menu/
        └── Backgrounds/
            ├── MainMenu.uo     ← properties + native block + sidecar refs
            └── MainMenu.dds    ← decoded texture payload

Class	Sidecars written
`Texture2D`	`<name>.dds`
`SwfMovie`, `GFxMovieInfo`	`<name>.gfx`
`SoundNodeWave`	`<name>.ogg` / `.wav` / `.mp3` / `.xma`, plus `.raw.wav`, `.xbox360.`, `.ps3.`
`StaticMesh`, `SkeletalMesh`	`<name>.glb` (extract-only)
Any class with a `RawData` property	`<name>.RawData.<ext>`, extension sniffed from the content

Material, MaterialInstanceConstant, MaterialInstanceTimeVarying, Font and MultiFont write no sidecar; their native data stays in the .uo.

Meta-objects (Class, ScriptStruct, Enum, Const, *Property) are emitted as UnrealScript-shaped declarations instead of property dumps. They're reference material — the mod packer skips them automatically.

Edit and pack

Edit the .uo text, or just drop a replacement .dds / .gfx / .ogg next to it, then:

ue3-tools --game-root /path/to/game pack-mod output/Interface --out mymod/

mymod/
└── Interface/
    ├── UI_Menu.Backgrounds.MainMenu.bin
    ├── Interface.newnames
    └── Interface.newexports        ← only if new objects were referenced

That set is what a loader such as CU3ML consumes at runtime. See Building Mods.

GUI

ue3-tools --game-root /path/to/game ui

The GUI is an inspector with a mod builder built in.

Inspect. Open packages and browse exports, imports and the name table, with views for UO code, hex, and the schema tree, plus texture previews.
Build a mod. The mod workspace lets you pick objects, fill in the mod's key, name, version, author and description (and optional Lua source), choose an output folder and press Build. It extracts the selected objects to a temporary directory and runs the same packer as pack-mod, writing <output>/<key>/mod.toml, main.lua and overrides/.

The GUI doesn't save extracted files for hand-editing. To keep .uo files and sidecars on disk, use the CLI extract command.