Skip to main content

rimsave-xray

See inside your RimWorld save. A read-only Windows tool that takes one .rws save and tells you where every byte went and what is eating your ticks: a terminal summary plus a self-contained HTML report, attributing bytes per section and per mod, with a ranked fix list.

It never writes to the save or the game folder. It prints the save's SHA-256 before and after the scan into the report so you can check.

The problem it solves

Your autosave is 200 MB and the game hitches when it writes. The usual advice is "check the save file size" or "disable half your mods", which is an evening of guessing. The runtime profilers (Dubs Performance Analyzer is the big one) tell you what code is slow while the game runs, but nothing tells you what is inside the save itself: which mod's things own the bytes, how many world pawns are still tracked, how much filth is lying around. rimsave-xray reads the save file once and answers exactly that.

Install

You need Windows and RimWorld 1.5+ (1.6 and the 1.7 unstable beta included). The scan itself works on any RimWorld save back to 1.3. The 1.7 fixtures in the test suite are from build 1.7.4976; 1.7 structural mappings may extend as the beta stabilizes toward the main branch, and anything not yet mapped in a 1.7 save is reported as such rather than guessed at.

The easy way is rimsavexray.exe from the latest release. It needs nothing else installed. Double-click it and it lists your saves, asks which one to scan, shows the summary, and waits for Enter before the window closes. The exe isn't signed, so Windows SmartScreen may warn the first time ("More info", then "Run anyway"). If something blocks unsigned programs outright, the pip install below works around that.

With Python 3.11 or newer from python.org (tick "Add python.exe to PATH" in its installer):

py -m pip install rimsavexray

Then rimsavexray runs from anywhere (py -m rimsavexray works the same).

Use it

Point it at a save. A path, a folder, or the in-game save name all work:

rimsavexray "Tribe of Estian"
rimsavexray "C:\Users\me\...\Saves\Autosave-1.rws"
rimsavexray "demosave 1.rws.gz"

On a 42.6 MB, 815-mod save:

save        C:\Users\...\Saves\Tribe of Estian.rws
file size   42.6 MB
gameVersion 1.5.4297 rev1079   ticks 18303663
mods        815 in the save's load order
sections    maps is the biggest at 18.8 MB (44.1% of the save)
top mod     Vanilla (Core) - 14.3 MB (33.6%)
world pawns 27 tracked (6 alive, 21 dead)
map things  37032 on 1 map(s): 466 floor items, 550 filth, 15 corpses
mods by bytes Vanilla (Core) 14.3 MB (33.6%), Vanilla (Ideology) 19.5 KB (0.0%), Vanilla (Biotech) 2.0 KB (0.0%)
unattributed 117 defs (3.5 MB) no installed mod defines

fix list:
 [!] Mod Vanilla (Core) owns 14.3 MB (33.6% of the save) (vanilla content).
 [ ] 6 world pawns still tracked (18 dead, 18 apparel items in their inventories) - within the 800 rule threshold.

read-only   SHA-256 before 9a6479a92635d9817621bd65e3ad28bbb1309ae683ee649202ae4143bc49cb22
            SHA-256 after  9a6479a92635d9817621bd65e3ad28bbb1309ae683ee649202ae4143bc49cb22
report      rimsavexray-report.html

The HTML report (written next to the program, --out to place it elsewhere) has the byte bars per section, per map, the Top 25 defs by bytes with the mod that owns each, every mod by bytes owned, the ranked fix list, and the world pawn breakdown by faction:

report

defs and mods

Options:

--json        print the full result as JSON (same numbers as the HTML)
--out FILE    where to write the report; --out none skips it
--game PATH   the RimWorld install folder, if Steam isn't findable
--list        list the saves in the game's Saves folder
--open        open the report in the browser when done

No argument at all means the newest save, and in the double-clicked exe that means it asks you first, with sizes and dates.

How attribution works

The scanner walks the save once with the standard library's streaming XML parser and never builds a tree, so a 400 MB save parses in well under a minute using under 50 MB of memory (there is a test that proves it). Every byte lands in exactly one section (meta, game, world, maps), every map thing and every world pawn is measured to the byte and attributed to its def.

Def to mod comes from the save itself: the mod list in meta/modIds is the load order, and for every mod there that is installed, the mod's own Defs/**/*.xml files are read for the defNames they define, along with any defs its Patches/*.xml insert or replace. When two mods define the same defName, the last one in load order owns it, which is how the game resolves it too. Core, Royalty, Ideology, Biotech, Odyssey and Anomaly are grouped as Vanilla. Mods that are not installed are reported as "unattributed: mod folder not found", and the counts and byte totals stay exact either way.

Gzipped saves (.rws.gz, the format some backup and analysis tools write) open transparently; byte attribution is on the XML inside, the file size on disk is shown separately.

The rules

Every message prints the counted number it fired on.

rule fires when says
world-pawns over 800 world pawns outside your faction how many are tracked, dead, and holding apparel; dev-mode "Clean up world pawns"
floor-items over 20000 items on maps consolidate or sell
filth over 5000 filth clean it or use a filth-clearing mod
apparel-on-corpses over 2000 apparel items on dead pawns strip or destroy corpses
save-bytes-by-mod one mod over 15% of save bytes which mod owns how many MB
component-bytes one component Class over 3% of save bytes which mod component quietly holds the bytes
autosave-size file over 150 MB load time and autosave hitch

Every message prints the counted number it fired on.

Limitations

Windows only (the Steam and Saves folder discovery is Windows-shaped; the scanner itself is pure Python). Runtime-generated defs like Corpse_Human are attributed to the def they wrap (Human's owner). Thing comps are counted where saves record them; saves rarely record any. The tool is strictly read-only and is not a mod manager, a save cleaner, or a mod: it tells you where the weight is, you decide what to do about it.

Using it while you build mods

Any save from any loadout scans, and the drift between two saves of the same colony is often the interesting part while developing a mod: play a few days on the old build, save, swap to the new build, play the same stretch, then

py examples\save-drift-check.py old.rws new.rws --game "D:\...\RimWorld"

It prints the byte drift per section and per mod, the biggest growing and shrinking defs, and exits 2 when the save grew past a budget (--max-growth-pct, default 5), which makes it usable as a CI gate after a playtest. It also answers version questions: point it at a pre-migration 1.6 backup and the migrated 1.7 save and it shows exactly what the migration changed (on our real test save, 1.7 shed 2.7 MB, nearly all plants and filth). On a real autosave rotation it reads like a story: grass dying back for the season (-260 KB), a fire (BurnedTree -39 KB, Filth_Ash +43 KB), quail arriving (+39 KB).

rimsavexray is also a plain library: from rimsavexray.scan import stream_scan gives you the full result (sections, per-def bytes, world pawns) as data, and --json gives the same numbers without importing anything.

One boundary to know: mod attribution covers things and world pawns, which is where save bloat lives. Data a mod keeps in game, world or map components is measured separately in the report's "Components by Class" table, with the Class namespace naming the mod (PipeSystem., Convergence.), but it does not roll into the mod's byte total.

Development

py -m pip install -e . pytest
py -m pytest                    # everything
py -m pytest -m "not slow"      # skip the 400 MB scale gate

The three saves under tests/fixtures/ are the MIT-licensed demosaves from dagpunk/rimhistory. The two waylith *.rws.gz fixtures were made for the 1.7 upgrade on this project's own machine from the real 1.7 unstable install: one new colony saved in 1.7, one real 1.6 save loaded into 1.7 and re-saved there. The save-format paths the scanner relies on (meta, modIds, tickManager, thing[@Class]/def, worldPawns) were cross-checked against those fixtures and against real 1.5 and 1.6 saves.

MIT license. If a save of yours doesn't scan, that's a bug: please open an issue with the save's name, size and gameVersion.

Metadata

Release files for rimsavexray 1.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rimsavexray 1.4.1
File Size Uploaded Provenance Actions
rimsavexray-1.4.1.tar.gz 47.5 kB Without provenance Details for rimsavexray-1.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rimsavexray 1.4.1
File Interpreter ABI Platform Actions
rimsavexray-1.4.1-py3-none-any.whl Python 3 none any Details for rimsavexray-1.4.1-py3-none-any.whl

Total release size: 78.8 kB

Release files / rimsavexray-1.4.1.tar.gz

Download URL rimsavexray-1.4.1.tar.gz
Size 47.5 kB
Tags Source
SHA-256 checksum
How to use checksums
47398720fa3d1044ab480b241cc55edab00c9d5631afbd099feb21538609b3c4
BLAKE2b-256 checksum
How to use checksums
01a704e57524dcb5ae4c81b9de12060dc7a9923ec62a0e4df4351356906f47f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / rimsavexray-1.4.1-py3-none-any.whl

Download URL rimsavexray-1.4.1-py3-none-any.whl
Size 31.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b26df5329f97db07a051e73efa6ab9dbc2ddab44ecd531d6d220cff9043c0d4b
BLAKE2b-256 checksum
How to use checksums
6e5d1d746f24e1c25eaf66eef1d630250bf3ece6600c1fbb72a5ad28a3e55afe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for rimsavexray 1.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page