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.

If RPFM says rpfm_server Not Responding: RPFM’s backend, rpfm_server.exe, took too long to start. This usually means Windows security or your antivirus blocked it, as it’s not signed. Allow rpfm_server.exe (or RPFM’s whole folder) in your security software, then restart RPFM.

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.

Paths inside other Flatpak apps: the Flatpak can’t read the data folders of other Flatpak apps (for example, a game installed through Steam’s Flatpak), even if the file dialog lets you pick them. When one of your configured paths is in one, RPFM shows the command to grant it access (Copy Command). Run it in a terminal with RPFM closed, or set the same paths with Flatseal, then start RPFM again.

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.

Split view

The editor area can show two tab panes side by side. Right-click a file tab and pick Move to Other Pane to send it to the second pane (or back to the first); Merge Panes moves every tab back into a single pane. A pane is only shown while it has tabs open.

Files you open from the Pack tree go to the pane that last had keyboard focus. A file is only ever open in one pane: opening it again focuses its existing tab, wherever it is. Each pane keeps its own preview tab. The split position is remembered between runs.

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.
• Run Script ▸ <script> — run one of your plugin scripts against the selection. The submenu lists every script in your config scripts folder.

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, Lz4Block), 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, Index Is Encrypted and Data Is Encrypted (editable), and Header Is Extended (read-only). The encryption flags are applied the next time the Pack is saved, and are only available for PFH4 and newer Packs (Rome 2 and later games); older formats can’t be encrypted. The optimiser’s Encrypt the Pack option sets both flags for you (see Optimising a mod).

Compression Format

A submenu listing the supported compression formats: None, Lzma1, Lz4, Zstd, Lz4Block. Which formats actually work depends on the active game and the Pack version (Lz4Block is only for Shogun 2 Complete Edition PFH3 Packs, the rest only for PFH5 and newer Packs). 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.

Plugin scripts

Experimental. Plugin scripts are a new, experimental feature. The way scripts are invoked and how data is handed to them may still change in future versions.

Plugin scripts let you run your own Python or Lua scripts against the files you have selected in the Pack tree. They’re meant for bulk, repetitive edits that would be tedious to do by hand — prefixing every Loc entry, rewriting a column across many tables, batch-renaming references, and so on.

Installing a script

Drop a .py (Python) or .lua (Lua) file into the scripts folder inside RPFM’s config folder. RPFM creates the folder for you the first time it’s needed; you can also reach the config folder quickly via Game Selected → Open RPFM’s Config Folder.

The interpreter is chosen from the file extension, so python (for .py) or lua (for .lua) must be available on your system PATH. The bundled Lua examples run on Lua 5.1 through 5.4.

You’ll find ready-to-use examples in the examples/plugin_scripts/ folder of the RPFM repository.

Running a script

1. Select one or more files/folders in the Pack tree.
2. Right-click and open the Run Script submenu. It lists every script currently in your scripts folder (or No scripts found if the folder is empty).
3. Pick a script. RPFM runs it and reads the results back into the Pack.

How a script is run

1. The files you selected are extracted to a temporary folder that mirrors their in-Pack layout:
   • DB and Loc tables are written as TSV (tab-separated, quoting disabled), exactly like the normal Extract action.
   • Everything else is written as raw binary.
2. Your script is launched with the extracted file paths as arguments (python <script> <paths...> or lua <script> <paths...>).
3. When the script finishes, RPFM reads the (possibly modified) files back into the Pack. Open views of changed files are reloaded and the Pack is marked as modified.

Files the script deletes are left untouched in the Pack, and files it creates anew are ignored — only the originally-selected files are read back.

The TSV format

When a script receives a DB table or Loc file, it gets a TSV with two header rows before the data:

key<TAB>text<TAB>tooltip          <- column names
#Loc;1;text/db/mymod.loc<TAB><TAB> <- metadata: #table_type;version;path
mymod_key1<TAB>Hello world<TAB>false

Rows are \r\n-terminated and values are never quoted (so they can’t contain tabs or newlines). Keep the two header rows intact when editing, or RPFM won’t be able to read the table back.

Debugging

Every run writes the script’s output to last_run.log inside the scripts folder (overwritten each run). It contains the script path, exit status, and the full stdout/stderr. If a script exits with a non-zero status, RPFM also shows its stderr in a dialog. The same output is logged to the RPFM Server terminal.

Lua tests

Experimental. Lua tests are new, and the way they emulate the game may still change in future versions.

Lua tests let you check what your mod’s scripts do without starting the game. RPFM runs your scripts together with the game’s own script libraries, fakes the game around them, and tells you whether they did what you expected.

Lua tests need the game’s Assembly Kit, as RPFM uses its scripting docs to know what the game’s functions return. Only campaign scripts are supported for now.

Writing a test file

A test file is a .lua file that describes the situation to test, and what your scripts should do in it. Keep test files outside script/, for example in a tests/ folder of your Pack, so the game never loads them:

-- Code outside tests runs before the game starts: set up the factions and regions your scripts need.
local kislev = rpfm.faction { key = "wh3_main_ksl_kislev", is_human = true }
local empire = rpfm.faction { key = "wh_main_emp_empire", is_human = false }

rpfm.test("gives gold to Kislev at the start of its turn", function()
    rpfm.fire("FactionTurnStart", { faction = kislev })
    rpfm.assert_called("treasury_mod", "wh3_main_ksl_kislev", 500)
end)

rpfm.test("doesn't give gold to AI factions", function()
    rpfm.fire("FactionTurnStart", { faction = empire })
    rpfm.assert_not_called("treasury_mod")
end)

This tests a mod script like this one, in script/campaign/mod/kislev_gold.lua:

core:add_listener(
    "kislev_gold",
    "FactionTurnStart",
    function(context) return context:faction():name() == "wh3_main_ksl_kislev" and context:faction():is_human() end,
    function(context) cm:treasury_mod(context:faction():name(), 500) end,
    true
)

How a test runs

Every test gets its own, fresh game. For each one, RPFM:

1. Runs the top-level code of the test file, creating the factions, regions and characters it sets up.
2. Loads the game’s script libraries, then the mods of your open Packs (script/campaign/mod/), like the game does.
3. Triggers NewSession, WorldCreated, UICreated and FirstTickAfterWorldCreated, so your mods’ listeners are registered and their first-tick code has run.
4. Runs the test’s function.

Nothing done by a test is left behind for the next one: globals, listeners, timers and recorded calls all start from scratch.

The test API

Setting up the world

Fields can be plain values, other objects, or functions called with the arguments of each call. Methods returning lists, like region_list or character_list, can be given plain arrays: they’re turned into the list the game would return, with num_items, is_empty and item_at.

local kiev = rpfm.region { key = "wh3_main_combi_region_kislev", is_province_capital = true }
local katarin = rpfm.character { character_subtype_key = "wh3_main_ksl_katarin", rank = 10 }

local kislev = rpfm.faction {
    key = "wh3_main_ksl_kislev",
    is_human = true,
    treasury = 2000,
    region_list = { kiev },
    character_list = { katarin },

    -- Called with the arguments the script passed.
    has_effect_bundle = function(bundle) return bundle == "my_bundle" end,
}

rpfm.mock(kiev, "owning_faction", kislev)
rpfm.mock(katarin, "faction", kislev)

Factions and regions from the game’s database exist even if your test doesn’t create them, so scripts looking them up by key, like with cm:get_faction, find them. Anything a test doesn’t set up returns a neutral value of the type the scripting docs say, like false, 0, an empty string, or a null object.

Making things happen

rpfm.end_turn() also moves the turn number forward, and triggers these events, in this order:

1. WorldStartRound.
2. FactionRoundStart, for every faction.
3. For each faction: FactionTurnStart, RegionTurnStart for each of its regions, CharacterTurnStart for each of its characters, FactionBeginTurnPhaseNormal, FactionAboutToEndTurn, CharacterTurnEnd for each character, RegionTurnEnd for each region, and FactionTurnEnd.

Only the regions and characters given to the faction’s region_list and character_list get their events.

Checking the results

rpfm.assert_called only checks the arguments you give it, so rpfm.assert_called("treasury_mod", "wh3_main_ksl_kislev") passes whatever the amount was. When it fails, it lists the calls that were made instead:

expected a call to treasury_mod("wh3_main_ksl_kislev", 500), got treasury_mod("wh3_main_ksl_kislev", 250)

Your scripts’ own globals are there too, so tests can inspect and change them directly, like enabling a single feature of your mod before checking it. Any other Lua error in a test, like one from error() or assert(), fails it too.

Examples

Timers

Scripts using cm:callback or cm:repeat_callback only run their callbacks when game time moves forward:

-- The mod: warns the player 10 seconds after the campaign starts, and every 30 seconds after that.
my_mod_warnings = 0

cm:add_first_tick_callback(function()
    cm:callback(function() my_mod_warnings = my_mod_warnings + 1 end, 10)
    cm:repeat_callback(function() my_mod_warnings = my_mod_warnings + 1 end, 30, "my_mod_reminder")
end)

-- The test.
rpfm.test("warns after 10 seconds, then every 30", function()
    rpfm.advance_time(5)
    rpfm.assert_equal(my_mod_warnings, 0, "after 5 seconds")

    rpfm.advance_time(5)
    rpfm.assert_equal(my_mod_warnings, 1, "after 10 seconds")

    rpfm.advance_time(80)
    rpfm.assert_equal(my_mod_warnings, 4, "after 90 seconds")
end)

For timers reported through events, rpfm.advance_time triggers TimeTrigger with the timer’s id in context.string, like the game does.

Several turns

local kislev = rpfm.faction { key = "wh3_main_ksl_kislev", is_human = true }

rpfm.test("pays every turn, for three turns", function()
    rpfm.end_turn()
    rpfm.end_turn()
    rpfm.end_turn()

    rpfm.assert_equal(#rpfm.calls_to("treasury_mod"), 3)
    rpfm.assert_equal(cm:model():turn_number(), 4)
end)

Changing the world during a test

rpfm.mock can be used inside a test, to change the world between events. Here, a mod that should only reward a faction once it owns a region:

local kislev = rpfm.faction { key = "wh3_main_ksl_kislev", is_human = true }
local kiev = rpfm.region { key = "wh3_main_combi_region_kislev" }

rpfm.test("rewards Kislev once it owns Kislev", function()
    rpfm.fire("FactionTurnStart", { faction = kislev })
    rpfm.assert_not_called("apply_effect_bundle")

    rpfm.mock(kiev, "owning_faction", kislev)
    rpfm.mock(kislev, "region_list", { kiev })

    rpfm.fire("FactionTurnStart", { faction = kislev })
    rpfm.assert_called("apply_effect_bundle", "my_reward_bundle", "wh3_main_ksl_kislev")
end)

Checking the calls yourself

rpfm.calls_to gives you every call, for checks the assertions can’t do, like the order or the number of calls:

local kislev = rpfm.faction { key = "wh3_main_ksl_kislev", is_human = true }
local ungol = rpfm.faction { key = "wh3_main_ksl_ungol", is_human = true }

rpfm.test("pays every human faction once per round, in turn order", function()
    rpfm.end_turn()

    local payments = rpfm.calls_to("treasury_mod")
    rpfm.assert_equal(#payments, 2, "number of payments")

    -- Each entry has the arguments of a call, in order.
    rpfm.assert_equal(payments[1][1], "wh3_main_ksl_kislev")
    rpfm.assert_equal(payments[2][1], "wh3_main_ksl_ungol")
end)

Calls are recorded when they reach the game, so library functions like cm:treasury_mod show up under the name of the game function they end up calling, which is usually the same.

UI events

UI events, like clicks, carry the name of the component in context.string, which can be set like any other accessor:

rpfm.test("clicking my button opens my panel", function()
    rpfm.fire("ComponentLClickUp", { string = "my_mod_button" })
    rpfm.assert_equal(my_mod.panel_open, true)
end)

Testing a single feature

As tests see your scripts’ globals, they can reach inside your mod, like to change its settings or call its functions directly:

rpfm.test("the difficulty setting doubles the gold", function()
    my_mod.settings.difficulty = "hard"
    my_mod.pay_faction(kislev)
    rpfm.assert_called("treasury_mod", "wh3_main_ksl_kislev", 1000)
end)

Running tests

Select one or more test files in the Pack tree, right-click them and choose Run Lua Tests. The results window lists every test, with:

• Errors: why it failed. Tests also fail when one of your scripts errors while the test runs, or while the game starts.
• Undocumented calls: game functions your scripts called that the scripting docs don’t describe. They return placeholder values, so a test depending on them may not match the game.
• Output: everything the scripts printed, with print or out. For long runs, only the latest lines are kept.

Errors of the game’s own scripts while starting are listed separately, and never fail your tests: they usually mean the fake game lacks something those scripts need.

Tests can also be run from tools and AI agents connected to the server, through the LuaRunTests command or the lua_run_tests MCP tool. These can also load the vanilla scripts of a campaign, like main_warhammer, by passing its name. That’s closer to the game, but slower, and more likely to hit parts of the game the harness doesn’t fake. Running tests from the Pack tree only loads the script libraries and your mods.

Limitations

The game is faked, not run, so keep in mind that:

• Only what your tests set up exists, besides the factions and regions of the game’s database. Armies don’t move, battles don’t happen, and methods like treasury_mod are recorded but don’t change what treasury returns, unless your test mocks it.
• Methods the scripting docs don’t have return placeholder values, and are listed under Undocumented calls. Asking a documented object for a method it doesn’t have returns nil, like in the game.
• Scripts can’t run programs, load DLLs, or touch your files. Files they write are kept in memory, and can be read back during the same test.
• string.len, string.sub and string.find count characters instead of bytes, and string.find doesn’t use patterns, like in the game. The original versions are available as string.len_lua, string.sub_lua and string.find_lua.
• Scripts running for too long, like when stuck in a loop, are stopped, failing the test.

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.
• Split view. Tabs can be moved to a second pane to see two files side by side. See Split view.
• 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.

Lua scripts

When a diagnostics check runs, its results for the open script are shown in the editor itself, like in an IDE: the offending code is underlined, and its line gets a mark in the margin. See Diagnostics for the checks performed.

Hovering a documented function, accessor or event in a Lua script shows its docs. Both features rely on the scripting docs of the game’s Assembly Kit, completed with the vanilla scripts from the dependencies cache, so they need the Assembly Kit path set and the cache generated. To run a mod’s scripts outside the game, see Lua tests.

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 templates the AI (and multiple-selection drag-outs) use to deploy armies. Supported for Shogun 2, Rome 2, Attila, Thrones of Britannia, Troy, Pharaoh, Three Kingdoms and Warhammer 3.

Each formation is a set of blocks:

• Absolute blocks sit at a fixed position. Every formation needs at least one, as it anchors the rest.
• Relative blocks sit at an offset from another block, their parent.
• Spans group other blocks, so relative blocks can be positioned from the whole group.

The editor has three columns:

• Formations: the list of formations, with add, clone and delete. Formations with issues get an error or warning icon.
• Canvas and blocks tree: the canvas draws a simulated deployment of the selected formation over a grid in meters, with the front at the top. The tree below shows each block under its parent. Selection is shared between both.
  • Drag blocks to move them. Their offsets snap to the grid step set above the canvas. Dragging a span moves all its members.
  • Shift+drag from a block to another to make the second one its parent.
  • Drag on empty space to select several blocks, and right-click for the block actions (add, add span over the selection, delete, delete with children).
  • Units per Block changes how many units the simulation assumes, so you can check how the formation stretches.
• Inspector: the properties of the selected formation, container or span, including AI purposes, unit category requirements, supported subcultures and factions (picked from the ones in the game and the open Packs), and each block’s entity preferences.

Files opened from the game or from dependencies are read-only. Edits can be undone with Ctrl+Z. Deleting a block re-attaches its children to the closest surviving ancestor, keeping them in place. Issues like missing references or blocks depending on each other in a loop are reported in the Diagnostics panel.

The simulated layout assumes a relative block’s offset is a gap measured from its parent’s edge, and that a zero offset centers it on the parent. This hasn’t been confirmed in-game yet, so the canvas may not match the game exactly.

If you need the raw data, enable Use Debug View for Group Formations in the settings to open these files as JSON instead.

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. Newly opened Packs are ticked automatically, unless Auto-select Open Packs in Global Search is disabled in the settings.
• 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

Click a column header to sort the results by that column (severity, file, type, etc.), so you can group everything of one kind together or push all the errors to the top.

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 (src) — the original (typically English) text.
• Translation (dst) — your translated text.
• Needs retranslation (retr) — boolean. Set when the source text changed since the translation was last saved (the “outdated” state).
• Removed (rem) — 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.
• Auto-translated (aut) — boolean. Set when the Translator filled the row automatically (from vanilla loc data or a translation service) and the user hasn’t reviewed it yet. Editing the translation clears the flag.

The JSON file also records its format version. 0 is the legacy format (compatible with older Translation Hub tooling); 1 is the current format, which adds the aut flag, the source language (src_lang), the list of authors (typed comma-separated in the Authors field) and the glossary. It’s selectable from the translator UI for English sources, and new translations default to 1. Switching it rewrites the file in the chosen format on the next save.

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. AI translations are told which game the mod is for, and to prefer the game’s official translations for its terms and names. The batch button in the toolbar auto-translates every outdated line at once with DeepL, AI or Google Translate. By default it only fills lines with no translation; lines with an outdated translation are left for you to fix, unless Overwrite existing outdated translations is checked in its menu. Batch results are marked as auto-translated so you can review them. A progress dialog shows how far along it is and lets you cancel it. Requests are spaced out, and when a service rate-limits them RPFM slows down and retries. DeepL gets up to 50 lines per request, so it needs far fewer requests; if one of those requests fails, all its lines are reported as failed. At the end, a results dialog shows how many lines were translated, failed, or were left unprocessed, with the failed lines and their errors in its details.
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>/<SOURCE>-<LANGUAGE>.json (or <LANGUAGE>.json for format 0). This is the file you contribute to the Translation Hub.

Editing a line

Clear translation resets the selected line to untranslated. It has a configurable shortcut, unbound by default.

To keep the editor compact, the quick start instructions, the auto-translation settings (the ones applied when a line is selected) and the formatted in-game style previews of the source and translated text are hidden by default. Show them with the Help, Auto-translate settings and Preview toggles.

Glossary

The glossary is a per-translation list of source terms and the translation you want used for each one, like faction or unit names. Open it with the Glossary button: it opens over the right side of the translator, so the lines stay visible for reference, and its close button hides it again. Edit it like any other table, with its toolbar, right-click menu or shortcuts. Entries without a source term are ignored.

When auto-translating, the glossary is used like this:

• DeepL: with the Use a DeepL glossary toolbar button enabled (the default), RPFM stores the glossary in your DeepL account and DeepL enforces its terms. There’s one per Pack and language pair, named RPFM <game>/<pack> <source>-<target> <fingerprint>; it’s reused while the glossary doesn’t change, and replaced when it does. Entries without a translation are left out of it. If it can’t be stored, or the button is disabled, the glossary is sent as a hint instead.
• AI: the glossary is included in the prompt, as a hint.
• Google Translate: doesn’t support it.

Review glossary terms in hint-based results, as the service may not always follow them.

The glossary is saved with the translation, and only format 1 can store it. With format 0 the Glossary button is disabled.

Translating from a language other than English

When opening the Translator, you pick the language the mod is written in. The last one you picked is preselected.

The Translation Hub only ships vanilla texts in English. For any other source language, RPFM extracts them from the game’s own local_<language> packs the first time you pick that language. It saves them to <config>/translations_local/<game>/vanilla_<language>.tsv, so they stay available after the game no longer has that language installed.

Many games only install the language they’re set to. If the source language isn’t installed, the Translator warns you that vanilla lines won’t be auto-translated. To get those texts:

1. Change the game’s language to the source language in Steam (Properties → General → Language) and let Steam download it.
2. Open the Translator with that language as source. RPFM saves its vanilla texts and tells you when it’s done.
3. Switch the game back to your language, and open the Translator again.

Sharing through the Translation Hub

Once you’ve finished a translation, click Submit to the Translation Hub in the translator:

1. RPFM saves the translation, and shows a summary: the pack, the languages, how many lines are translated, and warnings about lines still pending or auto-translated and not reviewed. Fill in the authors there if you haven’t, so you get credited, and click Submit.
2. The first time, RPFM asks you to sign in with GitHub. It opens GitHub in your browser and copies a code to your clipboard: paste it there and approve RPFM. You only need to do this once. RPFM keeps the sign-in in your system’s keyring, and you can sign out from Settings > GitHub.
3. RPFM opens a pull request on the Translation Hub with your translation, through your own fork of it, which it creates the first time. If you submit the same translation again while its pull request is open, the pull request is updated instead.
4. Once the pull request is 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>/<SOURCE>-<LANGUAGE>.json (or <LANGUAGE>.json for format 0). This is the file you share.

Sharing a translation

Click Submit to the Translation Hub in the translator. RPFM saves the translation, shows you a summary to confirm, and opens a pull request on the Total War Translation Hub with it. The first time, it asks you to sign in with GitHub. See the Translator’s docs for the details.

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, Encrypt the Pack (turns on index and data encryption; disabled for games whose Packs predate PFH4).
• 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 JSON-RPC over WebSocket, 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).
• 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 Methods.

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 JSON-RPC requests and matches their responses by ID. See WebSocket protocol.
• MCP — for AI agents and other clients that already speak MCP. The server exposes most methods as tools, plus prompts and resources. See MCP interface.

Under the hood both pathways use the same Session abstraction. Each WebSocket connection gets its own isolated session with its own open Packs and dependency cache, and can reattach to it by passing its previous session_id back on the handshake. All MCP clients share one session, separate from the WebSocket ones. A WebSocket client and an MCP client 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 its last WebSocket session is gone, with no other session left. A server only used by MCP clients keeps running until stopped.

Where to next

• Sessions & connection lifecycle — what happens on connect, disconnect, reconnect.
• WebSocket protocol — message envelope, errors, jobs and conventions.
• Methods — every method of the API.
• MCP interface — what tools the MCP endpoint exposes.
• Client example — a concrete TypeScript / C# client implementation.

Sessions & connection lifecycle

Each WebSocket connection lives inside a session, and all MCP clients share one more. A session owns a dedicated background thread that runs its requests serially against its in-memory state (open Packs, dependency cache, settings).

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

Lifecycle

1. Connect. A client opens /ws without a session ID. The server allocates a new SessionId, spins up a background thread, and immediately sends a session.connected notification so the client can stash the ID for later reconnection.

   { "jsonrpc": "2.0", "method": "session.connected", "params": { "session_id": 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).

3. Disconnect. When the WebSocket drops without a session.disconnect request, 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. Call session.disconnect before closing your socket and the session is removed immediately, telemetry is flushed, and the background thread exits.

   { "jsonrpc": "2.0", "id": 99, "method": "session.disconnect" }
   

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

The MCP session

MCP clients have no disconnect signal the server can rely on, and newer MCP versions have no sessions at all, so all MCP clients share one session. It’s created by the first tool call, and removed after 5 minutes without tool calls, unless it has open packs or unfinished jobs. The next tool call creates a new one. Removing it never stops the server, so a server started by hand for MCP clients keeps running.

Autosaves

Every session autosaves its packs on its own, every autosave_interval minutes of its settings (0 disables them), keeping the newest autosave_amount autosaves of each pack. Only the packs changed since their last autosave or save are autosaved, and they’re written in the background, so requests don’t wait for them. Packs with autosaves disabled in their settings, and packs that aren’t mods or movies, are never autosaved. When the autosave folder grows past 25 GB, the server logs a warning.

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 (msg.method === "session.connected") {
    sessionId = msg.params.session_id;
    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 session.connected notification 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.
• Settings: sessions start with the ones in RPFM’s settings.json, and clients can replace them with session.configure.
• Jobs and their results.

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

WebSocket protocol

The /ws endpoint speaks JSON-RPC 2.0: every WebSocket text frame is one JSON-RPC request from the client, or one response or notification from the server. The methods themselves are listed in Methods.

Connecting

Open a WebSocket to ws://127.0.0.1:45127/ws. To reattach to an existing session, pass its ID: ws://127.0.0.1:45127/ws?session_id=12345 (see Sessions).

Right after connecting, the server sends a session.connected notification with the ID of your session:

{ "jsonrpc": "2.0", "method": "session.connected", "params": { "session_id": 12345 } }

Store it if you want to reconnect to the same session later.

Requests and responses

A request names a method and passes its params as an object:

{ "jsonrpc": "2.0", "id": 7, "method": "table.rows", "params": { "file": { "source": { "pack": "0b4c5a62-7d3e-4f1a-9c2b-8e6d5f4a3b21" }, "path": "db/units_tables/my_units" }, "limit": 2 } }

The response carries the same id, and either a result or an error:

{ "jsonrpc": "2.0", "id": 7, "result": { "columns": ["key", "..."], "rows": [ ... ], "total": 51 } }

Use a different id for each request: responses arrive in the order requests finish, not the order they were sent. Requests of the same session still run in the order they arrived, one at a time, so a pack.save sent before a pack.close always saves the pack before closing it.

Methods without params can omit params.

Errors

Failed requests get an error with a code, a message, and a data object with the kind of error, so clients can match on it without parsing the message:

{ "jsonrpc": "2.0", "id": 8, "error": { "code": -32001, "message": "Pack not found: nope.pack", "data": { "kind": "pack_not_found", "details": "nope.pack" } } }

Jobs

Methods that can take a long time (selecting a game, generating the dependencies cache, diagnostics, search, schema updates, the optimizer, Lua tests) run as jobs. They answer right away with the ID of their job:

{ "jsonrpc": "2.0", "id": 9, "result": { "job": 3 } }

The job then runs in order with the other requests of the session, and every change of its state is sent as a job.updated notification:

{ "jsonrpc": "2.0", "method": "job.updated", "params": { "job": 3, "method": "session.set_game", "state": "running", "stage": "Loading the schema and the dependencies" } }
{ "jsonrpc": "2.0", "method": "job.updated", "params": { "job": 3, "method": "session.set_game", "state": "finished", "result": { ... } } }

A job is queued, running (with an optional stage, and an optional progress from 0 to 100), finished (with the result of its method), failed (with its error) or cancelled. Instead of following the notifications, you can also call job.wait, which answers when the job ends or after a timeout, or job.status. Queued jobs can be cancelled with job.cancel; running ones can’t.

Diagnostics checks (diagnostics.run) don’t make other requests wait: a running check stops when another request arrives, and goes back to the queue behind it. A new check replaces the previous one if it hasn’t ended, which ends cancelled, and also checks what the replaced one would have checked. Follow the job of the last check you started to get its results.

Conventions

• Pack keys. Open packs are identified by the key that pack.open, pack.new and session.status return: a UUID, like 0b4c5a62-7d3e-4f1a-9c2b-8e6d5f4a3b21. Keys never change while a pack is open, even when it’s saved under another name, and aren’t reused. A pack’s name is its file name, and its path is only set if it’s saved on disk. A method’s pack param is always the open pack it works on or changes. Where it’s optional, like in lookups and lists, setting it limits the method to that pack.
• Sources. Files are found in a source: { "pack": "<key>" } for an open pack, or "game_files", "parent_files" or "assembly_kit" for the dependencies. A file is a { "source": ..., "path": ... } pair.
• Reading and writing. Methods reading files take a source or a file, so they can read from anywhere. Methods changing files take a pack and a path, as only the files of open packs can change.
• Paths. Paths inside packs use /. Where a method takes files or folders, a path is a file if one exists with that path, and a folder otherwise. Filters by path are called path_prefix. Paths on disk have names saying what they are, like destination or tsv_path.
• Table names. Tables are named by their full name, like units_tables, in params (table_name) and in results, including the references between columns.
• Pagination. Lists take an offset and an optional limit, and include the total amount of items, so you never get more than you asked for.
• Settings. Sessions start with the settings in RPFM’s settings.json. Clients with their own settings, like the UI, send them with session.configure.

A complete round-trip

const ws = new WebSocket("ws://127.0.0.1:45127/ws");
let nextId = 1;
const pending = new Map<number, (message: any) => void>();

function call(method: string, params?: object): Promise<any> {
  const id = nextId++;
  ws.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
  return new Promise((resolve, reject) => pending.set(id, (message) => message.error ? reject(message.error) : resolve(message.result)));
}

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if ("id" in message) {
    pending.get(message.id)?.(message);
    pending.delete(message.id);
  } else if (message.method === "session.connected") {
    console.log("session", message.params.session_id);
  }
};

ws.onopen = async () => {
  const pack = await call("pack.open", { paths: ["/path/to/my_mod.pack"] });
  const files = await call("files.list", { source: { pack: pack.key }, path_prefix: "db/", limit: 20 });
  console.log(files.total, files.files);
};

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

var request = JsonSerializer.Serialize(new {
    jsonrpc = "2.0",
    id = 1,
    method = "pack.open",
    @params = new { paths = new[] { "/path/to/my_mod.pack" } },
});

await ws.SendAsync(Encoding.UTF8.GetBytes(request), WebSocketMessageType.Text, true, CancellationToken.None);

// Read messages until the one with "id": 1 arrives. The first one is the session.connected notification.

Disconnecting cleanly

Call session.disconnect before closing the socket. The server removes your session right away instead of keeping it for 5 minutes, and exits if it was the last one:

{ "jsonrpc": "2.0", "id": 99, "method": "session.disconnect" }

What’s next

• Methods — every method, with its request and response types.
• Sessions — reconnection and session lifetime.
• Client example — a complete client with typed helpers.

Methods

Every method of the API, grouped by domain. Each domain’s page lists the params and the result of its methods, generated from the request and response structs of rpfm_ipc::api. Methods marked as jobs answer right away with a job ID, and send their result when the job ends (see Jobs).

Methods meant for clients with their own views of the files, like the UI, return RPFM’s own types (decoded files, typed search matches, full diagnostics), shown as any in their pages. Simpler clients should prefer the paginated methods next to them, like table.rows, search.matches or diagnostics.list.

Session and dependencies

Packs

Files

Tables

Schema

References

Diagnostics

Search

Notes

Tools

Translations

GitHub

Updates

Jobs

Session and dependencies

Methods about the state of the session.

session.status

Returns the selected game, what’s loaded for it, and the open packs.

Params (GetSessionStatus)

Empty object: {}.

Result (SessionStatus)

session.configure

Replaces the settings the session runs with.

Sessions start with the settings in the settings file. Clients owning their own settings send them with this before anything else, and again whenever they change.

Params (Configure)

Result (Done)

Empty object: {}.

session.disconnect

Tells the server the client is closing, so its WebSocket session is removed right away instead of waiting for the timeout. Only for WebSocket clients.

Params (Disconnect)

Empty object: {}.

Result (Done)

Empty object: {}.

session.set_game

Selects a game, loading its schema and, optionally, its dependencies.

Runs as a job: answers right away with a job ID, and sends its result when the job ends (see Jobs).

Params (SetGame)

Result (SessionStatus)

dependencies.generate_cache

Generates the dependencies cache of the selected game from its files and Assembly Kit, and loads it.

Runs as a job: answers right away with a job ID, and sends its result when the job ends (see Jobs).

Params (GenerateDependenciesCache)

Result (SessionStatus)

dependencies.rebuild

Reloads the dependencies of the selected game, like after changing the packs the open packs depend on.

Runs as a job: answers right away with a job ID, and sends its result when the job ends (see Jobs).

Params (RebuildDependencies)

Result (SessionStatus)

dependencies.tables

Returns the tables of the game files, and the startpos, twad and CEO tables of the schema, with their version.

Params (ListDependencyTables)

Empty object: {}.

Result (DependencyTables)

dependencies.info

Returns the files of the dependencies of the selected game.

Meant for clients showing the dependencies as a tree. Others should use files.list.

Params (GetDependenciesInfo)

Empty object: {}.

Result (DependenciesInfo)

One of RPFM’s own types, without a schema. See its docs in rpfm_lib or rpfm_extensions.

dependencies.table_data

Returns every decoded table of a type in the game files and the parent packs.

Meant for clients comparing whole tables. Others should use table.rows.

Params (GetDependencyTableData)

Result (DependencyTableData)

Types

Type DependenciesStatus

What’s loaded of the dependencies of the selected game.

Type PackSummary

Short description of an open pack.

Packs

Methods about the open packs.

pack.info

Returns the details of an open pack.

Params (GetPackInfo)

Result (PackDetails)

pack.new

Creates a new empty pack. It has no path on disk until it’s saved with a path.

Params (NewPack)

Result (PackSummary)

pack.open

Opens one or more packs from disk, merged into a single one.

Params (OpenPack)

Result (PackSummary)

pack.open_vanilla

Opens all the vanilla packs of the selected game, merged into a single one.

Params (OpenVanillaPacks)

Empty object: {}.

Result (PackSummary)

pack.close

Closes an open pack, discarding unsaved changes.

Params (ClosePack)

Result (Done)

Empty object: {}.

pack.close_all

Closes all open packs, discarding unsaved changes.

Params (CloseAllPacks)

Empty object: {}.

Result (Done)

Empty object: {}.

pack.save

Saves an open pack to disk.

Params (SavePack)

Result (PackSummary)

pack.update

Changes properties of an open pack. Only the fields set are changed.

Params (UpdatePack)

Result (PackDetails)

pack.settings

Returns the settings of an open pack.

Params (GetPackSettings)

Result (PackSettingsValues)

pack.update_settings

Changes settings of an open pack. Only the keys set are changed.

Params (UpdatePackSettings)

Result (PackSettingsValues)

Types

Type PackDependency

A pack another pack depends on.

Type PackSettingsValues

Settings of a pack, by type of value and key, like diagnostics_files_to_ignore or disable_autosaves.

Files

Methods about the files of the open packs and the dependencies.

files.list

Lists the files of a source, sorted by path.

Params (ListFiles)

Result (FileList)

files.create

Creates a new empty file in an open pack.

Params (CreateFile)

Result (FileEntry)

files.add_from_disk

Adds files and folders from disk to an open pack.

Params (AddFilesFromDisk)

Result (FilesAdded)

files.copy

Copies files and folders from any source into an open pack, keeping their paths.

Params (CopyFiles)

Result (FilesAdded)

files.delete

Deletes files and folders from an open pack.

Params (DeleteFiles)

Result (FilesDeleted)

files.rename

Renames or moves files and folders of an open pack.

Params (RenameFiles)

Result (FilesRenamed)

files.duplicate

Copies files of an open pack in the same pack, adding a number to their names.

Params (DuplicateFiles)

Result (FilesAdded)

files.extract

Extracts files and folders of an open pack, the game files or the parent packs to disk.

Params (ExtractFiles)

Result (FilesExtracted)

file.read

Returns the contents of a file of any source.

Params (ReadFile)

Result (FileContents)

file.write

Replaces the contents of a file of an open pack.

Params (WriteFile)

Result (Done)

Empty object: {}.

animpack.list

Lists the files inside an AnimPack of any source.

Params (ListAnimPack)

Result (FileList)

animpack.add

Copies files of an open pack into an AnimPack of an open pack.

Params (AddToAnimPack)

Result (FilesAdded)

animpack.extract

Copies files of an AnimPack of any source into an open pack.

Params (ExtractFromAnimPack)

Result (FilesAdded)

animpack.delete

Deletes files from an AnimPack of an open pack.

Params (DeleteFromAnimPack)

Result (Done)

Empty object: {}.

file.view_data

Returns a file decoded as a client opening it in a view needs it.

Meant for clients with views for each type of file. Others should use file.read.

Params (GetViewData)

Result (ViewData)

One of:

• { "Decoded": … }: The decoded file, and its info.
  • Decoded ([any, any], yes)
• { "AnimPack": … }: The info of the files of an AnimPack, and of the AnimPack itself.
  • AnimPack ([any, any], yes)
• { "Video": … }: The info of a video, without its frames, and of the file.
  • Video ([any, any], yes)
• { "Notes": … }: The notes of a pack, as markdown.
  • Notes (any, yes)
• "Unsupported": The file is of a type that is not decoded.

files.info

Returns the info of files of an open pack, like their original pack and last modification time.

Meant for clients showing the files of a pack as a tree. Others should use files.list.

Params (GetFilesInfo)

Result (FilesInfo)

files.paste

Copies or moves files and folders of open packs into a folder of an open pack.

Each selected file or folder is pasted with its own name under the destination folder, not with its full path. Meant for clients with a clipboard. Others should use files.copy and files.rename.

Params (PasteFiles)

Result (FilesPasted)

files.from_all_sources

Returns files and folders found in the open packs, the parent packs and the game files.

Meant for clients editing files of several sources at once, like the UI’s tools. Others should use file.read.

Params (GetFilesFromAllSources)

Result (FilesFromAllSources)

files.save_files

Adds files to an open pack, replacing the ones with the same path, optionally optimizing the pack after it.

Meant for clients editing files outside of the server, like the UI’s tools. Others should use file.write.

Params (SaveFiles)

Result (FilesChanged)

file.open_external

Extracts a file of an open pack to a temporary folder, and opens it in the system’s default program for its type.

Params (OpenInExternalProgram)

Result (ExternalFile)

file.save_external

Replaces a file of an open pack with the file on disk an external program edited.

Params (SaveExternalFile)

Result (Done)

Empty object: {}.

Types

Type FileData

Contents of a file.

One of:

• { "kind": "text", "text": … }: The text of a text file.
  • text (string, yes): The text.
• { "kind": "decoded", "data": … }: The decoded file, as JSON, in the format file.read returns it.
  • data (any, yes): The decoded file.
• { "kind": "raw", "base64": … }: The bytes of the file.
  • base64 (string, yes): The bytes, encoded in base64.

Type FileEntry

A file in a listing.

Type FileRef

A file in one of the sources.

Type FileRename

A rename of a file or folder.

Type FileSource

Where a file is.

One of:

• { "pack": … }: An open pack, by key.
  • pack (string, yes)
• "game_files": The vanilla files of the selected game.
• "parent_files": The files of the parent packs of the open packs.
• "assembly_kit": The tables of the selected game’s Assembly Kit. Their paths are db/<table_name>/ak_data.

Type NewFileKind

Type of a new file.

One of:

• { "type": "db", "table_name": …, "version"?: … }: An empty DB table.
  • table_name (string, yes): Name of the table, like units_tables.
  • version (integer or null, no): Version of the table. If not set, the version the table has in the game files is used, or the newest one if the game files are not loaded or don’t have the table.
• { "type": "loc" }: An empty Loc table.
• { "type": "text", "format"?: … }: An empty text file.
  • format (string or null, no): Format of the text, like Plain, Lua, Xml or Json. Defaults to Plain.
• { "type": "anim_pack" }: An empty AnimPack.
• { "type": "portrait_settings", "version": …, "copy_entries"?: … }: A portrait settings file, optionally with entries copied from the vanilla ones.
  • version (integer, yes): Version of the file format.
  • copy_entries (array of EntryCopy, no, default []): Vanilla entries to copy into the new file, with the ID each copy gets.
• { "type": "vmd" }: An empty VMD (variant mesh definition) file.
• { "type": "ws_model" }: An empty WSModel file.

Type EntryCopy

An entry copied from a vanilla file, with a new ID.

Type ReadFormat

How to return the contents of a file.

One of:

• "decoded": The decoded file, as JSON. For DB and Loc tables, table.rows returns only the rows you need, and for images and other binary files raw is smaller.
• "text": The text, for text files like scripts, XML or JSON files.
• "raw": The bytes of the file, encoded in base64.

Tables

Methods to read DB and Loc tables, and their definitions.

Tables are described by their columns as rows see them: colour columns are merged, bitwise columns split and enum columns converted, so each row has one value per column.

table.info

Returns the definition and row count of a table.

Params (GetTableInfo)

Result (TableInfo)

table.rows

Returns rows of a table, optionally filtered and with only some columns.

Params (GetTableRows)

Result (TableRows)

schema.definition

Returns the columns of a table as defined in the schema.

Params (GetTableDefinition)

Result (TableDefinition)

table.edit

Edits rows of a DB or Loc table in an open pack.

Edits are applied in order, each one on the result of the previous ones. If any of them fails, none is applied.

Params (EditTable)

Result (TableEdited)

table.column_values

Returns the distinct values of a column of a table, sorted.

Params (GetColumnValues)

Result (ColumnValues)

table.unused_numbers

Returns numbers no row uses yet in an integer column of a table, for new rows needing unique ones, like ids.

Params (GetUnusedNumbers)

Result (UnusedNumbers)

table.merge

Merges tables of the same type of an open pack into a new one.

Params (MergeTables)

Result (TablesMerged)

table.upgrade

Updates a table of an open pack to the version it has in the game files.

Params (UpgradeTable)

Result (TableUpgraded)

table.rename_key

Changes a value of a key column of a table in every table of an open pack, including the columns referencing it and the loc keys generated from it.

Params (RenameKey)