Concepts

The layer stack

cpmm never copies mods into your game folder. It keeps them apart and, when the game starts, stacks them on top of it:

overwrite/            everything the game and tools write at runtime
mods/<last>/files     enabled mods, in load order:
…                     the last one in the load order sits highest and wins
mods/<first>/files
<game dir>            the real install, kept vanilla

When Steam launches the game, cpmm run -- %command% creates a private namespace, mounts this stack over the game directory with overlayfs, and starts the game inside it. Only the game and its tools see the mods. Steam, outside the namespace, still sees the real directory, so updates and “Verify integrity of game files” are unaffected. When the game exits, the namespace and the mount disappear.

Staging

Staging is the private store where cpmm keeps each installed mod’s files, one folder per mod, apart from the game. Installing a mod stages it; uninstalling moves its staged files to cpmm’s trash. Staging lives under ~/.local/share/cpmm unless you change staging_dir.

Vanilla game directory

Your real Cyberpunk 2077 install. cpmm never modifies it, which is why Steam’s updates and file checks keep working. cpmm unmanaged lists files in it that are neither vanilla nor owned by a mod, and --modified also lists vanilla files that were edited.

Overwrite

The overwrite layer is the top of the stack. It catches everything the game, Cyber Engine Tweaks, redscript and other tools write while running, so none of it lands in the game folder. cpmm overwrite shows what’s there; cpmm overwrite move <mod> keeps those files as part of a mod, and cpmm overwrite clear drops them.

Load order

The load order is the order of your enabled mods. A mod further down the load order wins a conflict with one above it.

cpmm sort builds a stable, dependency-aware order. It only enforces constraints between mods that actually overlap, through the same loose file or the same resource inside .archive files:

• A mod wins over the mods it requires.
• “Patch”, “fix”, “compat” and “addon” mods win over what they override.
• Add-on files win over the main file from the same Nexus page.
• Your own rules are enforced.

Everything else keeps its place. If the rules form a cycle, cpmm reports it and leaves the order as it is. To pin a winner between two unrelated mods:

cpmm rule <mod> --after <other>

Conflicts

A conflict is two enabled mods providing the same file or resource. cpmm finds three kinds:

• Loose-file conflicts: the same path in two mods. Byte-identical copies are filtered out.
• Archive resource conflicts: the same game asset inside two .archive files, read from their RDAR indexes. See cpmm archives.
• Redscript clashes: two mods using @replaceMethod on the same method, taking @if(ModuleExists(..)) guards into account.

The load order settles conflicts by default. To settle one without reordering, hide a mod’s copy (cpmm hide <mod> [paths]) or prefer a mod (cpmm prefer <mod> [paths]), which hides the other copies. Hidden files stay hidden across updates.

Profiles

A profile is a named set of enabled mods with its load order and rules. Installed files, hidden files, ignored requirements and the overwrite layer are shared between profiles, so a mod is downloaded and staged once however many profiles use it, and switching is instant.

cpmm profile                                # list (* = active)
cpmm profile create "Story run" --switch
cpmm profile switch "Story run"             # refused while the game runs

A mod installed while one profile is active is added to the others switched off. Your existing setup becomes the profile Default on first run.

Own saves

A profile either uses the game’s normal save folder (shared, which Steam Cloud syncs) or its own folder. cpmm swaps the folder in only inside the game’s namespace, so switching moves no files. Saves in a profile’s own folder aren’t synced to Steam Cloud.

cpmm profile create "Chaos run" --own-saves --copy-saves
cpmm profile saves "Chaos run" shared