What is RPFM?

Rusted PackFile Manager (RPFM) is a modding tool for every Total War game from Empire (2009) onwards. It’s a Rust + Qt6 reimplementation of the original PackFile Manager (PFM), built to be fast, accurate and pleasant to spend hours in.

What it does

In modern Total War games, the data the engine utilizes lives inside .pack files: archives that bundle DB tables, localisation strings, scripts, models, textures, animations, sounds and more. Modding the game means producing your own Pack and telling the launcher to load it on top of the vanilla data.

RPFM is the editor where that Pack is built. It opens, inspects, edits and saves Packs, and ships editors/viewers for every common file type inside them:

• DB tables — schema-aware grids with lookups, references, sorting, filtering, spreadsheet copy/paste and TSV import/export.
• Loc files — localisation tables with TSV import/export.
• Text & scripts — Lua, XML, JSON, HLSL and dozens of other text formats with KDE syntax highlighting.
• Animations — AnimPack, AnimTable, AnimFragment, MatchedCombat.
• Models & visuals — RigidModel, DDS/atlas images, Portrait Settings.
• Video — the proprietary CA_VP8 format.
• Specialised — ESF (saves and startpos), BMD (battle maps), and a few more.

Beyond editing individual files, RPFM understands a Pack as a whole and how it relates to the rest of the game data. That’s where the more interesting features live:

• Diagnostics that catch invalid references, missing locs, broken portrait variants, animation gaps and dozens of other classes of mod bugs before the game does.
• Global Search with regex across the open Pack — or across vanilla and parent mods too.
• Dependency manager that keeps track of vanilla data and parent mods and powers reference lookups everywhere else.
• Pack optimiser that strips ITM rows, datacore deletes and unused content to keep the final Pack lean.
• MyMod workspaces that bundle a Pack with its assets and templates, with one-click install to the game folder.
• Translator that makes keeping mod translations up to date painless.

How RPFM is built

RPFM is split into two cooperating processes:

• rpfm_ui — the Qt6 desktop application you interact with. Everything you see — menus, editors, dialogs — lives here.
• rpfm_server — a headless backend that does the heavy work: file I/O, schema decoding, diagnostics, search, dependency resolution. The UI launches it automatically.

This split exists because the same backend is also exposed over WebSocket and the Model Context Protocol, so AI tools and other clients can drive Total War file editing programmatically. If you’re a tool author, see the Server section.

A note on PFM

If you’ve used the original PackFile Manager, the menus and layouts will feel familiar — that’s deliberate. RPFM started as a straight reimplementation of PFM in Rust and Qt and has grown well past it, but the muscle memory should still mostly transfer.

Where to go next

• Installation — get RPFM on your machine.
• First-time configuration — point RPFM at your games so the smart features can do their job.
• The main window — orient yourself in the UI.

You can always reach this manual from inside RPFM via About → Open RPFM Manual, or by clicking in the manual button in the welcome page.

Installation

RPFM ships pre-built for Windows and Linux. macOS isn’t supported yet — there’s no maintained build.

Windows

1. Download the latest rpfm-vX.Y.Z-x86_64-pc-windows-msvc.zip from the releases page.
2. Extract the archive anywhere — your Documents folder, a tools folder on a secondary drive, anywhere you like. RPFM is portable; it doesn’t need an installer.
3. Run rpfm_ui.exe.

That’s it. The first launch will take you to first-time configuration.

Heads-up: Don’t extract the zip into a path that requires admin rights (e.g. Program Files). RPFM writes certain update-related files relative to where its files are, and a write-protected install path causes confusing errors.

Linux

Arch Linux and derivatives

The recommended install is the rpfm-bin package on the AUR:

# With your favourite AUR helper
paru -S rpfm-bin
# or yay -S rpfm-bin

There’s also rpfm-git if you want to build from the latest develop branch yourself.

Other distributions (Flatpak)

A Flatpak is the easiest way to run RPFM on any distro that supports Flatpak. The Flatpak bundles Qt6 and the KDE Frameworks RPFM needs, so you don’t have to install them yourself. Refer to the project’s releases page for the current Flatpak download.

Building from source

If your distro doesn’t have a maintained package and the Flatpak doesn’t fit, see Building from source.

macOS

There’s no maintained macOS build. The qt_* Qt6 bindings RPFM uses build on macOS in principle, but nobody is currently producing or testing macOS releases. If you want to take that on, contributions are welcome.

Updating

By default RPFM checks for updates on launch and shows a dialog when one is available. The update flow downloads the new version, replaces the binaries and restarts. Beta and stable channels are configurable from Preferences → Updates.

On Linux, in-app updates are disabled — your distribution’s package manager (or Flatpak) is the one in charge of updates. Update through the same channel you used to install.

Verifying it works

After launching for the first time you should see the welcome page, with quick links to the manual, recent Packs, and your update status. If you got that far, the install is good. Move on to first-time configuration.

First-time configuration

RPFM works on Pack files, but most of the interesting features — diagnostics, dependency lookups, MyMod, the optimiser — only work properly when RPFM knows where your games live and which schemas to use. The first-time configuration takes about a minute and unlocks everything.

Open Preferences (Edit → Preferences, or Ctrl+P then “Preferences”). Settings are laid out as a single scrollable list grouped into sections — Paths, General, Table, Debug, Diagnostics, Telemetry, AI — with a search field at the top you can use to jump straight to a setting by name.

1. Set the game paths

In the Paths section, point RPFM at every Total War game install you care about. For each game, browse to the folder that contains the game’s executable (e.g. …/steamapps/common/Warhammer 3 for Warhammer 3).

On first launch RPFM scans your Steam libraries and fills in the game (and Assembly Kit) paths it finds automatically, so in most cases you just need to check the list and fill any gaps by hand. Autodetection only runs when a path is empty — it never overwrites one you’ve set yourself — and it only covers Steam installs, so non-Steam copies still need to be pointed at manually.

You don’t have to fill in all of them — only the ones you mod. Empty entries are fine.

RPFM uses these paths to:

• Load vanilla data for reference lookups, diagnostics and ITM detection.
• Run the optimizer and the Tools (Faction Painter, Unit Editor, Translator) against a real game install.
• Resolve where MyMod installs its packs.

You can still switch to a game that has no path set, but anything that reads vanilla data (diagnostics, dependency cache, optimizer, Tools, MyMod install) will either fail or produce empty/false results until you point RPFM at the install.

2. Pick a default game

Still in Preferences, in the General section, set Default Game. RPFM will switch to that game on launch and treat its schema as the active one. You can change the active game later from the Game Selected menu — see The main window.

3. Set the MyMod and Secondary paths

Two workspace paths live in the Paths section:

• MyMod Base Path — folder where all your MyMod projects live. RPFM will create one subfolder per game inside it (e.g. MyMod/warhammer_3/, MyMod/three_kingdoms/). If you don’t plan to use MyMod, you can skip this — but most non-trivial mod projects benefit from the workspace structure MyMod provides. See What is MyMod?.
• Secondary Folder — folder where mod launchers (Runcher and any other launcher that supports this feature) store the mods they manage, outside the game’s /data and /content directories. Pointing RPFM at it populates the Pack → Open From Secondary submenu with the Packs in that folder, so you can open them without digging through the filesystem. Skip it if your launcher doesn’t support a secondary folder.

4. Download or check schemas

Schemas are the per-game definitions RPFM uses to decode DB tables. They don’t ship with the program — they’re pulled in through the Update Manager, and they need updating every time Creative Assembly patches a game.

From the menu bar, run About → Check Updates. The Update Manager handles the program itself, schemas, and a couple of other auxiliary data sets (Lua autogen, Empire/Napoleon AK) from one dialog, with a button per component; press the schemas one to fetch the latest set from the rpfm-schemas repo. Do this on first launch to get the initial schemas, and again whenever a Total War game gets a content patch.

5. (Optional) Generate the dependency cache

Diagnostics, references and the dependency manager are dramatically more useful with a dependencies cache of the vanilla game files for the active game. Generate it once per game:

Game Selected → Generate Dependencies Cache

Generating it can take a few minutes — RPFM is reading and indexing every vanilla Pack. The cache is automatically invalidated whenever the game updates, so you’ll need to regenerate it after every patch.

6. (Optional) Set up the Assembly Kit (where supported)

Some tables — units, buildings, technologies — only exist in the Assembly Kit and not in the game’s Pack files. If you want diagnostics and references to cover those too:

1. Install the Assembly Kit for the game from Steam (look for “Assembly Kit” or “Mod Tools” in the game’s tools list).
2. In Preferences → Paths, set the Assembly Kit path for the game.
3. Regenerate the dependencies cache (Game Selected → Generate Dependencies Cache). When an AK path is set, its data is folded into the same cache — there’s no separate step.

The AK isn’t shipped for every game. For Empire and Napoleon there’s no AK to install, but archived AK definitions are available as an optional download through the Update Manager (About → Check Updates) — grab them from there if you mod either game.

7. (Optional) Telemetry & crash reports

RPFM ships with two opt-out toggles in Preferences → Telemetry:

• Enable Usage Telemetry — anonymous counters of which actions get used. Helps prioritise development.
• Enable Crash Reports — automatic upload of panic reports to Sentry when something crashes. Helps fix bugs.

Both are on by default. Turning either off takes effect immediately.

You’re set

That’s the configuration done. The rest of the manual covers what you can actually do with the program — start with The main window for an orientation, or jump to a specific editor if you know what you’re after.

The main window

A quick orientation tour. Once you know where everything lives, the rest of the manual will make sense as it points at this or that panel.

The pieces

1. Menu bar. Top of the window. Houses every global action — see below.
2. Tab bar. Sits under the menu bar. One tab per open file.
3. Pack tree. Left dock, top half. Shows the files inside the open Packs. Right-click anything in the tree for context actions; double-click a file to open its editor in a new tab.
4. Dependencies. Left dock, under the Pack tree. Shows the contents of the active game’s dependencies cache (vanilla + parent mod Packs), so you can browse them alongside your own files.
5. Editor area. The big central region. Whatever tab is active here drives most of what you can do.
6. Side and bottom panels.
   • Diagnostics — bottom dock, visible by default. Lint-style warnings for the open Packs.
   • Global Search — right dock, hidden by default. Toggle from View or with its shortcut.
   • References — bottom dock, hidden by default. Populated when you ask “what points at this row?” from an editor.
   • Quick Notes — not a dock. It’s a side panel inside each file editor, toggled per-tab.
7. Status bar. Bottom strip. Shows short-lived status messages from the last operation.

The welcome page

When no Pack is open, the editor area is replaced by a welcome page with quick links to recent Packs, the manual, the GitHub project, the Patreon (wink wink), and some other useful stuff.

The command palette

Press Ctrl+P (or Ctrl+Shift+P for the action variant) anywhere in the app to open the command palette. It’s a fuzzy finder for:

• Open files (jump to any file inside the Pack by typing part of its path).
• Available commands (run any menu action by typing its name).

For most “where is the menu item that does X?” questions, the command palette is the answer.

The menu bar

Connecting the dots

If you want a focused walk-through of a particular task, the rest of this section covers Pack-level workflows:

• Opening, creating and saving Packs
• The Pack tree
• Pack settings & notes
• Dependencies

For the editors themselves (DB, Loc, Text, etc.), see the Editors section. For everything Pack-relationship-related (search, diagnostics, references), see Search & analysis.

Opening, creating and saving Packs

RPFM can have multiple Packs open at once. Most operations are scoped to a single Pack — the one currently selected. The Pack menu is your starting point for everything in this chapter.

Opening a Pack

The Pack menu has several entry points depending on where the Pack lives:

You can also drag-and-drop .pack files onto the main window to open them.

Multi-pack at once. When several Packs are open, the tree shows them as siblings. Diagnostics, search and dependencies all work across the open set, which is how you debug interactions between mods or compare a mod against vanilla.

Creating a new Pack

Pack → New Pack creates an empty Pack in memory. It isn’t on disk until you save it. The new Pack defaults to type Mod for the active game; to change the type or compression, right-click the Pack’s root in the Pack tree and use the Change PackFile Type and Compression Format submenus before saving.

Pack types

RPFM supports every Pack type the engine understands. The most common are:

• Mod — the standard type for player-made mods. This is what you want 99 % of the time.
• Movie — official types used by Creative Assembly themselves. Only used in mods to load certain stuff.
• Boot — loads first, before everything else. Used by official content; rarely appropriate for player mods.
• Release, Patch — official types used by Creative Assembly. Don’t use these for your own work unless you know exactly why.

The active type can be changed from the Change PackFile Type submenu in the Pack tree’s right-click menu (on the Pack’s root).

Saving

If you have many Packs open, use Save All rather than going through them one at a time.

Compression

Packs can be compressed with LZMA1, LZ4 or ZSTD (game-dependent), or left uncompressed. Pick the format from the Compression Format submenu in the Pack tree’s right-click menu (on the Pack’s root). RPFM will only auto-compress tables for Warhammer 3 and newer — older games crash on compressed table data, so the option isn’t offered for them.

Sessions

rpfm_server (the headless backend the UI talks to) holds all of your currently open Packs — together with their dependencies — inside a single server-side session. Pack → Select Session… lets you reattach to that session if the UI was disconnected, getting every Pack back in one go — useful after a rpfm_ui crash where the server was still running. See Server overview for the details.

Autosave

RPFM autosaves the open Packs at the interval configured in Preferences → General → Autosave Interval. Recover from Pack → Open from Autosave. Setting the interval to 0 disables autosave.

What’s next

Now that you can move Packs in and out, the next chapter covers what to actually do with them: The Pack tree.

The Pack tree

The Pack tree is the left-hand panel listing the contents of every open Pack. Files are grouped by their in-Pack path (DB tables under db/, locs under text/, etc.). The tree is the entry point to almost every per-file action in RPFM.

Navigating

• Double-click a file to open its editor in a new tab.
• Single-click to select, and to open its editor in a preview tab. Multi-select with Shift (range) or Ctrl (additive).
• Right-click to open the context menu (covered below).
• Filter with the search box at the bottom of the tree. Matches against file paths; the tree collapses to show only matching entries.

Modified or newly-added items are marked with a thin vertical line on the right side of their row. Two states are drawn:

• Added — new file/folder since the Pack was opened (or since the last save).
• Modified — file with unsaved changes in the Pack (or a folder containing modified children). Modified takes priority over Added when both apply.

Both colours are configurable in Preferences → Appearance (Added and Modified colours, with separate light/dark theme entries). Folders inherit the most “active” state of their children. MyMod Pack roots also get an italic “MyMod” label drawn on the right side of the row.

Context menu

Right-clicking a file or folder gives you the actions below. Most also have keyboard shortcuts you can rebind in Preferences → Shortcuts.

The actions are grouped under three submenus (Add…, Create…, Open…) plus a flat list of file operations and Pack-level actions.

Add…

• Add File — pick one or several files from disk and add them to the Pack at the selected location.
• Add Folder — recursively add every file under a folder. The directory structure is preserved.

Create…

• New Folder — create an empty folder inside the Pack.
• New AnimPack / DB / Loc / Portrait Settings / Text — create an empty file of the chosen type at the selected location.
• New Quick File — create a file with its type autodetected, based on the folder you have selected.

Open…

• Open with Decoder — open the file in the DB Decoder. Used only for decoding tables.
• Open Dependency Manager — opens the in-Pack dependency manager. See Dependencies.
• Open Containing Folder — opens the folder containing your pack in your file manager.
• Open with External Program — open the file in the external program you have configured in your OS for its type. Edits are reloaded back into the Pack when you save in the external editor.
• Open PackFile Settings — opens Pack settings for the Pack the selection belongs to.
• Open Notes — opens the Notes view for the Pack.

File operations

• Rename/Move — rename the file or folder, or move it to a different in-Pack path. Renaming a folder rewrites every contained path; references in DB tables are not updated automatically.
• Delete — remove the selection from the Pack.
• Extract — write the selected files out to disk, preserving their tree structure.
• Copy Path — copy the in-Pack path to the system clipboard.
• Copy / Cut / Paste — clipboard operations within the Pack tree (or back into the same Pack at a new location).
• Duplicate — create a copy of the selected file inside the Pack.
• Copy To Pack ▸ <other Pack> — copy the selection into another open Pack. Useful when refactoring or splitting mods.
• Merge Tables — only enabled with multiple DB tables of the same definition (or multiple Loc files) selected. Combines them into one and removes the originals. Useful for collapsing many small tables into a single one.
• Update Tables — update the tables in the pack to their latest version supported by the game.
• Generate Missing Loc Data — generates Loc entries for fields in your pack that are missing them.

Pack-root actions

When you right-click the Pack root itself, additional Pack-level actions appear: Save Pack, Save Pack As…, Save Pack For Release…, Close Pack, Install / Uninstall, the Change PackFile Type submenu (Boot, Release, Patch, Mod, Movie, plus header flags), the Compression Format submenu (None, Lzma1, Lz4, Zstd), the Special Stuff actions for the active game (Optimize PackFile, Rescue PackFile, Build Starpos, Patch Siege AI, Live Export, Pack Map, Update Anim IDs), and MyMod actions when the Pack is a MyMod.

Multi-pack operations

Some context-menu actions know about every open Pack:

• Copy To Pack ▸ lists every other open Pack.
• Cut+Paste moves files within a Pack at a new location.

The tree itself only supports drag-drop within a single Pack. To move files between Packs, use Copy To Pack or Cut+Paste.

Tips

• The filter bar accepts substrings and regex. Use it to surface every loc, every animation, every file under text/db/, etc.
• Use Expand All / Collapse All at the bottom of the context menu to quickly fold or unfold the tree.

Pack settings & notes

Each Pack carries a small bundle of metadata that lives inside the Pack itself. These are spread across a few different views and menu actions in the UI; this page covers them.

Pack file type, compression, header flags

These live on the Pack root’s context menu (right-click the Pack in the tree). They are not inside the Pack Settings tab.

Change PackFile Type

A submenu listing the possible PFH file types: Boot, Release, Patch, Mod, Movie. Mods almost always want Mod (shows up in the launcher) or Movie (always-on, hidden from the launcher). The other three are CA-only types and should not be used for player mods.

The same submenu also exposes the header flags as checkable items: Index Includes Timestamp (editable), and Header Is Extended, Index Is Encrypted, Data Is Encrypted (read-only — RPFM cannot save encrypted Packs, but it can read them).

Compression Format

A submenu listing the supported compression formats: None, Lzma1, Lz4, Zstd. Which formats actually work depends on the active game. The selected format is applied the next time the Pack is saved.

Pack Settings tab

Open Pack Settings (Pack root context menu → Open ▸ Open PackFile Settings) opens the Pack Settings as a tab in the main view. It’s a flat scrolling form that holds RPFM-specific behavioural settings for the Pack:

• PackedFiles to Ignore on Diagnostics Check — paths (one per line, # for comments) that the diagnostics tool should skip. Supports per-folder, per-file, per-field and per-diagnostic ignore patterns. Files in this list still contribute reference data — they just aren’t analysed.
• Files to Ignore when Importing — paths to skip when importing from a MyMod folder. MyMod-only.
• Disable Autosaves for this PackFile — turns off autosaving for just this Pack.
• Do Not Generate Existing Locs — when checked, Generate Missing Locs skips Loc entries that already exist in vanilla or in parent files.

Click Apply Settings at the bottom to save changes back into the Pack.

The fields shown here are loaded dynamically from the Pack’s settings, so the exact list may grow over time as new options are added.

Notes

Notes in RPFM are structured — not a single free-form text area, but a list of short notes, each with a message and an optional URL. Notes can be attached to The Pack as a whole — created from the tree’s context menu → Open ▸ Open Notes with the Pack root selected (or with no file selected).

Notes are persisted inside the Pack, are visible in RPFM, and are ignored by the game.

Quick Notes panel

The active file editor includes a Quick Notes side panel that lists the notes attached to the open file. Toggle it from the file tab’s right-click menu → Toggle Quick Notes.

Where the data lives

Pack settings, notes and the dependency manager are stored in a small set of RPFM-reserved files inside the Pack (settings.rpfm_reserved, notes.rpfm_reserved, dependencies_manager_v2.rpfm_reserved). The game ignores these; other tools that don’t know about RPFM will see them as normal files. They round-trip cleanly between RPFM versions.

These reserved files are only written for Packs of type Mod or Movie. Switching the Pack to Boot, Release or Patch before saving therefore strips them.

Dependencies

“Dependencies” in RPFM means two related but distinct things:

1. The vanilla game data plus any parent mods you tell RPFM to consider when looking up references, running diagnostics, detecting ITM rows, and so on. This is the dependency cache.
2. The list of parent Packs declared inside your Pack. This is the dependency manager.

This chapter covers both.

The dependency cache

Most “smart” features in RPFM (reference lookups, table validation, ITM detection, datacore handling, the diagnostics panel, the optimiser, global search across vanilla, MyMod install) need to know what the vanilla game contains. RPFM keeps a cached snapshot of that data per-game.

Generating the cache

Game Selected → Generate Dependencies Cache builds (or refreshes) the cache for the currently active game. The generation can take a few minutes — RPFM is reading every vanilla Pack of the game. Re-run it whenever:

• The game gets a content patch.
• The schemas got updated.
• The cache appears empty/missing files in the Dependencies panel.

The cache is stored under RPFM’s config directory and is per-game.

Assembly Kit data

For games with an Assembly Kit, the cache build also picks up AK-only tables (units, buildings, technologies, etc. that aren’t shipped inside Packs) and stores them alongside the vanilla data. This happens automatically as part of Generate Dependencies Cache — there is no separate “Generate AK Database” command.

For this to work, RPFM needs to know where the Assembly Kit is installed. Set the path in Preferences → Paths → Assembly Kit for each game you have one for. If the path isn’t configured, the cache is still built but RPFM warns that diagnostics may produce false positives because some reference tables won’t be available.

The Dependencies panel

The Dependencies dock (toggle from View → Toggle Dependencies Window) lets you browse:

• Game Files — vanilla Packs, indexed.
• Parent Files — files contributed by parent mods you’ve declared.
• Assembly Kit Files — Assembly-Kit-only tables and locs.

You can open any vanilla / parent / AK file in a read-only editor — useful for checking how Creative Assembly does things, or comparing your overrides against their source.

The in-Pack dependency manager

A Pack can declare other Packs as parents. The game itself ignores this list, but RPFM uses it to identify the packs to load as part of the dependencies when opening the pack.

To edit a Pack’s declared parents, right-click the Pack in the tree → Open ▸ Open Dependency Manager. It opens as a tab in the main view.

The manager is a small two-column table:

• Load before ingame? — checkbox. Forces the game to load the pack as dependency if present. Alters the load order and is not recommended to check it.
• Pack — the parent Pack file name (e.g. parent_mod.pack).

Order can matter for some games — when in doubt, list parents in load order.

Setting parents matters for diagnostics. Without them declared, RPFM treats parent-mod content as missing and may report false positives in the diagnostics panel. If you’re modding on top of someone else’s mod, declare it.

Putting it together

A typical workflow when you start a new mod project:

1. Make sure the dependencies cache is built for your game (and that the Assembly Kit path is set in Preferences if the game has one).
2. In your new Pack, open the Dependency Manager and declare any parent mods you depend on.
3. From here on, Diagnostics, References, DB editor lookups and the Optimiser will all work correctly against your specific load order.

Editors overview

Every supported file type opens in a dedicated view that knows how to decode, present and re-encode that format. Views live in tabs in the central panel; the Pack tree is where you launch them from.

How editors behave

• Open by double-click. Double-clicking a file in the Pack tree opens it in a new tab. Re-opening an already-open file just brings its tab forward.
• Tabs do not survive Pack switches. Editors stay open until you close them, or you close the Pack underneath. RPFM warns before destroying unsaved changes.
• Save are usually on-edit, except in some editors. Editors save on edit the changes to the in-memory Pack, except some editors which have a save button at the bottom of the screen. You still need to save the Pack for changes to hit the .pack file on disk.
• External editing. From the tree’s context menu, Open with External Program extracts the file into a temp folder and hands it to your OS’s default app for that file type. Edits round-trip back into the Pack when you save them externally. There is no per-extension configuration in RPFM Preferences — the OS decides which app opens what.

Supported file types

JSON debug view means the file decodes via the lib, gets serialised to pretty JSON, opens in a text editor, and you save it by hitting Save (the JSON is parsed back into the typed structure). It’s editable but it’s not a UI — handle with care.

For the live list of formats rpfm_lib understands and their lib-side capability, see the rpfm_lib::files API docs. A format with full lib support may still only have a debug view in the UI.

The DB Decoder

A separate, lower-level tool for reverse-engineering binary table layouts. Used when a game patch changes a table format and the schema needs an update. See The DB Decoder.

DB tables

The DB editor is the heart of RPFM. Every Total War mod that changes unit stats, tech effects, building chains, faction colours, ability cooldowns or hundreds of other things does it by editing rows in a DB table.

What’s a DB table?

A binary file under db/<table_name>_tables/<file_name> inside a Pack. Each table has a schema-defined set of typed columns and a list of rows. RPFM resolves the schema for the active game on load, decodes the rows, and presents them as a grid you can edit like a spreadsheet.

Layout

The editor itself is just the grid plus a small status bar at the bottom (line counter, flagged-rows filter button). There is no top toolbar — every action lives in the grid’s right-click context menu, plus a couple of pop-up panels:

• Filter bar at the bottom of the grid, with Use Regex and Case Sensitive toggles and a column-group selector. Filter matches across the selected column group.
• Search panel (Ctrl+F) — a pop-up find/replace bar over the grid; column-aware. For project-wide replace use Global Search.
• Sidebar panel — a per-column hide / freeze checkbox grid. Open it from the right-click menu’s Sidebar entry. Frozen columns stay pinned to the left of the grid as you scroll.

The grid’s vertical header (row numbers) is always visible; the horizontal header is visible by default but column visibility/freezing is driven from the Sidebar panel rather than from a header right-click menu.

Right-click context menu

Right-click anywhere in the grid for the full action set. Highlights:

• Add Row / Insert Row / Delete Row / Delete Filtered-Out Rows
• Clone ▸ Clone & Insert Row / Clone & Append Row
• Copy ▸ Copy / Copy as LUA Table / Copy to Filter Value
• Paste / Paste as New Row
• Generate IDs, Rewrite Selection, Revert Values, Reset Selected Values, Invert Selection
• Resize Columns
• Import TSV / Export TSV
• Search (Ctrl+F opens the search bar)
• Sidebar (toggles the per-column hide/freeze panel)
• Find References — opens the References panel for the selected cell.
• Cascade Edition — rename a key everywhere it’s referenced; see below.
• Patch Columns — write a schema patch for the selected column without modifying the schema itself.
• Go To ▸ Go To Definition / Go To File / Go To Loc (when a matching loc column exists for the row).
• New Profile — save the current column visibility / sort / filter as a named profile.
• Undo / Redo.

Editing rows

The grid behaves like a spreadsheet:

• Click to select, double-click to edit.
• Tab / Shift+Tab move between columns; Enter commits.
• Range selection with Shift-click; column / row selection by clicking the header.
• Copy / Paste with Ctrl+C / Ctrl+V. RPFM supports pasting from Excel / LibreOffice / Google Sheets — copy cells from a spreadsheet and paste them straight in.
• Sort by clicking a column header.

Type-aware editing

Each column edits according to its declared type:

Lookups & references

When a column references another table (a foreign key), RPFM:

• Shows the referenced value’s lookup field (e.g. the unit’s display name) as part of the cell.
• Surfaces invalid references as red highlights and as Diagnostics entries.

The global default for “show lookups vs raw keys” is PackFile → Settings → Table → Enable Lookups.

Cascade Edition

Renaming a row’s key is normally a footgun: every other table that references that key will break. Cascade Edition does it safely.

1. Select the cell whose key you want to rename.
2. Right-click → Cascade Edition.
3. RPFM finds every reference to the old key across the active Pack and its parents, and asks for confirmation.
4. On confirm, the key is renamed everywhere atomically.

Use this whenever you rename a unit, building, faction, technology, or any other keyed entity that’s referenced by other tables.

TSV round-tripping

Export a DB table to TSV when you want to:

• Edit it in a spreadsheet program with formulas.
• Diff it in git as plain text.
• Run a script that produces the table mechanically.

The TSV header carries enough metadata for RPFM to re-import the file as the right table type. Re-importing replaces the table’s content wholesale.

Patches

If a column needs different display behaviour (a different lookup, a tooltip, a default value, …) without changing the table’s column layout, a schema patch overrides the field metadata at runtime. Patches ship inline inside each per-game schema file — there’s no separate overlay file to load. The right-click Patch Column action saves your override into a local per-game patch file under your config directory, which gets layered on top of the schema-shipped patches the next time the schema is loaded.

When the schema is wrong

If a table refuses to decode or shows obviously wrong values, the schema for that table is likely out of date.

1. About → Check Updates to pull the latest schemas (along with the program, lua autogen, and old-AK updates).
2. If the table was changed recently and no schema is available yet, open the file in the DB Decoder to update the definition manually.

See also: Diagnostics, References, Global Search.

Loc files

Loc files (anything ending in .loc — vanilla puts them under text/, mods conventionally use text/db/ or text/) hold the localisation strings the game shows to the player. The Loc editor is a simplified DB editor with three columns: key, text, and tooltip.

The columns

• Key. The string the game uses to look up the entry. Must be unique within the Pack. Conventionally namespaced (e.g. units_descr_short_text_my_unit).
• Text. The actual displayed string, in whatever language this loc file is for. Supports the engine’s inline tags ([[col:red]], [[/col]], etc.) — RPFM doesn’t validate them, but Diagnostics will catch obviously broken pairs.
• Tooltip. Unknown. Historically called tooltip for some reason.

Editing

Same controls as the DB editor: row add/remove/clone, find & replace, filter, sort by column, paste from spreadsheets, TSV round-tripping. The text columns are wide by default since most rows have multi-word values.

Diagnostics for locs

Several entries in the Diagnostics panel target locs specifically:

• Empty key / empty text — usually a typo or an accidental row.
• Duplicated key — two rows with the same key in the same Loc file.
• Invalid escape sequences — usually [[col:…]] tags without a matching closer.

Run diagnostics after a translation pass to catch the easy mistakes.

TSV workflow for translators

The recommended flow for translating a mod is:

1. Open the mod in RPFM.
2. Use Tools → Translator to extract translatable strings into a structured editor (see Translator) — this is the best path for full mod translations because it integrates with the Total War Translation Hub.

If you really want raw TSV instead, every Loc editor has Export TSV — translate in a spreadsheet, then Import TSV to bring the translation back in.

Text & scripts

Anything text-shaped opens in the text editor. RPFM uses KTextEditor under the hood, which means proper syntax highlighting, line numbers, find/replace, multi-cursor and the rest of the modern code-editor toolkit — for free, on every supported language.

What counts as “text”

RPFM auto-detects text-shaped files by extension. The editor handles, among others:

• Scripts — Lua, Python, batch files, shell.
• Markup — XML, HTML, JSON, YAML, TOML, INI.
• Shaders — HLSL, GLSL, CG, FX.
• CA-specific — .battle_script, .twui, .twui.xml, .kfa, .kfc, .kfp, .tweak, .environment.
• Plain — .txt, .md, .csv (when not opened as a table).

For the full list, see the rpfm_lib::files::text module.

Features

The KTextEditor backend gives you:

• Syntax highlighting for every detected language.
• Find / replace (Ctrl+F / Ctrl+R) with regex support.
• Multi-cursor / column selection (Ctrl+Alt+click).
• Bookmarks and quick-jump.
• Code folding for languages that support it.
• Indent / unindent (Tab / Shift+Tab).
• Open / save integration with the Pack — your edits go into the in-memory Pack on save.

External editor

If you’d rather use VS Code, Neovim or anything else, Open with External Program from the Pack tree’s right-click menu extracts the file to a temp folder and opens it with your OS’s default app for that extension; saving it externally pushes the change back into the Pack. There’s no per-extension override inside RPFM — the OS picks the app.

Images & DDS

The image editor is a viewer that handles most image formats CA uses, including DDS, PNG, JPG and the various atlas formats.

What it does

• Preview the image — most DDS formats decode to PNG for display, including the BC1–BC7 compressed variants.
• Zoom with the mouse wheel; pan by dragging.

What it doesn’t do

There’s no in-app pixel editor. To edit an image:

1. Extract it from the Pack (Pack tree → Extract).
2. Open it in your image editor of choice (GIMP, Photoshop, Krita…).
3. Save it back to disk.
4. Add it back to the Pack at the same path (Pack tree → Add File…), or use Open with External Program to wire your editor up so the round-trip happens automatically.

Atlases

.atlas files are layout maps for sprite sheets — each entry references a region of an associated DDS. They open in their own simple table editor (under Specialised editors) rather than the image viewer.

Video (CA_VP8)

.ca_vp8 is a Creative Assembly–specific container around a VP8 video stream — used for movies, intros and similar. RPFM has full read/write support and can convert to and from the standard .ivf container.

What you can do

• Inspect stream metadata: width, height, frame count, framerate, codec version (v0 or v1).
• Convert to and from IVF — can convert CA_VP8 files to and from IVF files, editable with ffmpeg.
• Check video integrity — verify the stream parses cleanly. Useful when debugging a video the game refuses to play.

Editing a video

There’s no in-app video editor. To re-encode a CA_VP8:

1. Convert the file to IVF (button in the editor toolbar).
2. Open the IVF in your video tool of choice and produce a new VP8 stream. FFmpeg works:

   ffmpeg -i input.mp4 -c:v vp8 -b:v 2M output.ivf
   

3. Convert back from IVF in the editor to bake the new stream into the .ca_vp8.

AnimPack

An AnimPack (.animpack) is a container file CA uses to bundle animation-related game data — animation tables (AnimsTable), animation fragments (AnimFragmentBattle), matched-combat tables, and the raw .bin animation files referenced by them — into a single archive the engine can load efficiently. From a modder’s perspective it’s a “Pack inside a Pack”.

Layout

The editor opens as a single tab with two side-by-side panels and an instructions banner across the top.

• Left panel — a live view of the main contents tree of every open Pack. It mirrors what you see in the dockable Pack tree, including all open Packs simultaneously.
• Right panel — the contents of the AnimPack itself. Read-only display: you can browse and filter, but you can’t open files into editors from here.

Each panel has its own filter line edit, case-sensitive toggle, auto-expand-matches toggle, and Expand-all / Collapse-all shortcuts.

What you can do

The editor exposes exactly three operation:

• Copy a file into the AnimPack — double-click a file in the left panel. The file is copied from the open Pack into the AnimPack.
• Copy a file out of the AnimPack — double-click a file in the right panel. The file is copied out of the AnimPack into the open Pack at the same path.
• Delete a file from the AnimPack — select it on the right panel and press Del (the action is shortcut-bound; there is no visible context menu).

If the open AnimPack is from vanilla (GameFiles) or a parent mod (ParentFiles) rather than your own Pack, the copy-in action is silently disabled — you can only modify AnimPacks you own. Copy-out from a vanilla AnimPack into your own Pack is allowed.

Which Pack the operations target (multiple Packs open)

Every operation resolves the target Pack from the left panel’s own selection inside the AnimPack tab (or, if nothing is selected there, the first editable Pack in the panel). The dock’s selection is irrelevant here.

• Copy in: source files come from the Pack of the file you double-clicked on the left panel, and the AnimPack inside that same Pack is what gets modified.
• Copy out: the file is written into the Pack currently selected (or first) on the left panel of the AnimPack tab. If that Pack doesn’t have an AnimPack at the same path, the operation errors.
• Delete: operates on the AnimPack inside the Pack currently selected (or first) on the left panel.

So to switch which Pack you’re working against, click a node belonging to that Pack inside the AnimPack tab’s left panel — not in the dockable contents tree.

Caveats

• Renaming files inside an AnimPack is not supported in the editor — you’d have to copy out, rename in the parent Pack, copy back in, and delete the original.

Animations

Three closely related animation file types share a chapter but each have different UI maturity in RPFM today: AnimsTable, AnimFragmentBattle, and MatchedCombat.

If you’re new to TW animation modding, the practical order is: AnimsTable defines the animation library; AnimFragmentBattle says how those animations apply to a creature in battle; MatchedCombat orchestrates the synchronised “two units fighting each other” animations.

AnimsTable

UI is a JSON debug view: the file decodes via the lib, gets serialised to pretty JSON in a text editor, and saving parses the JSON back into the structured form. Round-trip works, but there is no row-grid UI yet — you edit JSON.

AnimFragmentBattle

A proper structured editor — the only one of the three that has a custom UI. The view exposes the fragment’s metadata (skeleton name, locomotion graphs, identity flags) as form widgets, and the per-entry table as an embedded grid.

Diagnostics for AnimFragmentBattle catch:

• Missing locomotion graph references.
• Missing referenced animation files.
• Missing sound files.

MatchedCombat

UI is a JSON debug view, same model as AnimsTable. The lib has different decode paths per game (Three Kingdoms, Warhammer 3, and a default for the rest) so the JSON shape varies, but the editor is the same generic JSON editor.

Anim & legacy formats

.anim files (the raw animation streams the others reference) currently have no UI viewer at all in RPFM. The lib has read support so they’re decodable programmatically, but double-clicking one in the tree will not open it.

Portrait Settings

Files matching *portrait_settings*.bin (typically under ui/) describe how a character’s portrait is composed in-game: which art set the character belongs to, which variants of that art set are available, the head-and-body camera setup for each entry, and which texture files supply the diffuse and mask layers for each variant. The Portrait Settings editor gives you a structured view instead of a binary blob.

Layout

The tab is one widget split between a left list of entries and a right detailed view.

• Entries list (left) — one row per “art set entry”, keyed by its art_set_id. The id is what tables like campaign_character_arts_tables.art_set_id reference. A filter line edit sits above the list.
• Detailed view (right) — driven by the entry currently selected on the left. Contains, in order:
  • Head camera group box — z, y, yaw, pitch, distance, theta, phi, fov, skeleton node.
  • Body camera group box (checkable — toggle the title bar to enable/disable the body camera for this entry) — z, y, yaw, pitch, fov, skeleton node.
  • Variants group box — its own filtered list of variants belonging to this entry. Selecting a variant fills the rest of the panel.
  • Variant fields — diffuse file, mask 1 / 2 / 3 file paths (line edits), season (string), level (spinbox), age (spinbox), politician (checkbox), faction leader (checkbox).
  • Texture previews — four group boxes (diffuse, mask 1 / 2 / 3) that render the actual texture from the referenced path (with a fallback search that swaps /portholes/ for /units/). The previews refresh ~500ms after you finish editing the path.

Which fields are visible depends on the file’s binary version: older versions hide the fields that didn’t exist yet (e.g. version 1 has only the spherical head-camera fields and no body camera; version 4 omits season/level/age/politician/faction-leader and the spherical head fields). The editor adjusts visibility automatically on load.

Operations

All operations are right-click context menus on the two list views, not toolbar buttons. There is no toolbar.

On the entries list:

• Add — create a new empty entry.
• Clone — duplicate the selected entry (disabled until you have a selection).
• Delete — remove the selected entry (disabled until you have a selection).
• Delete filtered-out rows — once a filter is active in the entries list, delete every entry that the filter is currently hiding. Useful for trimming an entry set down to only the rows that match a pattern.

On the variants list:

• Add, Clone, Delete — same semantics, scoped to the selected entry’s variants. There is no “delete filtered-out rows” on the variants list.

Beyond that:

• Edit fields — change spinboxes, line edits, checkboxes directly. All changes are buffered into the selected list item and committed when you save the file. There is no separate “apply” step.
• Filters — the entries filter and the variants filter are independent line edits with case-insensitive substring matching, debounced behind a short timer.

Diagnostics integration

The Portrait Settings checks in Diagnostics cover:

• Datacored Portrait Settings file — the file is identical to a vanilla one and adds nothing.
• Invalid Art Set Id — the entry’s art_set_id isn’t declared in campaign_character_arts_tables.art_set_id (across vanilla, parents, and the open Pack).
• Invalid Variant Filename — a variant’s filename isn’t declared in variants_tables.variant_filename (or variant_name, as a fallback for older games).
• Missing texture file — for each variant, separate checks for the diffuse and the three masks: the referenced path doesn’t exist anywhere in the open Pack, parents, or vanilla.

For a tidy mod, run diagnostics after a portrait pass — it’ll catch most of the small mistakes that produce missing-portrait icons in-game.

Audio

CA’s audio pipeline is built on Wwise and ships as several related artefacts inside Packs:

• Sound banks (.bnk) — Wwise-format containers with the audio assets.
• Sound bank databases — table-shaped indices that match bank IDs to game-side names.
• Sound events — DB-shaped tables the rest of the game references when something needs to play.

In RPFM today the only dedicated UI is a play/stop media player for individual audio files (.wav, .ogg, …).

What you can do

• Play / stop any audio file the editor recognises (the audio editor view is just two toolbar buttons).

What you can’t (yet)

• Author or repackage a .bnk from raw audio inside RPFM.
• Inspect a .bnk’s internal event list, listed assets, or other internal metadata.

For new audio content, use Asset Editor.

RigidModel

.rigid_model_v2 (RMV2) is CA’s in-engine 3D model format — used for units, monsters, buildings, props and effectively everything you see on the battle map. RPFM reads and writes versions 6, 7 and 8 of the format. Pre-RMV2 model formats (the ones in Empire and Napoleon) are not supported.

Layout

The tab is a horizontal splitter: the editor form on the left, and (when enabled) the 3D preview on the right.

The editor form contains:

• RMV group box — the format version combobox (8 / 7 / 6) and the Export to glTF button.
• LOD tree — every LOD in the file as a top-level node (Lod 0, Lod 1, …); each LOD’s mesh blocks appear as children, labelled with the material name (e.g. Mesh Block 0 (Material: weighted_skin)). Selecting a LOD or a mesh block fills the detail panels on the right; switching selection auto-saves the previous selection’s edits back into the in-memory model.
• Detailed view group box (per-LOD) — visibility distance, authored LOD number, quality level. Active when any LOD or mesh block is selected.
• Mesh block group box (per-mesh-block) — mesh name, texture folder, shader name. Only active when a mesh block is selected, not the LOD root.
• Textures table — two columns (texture_type, texture_path) listing the textures attached to the selected mesh block’s material. Editable like a regular table view.

Editing

The editor is editable, not read-only — for files inside your own Pack. When a file is loaded from GameFiles or ParentFiles, the save path is a no-op (you can change the fields, but they won’t be persisted).

What you can change from the UI:

• Per-LOD: visibility distance, authored LOD number, quality level.
• Per-mesh-block: mesh name, texture directory, shader filters.
• Per-texture: texture type and path, via the textures table.
• Per-file: format version (re-encode as 6, 7 or 8 via the combobox).

What is not editable from the UI: vertex data, bones, geometry, attachment points, custom material parameters, cloth/grass/collision-specific data. To make changes there, author the model in Blender / 3ds Max / Maya with the appropriate CA exporter and import the resulting .rigid_model_v2 into your Pack.

3D preview

The 3D preview is gated by both:

• The support_model_renderer Cargo feature at build time. Default release builds may or may not include it depending on the platform — the renderer pulls in a separate native library that isn’t on every target.
• A runtime setting (enable_renderer in preferences). Even when the build supports it, the renderer is only spun up when this setting is on.

When both conditions are met and the model loads, the renderer attaches as a second pane in the splitter and stays in sync with the file’s in-memory state on save and reload. Failures to load the renderer are non-fatal — the editor still works, just without the 3D pane.

glTF export

Export to glTF in the RMV group box converts the current in-memory model to glTF 2.0 (one scene per LOD) and writes it to a path you pick via a Save dialog. Useful for opening CA models in Blender or other standard 3D tooling.

The same conversion is available programmatically via rpfm_extensions::gltf for tools that want to batch-convert outside the UI.

Specialised editors

Several less-common file types have dedicated views that didn’t warrant their own chapter. Grouped here for completeness.

UnitVariant

Variant mesh definitions for units — which RigidModel goes with which faction colour scheme, kit, etc. The view is a proper structured editor: a categories list on the left, a variants list in the middle for the selected category, and a per-variant form on the right (mesh file, texture folder, an unknown numeric value). Add / clone / delete on both lists from their right-click menus.

A separate read-only JSON debug view for the same file type also exists behind a settings, in case you want to edit the file more freely.

Atlas

Sprite-sheet layout files. Each row defines a region (UV rectangle + name) within an associated texture. Atlas files open in the regular DB editor — full grid editing, TSV round-trip, the whole DB editor toolset.

ESF

.esf is CA’s binary format for save games and startpos files. Massive, deeply nested, and slow to parse. RPFM exposes it as a tree of nested nodes with typed leaves (ints, floats, strings, arrays).

Disabled by default. The ESF editor lives behind the Enable ESF Editor toggle in PackFile → Settings → Debug. Turn it on first; otherwise opening an .esf falls back to the JSON debug view.

• Browse the full structure as a tree.
• Edit leaf values in place via a side detail panel.
• Filter within the loaded ESF (substring + regex toggle, plus an “auto-expand matches” option).

Writing is supported but slow on big files (a multi-hundred-MB save can take a few seconds). Most ESF editing is for startpos files in a campaign mod context.

BMD

Battle Map Definition files — the binary scene description for battle maps (terrain, props, lighting). The current view is a JSON text editor: the file decodes via the lib, gets serialised to pretty JSON, and saves parse the JSON back. Editable but unstructured.

Group formations

Formation definitions for unit groups (e.g. infantry block, cavalry charge wedge). UI is a JSON debug view — the lib supports full read/write for the per-game variants (Warhammer 3 / Three Kingdoms / Troy / Rome 2 / Shogun 2 each have their own decode path), but the editor is the generic JSON editor.

Animation file formats summary

For convenience, here’s where each animation-shaped format lives in the manual:

The DB Decoder

The DB Decoder is a low-level tool for reverse-engineering or fixing a DB table’s binary layout. You only need it when:

• A game patch changed a table’s columns and the schema is now wrong (rows decode as garbage, or fail outright).
• You’re adding support for a previously unknown table.

For routine editing, you want the DB editor. The Decoder is a development tool.

Opening the Decoder

Right-click a DB file in the Pack tree → Open ▸ Open with Decoder. The file opens in its own tab and the decoder takes over the whole tab.

Layout

The decoder isn’t a “preview-the-table” view. It’s a byte-walker: a cursor moves through the file, and you commit one field at a time to the schema. The tab is laid out as:

• Hex pane (top-left) — three monospace columns: byte offsets, raw hex bytes, and the ASCII rendering. The header bytes are shaded one colour, the bytes already covered by the schema you’re building are shaded another (yellow on light themes), and the next byte the cursor is sitting on is shaded a third (magenta on light themes).
• Fields table (top-right) — one row per field already committed to the schema. Columns include Field Name, Field Type, First Row Decoded (the value at that position in row 1 of the file), Is key?, Ref. to Table, Ref. to Column, Lookup Columns, Default Value, Is Filename, Filename Relative Path, CA Order, Description, Bitwise Fields, Enum Data, Is Part of Colour. Right-click a row for Move Up / Down / Left / Right / Delete.
• Current Field Decoded (middle) — for the bytes at the current cursor position, this panel shows what they would decode to as every supported type, side by side. Each row is one type, with a line edit showing the candidate value and a Use this button that commits that type as the next field and advances the cursor.
• PackedFile Info (right) — table type, an editable version (spinbox), and the entry count read from the header.
• Versions list (right, bottom) — every other version of this table that the schema already knows about. Right-click for Load definition (replace the in-progress definition with that version’s) or Delete definition (remove that version from the schema).
• Buttons (bottom row) — Import from Assembly Kit, Test Definition, Remove all fields, Finish it!.

There is no live preview of the decoded table.

Workflow

1. Read the header

DB files start with: an optional GUID block, an optional version block, a one-byte flag, and a u32 entry count. The decoder reads this for you on open and pre-shades that region in the hex pane — your cursor starts immediately after it.

2. Pick a starting point (optional)

Three shortcuts before you start decoding by hand:

• Import from Assembly Kit — if the AK ships a definition for this table, load it and let the decoder render it. Most often the right starting point.
• Versions list → Load definition — if a previous version of this table is in the schema, load it and only fix what changed (CA usually adds columns rather than reshuffling the layout).

3. Commit fields one at a time

For each field, look at the Current Field Decoded panel and pick the row whose value looks plausible (a string that reads as text; an integer in a believable range; a float that isn’t 1e-39). Hit Use this on that row. The cursor advances by the size of that type, the field appears in the fields table, and the panel updates with the next set of candidates.

The supported types are: Boolean, F32, F64, I16, I32, I64, OptionalI16, OptionalI32, OptionalI64, ColourRGB, StringU8, StringU16, OptionalStringU8, OptionalStringU16, SequenceU32. There is no I8, the colour type is ColourRGB (no alpha), and the only sequence variant is SequenceU32.

After committing, edit the row in the fields table to fill in the Field Name (this is what becomes the column header in the DB editor) and any other metadata you have — key flag, references to other tables, default value, etc.

If you commit the wrong type, right-click the field and use Move Up / Down to reorder, Delete to remove it (which rewinds the cursor by that field’s size), or just hit Remove all fields and start over.

4. Test

Test Definition re-decodes the current file with the in-progress definition. On success you get a “Seems ok.” dialog. On failure you get the decoder error, with extra context for incomplete decodes (so you can see how far it got before things went wrong).

The decoder doesn’t iterate over multiple files for you — to validate the definition against vanilla or other parent files, save it first, then open one of those files in the regular DB editor.

5. Save

Finish it! writes the definition into the active schema for the version shown in the PackedFile Info spinbox, and reloads any DB editor tabs already open on this table so they pick up the new definition.

6. Submit upstream

Schema changes saved locally only live in your install until you submit them. PR them to rpfm-schemas so everyone benefits — see Schemas & patches.

Tips

• Most schema breakages are “CA inserted a new column” rather than a wholesale layout change. Load the previous version from the versions list and walk the cursor up to the suspected insertion point — the candidates panel will tell you where the layout diverges.
• SequenceU32 columns are recursive: a u32 count followed by that many copies of an inner sub-row. Decode them last and expand them in the fields table to define the inner fields.

Global Search

The Global Search panel finds — and optionally replaces — text across every supported file type in the open Packs (and, optionally, in vanilla and parent mods). It’s the closest thing RPFM has to a project-wide grep.

Toggle the panel from View → Toggle Global Search Window (default shortcut Ctrl+Shift+F).

Pattern & options

• Pattern. What to match. By default it’s a literal substring search.
• Use Regex. Treat the pattern as a regular expression instead.
• Case sensitive. Off by default.

There is no “match whole word” toggle — wrap the pattern in word boundaries yourself in regex mode (\bword\b) if you need that behaviour.

Sources

A search can target several sources independently:

• Per-Pack checkboxes. One checkbox per open Pack appears under the Sources group; tick the ones you want included.
• Game Files. Vanilla files for the active game (requires the dependencies cache).
• Parent Files. Parent mods declared by the active Pack (see Dependencies).
• Assembly Kit Files. AK-only tables and locs (requires the AK install path to be configured for the active game).

You can mix any combination. The result tree groups matches per source.

File types covered

The search has a per-file-type checkbox for every editable type RPFM knows about. There’s also a Search on All master toggle and a Search on All Common toggle (DB / Loc / Text — the day-to-day editable types).

For DB tables and Loc files the matches are cell-level with row context; for text-style files matches are line-level; for the structured types (Atlas, Portrait Settings, etc.) matches are field-level inside the file’s structure.

Working with results

Each match in the results tree is clickable: clicking a DB cell opens the table and selects the cell, clicking a Loc match opens the right loc file at the right key, and so on.

Multi-select results to scope a follow-up replace.

Replace

Two modes:

• Replace match — replace the currently-selected match(es) with the replacement text.
• Replace all matches — replace every match in the result set in one shot.

Replace operations only run on Packs (Game / Parent / AK sources are read-only and skipped automatically).

Replace is destructive. Make sure you’ve saved (or have a recent autosave) before doing a project-wide replace, especially with regex.

Diagnostics panel

Diagnostics is RPFM’s static analyser for Packs. It runs a battery of checks across the open Packs and surfaces structured warnings and errors — invalid references, missing locs, broken portrait variants, datacore mistakes, and dozens of other classes of mod bug.

Toggle the panel from View → Toggle Diagnostics Window.

What it checks

Diagnostics is grouped internally by check category (one variant of DiagnosticType per category):

Every diagnostic carries a severity (Info, Warning, Error), a category, the file path it applies to, the row/cell/field it relates to, and a short description.

Running diagnostics

• Run all — checks every file in every open Pack.
• Run on open files — limited scope; useful in big Packs.
• Auto-run — two togglable triggers in PackFile → Settings → Diagnostics:
  • Trigger diagnostics on Pack open
  • Trigger diagnostics on table edit (only fires while the diagnostics dock is visible)

There are no “on file add” or “on Pack save” auto-run triggers.

Triaging results

Double-click a diagnostic to jump to the offending file / row / cell. Right-click for the ignore actions:

• Ignore Parent Folder / Ignore Field for Parent Folder — skip every diagnostic on every file in the parent folder, optionally narrowed to a specific field.
• Ignore File / Ignore Field for File — skip every diagnostic on this file, optionally narrowed to a specific field.
• Ignore Diagnostic for Parent Folder / Ignore Diagnostic in Field for Parent Folder — skip just this specific diagnostic type across the parent folder, optionally narrowed to a field.
• Ignore Diagnostic for File / Ignore Diagnostic in Field for File — same, scoped to one file.
• Ignore Diagnostic for Pack — skip this diagnostic type across the whole Pack.

There is no “Fix automatically” or “Copy diagnostic” action today — every fix is manual.

Where ignores live

Each ignore action appends one line to the Pack’s Files Ignored on Diagnostics Check setting (the multi-line text field exposed in the Pack Settings tab — see Pack settings & notes). The Pack Settings tab also documents the per-file / per-field / per-diagnostic syntax if you want to write entries by hand.

These ignores live inside the Pack itself, survive across RPFM restarts, and travel with the .pack to anyone else who opens it.

Reading severities

• Error — something that will cause a problem in-game.
• Warning — likely a problem, but might not be a problem in-game.
• Info — heads-up; noteworthy but not necessarily wrong.

If you’re shipping a mod, aim for zero errors and as few warnings as possible. Info entries are usually fine to leave alone.

References panel

The References panel answers the question “where else is this referenced?” for any DB cell. It’s the modder’s “find all usages” — invaluable before deleting, renaming, or changing a row whose key something else depends on.

Toggle the panel from View → Toggle References Window.

Triggering a reference search

In any DB editor, right-click a cell whose value is a key (typically a primary key or a foreign-key value) and choose Find References. The References panel populates with every other place that key appears — across the open Pack, parent mods, vanilla, and (where relevant) the Assembly Kit.

Reading the results

Each result is a row in a small table with these columns:

• Data Source — PackFile, ParentFiles, GameFiles, or AssKitFiles.
• Path — the in-Pack path of the file containing the reference.
• Column Name — the column that’s referencing the key (DB-only; blank for loc/filename refs).
• Row Number — the row containing the reference.

(There’s also a Column Number column, hidden by default — you can re-show it from the table header’s right-click menu if you need it.)

Click a result to jump to it.

Common workflows

• Before deleting a row. Run a reference search on the row’s key. If anything in your Pack references it, you’ll need to clean those up first. References from vanilla / parent mods mean the row probably shouldn’t be deleted at all.
• Before renaming a row. Same as above. If the references are all in your own Pack, Cascade Edition (right-click → Cascade Edition in the DB editor) can do the rename across them in one shot.
• Auditing a new feature. After adding a new unit, run a reference search on its key to confirm it’s wired up everywhere it should be (cost table, recruitment table, faction availability, etc.).
• Understanding a vanilla mechanic. Open a vanilla DB table from the Dependencies panel, reference-search a key that interests you, and follow the trail.

Limitations

References are computed from declared schema relationships — RPFM knows that column X in table A references column Y in table B because the schema says so. Hard-coded references in script files (Lua) or text-formatted UI files won’t show up unless the schema knows about them.

For text-only references (e.g. a Lua script that looks up a unit by string), use Global Search instead.

Quick Notes

The Quick Notes panel surfaces the active file’s notes inline at the side of the editor, so you don’t need to open the dedicated notes view every time you want to read or jot something down.

Toggle it from the file tab’s right-click menu → Toggle Quick Notes. There is no main-menu View entry for it, and no global shortcut by default — every editor tab gets its own panel that you turn on per-tab.

What notes actually are

Notes in RPFM are a structured list, not a single free-form text area. Each note has:

• A short message (the body).
• An optional URL (for linking out to a wiki page, issue tracker, etc.).
• An implicit attachment: either to the Pack as a whole, or to a specific in-Pack path.

The Quick Notes panel for a file shows every note attached to that file’s path, plus a + to add a new one and right-click Edit / Delete on each entry.

What it shows

When the focused editor changes (e.g. you switch tabs), each tab’s Quick Notes panel is independent and shows the notes for that tab’s file. There’s no automatic fall-back to “Pack notes” — Pack notes are accessed through the dedicated Notes view (see below).

For files opened from the Dependencies panel (vanilla / parent / AK files) Quick Notes is read-only and effectively empty: notes only exist for files that live in an open Pack.

Difference from “Open Notes”

• Open Notes (Pack tree context menu → Open ▸ Open Notes) opens a dedicated tab containing the same structured list view. Use this for browsing every note attached to a Pack, or for working with notes when you don’t have the relevant file open.
• Quick Notes panel is the same view embedded inside the active editor tab so you can read / jot without leaving the file.

A reminder about Save for Release

Save for Release does not strip notes. It runs the optimiser dialog before saving but leaves the Pack’s notes file (notes.rpfm_reserved) intact for Mod and Movie Packs. Notes are dropped only if you change the Pack type to Boot / Release / Patch before saving — at which point the notes section, the dependency manager and the per-Pack settings are all skipped.

Notes are intended for your own bookkeeping; if you don’t want them shipping with the Pack, delete them or change the Pack type before release.

What is MyMod?

A MyMod is RPFM’s idea of a mod project — a Pack that lives in a structured folder on disk, with optional Lua / Sublime / VSCode / Git scaffolding around it, and a few extra menu actions you don’t get with a plain Pack.

You can absolutely mod without MyMod. But for any non-trivial project, MyMod gives you:

• A predictable folder layout per game (<MyMod base>/<game key>/<mod name>/).
• A spot to keep raw asset files (PSDs, source XMLs, scripts in their working form) alongside the Pack they end up in.
• Optional Sublime / VSCode project scaffolding for Lua mods (via the tw_autogen Lua API definitions).
• Optional Git repository initialised inside the MyMod folder, with a configurable .gitignore.
• Per-MyMod Import (folder → Pack) and Export (Pack → folder) actions, so you can work on the mod’s contents as files on disk and then bundle them back up.
• Per-MyMod Delete that removes the whole folder via the system trash.
• Open and Install/Uninstall through dedicated menu entries.

The folder layout

When you create a MyMod, RPFM creates the folder and any opt-in scaffolding you ticked in the new-MyMod dialog:

<MyMod base>/<game key>/
├── <mod name>.pack                 the Pack itself (saved when you save the MyMod)
└── <mod name>/
    ├── .git/                       only if Git support was enabled
    ├── .gitignore                  only if Git support was enabled
    ├── .vscode/extensions.json     only if VSCode support was enabled
    └── <mod name>.sublime-project  only if Sublime support was enabled

The Pack itself also gets a per-Pack “Files Ignored on Import” setting populated from the dialog, so the Sublime/VSCode/Git scaffolding files are skipped when you later Import the folder back into the Pack.

The <MyMod base> is configured once in PackFile → Settings → Paths → Extra Paths → MyMod base path (First-time configuration). The game-key folders are created on demand the first time you save a MyMod for that game.

When to use MyMod (and when not to)

Use MyMod when:

• You’re starting a new mod and want a clean workspace.
• You want one-click Lua / VSCode / Sublime / Git scaffolding.
• The mod has source assets you want to keep alongside the Pack and round-trip via Import/Export.

Skip MyMod when:

• You’re making one-off edits to an existing Pack you already have on disk.
• You’re inspecting / debugging someone else’s Pack.

Active MyMods are per-Pack

A Pack is in MyMod mode when its on-disk path lives inside the MyMod base folder under one of the game-key subfolders. The mode is tracked per-Pack on the server: open a normal Pack and a MyMod side by side, and the MyMod-only context-menu actions appear only when you right-click the MyMod’s root.

The MyMod menu in the menu bar is mostly about creating new MyMods, opening existing ones, and bulk-running Import/Export across every open MyMod. The per-Pack actions (single Import, single Export, Delete, Open MyMod Folder) live in the Pack root’s right-click menu.

Next

• Creating and managing a MyMod
• Import / Export

Creating and managing a MyMod

The MyMod actions are split between the MyMod menu in the menu bar (creation, opening, bulk operations) and the Pack root’s right-click menu (per-Pack operations on a MyMod).

The MyMod menu

In the menu bar the MyMod menu has, in order:

• Open MyMod Folder — opens the configured <MyMod base> in your file manager.
• New MyMod — creates a new MyMod (covered below).
• Import All Open MyMods — runs Import on every Pack currently open in MyMod mode.
• Export All Open MyMods — runs Export on every Pack currently open in MyMod mode.
• (separator)
• <Game name> submenu — one per supported game, only visible if you have at least one MyMod for that game. Each submenu lists the .pack files inside <MyMod base>/<game key>/ as one click-to-open entry per mod.

New MyMod, Import All and Export All are disabled until a MyMod base path is configured in PackFile → Settings → Paths → Extra Paths.

Creating a MyMod

MyMod → New MyMod opens the new-MyMod dialog. The fields are:

• Game — combobox of supported games (Arena is excluded). Defaults to the currently-selected game.
• Mod Name — short identifier. Used as both the folder name and the Pack file name. No spaces allowed; the Accept button is disabled if the name contains spaces or is already in use.
• Lua Support group:
  • Create Sublime Text Project — drops a <mod_name>.sublime-project in the folder.
  • Create VSCode Project — drops .vscode/extensions.json in the folder, recommending the Lua and Code Runner extensions.
  • When either is enabled, RPFM also expects a .luarc.json to live there (auto-added to the import-ignore list).
• Create Git Repository With GitIgnore group (checkable) — when enabled, RPFM git inits the folder and writes a .gitignore. You can either type your own .gitignore contents in the GitIgnore Contents textedit, or tick Same as files ignored on import to mirror the import-ignore list.
• Files Ignored on Import — paths (one per line, relative to the MyMod folder) that RPFM should skip when later running Import. The Sublime/VSCode/Git scaffolding paths are appended automatically.

On confirm, RPFM:

1. Creates <MyMod base>/<game key>/<name>/ on disk.
2. Initialises .git, .gitignore, .vscode/, <name>.sublime-project as opted in.
3. Creates an empty Pack and saves it as <name>.pack inside the folder.
4. Stores the import-ignore list in the Pack’s settings.
5. Switches the active Game Selected to match the MyMod’s game.
6. Opens the Pack in a new tab and marks it as a MyMod on the server.

Switching MyMods

Use the per-game submenus in MyMod → <Game name> → <mod name> to open an existing MyMod. The previously-open Packs (MyMods or otherwise) are left untouched — opening a MyMod just opens that Pack alongside the others.

Per-MyMod actions (right-click the Pack root)

When you right-click the root of a Pack that’s in MyMod mode, the context menu adds four MyMod-only entries (greyed out / hidden for non-MyMod Packs):

• Import — folder → Pack for this MyMod. See Import / Export.
• Export — Pack → folder for this MyMod. See Import / Export.
• Delete Selected MyMod — moves the entire MyMod folder to the system trash after a confirmation. Cannot be undone from inside RPFM.
• Open MyMod Folder — opens the MyMod’s folder in your file manager.

Installing to the game folder

Install / Uninstall are not MyMod-specific menu items — they’re plain Pack actions that show up in the Pack root’s right-click menu for any saved Pack:

• Install copies <pack path> into <game install>/data/<pack name> so you can launch and test.
• Uninstall removes that copy.

For a “release” install (with the optimiser dialog), use Pack → Save Pack For Release before installing — see Pack operations.

Import / Export

MyMod’s Import and Export operations move content between a .pack file and a folder of files on disk. They’re the bridge between “Pack as opaque archive” and “mod content as files I can keep in version control or run scripts against.”

Both operations are per-Pack and only available when the Pack is in MyMod mode. There are two ways to invoke each:

• Right-click the Pack root in the tree and pick Import or Export — affects just that one MyMod.
• MyMod → Import All Open MyMods / MyMod → Export All Open MyMods — runs the same operation across every Pack currently open in MyMod mode.

There is no single-Pack equivalent in the menu bar — only the per-Pack right-click and the bulk menu-bar entries.

Export — Pack → folder

Export writes every file inside the MyMod’s Pack out to disk under the MyMod folder, preserving the in-Pack tree as on-disk subfolders.

After export you’ll have something like:

<MyMod base>/<game>/<mod>/
├── <mod>.pack                  the Pack itself (unchanged)
├── db/
│   ├── units_tables/my_units
│   └── ...
├── text/
│   └── my_mod.loc
├── script/
│   └── ...
└── ...

DB tables export as TSV by default, and will be parsed from TSV on import automatically.

Why export?

• Version control. Track files individually in git rather than as a single binary blob.
• External tooling. Run a script that processes a folder of files (validators, formatters, generators).
• Bulk renames or refactors that are easier to do with shell tools than with RPFM’s UI.
• Diffing two Packs — export both and diff -r.

Import — folder → Pack

Import is the reverse: scan the MyMod folder, collect every file under it (excluding any path listed in the Pack’s Files Ignored on Import setting), and add them to the Pack. Files at the same in-Pack path are replaced with the on-disk version.

Import is additive. Files that exist in the Pack but no longer exist on disk are not deleted. If you’ve removed a file from the on-disk folder and want it gone from the Pack too, delete it from the Pack manually (right-click → Delete).

The ignore list

The Files Ignored on Import list is the per-Pack setting you (optionally) populated when you created the MyMod. It lives in the Pack itself and is editable later via Open PackFile Settings (Pack settings & notes).

The new-MyMod dialog also auto-appends entries for any Sublime / VSCode / Git scaffolding you opted in to, so you don’t accidentally import .git/, .vscode/, the Sublime project file, or .luarc.json back into the Pack.

Round-tripping

Export → edit on disk → Import is the standard “I want to script changes to this mod” workflow. As long as the on-disk layout matches the in-Pack layout, RPFM treats it as a faithful round-trip.

Importing a folder that was exported from a different RPFM install (e.g. via git from a teammate) works the same. The MyMod folder layout is the contract — and the per-Pack ignore list lives inside the Pack itself, so it travels with the .pack.

Caveats

• Import is additive, not destructive. Removing a file from the on-disk folder won’t remove it from the Pack on the next Import — delete it from the Pack manually.
• Binary files (DDS, RigidModel, AnimPack, BMD, …) are exported as-is. Edit them in the appropriate external tool, save them back to the same path, and re-import.

Translator

The Translator is RPFM’s dedicated tool for translating mods. It’s a structured editor on top of a Pack’s loc data, plus an integration with the Total War Translation Hub so the resulting translations can be shared and applied automatically by Runcher.

Open from Tools → Translator with a Pack open.

What it does

The Translator presents every translatable string in the Pack as a structured row, with:

• Key — the loc key.
• Source text — the original (typically English) text.
• Translation — your translated text.
• Needs retranslation — boolean. Set when the source text changed since the translation was last saved (the “outdated” state).
• Removed — boolean. Set when the key was once translated but the mod no longer contains it (the “unused” state). The translation is kept in the JSON so it can come back if the key reappears.

The workflow

1. Auto-translate from vanilla. For keys that exist in vanilla loc data and are unchanged, the Translator will auto-translate them using the vanilla translations, leaving the modded or altered lines to be translated.
2. Translate row by row, or using one of the translation integrations.
3. Generate the translated loc. When you save, the Translator writes a translated .loc file into the Pack at the right path: text/!!!!!!translated_locs.loc for Warhammer 1 and newer (except Thrones of Britannia), or text/localisation.loc for Thrones of Britannia and older games. The translation works in-game immediately.
4. Persist the translation as JSON. The translation is also persisted to <config>/translations_local/<game>/<pack>/<LANGUAGE>.json. This is the file you contribute to the Translation Hub.

Sharing through the Translation Hub

Once you’ve finished a translation:

1. Find the JSON in <config>/translations_local/<game>/<pack>/.
2. Submit it to the Translation Hub as an issue or PR.
3. Once accepted, any Runcher user with Enable Translations turned on will get the translation automatically applied at launch — without altering the mod, and with outdated lines silently ignored. No more “I installed a translation pack but the mod was updated and now half the lines are wrong.”

For step-by-step instructions including screenshots, see the Translating a mod tutorial.

Faction Painter

The Faction Painter lets you edit faction colour schemes — primary / secondary / tertiary banner colours, uniform colours, and the related per-faction display knobs — without manually grinding through factions_tables and the colour columns.

Open from Tools → Faction Painter with a Pack open.

Workflow

1. Open the Pack you want to add faction colour overrides to.
2. Open Faction Painter.
3. Pick the faction in the list.
4. Adjust the colours (or hit Restore Vanilla Values to baseline first).
5. OK — RPFM writes the new values into the appropriate DB row in your Pack, creating it as an override if it didn’t exist already.

Edits are reflected immediately in any open DB editor for the affected tables (the tool tracks which paths it touched and reloads any matching open views after save).

Per-game caveats

Different games store faction colours in different tables. Faction Painter resolves the right table and column names per game from its game-config map, so the picker UI stays the same across games even when the underlying schema doesn’t.

Unit Editor

The Unit Editor is a higher-level alternative to editing units row-by-row across main_units_tables, land_units_tables, unit_variants_tables and the loc strings that name them. It gives you a single pane that pulls in the relevant rows from each table and presents the unit as a coherent thing.

Disabled by default. The Unit Editor lives behind the Enable Unit Editor debug toggle in PackFile → Settings → Debug. Turn it on first; the menu entry is greyed out otherwise. Treat it as a power-user / experimental tool.

Warhammer 2 and Warhammer 3 only. The tool’s game-config map only covers WH2 and WH3 today. The menu entry is enabled for any game once the toggle is on, but trying to open it on an unsupported game will fail.

Open from Tools → Unit Editor with a Pack open (and the debug toggle enabled).

What it covers

For each unit, the editor surfaces:

• The main_units_tables row.
• The land_units_tables row.
• The unit’s variant mesh references (unit_variants_tables etc., via the bundled variant editor).
• Loc strings (display name, description, short description, and — for WH2 — strengths_weaknesses_texts).

Editing any field writes back into the right DB row when you save. Cloning a unit propagates the related rows so they stay consistent.

Not currently covered, despite what older docs claimed: unit_stats_*_tables, cost / upkeep / recruitment-time tables, and the unit caps tables. If you need to tweak those, edit the tables directly in the DB editor.

Per-game scope

Like Faction Painter, the Unit Editor reads game-specific table and column names from its game-config map. Only Warhammer 2 and Warhammer 3 are wired up today.

Limitations

• Add / delete are limited. The primary “add” mechanism is Clone an existing unit; there’s no “delete unit” action.
• For wholesale unit-creation workflows (full kit replacement, animations, sound, custom stats), the conventional table-by-table approach is still required.

Tip

Cloning an existing unit and tweaking it is the most reliable way to add a new unit through this editor. Start from a vanilla unit close to what you want and go from there.

Translating a mod

There are three approaches to translating a Total War mod. RPFM supports all of them, but the third — using the integrated Translator — is the recommended one.

The simple way

The one new modders tend to do, because it’s the easiest:

1. Open the Pack.
2. Open the Loc files.
3. Manually translate the loc values.
4. Save the Pack.

It’s not recommended. When the mod gets an update, you have to retranslate everything, or hunt down the new and changed lines and translate just those. Both flows are painful and error-prone, and you usually end up with a translation that “works but is partially outdated”.

The TSV way

The one people that have been hit by the simple-way problems tend to do:

1. Open the Pack.
2. Export every Loc to TSV.
3. Use a translation tool to work on the TSV.
4. Import the locs back.
5. Save the Pack.

There are many variants of this — from “autotranslate everything with Google” (please proofread) to advanced workflows that isolate new / changed lines and only update those.

Translations are easier to update and easier to keep tidy in version control, but the workflow takes more setup time.

The new way: the Translator

RPFM ships with an integrated Translator that handles every painful part of the other two:

1. Open the Pack you want to translate.
2. Tools → Translator.
3. Translate the lines marked Needs Retranslation.
4. Hit Accept.
5. Save the Pack.

The Translator does the heavy lifting for you and fixes problems that have historically plagued translations:

• Detects lines unchanged from the vanilla English text and translates them automatically using the vanilla translation in the target language.
• When translating a submod, reuses translations from parent mods if they exist.
• When updating a translation, marks lines that have been removed, lines that have been altered, and lines that are new.
• Saves the translation in a structured form that’s easy to share and collaborate on.

This means: no time wasted updating a translation (open the updated mod in the Translator and accept), no lines stuck on old translations after an update, no terminology drift across files.

How to use the Translator

The translator window has two halves.

Left side: the loc list

Right side: the editor

At the top: a short instruction line and the target language (picked automatically based on the language you have the game on).

Auto-translation behaviour — what should happen when you select a new line:

• Auto-translate with DeepL — uses DeepL for high-quality machine translation. Requires a DeepL API key set in PackFile → Settings → AI.
• Auto-translate with AI — sends the line to any AI service that exposes the OpenAI chat-completions wire format, with optional context. Quality depends on the model you pick. Requires an API URL, API key and model in the same AI pane. Examples of supported endpoints:
  • OpenAI: https://api.openai.com/v1/chat/completions
  • Anthropic (OpenAI compat): https://api.anthropic.com/v1/chat/completions
  • Gemini (OpenAI compat): https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
  • OpenRouter: https://openrouter.ai/api/v1/chat/completions
  • Local (Ollama, vLLM, LM Studio, …): http://127.0.0.1:.../v1/chat/completions
• Auto-translate with Google Translate — mediocre but free.
• Copy Source Value — leaves the source text in place; useful for terms that don’t translate.
• Empty Translated Value — does nothing on selection; you write the translation from scratch.

When you save the current line:

• Replicate Edit in Pre-Translated Lines — also overwrite previously-translated lines that share the same source text.
• Only Edit the Current Line — disable cross-line replication entirely.

Below the behaviour selectors: the Original Value (raw + formatted preview) and the Translated Value (raw + formatted preview, with prev/next buttons).

The pattern is: select a line, the right side loads it, you edit, you select the next line, repeat. When you’re done, Accept writes the translation to two places:

• Inside the open Pack, as text/!!!!!!translated_locs.loc (or text/localisation.loc for older games), so the translation works in-game immediately.
• On disk, as <RPFM config>/translations_local/<game>/<pack>/<LANGUAGE>.json. This is the file you share.

Sharing a translation

Submit the JSON to the Total War Translation Hub as an issue or a PR.

Why share?

• The Translator automatically searches the Hub for existing translations of mods you open. If someone translated this mod a year ago, you don’t start from scratch — you pick up where they left off.
• Runcher (and any other launcher using TWPatcher) automatically pulls the Hub at launch and applies translations transparently — fixing the dreaded “no text when not English” bug along the way.

So sharing makes the translation future-proof and lets others use it without juggling extra packs or worrying about parent-mod compatibility.

Optimising a mod

Before you ship a release, optimise. RPFM’s optimiser strips dead weight from a Pack — duplicated rows, rows identical to vanilla, modding-tool byproducts, unused portrait variants — and the result is smaller, more compatible, and less likely to break neighbouring mods.

Why bother

• Size. Removing dead rows shrinks the Pack — sometimes dramatically.
• Compatibility. Duplicated and identical-to-vanilla rows tend to be left forgotten in mod packs (even when Diagnostics warns about them) and end up causing compatibility issues when another mod tries to modify them. Your mod accidentally overwrites changes for no reason.
• Multi-language support. Identical-to-vanilla loc entries will overwrite the player’s localisation files if the player is not on English. So even though you’re not changing those lines, the optimiser-untouched Pack would silently turn them to English for non-English players. Bad.

How

Two right-click actions on the Pack root:

• Optimize PackFile — opens the optimiser dialog, runs the steps you’ve ticked, applies the result to the in-memory Pack but doesn’t save. Lets you review the result before committing.
• Save Pack For Release — opens the same optimiser dialog, runs it, and saves the result to disk. The shipping shortcut.

Both use the same OptimizerOptions under the hood. The dialog is where you fine-tune which steps run; your tick choices are persisted as defaults for the next invocation. There is no separate “Optimizer” pane in PackFile → Settings — the dialog itself is the configuration surface.

When

Right before you publish a release / update. Not earlier — the optimiser strips data, and that data is occasionally what you’re using as a reminder of intent during development.

What it actually does

The full step list lives in rpfm_extensions::optimizer, and the dialog groups them into four sections:

• Pack — Remove ITM (identical-to-master) files, Apply compression.
• Table (DB / Loc) — Import datacores into twad_key_deletes (Warhammer 3+, see Datacores), Optimize datacored tables, Remove duplicated entries, Remove ITM rows, Remove ITNR (identical to new row) rows, Remove empty files.
• Text — Remove unused .xml files in map/ folders, remove unused .xml files in the prefab folder, Remove .agf files, Remove .model_statistics files (the last two are BOB exporter byproducts).
• Portrait Settings — Remove unused art sets, Remove unused variants, Remove empty masks, Remove empty files.

Each step can be ticked or un-ticked from the dialog. The defaults are conservative — destructive steps like “Optimize datacored tables” and “Remove unused art sets / variants” are off out of the box.

Datacores (twad_key_deletes)

A short tour of an old, painful pattern in Total War modding — and how Warhammer 3 (patch 6.3+) and RPFM let you stop using it.

What’s a datacore?

To explain what a datacore is, first we need to explain how table rows are loaded by the engine. Imagine the following table layout:

• db/whatever_tables/@table — your high-priority overrides.
• db/whatever_tables/ztable — your low-priority overrides.
• db/whatever_tables/data__ — the vanilla table (filename varies per game).

When loading in-game, the three are merged. When two rows of the merged table have the same key, only the first one wins. So:

• @table contains new rows and rows intended to overwrite vanilla. To change a vanilla unit’s stats, you put the modified row here.
• ztable contains new rows you want overridden by other mods if they happen to clash (vanilla fixes, etc.).
• data__ is the vanilla data.

Notice the gap: there’s no clean way to remove a vanilla row. To delete a building effect, the historical workaround was to import the whole vanilla table into your mod with the offending row removed, then ship that. That’s a datacore.

Why datacores are bad

Imagine you have a fancy effects table and you want to remove one of the effects in a submod. You import the table into your submod, edit it, and it works. Until… the parent mod is updated to add new effects. Now your submodded table doesn’t have those new effects, and either you update your table with them or your submod silently strips them.

And what if another submod tries to remove a different effect? Highlander situation: there can only be one.

In summary: datacoring is sometimes useful, but it reduces compatibility, makes the mod way bigger than it needs to be, and increases maintenance burden. Avoid unless absolutely needed.

For Warhammer 3 from patch 6.3 onwards, you don’t have to.

Datacores BEGONE: twad_key_deletes_tables

Patch 6.3 introduced a new table type, twad_key_deletes_tables, with a simple shape:

The engine reads this table at runtime and deletes those rows from the named tables — replacing the need for datacores entirely.

There are three ways to use it.

1. Migrate existing datacores

If your mod already contains datacored tables and you want to convert them:

1. Right-click your Pack root → Optimize PackFile (or Save Pack For Release if you also want the optimiser to save the result).
2. In the optimiser dialog, tick Import datacores into twad_key_deletes under the Table section.
3. Accept.

RPFM analyses your datacored tables, finds the rows that are deleted relative to vanilla / parent, and adds them as entries to a new twad_key_deletes table. After running this, verify the new table contains the right keys, then delete the datacores.

Rename the generated table. RPFM will overwrite it if you re-run the optimiser. Pick a stable name like mymod_deletes.

2. Add deletes from the source table

The clean ergonomic flow when you’re removing entries you can see in another open table:

1. Right-click your Pack → Create ▸ New DB, type twad_key_deletes_tables as the table name, and create it once. Don’t edit it manually.
2. Open the source table (the one with the rows you want gone).
3. Select the rows.
4. Right-click → Add Selection to Key Deletes → pick your twad_key_deletes table.

RPFM adds the right keys to the deletes table for you. No manual key copying — and especially no risk of mistyping a multi-key composite, which is the easiest way to add an entry that silently does nothing. The submenu is only enabled when the active game is Warhammer 3 and the destination table exists in the open Pack.

3. Edit the table directly (last resort)

If neither of the above fits — for example, you want to delete a row that doesn’t exist in any open table you can right-click — you can edit twad_key_deletes like any other DB table. This is the highest risk path: bad keys silently do nothing in-game and RPFM can’t yet tell when you’ve fat-fingered a key. Use sparingly.

Caveats

A few things to keep in mind:

• Removing a referenced row crashes the game. If you delete a land_units row that’s still referenced by units_to_groupings, the game will crash on load — same as if you’d deleted the row in a datacore. Worse, the engine’s error dialog tends to point at the wrong Pack, and RPFM’s diagnostics don’t yet validate twad_key_deletes references. If a vanilla row is referenced from elsewhere, plan accordingly.
• Load order matters. If your high-priority mod removes a row and a lower-priority mod re-adds it (or vice versa), the engine will reflect the load order — the deletion gets undone.

These aren’t reasons to avoid twad_key_deletes; they’re reasons to think before removing rows. Compared to datacores, it’s still a massive ergonomic win.

Server overview

rpfm_server is a standalone backend process that exposes RPFM’s functionality over a local network protocol. The desktop UI (rpfm_ui) is one client of this server, but it isn’t the only one — anything that speaks WebSocket and JSON, or anything that speaks the Model Context Protocol, can drive the same backend.

This section is for tool authors and integrators. For end-user workflows, you don’t need anything here.

Architecture

┌──────────────────────┐    WebSocket    ┌──────────────────────┐
│       rpfm_ui        │ ◀────────────▶  │     rpfm_server      │
│  (Qt6 desktop app)   │                 │   (this binary)      │
└──────────────────────┘                 └──────────┬───────────┘
                                                    │
┌──────────────────────┐    HTTP/SSE                │
│   MCP clients (AI)   │ ◀──────────▶  /mcp ◀───────┘
└──────────────────────┘

• The server binds to 127.0.0.1:45127 by default.
• All clients talk to the same backend, but each connection has its own session (own open Packs, own dependency cache, own settings view).
• Behind the scenes the heavy lifting is in rpfm_lib and rpfm_extensions. The server is mostly an IPC gateway plus session bookkeeping.

What the server can do

Pretty much everything rpfm_ui can:

• Open, save, close and inspect Packs.
• Add, extract, rename, copy, delete, duplicate files.
• Read and write every supported file type (DB tables, Loc, text, animations, …).
• Run search, diagnostics, references against open Packs.
• Manage dependencies, schemas, MyMods.
• Drive the optimizer, the translator, startpos building, glTF export, etc.

The full surface is documented in Commands and Responses.

Endpoints

The server exposes three HTTP endpoints on 127.0.0.1:45127:

Two ways in

You’ll typically pick one of two integration paths:

• WebSocket — for full programmatic access. You write client code that sends Command messages and matches Response messages by ID. See WebSocket protocol.
• MCP — for AI agents and other clients that already speak MCP. The server exposes 150+ tools, plus prompts and resources. See MCP interface.

Under the hood both pathways use the same Session abstraction, but each connection gets its own isolated session with its own open Packs and dependency cache. WebSocket clients can reattach to an existing session by passing their previous session_id back on the handshake; MCP clients always start a fresh session per connection. Two clients running side by side don’t share state — they share the server process.

Spawning the server

rpfm_ui spawns rpfm_server automatically and the UI’s lifecycle owns the server’s. To run the server standalone (for tool development, automated tests, or to keep it warm between UI sessions):

./rpfm_server

The server logs to stderr and stays in the foreground until every session is gone.

Where to next

• Sessions & connection lifecycle — what happens on connect, disconnect, reconnect.
• WebSocket protocol — message envelope, serialization conventions, in-flight requests.
• MCP interface — what tools the MCP endpoint exposes.
• Client example — a concrete TypeScript / C# client implementation.

Sessions & connection lifecycle

Each WebSocket and each MCP connection lives inside a session. A session owns a dedicated background thread that processes commands serially against its in-memory state (open Packs, dependency cache, settings cache).

Sessions are isolated: open packs in one session aren’t visible in another. This is what makes “many UI clients (or MCP clients) talking to one server” safe.

Lifecycle

1. Connect. A client opens /ws (or connects to /mcp) without a session ID. The server allocates a new SessionId, spins up a background thread, and immediately sends an unsolicited SessionConnected response so the client can stash the ID for later reconnection.

   { "id": 0, "data": { "SessionConnected": 12345 } }
   

2. Reconnect. A client opens /ws?session_id=12345. If the session still exists and isn’t shutting down, the new socket adopts it with all in-memory state preserved (open Packs, loaded dependencies, settings cache).

3. Disconnect. When the WebSocket drops without a Command::ClientDisconnecting, the session enters a 5-minute grace period (DEFAULT_SESSION_TIMEOUT_SECS = 300). Reconnecting cancels the timeout; otherwise the session and its background thread are torn down.

4. Graceful disconnect. Send ClientDisconnecting before closing your socket and the session is removed immediately, telemetry is flushed, and the background thread exits.

   { "id": 99, "data": "ClientDisconnecting" }
   

5. Empty manager → process exit. When the last session goes away the rpfm_server process exits, so no orphaned server lingers in the background.

Reconnection example

// First connect: store the session ID
const ws = new WebSocket("ws://127.0.0.1:45127/ws");
let sessionId: number | null = null;

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (typeof msg.data === "object" && "SessionConnected" in msg.data) {
    sessionId = msg.data.SessionConnected;
    console.log("session", sessionId);
  }
};

// Later, after a network blip, reconnect with the stored ID:
const ws2 = new WebSocket(`ws://127.0.0.1:45127/ws?session_id=${sessionId}`);

using var ws = new ClientWebSocket();
await ws.ConnectAsync(new Uri("ws://127.0.0.1:45127/ws"), CancellationToken.None);

int? sessionId = null;
// ... receive the SessionConnected message and store sessionId ...

// Later, reconnect:
using var ws2 = new ClientWebSocket();
await ws2.ConnectAsync(
    new Uri($"ws://127.0.0.1:45127/ws?session_id={sessionId}"),
    CancellationToken.None);

Listing active sessions

The /sessions REST endpoint returns every live session as JSON:

curl http://127.0.0.1:45127/sessions

[
  {
    "session_id": 12345,
    "connection_count": 0,
    "timeout_remaining_secs": 180,
    "is_shutting_down": false,
    "pack_names": ["my_mod.pack"]
  },
  {
    "session_id": 12346,
    "connection_count": 1,
    "timeout_remaining_secs": null,
    "is_shutting_down": false,
    "pack_names": []
  }
]

Fields:

The UI uses this endpoint to populate Pack → Select Session…, which lets a user reattach to a server session after the UI was killed or disconnected.

Per-session state

Each session has its own:

• Open Packs (with their full in-memory contents and metadata).
• Dependency cache view (game files, parent files, AK files).
• Active game selection.

When you call something like Command::SetGameSelected, you’re changing it for your session, not globally.

WebSocket protocol

This page covers the protocol layer: how messages are framed, serialized and correlated. The full vocabulary lives in Shared types, Commands and Responses.

Connecting

The server listens on ws://127.0.0.1:45127/ws by default. Append ?session_id=<id> to reconnect to an existing session — see Sessions.

const ws = new WebSocket("ws://127.0.0.1:45127/ws");

using var ws = new ClientWebSocket();
await ws.ConnectAsync(new Uri("ws://127.0.0.1:45127/ws"), CancellationToken.None);

Immediately after the handshake the server pushes an unsolicited SessionConnected message with the session ID:

{ "id": 0, "data": { "SessionConnected": 42 } }

Message envelope

Every message — both directions — is wrapped in a Message envelope:

{
  "id": <number>,
  "data": <Command or Response>
}

Request-response correlation

The id lets multiple requests be in flight simultaneously. Match each response back to its originating request by id. A typical client maintains a Map<id, { resolve, reject }> of pending requests and resolves them as responses arrive.

Serialization conventions

All messages are JSON. The Rust enums backing Command and Response are serialized by serde with these rules:

Struct variants use { "VariantName": { field: value, … } }.

This means the JSON shape closely mirrors how a Rust client would write the same request — handy when reading the Commands reference.

A complete round-trip

const ws = new WebSocket("ws://127.0.0.1:45127/ws");

let nextId = 1;
const pending = new Map<number, (resp: any) => void>();

function send(command: object | string): Promise<any> {
  const id = nextId++;
  return new Promise((resolve) => {
    pending.set(id, resolve);
    ws.send(JSON.stringify({ id, data: command }));
  });
}

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  const cb = pending.get(msg.id);
  if (cb) {
    pending.delete(msg.id);
    cb(msg.data);
  }
};

ws.onopen = async () => {
  const resp = await send({ OpenPackFiles: ["/path/to/my_mod.pack"] });
  console.log("opened:", resp);
};

using System.Net.WebSockets;
using System.Text;
using System.Text.Json;

using var ws = new ClientWebSocket();
await ws.ConnectAsync(new Uri("ws://127.0.0.1:45127/ws"), CancellationToken.None);

int nextId = 1;

async Task SendAsync(object command)
{
    var id = nextId++;
    var msg = JsonSerializer.Serialize(new { id, data = command });
    await ws.SendAsync(
        Encoding.UTF8.GetBytes(msg),
        WebSocketMessageType.Text, true, CancellationToken.None);
}

await SendAsync(new { OpenPackFiles = new[] { "/path/to/my_mod.pack" } });

For a fuller, production-shaped client see Client example.

Errors

Errors come back as the Error(String) response variant:

{ "id": 7, "data": { "Error": "Failed to open pack: …" } }

Treat any Error response as a rejection of the originating request. The error message is suitable to surface to a developer; for end-user UIs you’ll typically want to wrap it with friendlier copy.

Disconnecting cleanly

Send ClientDisconnecting before closing the socket so the server tears the session down immediately instead of waiting for the 5-minute timeout:

{ "id": 99, "data": "ClientDisconnecting" }

After sending, you can close the WebSocket. The server doesn’t reply.

What’s next

• Shared types — every payload type referenced in Command / Response.
• Commands — every variant the client can send.
• Responses — every variant the server can send back.

Shared Types

This page documents all the data types used in the RPFM server protocol. These types appear as parameters in Commands and as payloads in Responses.

All types are serialized as JSON. Nullable fields use null when absent.

Core Types

DataSource

Discriminates where file data originates from. Serialized as a plain string.

type DataSource = "PackFile" | "GameFiles" | "ParentFiles" | "AssKitFiles" | "ExternalFile";

// Serialize as a plain string — idiomatic C# is an enum with [JsonStringEnumConverter]:
public enum DataSource
{
    PackFile,
    GameFiles,
    ParentFiles,
    AssKitFiles,
    ExternalFile,
}

ContainerPath

A file or folder path within a Pack. Serialized as a tagged enum:

{ "File": "db/units_tables/data" }
{ "Folder": "db/units_tables" }

type ContainerPath =
  | { File: string }
  | { Folder: string };

// Serialize as either { "File": "..." } or { "Folder": "..." }:
public abstract class ContainerPath { }
public class ContainerPathFile   : ContainerPath { public string File { get; set; } }
public class ContainerPathFolder : ContainerPath { public string Folder { get; set; } }

RFileInfo

Metadata about a packed file within a container.

interface RFileInfo {
  path: string;
  container_name: string | null;
  timestamp: number | null;
  file_type: string;
}

public class RFileInfo
{
    public string Path { get; set; }
    public string? ContainerName { get; set; }
    public long? Timestamp { get; set; }
    public string FileType { get; set; }
}

ContainerInfo

Reduced representation of a Pack file (container-level metadata).

interface ContainerInfo {
  file_name: string;
  file_path: string;
  pfh_version: PFHVersion;
  pfh_file_type: PFHFileType;
  bitmask: PFHFlags;
  compress: CompressionFormat;
  timestamp: number;
}

public class ContainerInfo
{
    public string FileName { get; set; }
    public string FilePath { get; set; }
    public PFHVersion PfhVersion { get; set; }
    public PFHFileType PfhFileType { get; set; }
    public PFHFlags Bitmask { get; set; }
    public CompressionFormat Compress { get; set; }
    public ulong Timestamp { get; set; }
}

DependenciesInfo

Information about loaded dependency files, used to populate dependency tree views.

interface DependenciesInfo {
  asskit_tables: RFileInfo[];
  vanilla_packed_files: RFileInfo[];
  parent_packed_files: RFileInfo[];
}

public class DependenciesInfo
{
    public List<RFileInfo> AsskitTables { get; set; }
    public List<RFileInfo> VanillaPackedFiles { get; set; }
    public List<RFileInfo> ParentPackedFiles { get; set; }
}

SessionInfo

Information about an active session on the server. Returned by the GET /sessions REST endpoint.

interface SessionInfo {
  session_id: number;
  connection_count: number;
  timeout_remaining_secs: number | null;
  is_shutting_down: boolean;
  pack_names: string[];
}

public class SessionInfo
{
    public int SessionId { get; set; }
    public int ConnectionCount { get; set; }
    public double? TimeoutRemainingSecs { get; set; }
    public bool IsShuttingDown { get; set; }
    public List<string> PackNames { get; set; }
}

File Types

NewFile

Parameters for creating a new packed file. Serialized as a tagged enum — the variant name determines the file type:

Example:

{ "DB": ["my_table", "units_tables", 4] }
{ "Text": ["script.lua", "Lua"] }

type NewFile =
  | { AnimPack: string }
  | { DB: [string, string, number] }
  | { Loc: string }
  | { PortraitSettings: [string, number, [string, string][]] }
  | { Text: [string, string] }
  | { VMD: string }
  | { WSModel: string };

// Tagged-enum payload — one class per variant:
public abstract class NewFile { }
public class NewFileAnimPack : NewFile { public string AnimPack { get; set; } }
public class NewFileDB : NewFile { public Tuple<string, string, int> DB { get; set; } }
public class NewFileLoc : NewFile { public string Loc { get; set; } }
public class NewFilePortraitSettings : NewFile
{
    public Tuple<string, uint, List<Tuple<string, string>>> PortraitSettings { get; set; }
}
public class NewFileText : NewFile { public Tuple<string, string> Text { get; set; } }  // second is TextFormat enum
public class NewFileVMD : NewFile { public string VMD { get; set; } }
public class NewFileWSModel : NewFile { public string WSModel { get; set; } }

VideoInfo

Metadata specific to video files.

interface VideoInfo {
  format: string;
  version: number;
  codec_four_cc: string;
  width: number;
  height: number;
  num_frames: number;
  framerate: number;
}

public class VideoInfo
{
    public string Format { get; set; }
    public int Version { get; set; }
    public string CodecFourCc { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }
    public int NumFrames { get; set; }
    public double Framerate { get; set; }
}

FileType

Identifies the type of a packed file. Serialized as a plain string:

type FileType =
  | "Anim" | "AnimFragmentBattle" | "AnimPack" | "AnimsTable" | "Atlas" | "Audio"
  | "BMD" | "BMDVegetation" | "Dat" | "DB" | "ESF" | "Font" | "GroupFormations"
  | "HlslCompiled" | "Image" | "Loc" | "MatchedCombat" | "Pack" | "PortraitSettings"
  | "RigidModel" | "SoundBank" | "Text" | "UIC" | "UnitVariant" | "Video" | "VMD"
  | "WSModel" | "Unknown";

public enum FileType
{
    Anim, AnimFragmentBattle, AnimPack, AnimsTable, Atlas, Audio,
    BMD, BMDVegetation, Dat, DB, ESF, Font, GroupFormations,
    HlslCompiled, Image, Loc, MatchedCombat, Pack, PortraitSettings,
    RigidModel, SoundBank, Text, UIC, UnitVariant, Video, VMD,
    WSModel, Unknown,
}

CompressionFormat

Compression format for Pack files. Serialized as a plain string:

type CompressionFormat = "None" | "Lzma1" | "Lz4" | "Zstd";

public enum CompressionFormat { None, Lzma1, Lz4, Zstd }

PFHFileType

Pack file type. Serialized as a plain string:

type PFHFileType = "Boot" | "Release" | "Patch" | "Mod" | "Movie";

public enum PFHFileType { Boot, Release, Patch, Mod, Movie }

PFHVersion

PFH (Pack file header) format version. Serialized as a plain string:

type PFHVersion = "PFH0" | "PFH2" | "PFH3" | "PFH4" | "PFH5" | "PFH6";

public enum PFHVersion { PFH0, PFH2, PFH3, PFH4, PFH5, PFH6 }

PFHFlags

Pack file header flags. Serialized as a single integer (a u32 bitmask) with these bits:

// Raw u32 on the wire. Use bitwise-and against the constants to test flags.
type PFHFlags = number;

const PFH_HAS_EXTENDED_HEADER      = 0x0000_0100;
const PFH_HAS_ENCRYPTED_INDEX      = 0x0000_0080;
const PFH_HAS_INDEX_WITH_TIMESTAMPS = 0x0000_0040;
const PFH_HAS_ENCRYPTED_DATA       = 0x0000_0010;

[Flags]
public enum PFHFlags : uint
{
    None = 0,
    HasExtendedHeader      = 0x0000_0100,
    HasEncryptedIndex      = 0x0000_0080,
    HasIndexWithTimestamps = 0x0000_0040,
    HasEncryptedData       = 0x0000_0010,
}

SupportedFormats

Video container format. Serialized as a plain string:

type SupportedFormats = "CaVp8" | "Ivf";

public enum SupportedFormats { CaVp8, Ivf }

OperationalMode

Per-pack operational mode, controlling MyMod behaviour. Serialized as a tagged enum:

Example:

{ "MyMod": ["warhammer_2", "my_mymod.pack"] }
"Normal"

type OperationalMode =
  | { MyMod: [string, string] }
  | "Normal";

// Serialize as either { "MyMod": [string, string] } or the string "Normal".
public abstract class OperationalMode { }
public class OperationalModeMyMod : OperationalMode
{
    public string GameFolder { get; set; }
    public string MyModPackName { get; set; }
}
public class OperationalModeNormal : OperationalMode { }

Data Types

DecodedData

Cell data in a table. Serialized as a tagged enum — the variant name indicates the data type:

Example:

{ "StringU8": "hello" }
{ "I32": 42 }
{ "Boolean": true }

type DecodedData =
  | { Boolean: boolean }
  | { F32: number } | { F64: number }
  | { I16: number } | { I32: number } | { I64: number }
  | { ColourRGB: string }
  | { StringU8: string } | { StringU16: string }
  | { OptionalI16: number } | { OptionalI32: number } | { OptionalI64: number }
  | { OptionalStringU8: string } | { OptionalStringU16: string }
  | { SequenceU16: number[] } | { SequenceU32: number[] };

// Tagged-enum — one class per variant. Branch on the JSON key.
public abstract class DecodedData { }
public class DecodedDataBoolean         : DecodedData { public bool Boolean { get; set; } }
public class DecodedDataF32             : DecodedData { public float F32 { get; set; } }
public class DecodedDataF64             : DecodedData { public double F64 { get; set; } }
public class DecodedDataI16             : DecodedData { public short I16 { get; set; } }
public class DecodedDataI32             : DecodedData { public int I32 { get; set; } }
public class DecodedDataI64             : DecodedData { public long I64 { get; set; } }
public class DecodedDataColourRGB       : DecodedData { public string ColourRGB { get; set; } }
public class DecodedDataStringU8        : DecodedData { public string StringU8 { get; set; } }
public class DecodedDataStringU16       : DecodedData { public string StringU16 { get; set; } }
public class DecodedDataOptionalI16     : DecodedData { public short OptionalI16 { get; set; } }
public class DecodedDataOptionalI32     : DecodedData { public int OptionalI32 { get; set; } }
public class DecodedDataOptionalI64     : DecodedData { public long OptionalI64 { get; set; } }
public class DecodedDataOptionalStringU8 : DecodedData { public string OptionalStringU8 { get; set; } }
public class DecodedDataOptionalStringU16: DecodedData { public string OptionalStringU16 { get; set; } }
public class DecodedDataSequenceU16     : DecodedData { public byte[] SequenceU16 { get; set; } }
public class DecodedDataSequenceU32     : DecodedData { public byte[] SequenceU32 { get; set; } }

TableInMemory

In-memory table data structure used by DB and Loc files.

interface TableInMemory {
  table_name: string;
  definition: Definition;
  definition_patch: DefinitionPatch;
  table_data: DecodedData[][];
  altered: boolean;
}

public class TableInMemory
{
    public string TableName { get; set; }
    public Definition Definition { get; set; }
    public DefinitionPatch DefinitionPatch { get; set; }
    public List<List<DecodedData>> TableData { get; set; }
    public bool Altered { get; set; }
}

RFile

A raw packed file.

interface RFile {
  path: string;
  timestamp: number | null;
  file_type: FileType;
  container_name: string | null;
  data: unknown;
}

public class RFile
{
    public string Path { get; set; }
    public long? Timestamp { get; set; }
    public FileType FileType { get; set; }
    public string? ContainerName { get; set; }
    public object Data { get; set; }
}

RFileDecoded

Decoded file content. Serialized as a tagged enum — the variant name indicates the file type. See Decoded File Types for each type’s structure.

Variants: Anim, AnimFragmentBattle, AnimPack, AnimsTable, Atlas, Audio, BMD, BMDVegetation, Dat, DB, ESF, Font, GroupFormations, HlslCompiled, Image, Loc, MatchedCombat, Pack, PortraitSettings, RigidModel, SoundBank, Text, UIC, UnitVariant, Unknown, Video, VMD, WSModel.

Example:

{ "DB": { "mysterious_byte": true, "guid": "", "table": { ... } } }
{ "Text": { "encoding": "Utf8Bom", "format": "Lua", "contents": "-- script" } }

// One variant per known file type. Most carry the decoded type described below;
// a handful (VMD, WSModel) wrap a Text payload.
type RFileDecoded =
  | { Anim: unknown } | { AnimFragmentBattle: AnimFragmentBattle }
  | { AnimPack: unknown } | { AnimsTable: AnimsTable }
  | { Atlas: Atlas } | { Audio: Audio }
  | { BMD: Bmd } | { BMDVegetation: unknown }
  | { Dat: unknown } | { DB: DB }
  | { ESF: ESF } | { Font: unknown }
  | { GroupFormations: GroupFormations } | { HlslCompiled: unknown }
  | { Image: Image } | { Loc: Loc }
  | { MatchedCombat: MatchedCombat } | { Pack: unknown }
  | { PortraitSettings: PortraitSettings } | { RigidModel: RigidModel }
  | { SoundBank: unknown } | { Text: Text }
  | { UIC: UIC } | { UnitVariant: UnitVariant }
  | { Unknown: unknown } | { Video: unknown }
  | { VMD: Text } | { WSModel: Text };

// Tagged enum — one wrapper class per variant. Only the most common ones shown.
public abstract class RFileDecoded { }
public class RFileDecodedDB : RFileDecoded { public DB DB { get; set; } }
public class RFileDecodedLoc : RFileDecoded { public Loc Loc { get; set; } }
public class RFileDecodedText : RFileDecoded { public Text Text { get; set; } }
public class RFileDecodedImage : RFileDecoded { public Image Image { get; set; } }
public class RFileDecodedRigidModel : RFileDecoded { public RigidModel RigidModel { get; set; } }
// ... one class per variant listed in the enum above.

TableReferences

Reference data for a column, used by lookup/autocomplete features.

interface TableReferences {
  field_name: string;
  referenced_table_is_ak_only: boolean;
  referenced_column_is_localised: boolean;
  data: Record<string, string>;
}

public class TableReferences
{
    public string FieldName { get; set; }
    public bool ReferencedTableIsAkOnly { get; set; }
    public bool ReferencedColumnIsLocalised { get; set; }
    public Dictionary<string, string> Data { get; set; }
}

Decoded File Types

DB

Decoded database table file.

interface DB {
  mysterious_byte: boolean;
  guid: string;
  table: TableInMemory;
}

public class DB
{
    public bool MysteriousByte { get; set; }
    public string Guid { get; set; }
    public TableInMemory Table { get; set; }
}

Loc

Decoded localisation file.

interface Loc {
  table: TableInMemory;
}

public class Loc
{
    public TableInMemory Table { get; set; }
}

Text

Decoded text file.

interface Text {
  encoding: TextEncoding;
  format: TextFormat;
  contents: string;
}

public class Text
{
    public TextEncoding Encoding { get; set; }
    public TextFormat Format { get; set; }
    public string Contents { get; set; }
}

TextEncoding

Character encoding of a text file’s contents. Serialized as a plain string:

Rust source name: Encoding (in rpfm_lib::files::text). This doc uses the more descriptive name TextEncoding for clarity — the on-the-wire JSON is identical.

type TextEncoding = "Iso8859_1" | "Utf8" | "Utf8Bom" | "Utf16Le";

public enum TextEncoding { Iso8859_1, Utf8, Utf8Bom, Utf16Le }

TextFormat

Source-code format / syntax-highlighting language for a text file. Also used as the second element of the NewFile.Text payload. Serialized as a plain string:

type TextFormat =
  | "Bat" | "Cpp" | "Html" | "Hlsl" | "Json" | "Js" | "Css"
  | "Lua" | "Markdown" | "Plain" | "Python" | "Sql" | "Xml" | "Yaml";

public enum TextFormat { Bat, Cpp, Html, Hlsl, Json, Js, Css, Lua, Markdown, Plain, Python, Sql, Xml, Yaml }

Image

Decoded image file.

interface Image {
  data: number[];
  converted_data: number[] | null;
}

public class Image
{
    public byte[] Data { get; set; }
    public byte[]? ConvertedData { get; set; }
}

RigidModel

Decoded RigidModel (3D model) file.

interface RigidModel {
  version: number;
  uk_1: number;
  skeleton_id: string;
  lods: unknown[];
}

public class RigidModel
{
    public uint Version { get; set; }
    public uint Uk1 { get; set; }
    public string SkeletonId { get; set; }
    public List<object> Lods { get; set; }
}

ESF

Decoded ESF (Empire Save Format) file.

interface ESF {
  signature: string;
  unknown_1: number;
  creation_date: number;
  root_node: unknown;
}

public class ESF
{
    public string Signature { get; set; }
    public uint Unknown1 { get; set; }
    public uint CreationDate { get; set; }
    public object RootNode { get; set; }
}

Bmd

Decoded BMD (Battle Map Data) file.

// Only the stable header field is typed; the rest is format-specific and opaque.
interface Bmd {
  serialise_version: number;
  [other: string]: unknown;
}

public class Bmd
{
    public uint SerialiseVersion { get; set; }
    // plus format-specific fields depending on serialise_version
}

AnimFragmentBattle

Decoded AnimFragmentBattle file.

interface AnimFragmentBattle {
  version: number;
  entries: unknown[];
  skeleton_name: string;
  subversion: number;
}

public class AnimFragmentBattle
{
    public uint Version { get; set; }
    public List<object> Entries { get; set; }
    public string SkeletonName { get; set; }
    public uint Subversion { get; set; }
}

AnimsTable

Decoded AnimsTable file.

interface AnimsTable {
  version: number;
  entries: unknown[];
}

public class AnimsTable
{
    public uint Version { get; set; }
    public List<object> Entries { get; set; }
}

Atlas

Decoded Atlas (sprite sheet) file.

interface Atlas {
  version: number;
  unknown: number;
  entries: unknown[];
}

public class Atlas
{
    public uint Version { get; set; }
    public uint Unknown { get; set; }
    public List<object> Entries { get; set; }
}

Audio

Decoded Audio file.

interface Audio {
  data: number[];
}

public class Audio
{
    public byte[] Data { get; set; }
}

GroupFormations

Decoded GroupFormations file.

interface GroupFormations {
  formations: unknown[];
}

public class GroupFormations
{
    public List<object> Formations { get; set; }
}

MatchedCombat

Decoded MatchedCombat file.

interface MatchedCombat {
  version: number;
  entries: unknown[];
}

public class MatchedCombat
{
    public uint Version { get; set; }
    public List<object> Entries { get; set; }
}

PortraitSettings

Decoded PortraitSettings file.

interface PortraitSettings {
  version: number;
  entries: unknown[];
}

public class PortraitSettings
{
    public uint Version { get; set; }
    public List<object> Entries { get; set; }
}

UIC

Decoded UIC (UI Component) file.

interface UIC {
  version: number;
  source_is_xml: boolean;
  comment: string;
  precache_condition: string;
  hierarchy: Record<string, unknown>;
  components: Record<string, unknown>;
}

public class UIC
{
    public uint Version { get; set; }
    public bool SourceIsXml { get; set; }
    public string Comment { get; set; }
    public string PrecacheCondition { get; set; }
    public Dictionary<string, object> Hierarchy { get; set; }
    public Dictionary<string, object> Components { get; set; }
}

UnitVariant

Decoded UnitVariant file.

interface UnitVariant {
  version: number;
  unknown_1: number;
  categories: unknown[];
}

public class UnitVariant
{
    public uint Version { get; set; }
    public uint Unknown1 { get; set; }
    public List<object> Categories { get; set; }
}

Schema Types

FieldType

The data type of a field in a schema definition. Most values are plain strings; sequence types wrap a nested Definition:

type FieldType =
  | "Boolean" | "F32" | "F64" | "I16" | "I32" | "I64"
  | "ColourRGB" | "StringU8" | "StringU16"
  | "OptionalI16" | "OptionalI32" | "OptionalI64"
  | "OptionalStringU8" | "OptionalStringU16"
  | { SequenceU16: Definition }
  | { SequenceU32: Definition };

// Mix of plain-string and tagged-enum variants. Model it as a tagged union:
public abstract class FieldType { }
public class FieldTypePrimitive : FieldType { public string Kind { get; set; } }  // e.g. "I32"
public class FieldTypeSequenceU16 : FieldType { public Definition SequenceU16 { get; set; } }
public class FieldTypeSequenceU32 : FieldType { public Definition SequenceU32 { get; set; } }

Field

A single field descriptor within a Definition.

interface Field {
  name: string;
  field_type: FieldType;
  is_key: boolean;
  default_value: string | null;
  is_filename: boolean;
  filename_relative_path: string | null;
  is_reference: [string, string] | null;
  lookup: string[] | null;
  description: string;
  ca_order: number;
  is_bitwise: number;
  enum_values: Record<number, string>;
  is_part_of_colour: number | null;
}

public class Field
{
    public string Name { get; set; }
    public FieldType FieldType { get; set; }
    public bool IsKey { get; set; }
    public string? DefaultValue { get; set; }
    public bool IsFilename { get; set; }
    public string? FilenameRelativePath { get; set; }
    public Tuple<string, string>? IsReference { get; set; }
    public List<string>? Lookup { get; set; }
    public string Description { get; set; }
    public short CaOrder { get; set; }
    public int IsBitwise { get; set; }
    public Dictionary<int, string> EnumValues { get; set; }
    public byte? IsPartOfColour { get; set; }
}

Definition

Schema definition for a specific version of a DB table.

Note: The fields list is ordered to match the binary encoding of the table, which is not necessarily the order columns appear in the decoded/displayed data. To get fields in decoded column order (with bitwise expansion, enum conversion, and colour merging applied), use the FieldsProcessed command, passing the Definition as input.

interface Definition {
  version: number;
  fields: Field[];
  localised_fields: Field[];
  localised_key_order: number[];
}

public class Definition
{
    public int Version { get; set; }
    public List<Field> Fields { get; set; }
    public List<Field> LocalisedFields { get; set; }
    public List<uint> LocalisedKeyOrder { get; set; }
}

Schema

The full schema containing all table definitions for a game.

interface Schema {
  version: number;
  definitions: Record<string, Definition[]>;
  patches: Record<string, DefinitionPatch>;
}

public class Schema
{
    public ushort Version { get; set; }
    public Dictionary<string, List<Definition>> Definitions { get; set; }
    public Dictionary<string, DefinitionPatch> Patches { get; set; }
}

DefinitionPatch

A patch applied to a schema definition. Serialized as a nested map:

{
  "field_name": {
    "property_name": "property_value"
  }
}

Type: Record<string, Record<string, string>>

type DefinitionPatch = Record<string, Record<string, string>>;

// DefinitionPatch is a type alias for the nested map:
using DefinitionPatch = System.Collections.Generic.Dictionary<string, System.Collections.Generic.Dictionary<string, string>>;

Pack Settings Types

PackSettings

Per-pack configuration stored inside the Pack file.

interface PackSettings {
  settings_text: Record<string, string>;
  settings_string: Record<string, string>;
  settings_bool: Record<string, boolean>;
  settings_number: Record<string, number>;
}

public class PackSettings
{
    public Dictionary<string, string> SettingsText { get; set; }
    public Dictionary<string, string> SettingsString { get; set; }
    public Dictionary<string, bool> SettingsBool { get; set; }
    public Dictionary<string, int> SettingsNumber { get; set; }
}

Note

A note attached to a path within the Pack file.

interface Note {
  id: number;
  message: string;
  url: string | null;
  path: string;
}

public class Note
{
    public ulong Id { get; set; }
    public string Message { get; set; }
    public string? Url { get; set; }
    public string Path { get; set; }
}

OptimizerOptions

Configuration for the pack optimizer.

interface OptimizerOptions {
  pack_remove_itm_files: boolean;
  db_import_datacores_into_twad_key_deletes: boolean;
  db_optimize_datacored_tables: boolean;
  table_remove_duplicated_entries: boolean;
  table_remove_itm_entries: boolean;
  table_remove_itnr_entries: boolean;
  table_remove_empty_file: boolean;
  text_remove_unused_xml_map_folders: boolean;
  text_remove_unused_xml_prefab_folder: boolean;
  text_remove_agf_files: boolean;
  text_remove_model_statistics_files: boolean;
  pts_remove_unused_art_sets: boolean;
  pts_remove_unused_variants: boolean;
  pts_remove_empty_masks: boolean;
  pts_remove_empty_file: boolean;
}

public class OptimizerOptions
{
    public bool PackRemoveItmFiles { get; set; }
    public bool DbImportDatacoresIntoTwadKeyDeletes { get; set; }
    public bool DbOptimizeDatacoredTables { get; set; }
    public bool TableRemoveDuplicatedEntries { get; set; }
    public bool TableRemoveItmEntries { get; set; }
    public bool TableRemoveItnrEntries { get; set; }
    public bool TableRemoveEmptyFile { get; set; }
    public bool TextRemoveUnusedXmlMapFolders { get; set; }
    public bool TextRemoveUnusedXmlPrefabFolder { get; set; }
    public bool TextRemoveAgfFiles { get; set; }
    public bool TextRemoveModelStatisticsFiles { get; set; }
    public bool PtsRemoveUnusedArtSets { get; set; }
    public bool PtsRemoveUnusedVariants { get; set; }
    public bool PtsRemoveEmptyMasks { get; set; }
    public bool PtsRemoveEmptyFile { get; set; }
}

SettingsSnapshot

A full batch of settings. Returned by the SettingsGetAll command — much cheaper than round-tripping per-key getters when you need many settings at once. Each field is a map from setting key to value for one primitive type.

interface SettingsSnapshot {
  bool: Record<string, boolean>;
  i32: Record<string, number>;
  f32: Record<string, number>;
  string: Record<string, string>;
  raw_data: Record<string, number[]>;
  vec_string: Record<string, string[]>;
}

public class SettingsSnapshot
{
    public Dictionary<string, bool> Bool { get; set; }
    public Dictionary<string, int> I32 { get; set; }
    public Dictionary<string, float> F32 { get; set; }
    public Dictionary<string, string> String { get; set; }
    public Dictionary<string, byte[]> RawData { get; set; }
    public Dictionary<string, List<string>> VecString { get; set; }
}

Translation Types

Translation

A single translation entry for a Loc key.

interface Translation {
  key: string;
  value_original: string;
  value_translated: string;
  needs_retranslation: boolean;
  removed: boolean;
}

public class Translation
{
    public string Key { get; set; }
    public string ValueOriginal { get; set; }
    public string ValueTranslated { get; set; }
    public bool NeedsRetranslation { get; set; }
    public bool Removed { get; set; }
}

PackTranslation

Translation data for a pack in a specific language.

interface PackTranslation {
  language: string;
  pack_name: string;
  translations: Record<string, Translation>;
}

public class PackTranslation
{
    public string Language { get; set; }
    public string PackName { get; set; }
    public Dictionary<string, Translation> Translations { get; set; }
}

Diagnostics Types

Diagnostics

Diagnostics report configuration and results.

interface Diagnostics {
  folders_ignored: string[];
  files_ignored: string[];
  fields_ignored: string[];
  diagnostics_ignored: string[];
  results: DiagnosticType[];
}

public class Diagnostics
{
    public List<string> FoldersIgnored { get; set; }
    public List<string> FilesIgnored { get; set; }
    public List<string> FieldsIgnored { get; set; }
    public List<string> DiagnosticsIgnored { get; set; }
    public List<DiagnosticType> Results { get; set; }
}

DiagnosticType

A single diagnostic result. Serialized as a tagged enum — the variant name indicates which kind of diagnostic fired:

Each payload is a struct with at least path: string and results: <SpecificDiagnosticReport>[] (the concrete inner fields vary by diagnostic kind and are treated as opaque by this doc). The full structures live in rpfm_extensions::diagnostics — e.g. TableDiagnostic, PackDiagnostic, ConfigDiagnostic, and so on. Clients that only need to display diagnostic results can round-trip the JSON without decoding these payloads.

// The inner payloads are left opaque here — their shape depends on the diagnostic kind.
type DiagnosticType =
  | { AnimFragmentBattle: unknown }
  | { Config: unknown }
  | { Dependency: unknown }
  | { DB: unknown }
  | { Loc: unknown }
  | { Pack: unknown }
  | { PortraitSettings: unknown }
  | { Text: unknown };

public abstract class DiagnosticType { }
public class DiagnosticTypeAnimFragmentBattle : DiagnosticType { public object AnimFragmentBattle { get; set; } }
public class DiagnosticTypeConfig             : DiagnosticType { public object Config { get; set; } }
public class DiagnosticTypeDependency         : DiagnosticType { public object Dependency { get; set; } }
public class DiagnosticTypeDB                 : DiagnosticType { public object DB { get; set; } }
public class DiagnosticTypeLoc                : DiagnosticType { public object Loc { get; set; } }
public class DiagnosticTypePack               : DiagnosticType { public object Pack { get; set; } }
public class DiagnosticTypePortraitSettings   : DiagnosticType { public object PortraitSettings { get; set; } }
public class DiagnosticTypeText               : DiagnosticType { public object Text { get; set; } }

Update Types

APIResponse

Response from a program update check. Serialized as a tagged enum:

type APIResponse =
  | { NewBetaUpdate: string }
  | { NewStableUpdate: string }
  | { NewUpdateHotfix: string }
  | "NoUpdate"
  | "UnknownVersion";

// Serialize as either a wrapped object { "<Variant>": "version" } or a bare string.
public abstract class APIResponse { }
public class APIResponseNewBetaUpdate   : APIResponse { public string NewBetaUpdate { get; set; } }
public class APIResponseNewStableUpdate : APIResponse { public string NewStableUpdate { get; set; } }
public class APIResponseNewUpdateHotfix : APIResponse { public string NewUpdateHotfix { get; set; } }
public class APIResponseNoUpdate        : APIResponse { }
public class APIResponseUnknownVersion  : APIResponse { }

GitResponse

Response from a git-based update check (schemas, translations, etc.):

type GitResponse = "NewUpdate" | "NoUpdate" | "NoLocalFiles" | "Diverged";

public enum GitResponse { NewUpdate, NoUpdate, NoLocalFiles, Diverged }

Search Types

SearchSource

Which data source to search. Serialized as a tagged enum — the Pack variant carries a pack key, the rest are plain strings:

Example:

{ "Pack": "my_mod.pack" }
"GameFiles"

type SearchSource =
  | { Pack: string }
  | "ParentFiles"
  | "GameFiles"
  | "AssKitFiles";

// Serialize as either { "Pack": "pack_key" } or a bare string.
public abstract class SearchSource { }
public class SearchSourcePack        : SearchSource { public string Pack { get; set; } }
public class SearchSourceParentFiles : SearchSource { }
public class SearchSourceGameFiles   : SearchSource { }
public class SearchSourceAssKitFiles : SearchSource { }

SearchOn

Boolean flags for which file types to include in a search. Each field corresponds to a file type:

anim, anim_fragment_battle, anim_pack, anims_table, atlas, audio, bmd, db, esf, group_formations, image, loc, matched_combat, pack, portrait_settings, rigid_model, sound_bank, text, uic, unit_variant, unknown, video, schema

All fields are boolean.

interface SearchOn {
  anim: boolean;
  anim_fragment_battle: boolean;
  anim_pack: boolean;
  anims_table: boolean;
  atlas: boolean;
  audio: boolean;
  bmd: boolean;
  db: boolean;
  esf: boolean;
  group_formations: boolean;
  image: boolean;
  loc: boolean;
  matched_combat: boolean;
  pack: boolean;
  portrait_settings: boolean;
  rigid_model: boolean;
  sound_bank: boolean;
  text: boolean;
  uic: boolean;
  unit_variant: boolean;
  unknown: boolean;
  video: boolean;
  schema: boolean;
}

public class SearchOn
{
    public bool Anim { get; set; }
    public bool AnimFragmentBattle { get; set; }
    public bool AnimPack { get; set; }
    public bool AnimsTable { get; set; }
    public bool Atlas { get; set; }
    public bool Audio { get; set; }
    public bool Bmd { get; set; }
    public bool Db { get; set; }
    public bool Esf { get; set; }
    public bool GroupFormations { get; set; }
    public bool Image { get; set; }
    public bool Loc { get; set; }
    public bool MatchedCombat { get; set; }
    public bool Pack { get; set; }
    public bool PortraitSettings { get; set; }
    public bool RigidModel { get; set; }
    public bool SoundBank { get; set; }
    public bool Text { get; set; }
    public bool Uic { get; set; }
    public bool UnitVariant { get; set; }
    public bool Unknown { get; set; }
    public bool Video { get; set; }
    public bool Schema { get; set; }
}

GlobalSearch

Global search configuration and results.

interface GlobalSearch {
  pattern: string;
  replace_text: string;
  case_sensitive: boolean;
  use_regex: boolean;
  sources: SearchSource[];
  search_on: SearchOn;
  matches: Matches;
  game_key: string;
}

public class GlobalSearch
{
    public string Pattern { get; set; }
    public string ReplaceText { get; set; }
    public bool CaseSensitive { get; set; }
    public bool UseRegex { get; set; }
    public List<SearchSource> Sources { get; set; }
    public SearchOn SearchOn { get; set; }
    public Matches Matches { get; set; }
    public string GameKey { get; set; }
}

Matches

The results of a global search, grouped by file type. Each field is an array of per-type match containers (defined in the next section) — except schema, which is a single SchemaMatches container.

interface Matches {
  anim: UnknownMatches[];
  anim_fragment_battle: AnimFragmentBattleMatches[];
  anim_pack: UnknownMatches[];
  anims_table: UnknownMatches[];
  atlas: AtlasMatches[];
  audio: UnknownMatches[];
  bmd: UnknownMatches[];
  db: TableMatches[];
  esf: UnknownMatches[];
  group_formations: UnknownMatches[];
  image: UnknownMatches[];
  loc: TableMatches[];
  matched_combat: UnknownMatches[];
  pack: UnknownMatches[];
  portrait_settings: PortraitSettingsMatches[];
  rigid_model: RigidModelMatches[];
  sound_bank: UnknownMatches[];
  text: TextMatches[];
  uic: UnknownMatches[];
  unit_variant: UnitVariantMatches[];
  unknown: UnknownMatches[];
  video: UnknownMatches[];
  schema: SchemaMatches;
}

public class Matches
{
    public List<MatchContainer<UnknownMatch>> Anim { get; set; }
    public List<MatchContainer<AnimFragmentBattleMatch>> AnimFragmentBattle { get; set; }
    public List<MatchContainer<UnknownMatch>> AnimPack { get; set; }
    public List<MatchContainer<UnknownMatch>> AnimsTable { get; set; }
    public List<MatchContainer<AtlasMatch>> Atlas { get; set; }
    public List<MatchContainer<UnknownMatch>> Audio { get; set; }
    public List<MatchContainer<UnknownMatch>> Bmd { get; set; }
    public List<MatchContainer<TableMatch>> Db { get; set; }
    public List<MatchContainer<UnknownMatch>> Esf { get; set; }
    public List<MatchContainer<UnknownMatch>> GroupFormations { get; set; }
    public List<MatchContainer<UnknownMatch>> Image { get; set; }
    public List<MatchContainer<TableMatch>> Loc { get; set; }
    public List<MatchContainer<UnknownMatch>> MatchedCombat { get; set; }
    public List<MatchContainer<UnknownMatch>> Pack { get; set; }
    public List<MatchContainer<PortraitSettingsMatch>> PortraitSettings { get; set; }
    public List<MatchContainer<RigidModelMatch>> RigidModel { get; set; }
    public List<MatchContainer<UnknownMatch>> SoundBank { get; set; }
    public List<MatchContainer<TextMatch>> Text { get; set; }
    public List<MatchContainer<UnknownMatch>> Uic { get; set; }
    public List<MatchContainer<UnitVariantMatch>> UnitVariant { get; set; }
    public List<MatchContainer<UnknownMatch>> Unknown { get; set; }
    public List<MatchContainer<UnknownMatch>> Video { get; set; }
    public MatchContainer<SchemaMatch> Schema { get; set; }
}

Match Types

Search results use specialized match types per file format. All match containers share the same wrapper shape:

TableMatch (used for DB and Loc files):

TextMatch (used for text files):

UnknownMatch (used for binary/unknown files):

AnimFragmentBattleMatch (used for AnimFragmentBattle files):

AtlasMatch (used for Atlas files — same structure as TableMatch):

PortraitSettingsMatch (used for PortraitSettings files):

RigidModelMatch (used for RigidModel files):

UnitVariantMatch (used for UnitVariant files):

SchemaMatch (used for schema searches):

All match container types (TableMatches, TextMatches, AnimFragmentBattleMatches, etc.) use the wrapper shape from the top of this section — { path, source, container_name, matches } — with matches being an array of the corresponding per-type match struct.

interface TableMatch {
  column_name: string;
  column_number: number;
  row_number: number;
  start: number;
  end: number;
  text: string;
}

interface TextMatch {
  row: number;
  start: number;
  end: number;
  text: string;
}

interface UnknownMatch {
  pos: number;
  len: number;
}

interface AnimFragmentBattleMatch {
  skeleton_name: boolean;
  table_name: boolean;
  mount_table_name: boolean;
  unmount_table_name: boolean;
  locomotion_graph: boolean;
  entry:
    | [number, [number, boolean, boolean, boolean] | null, boolean, boolean, boolean, boolean, boolean]
    | null;
  start: number;
  end: number;
  text: string;
}

interface AtlasMatch extends TableMatch {}  // same shape as TableMatch

interface PortraitSettingsMatch {
  entry: number;
  id: boolean;
  camera_settings_head: boolean;
  camera_settings_body: boolean;
  variant: [number, boolean, boolean, boolean, boolean, boolean] | null;
  start: number;
  end: number;
  text: string;
}

interface RigidModelMatch {
  skeleton_id: boolean;
  mesh_value: [number, number] | null;
  mesh_name: boolean;
  mesh_mat_name: boolean;
  mesh_textute_directory: boolean;
  mesh_filters: boolean;
  mesh_att_point_name: number | null;
  mesh_texture_path: number | null;
  start: number;
  end: number;
  text: string;
}

interface UnitVariantMatch {
  entry: number;
  name: boolean;
  variant: [number, boolean, boolean] | null;
  start: number;
  end: number;
  text: string;
}

interface SchemaMatch {
  table_name: string;
  version: number;
  column: number;
  column_name: string;
}

// The wrapper that groups matches for one file, used by every *Matches type:
interface MatchContainer<M> {
  path: string;
  source: SearchSource;
  container_name: string;
  matches: M[];
}
type TableMatches              = MatchContainer<TableMatch>;
type TextMatches               = MatchContainer<TextMatch>;
type UnknownMatches            = MatchContainer<UnknownMatch>;
type AnimFragmentBattleMatches = MatchContainer<AnimFragmentBattleMatch>;
type AtlasMatches              = MatchContainer<AtlasMatch>;
type PortraitSettingsMatches   = MatchContainer<PortraitSettingsMatch>;
type RigidModelMatches         = MatchContainer<RigidModelMatch>;
type UnitVariantMatches        = MatchContainer<UnitVariantMatch>;
type SchemaMatches             = MatchContainer<SchemaMatch>;

public class TableMatch
{
    public string ColumnName { get; set; }
    public uint ColumnNumber { get; set; }
    public long RowNumber { get; set; }
    public long Start { get; set; }
    public long End { get; set; }
    public string Text { get; set; }
}

public class TextMatch
{
    public ulong Row { get; set; }
    public long Start { get; set; }
    public long End { get; set; }
    public string Text { get; set; }
}

public class UnknownMatch
{
    public long Pos { get; set; }
    public long Len { get; set; }
}

// AtlasMatch has the same shape as TableMatch.
public class AtlasMatch : TableMatch { }

public class SchemaMatch
{
    public string TableName { get; set; }
    public int Version { get; set; }
    public int Column { get; set; }
    public string ColumnName { get; set; }
}

// AnimFragmentBattleMatch, PortraitSettingsMatch, RigidModelMatch and UnitVariantMatch
// follow the tables above; field-for-field translations are straightforward
// (booleans → bool, nullable tuples → Tuple<...>? or a named class).

// Wrapper shared by every *Matches type:
public class MatchContainer<M>
{
    public string Path { get; set; }
    public SearchSource Source { get; set; }
    public string ContainerName { get; set; }
    public List<M> Matches { get; set; }
}

MatchHolder

A tagged enum wrapping a single file type’s matches. The variant name indicates the file type:

{ "Db": { "path": "db/units_tables/data", "matches": [...] } }
{ "Text": { "path": "script/campaign/mod.lua", "matches": [...] } }

Variants: Anim, AnimFragmentBattle, AnimPack, AnimsTable, Atlas, Audio, Bmd, Db, Esf, GroupFormations, Image, Loc, MatchedCombat, Pack, PortraitSettings, RigidModel, SoundBank, Text, Uic, UnitVariant, Unknown, Video, Schema.

// Most variants carry an UnknownMatches; only the rich-formatted file types carry their own match container.
type MatchHolder =
  | { Anim: UnknownMatches }
  | { AnimFragmentBattle: AnimFragmentBattleMatches }
  | { AnimPack: UnknownMatches }
  | { AnimsTable: UnknownMatches }
  | { Atlas: AtlasMatches }
  | { Audio: UnknownMatches }
  | { Bmd: UnknownMatches }
  | { Db: TableMatches }
  | { Esf: UnknownMatches }
  | { GroupFormations: UnknownMatches }
  | { Image: UnknownMatches }
  | { Loc: TableMatches }
  | { MatchedCombat: UnknownMatches }
  | { Pack: UnknownMatches }
  | { PortraitSettings: PortraitSettingsMatches }
  | { RigidModel: RigidModelMatches }
  | { SoundBank: UnknownMatches }
  | { Text: TextMatches }
  | { Uic: UnknownMatches }
  | { UnitVariant: UnitVariantMatches }
  | { Unknown: UnknownMatches }
  | { Video: UnknownMatches }
  | { Schema: SchemaMatches };

// One wrapper class per variant. Only the most common ones shown — pattern is identical for the rest.
public abstract class MatchHolder { }
public class MatchHolderDb   : MatchHolder { public MatchContainer<TableMatch> Db { get; set; } }
public class MatchHolderLoc  : MatchHolder { public MatchContainer<TableMatch> Loc { get; set; } }
public class MatchHolderText : MatchHolder { public MatchContainer<TextMatch> Text { get; set; } }
public class MatchHolderSchema : MatchHolder { public MatchContainer<SchemaMatch> Schema { get; set; } }
// ... one class per variant listed above; most wrap MatchContainer<UnknownMatch>.

Commands

This page documents all commands that can be sent to the RPFM server. Each command is wrapped in a Message with a unique id.

Commands with no parameters are serialized as plain strings. Commands with parameters use the { "CommandName": params } format. See the serialization convention for details.

Most commands that operate on a specific pack take a pack_key string as their first parameter. The pack key is returned by OpenPackFiles or NewPack when you open or create a pack.

Lifecycle

Exit

Close the background thread. Do not use directly — the server manages this internally.

Response: None (breaks the server loop).

type ExitRequest = "Exit";
// No response — the server loop terminates.

// Request: send the literal string "Exit". No response.

ClientDisconnecting

Signal that the client is intentionally disconnecting. Allows the server to clean up the session immediately.

Response: "Success"

{ "id": 1, "data": "ClientDisconnecting" }

type ClientDisconnectingRequest = "ClientDisconnecting";
type ClientDisconnectingResponse = "Success";

// Request: send the literal string "ClientDisconnecting".
// Response: the literal string "Success".

PackFile Operations

NewPack

Create a new empty Pack.

Response: { String: string } — the assigned pack key.

{ "id": 1, "data": "NewPack" }

type NewPackRequest = "NewPack";
type NewPackResponse = { String: string };

// Request: send the literal string "NewPack".
public class NewPackResponse
{
    public string String { get; set; }
}

OpenPackFiles

Open one or more Pack files and merge them into the current session.

Response: { StringContainerInfo: [string, ContainerInfo] } — pack key and metadata.

{ "id": 1, "data": { "OpenPackFiles": ["/path/to/my_mod.pack"] } }

type OpenPackFilesRequest = { OpenPackFiles: string[] };
type OpenPackFilesResponse = { StringContainerInfo: [string, ContainerInfo] };

public class OpenPackFilesRequest
{
    public List<string> OpenPackFiles { get; set; }
}
public class OpenPackFilesResponse
{
    public Tuple<string, ContainerInfo> StringContainerInfo { get; set; }
}

LoadAllCAPackFiles

Open all CA Pack files for the selected game as one merged Pack.

Response: { StringContainerInfo: [string, ContainerInfo] }

{ "id": 1, "data": "LoadAllCAPackFiles" }

type LoadAllCAPackFilesRequest = "LoadAllCAPackFiles";
type LoadAllCAPackFilesResponse = { StringContainerInfo: [string, ContainerInfo] };

// Request: send the literal string "LoadAllCAPackFiles".
public class LoadAllCAPackFilesResponse
{
    public Tuple<string, ContainerInfo> StringContainerInfo { get; set; }
}

ListOpenPacks

List all currently open packs with their keys and metadata.

Response: { VecStringContainerInfo: [string, ContainerInfo][] }

{ "id": 1, "data": "ListOpenPacks" }

type ListOpenPacksRequest = "ListOpenPacks";
type ListOpenPacksResponse = { VecStringContainerInfo: [string, ContainerInfo][] };

// Request: send the literal string "ListOpenPacks".
public class ListOpenPacksResponse
{
    public List<Tuple<string, ContainerInfo>> VecStringContainerInfo { get; set; }
}

ClosePack

Close a specific open Pack.

Response: "Success"

{ "id": 1, "data": { "ClosePack": "my_mod.pack" } }

type ClosePackRequest = { ClosePack: string };
type ClosePackResponse = "Success";

public class ClosePackRequest
{
    public string ClosePack { get; set; }
}
// Response: the literal string "Success".

CloseAllPacks

Close all currently open Packs.

Response: "Success"

{ "id": 1, "data": "CloseAllPacks" }

type CloseAllPacksRequest = "CloseAllPacks";
type CloseAllPacksResponse = "Success";

// Request: send the literal string "CloseAllPacks".
// Response: the literal string "Success".

SavePack

Save a specific open Pack to disk.

Response: { ContainerInfo: ContainerInfo }

{ "id": 1, "data": { "SavePack": "my_mod.pack" } }

type SavePackRequest = { SavePack: string };
type SavePackResponse = { ContainerInfo: ContainerInfo };

public class SavePackRequest
{
    public string SavePack { get; set; }
}
public class SavePackResponse
{
    public ContainerInfo ContainerInfo { get; set; }
}

SavePackAs

Save a specific open Pack to a new path.

Response: { ContainerInfo: ContainerInfo }

{ "id": 1, "data": { "SavePackAs": ["my_mod.pack", "/path/to/new_mod.pack"] } }

type SavePackAsRequest = { SavePackAs: [string, string] };
type SavePackAsResponse = { ContainerInfo: ContainerInfo };

public class SavePackAsRequest
{
    public Tuple<string, string> SavePackAs { get; set; }
}
public class SavePackAsResponse
{
    public ContainerInfo ContainerInfo { get; set; }
}

CleanAndSavePackAs

Clean a Pack from corrupted/undecoded files and save to disk. Only use if the Pack is otherwise unsaveable.

Response: { ContainerInfo: ContainerInfo }

{ "id": 1, "data": { "CleanAndSavePackAs": ["my_mod.pack", "/path/to/cleaned.pack"] } }

type CleanAndSavePackAsRequest = { CleanAndSavePackAs: [string, string] };
type CleanAndSavePackAsResponse = { ContainerInfo: ContainerInfo };

public class CleanAndSavePackAsRequest
{
    public Tuple<string, string> CleanAndSavePackAs { get; set; }
}
public class CleanAndSavePackAsResponse
{
    public ContainerInfo ContainerInfo { get; set; }
}

GetPackFileDataForTreeView

Get tree view data (container info and file list) for a specific pack.

Response: { ContainerInfoVecRFileInfo: [ContainerInfo, RFileInfo[]] }

{ "id": 1, "data": { "GetPackFileDataForTreeView": "my_mod.pack" } }

type GetPackFileDataForTreeViewRequest = { GetPackFileDataForTreeView: string };
type GetPackFileDataForTreeViewResponse = { ContainerInfoVecRFileInfo: [ContainerInfo, RFileInfo[]] };

public class GetPackFileDataForTreeViewRequest
{
    public string GetPackFileDataForTreeView { get; set; }
}
public class GetPackFileDataForTreeViewResponse
{
    public Tuple<ContainerInfo, List<RFileInfo>> ContainerInfoVecRFileInfo { get; set; }
}

GetPackedFilesInfo

Get metadata for one or more packed files by path.

Response: { VecRFileInfo: RFileInfo[] }

{ "id": 1, "data": { "GetPackedFilesInfo": ["my_mod.pack", ["db/units_tables/data"]] } }

type GetPackedFilesInfoRequest = { GetPackedFilesInfo: [string, string[]] };
type GetPackedFilesInfoResponse = { VecRFileInfo: RFileInfo[] };

public class GetPackedFilesInfoRequest
{
    public Tuple<string, List<string>> GetPackedFilesInfo { get; set; }
}
public class GetPackedFilesInfoResponse
{
    public List<RFileInfo> VecRFileInfo { get; set; }
}

GetRFileInfo

Get the info of a single packed file.

Response: { OptionRFileInfo: RFileInfo | null }

{ "id": 1, "data": { "GetRFileInfo": ["my_mod.pack", "db/units_tables/data"] } }

type GetRFileInfoRequest = { GetRFileInfo: [string, string] };
type GetRFileInfoResponse = { OptionRFileInfo: RFileInfo | null };

public class GetRFileInfoRequest
{
    public Tuple<string, string> GetRFileInfo { get; set; }
}
public class GetRFileInfoResponse
{
    public RFileInfo? OptionRFileInfo { get; set; }
}

GetPackFilePath

Get the filesystem path of a specific open Pack.

Response: { PathBuf: string }

type GetPackFilePathRequest = { GetPackFilePath: string };
type GetPackFilePathResponse = { PathBuf: string };

public class GetPackFilePathRequest
{
    public string GetPackFilePath { get; set; }
}
public class GetPackFilePathResponse
{
    public string PathBuf { get; set; }
}

GetPackFileName

Get the file name of a specific open Pack.

Response: { String: string }

type GetPackFileNameRequest = { GetPackFileName: string };
type GetPackFileNameResponse = { String: string };

public class GetPackFileNameRequest
{
    public string GetPackFileName { get; set; }
}
public class GetPackFileNameResponse
{
    public string String { get; set; }
}

SetPackFileType

Change the PFH type of a specific open Pack (e.g., Mod, Movie, Boot).

Response: "Success"

type SetPackFileTypeRequest = { SetPackFileType: [string, PFHFileType] };
type SetPackFileTypeResponse = "Success";

public class SetPackFileTypeRequest
{
    public Tuple<string, string> SetPackFileType { get; set; }  // second is PFHFileType enum serialized as string
}
// Response: the literal string "Success".

ChangeIndexIncludesTimestamp

Toggle the “Index Includes Timestamp” flag for a specific pack.

Response: "Success"

type ChangeIndexIncludesTimestampRequest = { ChangeIndexIncludesTimestamp: [string, boolean] };
type ChangeIndexIncludesTimestampResponse = "Success";

public class ChangeIndexIncludesTimestampRequest
{
    public Tuple<string, bool> ChangeIndexIncludesTimestamp { get; set; }
}
// Response: the literal string "Success".

ChangeCompressionFormat

Change the compression format of a specific open Pack.

Response: { CompressionFormat: CompressionFormat } — actual format set (may differ if unsupported).

type ChangeCompressionFormatRequest = { ChangeCompressionFormat: [string, CompressionFormat] };
type ChangeCompressionFormatResponse = { CompressionFormat: CompressionFormat };

public class ChangeCompressionFormatRequest
{
    public Tuple<string, string> ChangeCompressionFormat { get; set; }  // second is CompressionFormat enum as string
}
public class ChangeCompressionFormatResponse
{
    public string CompressionFormat { get; set; }
}

OptimizePackFile

Run the optimizer over a specific open Pack.

Response: { HashSetStringHashSetString: [string[], string[]] } — deleted and added paths.

type OptimizePackFileRequest = { OptimizePackFile: [string, OptimizerOptions] };
type OptimizePackFileResponse = { HashSetStringHashSetString: [string[], string[]] };

public class OptimizePackFileRequest
{
    public Tuple<string, OptimizerOptions> OptimizePackFile { get; set; }
}
public class OptimizePackFileResponse
{
    public Tuple<HashSet<string>, HashSet<string>> HashSetStringHashSetString { get; set; }
}

PatchSiegeAI

Patch Siege AI for Warhammer siege maps in a specific pack.

Response: { StringVecContainerPath: [string, ContainerPath[]] }

type PatchSiegeAIRequest = { PatchSiegeAI: string };
type PatchSiegeAIResponse = { StringVecContainerPath: [string, ContainerPath[]] };

public class PatchSiegeAIRequest
{
    public string PatchSiegeAI { get; set; }
}
public class PatchSiegeAIResponse
{
    public Tuple<string, List<ContainerPath>> StringVecContainerPath { get; set; }
}

Game Selection

GetGameSelected

Get the currently selected game key.

Response: { String: string }

{ "id": 1, "data": "GetGameSelected" }

type GetGameSelectedRequest = "GetGameSelected";
type GetGameSelectedResponse = { String: string };

// Request: send the literal string "GetGameSelected".
public class GetGameSelectedResponse
{
    public string String { get; set; }
}

SetGameSelected

Change the selected game. Optionally rebuilds dependencies.

Response: { CompressionFormatDependenciesInfo: [CompressionFormat, DependenciesInfo | null] }

{ "id": 1, "data": { "SetGameSelected": ["warhammer_3", true] } }

type SetGameSelectedRequest = { SetGameSelected: [string, boolean] };
type SetGameSelectedResponse = {
  CompressionFormatDependenciesInfo: [CompressionFormat, DependenciesInfo | null]
};

public class SetGameSelectedRequest
{
    public Tuple<string, bool> SetGameSelected { get; set; }
}
public class SetGameSelectedResponse
{
    public Tuple<string, DependenciesInfo?> CompressionFormatDependenciesInfo { get; set; }
}

GenerateDependenciesCache

Generate the dependencies cache for the currently selected game.

Response: { DependenciesInfo: DependenciesInfo }

type GenerateDependenciesCacheRequest = "GenerateDependenciesCache";
type GenerateDependenciesCacheResponse = { DependenciesInfo: DependenciesInfo };

// Request: send the literal string "GenerateDependenciesCache".
public class GenerateDependenciesCacheResponse
{
    public DependenciesInfo DependenciesInfo { get; set; }
}

UpdateCurrentSchemaFromAssKit

Update the current schema with data from the game’s Assembly Kit.

Response: "Success"

type UpdateCurrentSchemaFromAssKitRequest = "UpdateCurrentSchemaFromAssKit";
type UpdateCurrentSchemaFromAssKitResponse = "Success";

// Request: send the literal string "UpdateCurrentSchemaFromAssKit".
// Response: the literal string "Success".

PackedFile Operations

NewPackedFile

Create a new packed file inside a specific open Pack.

Response: "Success"

{ "id": 1, "data": { "NewPackedFile": ["my_mod.pack", "db/units_tables/data", { "DB": ["data", "units_tables", 4] }] } }

type NewPackedFileRequest = { NewPackedFile: [string, string, NewFile] };
type NewPackedFileResponse = "Success";

public class NewPackedFileRequest
{
    public Tuple<string, string, NewFile> NewPackedFile { get; set; }
}
// Response: the literal string "Success".

AddPackedFiles

Add files from the filesystem to a specific open Pack.

Response: { VecContainerPathOptionString: [ContainerPath[], string | null] } — added paths and optional error.

type AddPackedFilesRequest = {
  AddPackedFiles: [string, string[], ContainerPath[], string[] | null]
};
type AddPackedFilesResponse = {
  VecContainerPathOptionString: [ContainerPath[], string | null]
};

public class AddPackedFilesRequest
{
    public Tuple<string, List<string>, List<ContainerPath>, List<string>?> AddPackedFiles { get; set; }
}
public class AddPackedFilesResponse
{
    public Tuple<List<ContainerPath>, string?> VecContainerPathOptionString { get; set; }
}

DecodePackedFile

Decode a packed file for display.

Response: Type-specific (e.g., { DBRFileInfo: [DB, RFileInfo] }, { TextRFileInfo: [Text, RFileInfo] }, "Unknown", etc.)

{ "id": 1, "data": { "DecodePackedFile": ["my_mod.pack", "db/units_tables/data", "PackFile"] } }

type DecodePackedFileRequest = { DecodePackedFile: [string, string, DataSource] };
// Response is one of many variants depending on the file type:
type DecodePackedFileResponse =
  | { AnimFragmentBattleRFileInfo: [AnimFragmentBattle, RFileInfo] }
  | { AnimPackRFileInfo: [RFileInfo[], RFileInfo] }
  | { AnimsTableRFileInfo: [AnimsTable, RFileInfo] }
  | { AtlasRFileInfo: [Atlas, RFileInfo] }
  | { AudioRFileInfo: [Audio, RFileInfo] }
  | { BmdRFileInfo: [Bmd, RFileInfo] }
  | { DBRFileInfo: [DB, RFileInfo] }
  | { ESFRFileInfo: [ESF, RFileInfo] }
  | { GroupFormationsRFileInfo: [GroupFormations, RFileInfo] }
  | { ImageRFileInfo: [Image, RFileInfo] }
  | { LocRFileInfo: [Loc, RFileInfo] }
  | { MatchedCombatRFileInfo: [MatchedCombat, RFileInfo] }
  | { PortraitSettingsRFileInfo: [PortraitSettings, RFileInfo] }
  | { RigidModelRFileInfo: [RigidModel, RFileInfo] }
  | { TextRFileInfo: [Text, RFileInfo] }
  | { UICRFileInfo: [UIC, RFileInfo] }
  | { UnitVariantRFileInfo: [UnitVariant, RFileInfo] }
  | { VideoInfoRFileInfo: [VideoInfo, RFileInfo] }
  | { VMDRFileInfo: [Text, RFileInfo] }
  | { WSModelRFileInfo: [Text, RFileInfo] }
  | { Text: Text }
  | "Unknown";

public class DecodePackedFileRequest
{
    public Tuple<string, string, string> DecodePackedFile { get; set; }  // third is DataSource enum
}
// Response: deserialize into a class with nullable properties for each variant,
// or branch on the first JSON key. Example:
public class DecodePackedFileResponse
{
    public Tuple<DB, RFileInfo>? DBRFileInfo { get; set; }
    public Tuple<Text, RFileInfo>? TextRFileInfo { get; set; }
    public Tuple<Loc, RFileInfo>? LocRFileInfo { get; set; }
    // ... one property per decoded variant above.
}

SavePackedFileFromView

Save an edited packed file back to the Pack.

Response: "Success"

type SavePackedFileFromViewRequest = { SavePackedFileFromView: [string, string, RFileDecoded] };
type SavePackedFileFromViewResponse = "Success";

public class SavePackedFileFromViewRequest
{
    public Tuple<string, string, RFileDecoded> SavePackedFileFromView { get; set; }
}
// Response: the literal string "Success".

DeletePackedFiles

Delete packed files from a specific open Pack.

Response: { VecContainerPath: ContainerPath[] } — deleted paths.

{ "id": 1, "data": { "DeletePackedFiles": ["my_mod.pack", [{ "File": "db/units_tables/data" }]] } }

type DeletePackedFilesRequest = { DeletePackedFiles: [string, ContainerPath[]] };
type DeletePackedFilesResponse = { VecContainerPath: ContainerPath[] };

public class DeletePackedFilesRequest
{
    public Tuple<string, List<ContainerPath>> DeletePackedFiles { get; set; }
}
public class DeletePackedFilesResponse
{
    public List<ContainerPath> VecContainerPath { get; set; }
}

CopyPackedFiles

Copy one or more packed files to the server-side clipboard, so they can later be pasted into the same or a different pack with PastePackedFiles. Path references only — nothing is duplicated until paste.

Response: "Success"

{ "id": 1, "data": { "CopyPackedFiles": { "my_mod.pack": [{ "File": "db/units_tables/data" }] } } }

type CopyPackedFilesRequest = { CopyPackedFiles: Record<string, ContainerPath[]> };
type CopyPackedFilesResponse = "Success";

public class CopyPackedFilesRequest
{
    public Dictionary<string, List<ContainerPath>> CopyPackedFiles { get; set; }
}
// Response: the literal string "Success".

CutPackedFiles

Same as CopyPackedFiles, but the source files will be deleted from their originating pack once PastePackedFiles runs.

Response: "Success"

{ "id": 1, "data": { "CutPackedFiles": { "my_mod.pack": [{ "File": "db/units_tables/data" }] } } }

type CutPackedFilesRequest = { CutPackedFiles: Record<string, ContainerPath[]> };
type CutPackedFilesResponse = "Success";

public class CutPackedFilesRequest
{
    public Dictionary<string, List<ContainerPath>> CutPackedFiles { get; set; }
}
// Response: the literal string "Success".

PastePackedFiles

Paste packed files from the internal clipboard into a pack. Works for both copied and cut files — on a cut paste, the source files are removed as part of this call.

Response: { VecContainerPathVecContainerPathString: [ContainerPath[], ContainerPath[], string] } — added paths, cut-deleted paths, source pack key.

{ "id": 1, "data": { "PastePackedFiles": ["my_mod.pack", "db/units_tables/"] } }

type PastePackedFilesRequest = { PastePackedFiles: [string, string] };
type PastePackedFilesResponse = {
  VecContainerPathVecContainerPathString: [ContainerPath[], ContainerPath[], string]
};

public class PastePackedFilesRequest
{
    public Tuple<string, string> PastePackedFiles { get; set; }
}
public class PastePackedFilesResponse
{
    public Tuple<List<ContainerPath>, List<ContainerPath>, string> VecContainerPathVecContainerPathString { get; set; }
}

DuplicatePackedFiles

Duplicate one or more packed files in place within the same pack. Each file is cloned with a numeric suffix appended to avoid name collisions.

Response: { VecContainerPath: ContainerPath[] } — new duplicated paths.

{ "id": 1, "data": { "DuplicatePackedFiles": ["my_mod.pack", [{ "File": "db/units_tables/data" }]] } }

type DuplicatePackedFilesRequest = { DuplicatePackedFiles: [string, ContainerPath[]] };
type DuplicatePackedFilesResponse = { VecContainerPath: ContainerPath[] };

public class DuplicatePackedFilesRequest
{
    public Tuple<string, List<ContainerPath>> DuplicatePackedFiles { get; set; }
}
public class DuplicatePackedFilesResponse
{
    public List<ContainerPath> VecContainerPath { get; set; }
}

ExtractPackedFiles

Extract packed files to the filesystem.

Response: { StringVecPathBuf: [string, string[]] }

{ "id": 1, "data": { "ExtractPackedFiles": ["my_mod.pack", { "PackFile": [{ "File": "db/units_tables/data" }] }, "/tmp/extract", false] } }

type ExtractPackedFilesRequest = {
  ExtractPackedFiles: [string, Record<DataSource, ContainerPath[]>, string, boolean]
};
type ExtractPackedFilesResponse = { StringVecPathBuf: [string, string[]] };

public class ExtractPackedFilesRequest
{
    public Tuple<string, Dictionary<string, List<ContainerPath>>, string, bool> ExtractPackedFiles { get; set; }
}
public class ExtractPackedFilesResponse
{
    public Tuple<string, List<string>> StringVecPathBuf { get; set; }
}

RenamePackedFiles

Rename packed files in a specific Pack.

Response: { VecContainerPathContainerPath: [ContainerPath, ContainerPath][] }

type RenamePackedFilesRequest = {
  RenamePackedFiles: [string, [ContainerPath, ContainerPath][]]
};
type RenamePackedFilesResponse = {
  VecContainerPathContainerPath: [ContainerPath, ContainerPath][]
};

public class RenamePackedFilesRequest
{
    public Tuple<string, List<Tuple<ContainerPath, ContainerPath>>> RenamePackedFiles { get; set; }
}
public class RenamePackedFilesResponse
{
    public List<Tuple<ContainerPath, ContainerPath>> VecContainerPathContainerPath { get; set; }
}

FolderExists

Check if a folder exists in a specific open Pack.

Response: { Bool: boolean }

type FolderExistsRequest = { FolderExists: [string, string] };
type FolderExistsResponse = { Bool: boolean };

public class FolderExistsRequest
{
    public Tuple<string, string> FolderExists { get; set; }
}
public class FolderExistsResponse
{
    public bool Bool { get; set; }
}

PackedFileExists

Check if a packed file exists in a specific open Pack.

Response: { Bool: boolean }

type PackedFileExistsRequest = { PackedFileExists: [string, string] };
type PackedFileExistsResponse = { Bool: boolean };

public class PackedFileExistsRequest
{
    public Tuple<string, string> PackedFileExists { get; set; }
}
public class PackedFileExistsResponse
{
    public bool Bool { get; set; }
}

GetPackedFileRawData

Get the raw binary data of a packed file.

Response: { VecU8: number[] }

type GetPackedFileRawDataRequest = { GetPackedFileRawData: [string, string] };
type GetPackedFileRawDataResponse = { VecU8: number[] };

public class GetPackedFileRawDataRequest
{
    public Tuple<string, string> GetPackedFileRawData { get; set; }
}
public class GetPackedFileRawDataResponse
{
    public byte[] VecU8 { get; set; }
}

AddPackedFilesFromPackFile

Copy packed files from one Pack into another.

Response: { VecContainerPath: ContainerPath[] }

type AddPackedFilesFromPackFileRequest = {
  AddPackedFilesFromPackFile: [string, string, ContainerPath[]]
};
type AddPackedFilesFromPackFileResponse = { VecContainerPath: ContainerPath[] };

public class AddPackedFilesFromPackFileRequest
{
    public Tuple<string, string, List<ContainerPath>> AddPackedFilesFromPackFile { get; set; }
}
public class AddPackedFilesFromPackFileResponse
{
    public List<ContainerPath> VecContainerPath { get; set; }
}

AddPackedFilesFromPackFileToAnimpack

Copy packed files from the main Pack into an AnimPack.

Response: { VecContainerPath: ContainerPath[] }

type AddPackedFilesFromPackFileToAnimpackRequest = {
  AddPackedFilesFromPackFileToAnimpack: [string, string, ContainerPath[]]
};
type AddPackedFilesFromPackFileToAnimpackResponse = { VecContainerPath: ContainerPath[] };

public class AddPackedFilesFromPackFileToAnimpackRequest
{
    public Tuple<string, string, List<ContainerPath>> AddPackedFilesFromPackFileToAnimpack { get; set; }
}
public class AddPackedFilesFromPackFileToAnimpackResponse
{
    public List<ContainerPath> VecContainerPath { get; set; }
}

AddPackedFilesFromAnimpack

Copy packed files from an AnimPack into the main Pack.

Response: { VecContainerPath: ContainerPath[] }

type AddPackedFilesFromAnimpackRequest = {
  AddPackedFilesFromAnimpack: [string, DataSource, string, ContainerPath[]]
};
type AddPackedFilesFromAnimpackResponse = { VecContainerPath: ContainerPath[] };

public class AddPackedFilesFromAnimpackRequest
{
    public Tuple<string, string, string, List<ContainerPath>> AddPackedFilesFromAnimpack { get; set; }  // second is DataSource enum
}
public class AddPackedFilesFromAnimpackResponse
{
    public List<ContainerPath> VecContainerPath { get; set; }
}

DeleteFromAnimpack

Delete packed files from an AnimPack.

Response: "Success"

type DeleteFromAnimpackRequest = {
  DeleteFromAnimpack: [string, string, ContainerPath[]]
};
type DeleteFromAnimpackResponse = "Success";

public class DeleteFromAnimpackRequest
{
    public Tuple<string, string, List<ContainerPath>> DeleteFromAnimpack { get; set; }
}
// Response: the literal string "Success".

ImportDependenciesToOpenPackFile

Import files from dependencies into a specific open Pack.

Response: { VecContainerPathVecString: [ContainerPath[], string[]] } — added paths, failed paths.

type ImportDependenciesToOpenPackFileRequest = {
  ImportDependenciesToOpenPackFile: [string, Record<DataSource, ContainerPath[]>]
};
type ImportDependenciesToOpenPackFileResponse = {
  VecContainerPathVecString: [ContainerPath[], string[]]
};

public class ImportDependenciesToOpenPackFileRequest
{
    public Tuple<string, Dictionary<string, List<ContainerPath>>> ImportDependenciesToOpenPackFile { get; set; }
}
public class ImportDependenciesToOpenPackFileResponse
{
    public Tuple<List<ContainerPath>, List<string>> VecContainerPathVecString { get; set; }
}

SavePackedFilesToPackFileAndClean

Save packed files to a specific Pack and optionally run optimizer.

Response: { VecContainerPathVecContainerPath: [ContainerPath[], ContainerPath[]] } — added and deleted paths.

type SavePackedFilesToPackFileAndCleanRequest = {
  SavePackedFilesToPackFileAndClean: [string, RFile[], boolean]
};
type SavePackedFilesToPackFileAndCleanResponse = {
  VecContainerPathVecContainerPath: [ContainerPath[], ContainerPath[]]
};

public class SavePackedFilesToPackFileAndCleanRequest
{
    public Tuple<string, List<RFile>, bool> SavePackedFilesToPackFileAndClean { get; set; }
}
public class SavePackedFilesToPackFileAndCleanResponse
{
    public Tuple<List<ContainerPath>, List<ContainerPath>> VecContainerPathVecContainerPath { get; set; }
}

GetPackedFilesNamesStartingWitPathFromAllSources

Get all file names under a path from all dependency sources.

Response: { HashMapDataSourceHashSetContainerPath: Record<DataSource, ContainerPath[]> }

type GetPackedFilesNamesStartingWitPathFromAllSourcesRequest = {
  GetPackedFilesNamesStartingWitPathFromAllSources: ContainerPath
};
type GetPackedFilesNamesStartingWitPathFromAllSourcesResponse = {
  HashMapDataSourceHashSetContainerPath: Record<DataSource, ContainerPath[]>
};

public class GetPackedFilesNamesStartingWitPathFromAllSourcesRequest
{
    public ContainerPath GetPackedFilesNamesStartingWitPathFromAllSources { get; set; }
}
public class GetPackedFilesNamesStartingWitPathFromAllSourcesResponse
{
    public Dictionary<string, List<ContainerPath>> HashMapDataSourceHashSetContainerPath { get; set; }
}

Dependency Commands

RebuildDependencies

Rebuild the dependencies by combining deps from all open packs.

Response: { DependenciesInfo: DependenciesInfo }

{ "id": 1, "data": { "RebuildDependencies": true } }

type RebuildDependenciesRequest = { RebuildDependencies: boolean };
type RebuildDependenciesResponse = { DependenciesInfo: DependenciesInfo };

public class RebuildDependenciesRequest
{
    public bool RebuildDependencies { get; set; }
}
public class RebuildDependenciesResponse
{
    public DependenciesInfo DependenciesInfo { get; set; }
}

IsThereADependencyDatabase

Check if a dependency database is loaded.

Response: { Bool: boolean }

type IsThereADependencyDatabaseRequest = { IsThereADependencyDatabase: boolean };
type IsThereADependencyDatabaseResponse = { Bool: boolean };

public class IsThereADependencyDatabaseRequest
{
    public bool IsThereADependencyDatabase { get; set; }
}
public class IsThereADependencyDatabaseResponse
{
    public bool Bool { get; set; }
}

GetTableListFromDependencyPackFile

Get all DB table names from dependency Pack files.

Response: { VecString: string[] }

type GetTableListFromDependencyPackFileRequest = "GetTableListFromDependencyPackFile";
type GetTableListFromDependencyPackFileResponse = { VecString: string[] };

// Request: send the literal string "GetTableListFromDependencyPackFile".
public class GetTableListFromDependencyPackFileResponse
{
    public List<string> VecString { get; set; }
}