# Configuration

`rem-essentials` uses one active runtime configuration and, when the REM
Launcher is used, one persistent user override file.

## Configuration files

### Active game configuration

The DLL reads only this file at game startup:

```text
Freelancer/EXE/rem-essentials.ini
```

The file is shipped with the mod and contains the complete setting schema,
descriptions, metadata, and release defaults. A manual installation only needs
this INI and `rem-essentials.dll` in the `EXE` directory.

If the active INI is missing, the DLL uses its compiled defaults. The compiled
defaults intentionally match the shipped INI, but distributing the INI is
recommended because it exposes every feature and typed parameter.

### Launcher user overrides

The REM Launcher stores player choices separately:

```text
My Games/REM/rem-essentials.user.ini
```

On Wine or Proton, `My Games` is inside the Windows user profile of the active
prefix. Its exact Linux path depends on how the Launcher or game prefix was
created.

The DLL does not read this user file. The Launcher merges matching values from
the user file into `Freelancer/EXE/rem-essentials.ini`:

- after a game/mod update
- after saving settings in the Launcher
- immediately before starting Freelancer

This allows an update to replace the shipped schema while retaining player
choices. New settings from an updated default INI appear automatically. Values
from the user override win when the same section and key exist in both files.

## Value precedence

At runtime, the effective value is determined in this order:

1. The compiled DLL fallback is used when no setting can be read.
2. `Freelancer/EXE/rem-essentials.ini` overrides the compiled fallback.
3. Before launch, the Launcher materializes values from
   `rem-essentials.user.ini` into the active INI.

For a manual installation without the Launcher, only the first two levels
apply. Editing the active INI is therefore sufficient.

## Sections and value types

Feature switches live in `[rem-essentials]`. Parameters used by the graphics,
saves, and screenshots behavior live in `[flplusplus]`.

Boolean values accept:

```text
true / false
1 / 0
yes / no
on / off
```

Integer, float, and string settings are described by the comments immediately
above each key. Metadata such as `type`, `min`, `max`, `default`, `group`, and
`risk` is also used by the Launcher to build the settings UI.

## Save directory behavior

REM keeps the historical installation-local save directory as its default:

```ini
[rem-essentials]
save_path_feature = true

[flplusplus]
save_in_directory = true
save_folder_name = Freelancer
```

With `save_in_directory = true`, the patched path is calculated relative to
`Freelancer.exe`:

```text
Freelancer/EXE/../SAVE
```

For an installation such as:

```text
/home/<user>/RemLauncher_AppData/current/Freelancer/EXE/Freelancer.exe
```

the effective save directory is:

```text
/home/<user>/RemLauncher_AppData/current/Freelancer/SAVE
```

With `save_in_directory = false`, the plugin instead uses the Windows
Documents folder exposed by Windows, Wine, or Proton and appends:

```text
My Games/<save_folder_name>
```

`save_folder_name` is therefore only relevant when
`save_in_directory = false`. Setting `save_path_feature = false` disables this
hook completely and restores Freelancer's unpatched path behavior.

Changing the setting does not move existing saves. Move existing files to the
selected directory before launching when switching between layouts.

## Manual installation

1. Copy `rem-essentials.dll` and `rem-essentials.ini` into `Freelancer/EXE`.
2. Add `rem-essentials.dll` to the appropriate `[Libraries]` section in
   `dacom.ini` and, for FLServer features, `dacomsrv.ini`.
3. Ensure `save_path_feature = true` and `save_in_directory = true` for the REM
   installation-local `SAVE` layout.
4. Fully restart Freelancer after changing the INI. Settings are read when the
   DLL is loaded.

## Launcher-managed installation

Use the Game Settings page to change supported values. Saving creates or
updates `My Games/REM/rem-essentials.user.ini`. Avoid manually changing the
active INI while a conflicting user override exists, because the Launcher will
materialize the user value again before game startup.