{"id":15567813,"url":"https://github.com/lucki/mod-manager","last_synced_at":"2025-04-11T23:22:32.757Z","repository":{"id":84596724,"uuid":"509447542","full_name":"Lucki/mod-manager","owner":"Lucki","description":"Simple game mod manager using OverlayFS","archived":false,"fork":false,"pushed_at":"2025-02-14T19:32:48.000Z","size":139,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T19:13:19.723Z","etag":null,"topics":["games","manager","mod","modification","modmanager","overlayfs"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lucki.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-01T12:31:27.000Z","updated_at":"2025-03-07T14:13:13.000Z","dependencies_parsed_at":"2023-03-12T23:45:42.875Z","dependency_job_id":null,"html_url":"https://github.com/Lucki/mod-manager","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucki%2Fmod-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucki%2Fmod-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucki%2Fmod-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lucki%2Fmod-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lucki","download_url":"https://codeload.github.com/Lucki/mod-manager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493263,"owners_count":21113219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["games","manager","mod","modification","modmanager","overlayfs"],"created_at":"2024-10-02T17:13:23.752Z","updated_at":"2025-04-11T23:22:32.749Z","avatar_url":"https://github.com/Lucki.png","language":"Rust","readme":"# Mod-Manager\n\nSimple game mod manager using OverlayFS.\n\nWhile a mod set is activated, the manager replaces the original game file path with an OverlayFS mount which contains the original game and a set of mods.\nThis allows other programs to easily access modded games exactly like if they weren't modded.\n\nMod sets are defined in a configuration file.\nMod sets can have any number of mods and can even be nested.\nAn empty (`\"\"`) active mod set name disables any mods.\nThe active mod set can be overridden with `--set` in the command line.\n\nThere are a two ways to handle mods, the first one is recommended:\n* Start each game with:\n  ~~~ text\n  mod-manager wrap \u003cgame-id\u003e -- \u003cgame-command\u003e\n  ~~~\n  * More flexible - mod sets can be adjusted per command call.\n  * Mods are enabled on demand.\n  * Automatic updates from launchers modify the real game files.\n  * Needs manual setup for every game.\n  * Steam/Bottles launch options example:\n    ~~~ text\n    mod-manager wrap \u003cgame-id\u003e -- %command%\n    ~~~\n* Run `mod-manager activate` at login and `mod-manager deactivate` at logout\n  * Only needs a setup once - enable and forget solution.\n  * Mods are always available.\n  * Launcher with automatic updates might try to access modded folders which means:\n    * If mounted immutable the update will probably fail\n    * If mounted writable the update will land in a persistent cache and will take precedence over mods in the future:\u003cbr\u003e\n      `$XDG_CACHE_HOME/mod-manager/\u003cgame-id\u003e/\u003cset-name\u003e_persistent`\n  * Example: `systemctl --user enable mod-manager.service`\n\n## Warning\n\nDo **not** change the *original* files while being mounted! This is a limitation of OverlayFS and is undefined behavior.\n\nAffected paths are:\n* The original game files, moved to a folder besides the game folder with a `_mod-manager` suffix:\u003cbr\u003e\n  ~~~ text\n  /path/to/game_mod-manager\n  ~~~\n* The used mod files:\n  ~~~ text\n  \u003cmod_root_path\u003e/\u003cmod-name\u003e\n  ~~~\n  Default: `$XDG_DATA_HOME/\u003cgame-id\u003e/\u003cmod-name\u003e`\n\nSo make sure to *deactivate* mods for games before altering their *original* game or mod files.\n\n## Usage\n\n~~~\nSimple game mod manager using OverlayFS\n\nUsage: mod-manager \u003cCOMMAND\u003e\n\nCommands:\n  activate    Activate a mod by mounting the OverlayFS inplace\n  deactivate  Deactivate an already activated mod by unmounting the OverlayFS\n  edit        Edit or create a configuration file for a game with $EDITOR\n  setup       Setup and collect changes for a new mod by making changes to the game\n  wrap        Wrap an external command in between an activation and deactivation\n  help        Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n~~~\n\u003cdetails\u003e\u003csummary\u003eActivate\u003c/summary\u003e\n\n~~~\nActivate a mod by mounting the OverlayFS inplace\n\nUsage: mod-manager activate [OPTIONS] [GAME]\n\nArguments:\n  [GAME]  Identifier matching the config file\n\nOptions:\n      --set \u003cSET\u003e  Override the \"active_set\" of the config file. Only applies when GAME is specified\n      --writable   Mount with write access. Only applies when GAME is specified\n  -h, --help       Print help\n~~~\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eDeactivate\u003c/summary\u003e\n\n~~~\nDeactivate an already activated mod by unmounting the OverlayFS\n\nUsage: mod-manager deactivate [GAME]\n\nArguments:\n  [GAME]  Identifier matching the config file\n\nOptions:\n  -h, --help  Print help\n~~~\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eEdit\u003c/summary\u003e\n\n~~~\nEdit or create a configuration file for a game with $EDITOR\n\nUsage: mod-manager edit \u003cGAME\u003e\n\nArguments:\n  \u003cGAME\u003e  Identifier matching the config file. Can be a new identifier\n\nOptions:\n  -h, --help  Print help\n~~~\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eSetup\u003c/summary\u003e\n\n~~~\nSetup and collect changes for a new mod by making changes to the game\n\nUsage: mod-manager setup [OPTIONS] \u003cGAME\u003e \u003cMOD\u003e\n\nArguments:\n  \u003cGAME\u003e  Identifier matching the config file. Can be a new identifier if PATH is also available.\n  \u003cMOD\u003e   New identifier for the mod\n\nOptions:\n      --path \u003cPATH\u003e  Creates a new config file for the game found in PATH\n      --set \u003cSET\u003e    Override the \"active_set\" of the config file\n  -h, --help         Print help\n~~~\n\nThis directive is a bit special and needs some additional explanation. It is intended for single usage and simplifies the creation process of new configs or mods.\n\n1. Two possibilities:\n    * The config file doesn't exist yet:\u003cbr\u003e\n      The `--path=\"/path/to/game/files\"` argument is needed. A new dummy config file will be created.\n    * The config file exists already:\u003cbr\u003e\n      For this directive the only required value in the config file is the `path = \"/to/the/game\"`.\n1. Run `mod-manager setup \u003cgame-id\u003e \u003cnew-mod-name\u003e`\n1. Now the changes can be made to the game, e.g. dropping files or folders into the games directory structure or executing an addon installer.\n1. When done press *Enter* and you'll find only the changes (basically the plain mod) in the `\u003cmod_root_path\u003e/\u003cmod-name\u003e`\u003cbr\u003e\n    Defaults to `$XDG_DATA_HOME/\u003cgame-id\u003e/\u003cmod-name\u003e`\n1. You can now add `\u003cmod-name\u003e` in your configuration file to sets.\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003eWrap\u003c/summary\u003e\n\n~~~\nWrap an external command in between an activation and deactivation\n\nUsage: mod-manager wrap [OPTIONS] \u003cGAME\u003e -- [COMMAND]...\n\nArguments:\n  \u003cGAME\u003e        Identifier matching the config file\n  [COMMAND]...  Command to wrap around to\n\nOptions:\n      --set \u003cSET\u003e  Override the \"active_set\" of the config file\n      --writable   Mount with write access\n  -h, --help       Print help\n~~~\n\u003c/details\u003e\n\n## Configuration file\n\nConfiguration files are placed in `$XDG_CONFIG_HOME/mod-manager` and written in [TOML](https://toml.io/en/latest).\n\nSee `complete.toml.example` and `minimal.toml.example` for examples.\n\n## Installation\nMake requires rust.\nBuild with `make build` or directly with `cargo build --release`\u003cbr\u003e\nThe executable is in `target/release/mod-manager`\n\nInstall with `make install`\u003cbr\u003e\nAdjust `PREFIX` and `DESTDIR` as needed.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucki%2Fmod-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucki%2Fmod-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucki%2Fmod-manager/lists"}