Issue #1628: atomsmasher, an offline tool that fixes a tactical save to be loadable

[whakomatic]

This is a proposal for the third fix in #1628. It adds a standalone Python tool. I dont see this as an addition to CH but its here for people to review and understand everything together. The final tool would be a workshop upload.

What it does

atomsmasher.py rewrites a tactical save offline, while the game is not running. It archives the history the way the game's native ArchiveHistory does at a mission's start state:

• The archive frame and the tactical start frame are kept as saved.
• For every object changed since the start, only its current version is kept, in the frame that wrote it, along with that frame's context. Active effects sync on load through that frame's context, so collapsing everything into one frame crashes the load. Keeping the frames avoids that.
• Frames that hold no current version are dropped. The kept frames are numbered after the old frame count, and the history indexes stored in contexts and units are renumbered to match.
• References to a dropped frame's context are written as -1, the same way the format writes an object that was not saved.

It checks its result before writing: it reports structure problems and compares every object's current state against the original by ObjectID.

Usage

python atomsmasher.py <save file>

It writes <save file>_archived beside the original, which shows as "(archived)" in the Load Game list. It needs Python 3.10 or later and has no dependencies.

Results

On an LWOTC save from the final mission (attached):
This file loads but the autosave for next will fail to load.

	Original	Archived
File size	18,283,594 bytes	7,007,229 bytes
History objects	111,593	45,831
Frames	13,958	2,019
Load copy (estimated)	737 MB	302 MB

The archived save loaded and played two XCOM turns and two alien turns with no errors, the same as the original.

On the turn 5 save from the large LWOTC mission in #1628, which crashed on load:

	Original	Archived
File size	6,941,623 bytes	2,107,940 bytes
History objects	167,304	15,960
Frames	4,141	1,148
Load copy (estimated)	1,104 MB	105 MB

SkipTurns wrote 82% of that save's history, and 99% of the unit states they wrote changed only visibility. Every object's current state in the archived save matches the original, apart from 95 effects created and removed during the mission and one renumbered history index.

The load copy is estimated at 6.6 KB per object. That figure was measured on saves that are mostly unit states, and it overstates saves like the first one, which loaded even though its estimate is past the limit.

[whakomatic]

Two save files, one with the Skip Turn Bloat and the other that is simply big.
Also the (python) atomsmasher.py file which is the tool to run on the save file.

Files.zip

[ToallaNova-O2D]

Q: I know the script doesn't handle strategic saves, but my question is more related to knowing if these kinds of issues do happen at that stage (like leaving the game too long on avenger/globe without going into missions).