Section: “Copy these files” is not an uninstall plan.
A responsible mod installer knows exactly what it changed. A manifest is a machine-readable receipt containing:
mod identifier and version;
supported game build;
relative destination path;
original file hash, if a file existed;
installed file hash;
backup location;
operation time and status.
Do not store absolute paths inside a portable manifest. Keep a trusted game root separately and resolve enclosed relative paths beneath it.
Treat installation as a reversible state transition with a durable journal, not as an unrecorded sequence of file copies:
The manifest records which state was reached. After a crash, that record tells the recovery code whether an original file still needs restoring.
Section: Model operations before touching disk.
Installing a new file and replacing an existing one need different undo actions. A new file can later be removed; a replaced file needs its backup restored. Record that distinction, the expected hashes, and the stage each operation has reached before writing anything:
Code example. The surrounding prose explains this example; the full lesson contains the exact code.
The distinction between Create and Replace prevents an uninstaller from deleting a file that existed before the mod.
In brief: Creating a file and replacing one need different undo actions; an uninstaller must know which operation it performed.
Section: Verify before replacement.
An install plan may be correct when created and stale five minutes later after a game update. Compare the file’s current hash with the hash recorded when the plan was made. If they differ, this replacement must stop instead of overwriting someone else’s change:
Code example. The surrounding prose explains this example; the full lesson contains the exact code.
This is an optimistic concurrency check. If the player updates the game or installs another mod between planning and installation, stop instead of overwriting an unexpected file.
Narration: Another mod can change a file after planning. Rechecking its hash prevents your old plan from overwriting that newer work.
Section: Write status durably.
An installer can crash after making a backup but before copying the replacement. The installer’s manifest stores the transaction in recoverable stages:
Alternative: The manifest is a recovery journal: each completed stage tells a restarted installer what already happened and which step can safely follow.
Code example. The surrounding prose explains this example; the full lesson contains the exact code.
Write the updated manifest to a temporary file, flush it, validate that it parses, then replace the old manifest. The receipt is part of the modification, not optional documentation.
Section: Uninstall by comparing hashes.
For a created file:
hash the current file;
delete it only if it still matches the mod’s installed hash;
otherwise report that someone changed it and leave it alone.
For a replaced file:
verify the current file still matches the installed hash;
verify the backup matches the recorded original hash;
restore through a temporary file;
hash the restored output;
mark the operation Restored.
That policy avoids erasing a user’s later work.
Section: Plan conflicts between mods.
Two mods that replace the same path conflict even when both work alone. Build an index from normalized relative path to owning mod:
Code example. The surrounding prose explains this example; the full lesson contains the exact code.
A conflict means the installer cannot choose a winner automatically. Show it before installation.
Section: The recovery test.
Use a copy of an open-source game’s data folder:
install a texture mod;
interrupt the installer after backup;
run recovery and confirm the original survives;
install completely;
edit one installed file manually;
uninstall and confirm the edited file is preserved with a warning;
restore the clean test folder and repeat.
A reversible mod is easier to learn from because every experiment has a defined way home. ✅