Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lucki/mod-manager

Simple game mod manager using OverlayFS
https://github.com/lucki/mod-manager

games manager mod modification modmanager overlayfs

Last synced: 13 days ago
JSON representation

Simple game mod manager using OverlayFS

Host: GitHub
URL: https://github.com/lucki/mod-manager
Owner: Lucki
Created: 2022-07-01T12:31:27.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2024-04-05T23:20:00.000Z (9 months ago)
Last Synced: 2024-10-31T05:02:59.940Z (about 2 months ago)
Topics: games, manager, mod, modification, modmanager, overlayfs
Language: Rust
Homepage:
Size: 94.7 KB
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: Readme.md

Awesome Lists containing this project

README

# Mod-Manager

Simple game mod manager using OverlayFS.

While 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.
This allows other programs to easily access modded games exactly like if they weren't modded.

Mod sets are defined in a configuration file.
Mod sets can have any number of mods and can even be nested.
An empty (`""`) active mod set name disables any mods.
The active mod set can be overridden with `--set` in the command line.

There are a two ways to handle mods, the first one is recommended:
* Start each game with:
~~~ text
mod-manager wrap --
~~~
* More flexible - mod sets can be adjusted per command call.
* Mods are enabled on demand.
* Automatic updates from launchers modify the real game files.
* Needs manual setup for every game.
* Steam/Bottles launch options example:
~~~ text
mod-manager wrap -- %command%
~~~
* Run `mod-manager activate` at login and `mod-manager deactivate` at logout
* Only needs a setup once - enable and forget solution.
* Mods are always available.
* Launcher with automatic updates might try to access modded folders which means:
* If mounted immutable the update will probably fail
* If mounted writable the update will land in a persistent cache and will take precedence over mods in the future:

`$XDG_CACHE_HOME/mod-manager//_persistent`
* Example: `systemctl --user enable mod-manager.service`

## Warning

Do **not** change the *original* files while being mounted! This is a limitation of OverlayFS and is undefined behavior.

Affected paths are:
* The original game files, moved to a folder besides the game folder with a `_mod-manager` suffix:

~~~ text
/path/to/game_mod-manager
~~~
* The used mod files:
~~~ text
/
~~~
Default: `$XDG_DATA_HOME//`

So make sure to *deactivate* mods for games before altering their *original* game or mod files.

## Usage

~~~
Simple game mod manager using OverlayFS

Usage: mod-manager

Commands:
activate Activate a mod by mounting the OverlayFS inplace
deactivate Deactivate an already activated mod by unmounting the OverlayFS
edit Edit or create a configuration file for a game with $EDITOR
setup Setup and collect changes for a new mod by making changes to the game
wrap Wrap an external command in between an activation and deactivation
help Print this message or the help of the given subcommand(s)

Options:
-h, --help Print help
-V, --version Print version
~~~
Activate

~~~
Activate a mod by mounting the OverlayFS inplace

Usage: mod-manager activate [OPTIONS] [GAME]

Arguments:
[GAME] Identifier matching the config file

Options:
--set Override the "active_set" of the config file. Only applies when GAME is specified
--writable Mount with write access. Only applies when GAME is specified
-h, --help Print help
~~~

Deactivate

~~~
Deactivate an already activated mod by unmounting the OverlayFS

Usage: mod-manager deactivate [GAME]

Arguments:
[GAME] Identifier matching the config file

Options:
-h, --help Print help
~~~

Edit

~~~
Edit or create a configuration file for a game with $EDITOR

Usage: mod-manager edit

Arguments:
Identifier matching the config file. Can be a new identifier if PATH is also available

Options:
-h, --help Print help
~~~

Setup

~~~
Setup and collect changes for a new mod by making changes to the game

Usage: mod-manager setup [OPTIONS]

Arguments:
Identifier matching the config file. Can be a new identifier if PATH is also available.
New identifier for the mod

Options:
--path Creates a new config file for the game found in PATH
--set Override the "active_set" of the config file
-h, --help Print help
~~~

This 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.

1. Two possibilities:
* The config file doesn't exist yet:

The `--path="/path/to/game/files"` argument is needed. A new dummy config file will be created.
* The config file exists already:

For this directive the only required value in the config file is the `path = "/to/the/game"`.
1. Run `mod-manager setup `
1. 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.
1. When done press *Enter* and you'll find only the changes (basically the plain mod) in the `/`

Defaults to `$XDG_DATA_HOME//`
1. You can now add `` in your configuration file to sets.

Wrap

~~~
Wrap an external command in between an activation and deactivation

Usage: mod-manager wrap [OPTIONS] -- [COMMAND]...

Arguments:
Identifier matching the config file
[COMMAND]... Command to wrap around to

Options:
--set Override the "active_set" of the config file
--writable Mount with write access
-h, --help Print help
~~~

## Configuration file

Configuration files are placed in `$XDG_CONFIG_HOME/mod-manager` and written in [TOML](https://toml.io/en/latest).

See `complete.toml.example` and `minimal.toml.example` for examples.

## Installation
Make requires rust.
Build with `make build` or directly with `cargo build --release`

The executable is in `target/release/mod-manager`

Install with `make install`

Adjust `PREFIX` and `DESTDIR` as needed.