# Starminer Mod Manager Player Guide

This guide is for the Windows manager ZIP downloaded from `smmods.com`.

## What It Changes

The manager only changes the selected Starminer install after you choose an
install, install or repair managed content, or enable or disable a mod.

Managed game files are limited to:

- profiled UE4SS loader files in `ILLSpace\Binaries\Win64`;
- `ILLSpace\Binaries\Win64\ue4ss\Mods\StarminerBridge`;
- catalog mod folders under `ILLSpace\Binaries\Win64\ue4ss\Mods`;
- `ILLSpace\Binaries\Win64\ue4ss\Mods\mods.txt` enablement entries.

It does not replace the game executable or edit base game content.

## Install The Manager

1. Download the latest `smmodmanager-<version>-windows-x64.zip` from
   `https://smmods.com/download/`.
2. Extract the ZIP to a user-writable folder, for example
   `%LOCALAPPDATA%\smmodmanager\`.
3. Run `smmodmanager.exe`.

Do not run the manager from inside the ZIP viewer. Extract it first so the
app executable, release manifest, and docs can sit beside each other.

## First Run

1. Use `Auto Detect` to find Starminer from Steam library folders.
2. If auto-detect cannot find it, use `Browse` and select the folder that
   contains `ILLSpace\Binaries\Win64`.
3. Use the default cache folder unless support asks you to use another one.
4. The manager refreshes automatically on launch. Press `Refresh` again only if
   you change the selected folder or want to reload state.

The default cache is `%LOCALAPPDATA%\smmodmanager\downloads`. Cached downloads
are stored by runtime/bridge/mod version and reused only after SHA256
verification against the SMMODS catalog.

## Install Or Repair Runtime And Bridge

Use `Install Runtime + Bridge` the first time you want to set up the managed
base stack. Use `Repair Runtime + Bridge` when:

- this is the first time using UE4SS mods for Starminer;
- launch readiness says the runtime or bridge is missing;
- a game update removed loader files;
- support asks you to repair the managed base stack.

The manager reads the runtime and bridge versions from the SMMODS catalog.
It does not ask you to choose a UE4SS build manually. If a required package is
not already cached, a download window shows progress, speed, and Pause/Resume
or Cancel controls before install starts.

## Install Mods

1. Select one or more catalog mod rows.
2. Press `Install Selected`.

The manager installs dependencies before the selected mod, verifies package
hashes before changing the game install, rejects unsafe archive paths, and
preserves unrelated `mods.txt` entries. If a required package is not already
cached, the same foreground download window appears before files are installed.

## Enable Or Disable Mods

1. Select one or more installed rows with valid manifests.
2. Press `Enable` or `Disable`.
3. The manager refreshes after the change.

Invalid installed mod folders cannot be toggled from the manager because their
manifest cannot be trusted. Unknown installed mods with valid manifests can be
toggled because they already exist in the selected game install.

## Update Manager Or Mods

Use `Check Updates` to see whether `smmods.com` has a newer manager ZIP.
If an update is available, download the new ZIP and extract it over the previous
manager folder or into a new folder. Updating the manager does not remove UE4SS,
StarminerBridge, installed mods, or `mods.txt` from any selected game install.

For mods and StarminerBridge, look for update-available state in the grid.
Use `Repair Runtime + Bridge` for the base stack or `Repair Selected` for
selected catalog mods.

## Launch Starminer

Use `Launch Starminer` from the manager. The manager checks launch readiness
first and blocks launch when required runtime or bridge pieces are missing.
Warnings such as unknown enabled mods or invalid disabled mods should be
reviewed, but they do not always block launch.

## Create A Support Report

Use `Support Report` when asking for help. The report is saved under:

```text
%LOCALAPPDATA%\smmodmanager\support
```

Attach the newest `support-report-*.json` file. It includes catalog metadata,
manager update state, runtime/bridge/mod state, launch readiness, and
per-check errors. It does not install, repair, enable, disable, or launch
anything.

## Clear The Download Cache

Use `Clean` beside the cache folder field to delete all cached downloads. The
next install or repair will download artifacts again. This is useful after a
failed download, interrupted network connection, or support request. Do not copy
random ZIPs into the cache unless support gives you exact instructions; cached
files still need to match catalog SHA256 values.

## Uninstall The Manager

Delete the extracted manager folder and any manager cache/support folders you no
longer need under `%LOCALAPPDATA%\smmodmanager`.

This removes the manager app only. It does not remove UE4SS, StarminerBridge,
installed mods, or `ue4ss\Mods\mods.txt` from a game install you previously selected.

## Remove Runtime And Bridge From A Game Install

Press `Uninstall Runtime + Bridge` to remove the profiled UE4SS loader files
and `StarminerBridge` from the selected game install. This does not remove
catalog mods, unknown local mods, or unrelated `mods.txt` entries.

## Remove Managed Mods From A Game Install

Select one or more installed mods with valid manifests, then press `Uninstall`.
The manager removes the selected mod folders and removes only those mod entries
from `ue4ss\Mods\mods.txt`.

Be careful not to delete unknown folders you still want. If you are unsure,
create a support report before uninstalling or changing files manually.

## Support Reports

Press `Support Report` to save and display the current report. The popup includes
the report text and a copy button. Send that report to `cpjet64` on Discord or
create a GitLab work item at
`https://gitlab.curtpme.com/starminer-modding/smmodmanager`.

## After A Starminer Game Update

After Steam updates Starminer:

1. Start the manager.
2. Review launch readiness and compatibility warnings after the automatic refresh.
3. Use `Repair Runtime + Bridge` if loader files or bridge files are
   missing.
4. Wait for SMMODS catalog updates if mods are marked incompatible with the new
   game build.

Do not install an unpinned UE4SS build manually unless support asks you to test
a specific runtime package. Public installs should follow the catalog runtime
profile.

## Common Problems

`Could not auto-detect Starminer`

Use `Browse` and select the Starminer install root, not the `Win64` or `ue4ss\Mods`
folder.

`download-failed`

Check internet access to `smmods.com`, then retry. If it keeps failing, create
a support report. Install failures now include an `Install failure diagnostics`
section in the popup, app log, and saved report with catalog/package URL checks.

`hash-mismatch`

Clear the download cache and retry. Do not install packages whose hashes differ
from catalog metadata.

`dependency-cycle`, `missing-dependency`, or `dependency-version-unsatisfied`

The catalog entry needs to be fixed or another dependency version needs to be
published. Create a support report and include the mod you tried to install.

`invalid-installed-manifest`

One installed folder has a broken or incompatible manifest. Disable it manually
only if you know the folder name, or ask support with a support report attached.

`permission-denied`

Close Starminer and any tools using files in the game folder, then retry. If the
game is installed under a protected folder, run from a Windows account that can
write to that install.

`file-locked`

Starminer or another tool is using a file the manager needs to replace. Close
Starminer, modding tools, editors, archive apps, and terminals pointed at the
game folder, then retry.
