Getting started

This guide gets you from a clean install to a running framework with plugins, on Windows or Linux. It assumes you already own and can launch the game. StellarResonance ships no game code or assets — you generate the IL2CPP interop locally from your own install (see ../DISCLAIMER.md).

Quality-of-life only. This framework is read-only and does not support cheating of any kind. If a future game patch adds anti-cheat, stop using it. See the README policy.

Two ways to install — launcher or manual — pan · zoom · search · click a box for its source

Easiest path — the launcher (Windows + Linux)

For most users, use the StellarResonance Launcher. It detects your game install, installs/updates the framework, toggles vanilla⇄modded, and launches the game — on both Windows and Linux. If you only want to use mods, stop here and grab the launcher.

The rest of this guide is the manual / developer path: building the framework yourself.

1. Find your game folder

The framework installs alongside the game’s IL2CPP runtime, in the game_mini folder:

Windows: …\Star\StarLauncher\game\release_<ver>\game_mini\ (under wherever the official launcher installed the game, e.g. C:\Program Files\Star\…).
Linux (Wine/Proton): <prefix>/drive_c/Star/StarLauncher/game/release_<ver>/game_mini/.

This folder is referred to as <game_mini> below.

2. Install the BepInEx loader (once)

The framework runs on BepInEx 6 (IL2CPP) — the pinned build is 6.0.0-be.755. Install the loader into <game_mini>:

Windows: download the BepInEx 6 IL2CPP be.755 build, extract it into <game_mini> so winhttp.dll and BepInEx/ sit next to the game executable.
Linux: extract the same build into <game_mini> (tools/setup-dev-env.sh downloads and unpacks it into tools/BepInEx-stage/), then add WINEDLLOVERRIDES=winhttp=n,b to your launcher’s per-game environment variables so Wine loads the Doorstop proxy.

tools/install-bepinex.sh automates the copy, but it is a maintainer helper: its source folder and its release_<ver> target are fixed inside the script, so edit them (and set STELLAR_PREFIX to your Wine prefix) before running it. It also turns BepInEx’s console and disk logging off for performance — set Enabled = true under [Logging.Disk] in <game_mini>/BepInEx/config/BepInEx.cfg if you want LogOutput.log.

Launch the game once. BepInEx generates the IL2CPP interop assemblies under <game_mini>/BepInEx/interop/ — the Unity/IL2CPP assemblies Infrastructure and Host compile against (or use the committed stubs, see step 3). Confirm the log exists at <game_mini>/BepInEx/LogOutput.log.

3. Build the framework

Install the .NET SDK 8.0+ (Windows / Linux / macOS), then:

dotnet build src/Stellar.sln -c Release \
  -p:GameInterop=<game_mini>/BepInEx/interop \
  -p:BepInExCore=<game_mini>/BepInEx/core

Use your platform’s real path for <game_mini> (Windows: C:\…\game_mini\BepInEx\interop; Linux: /.../game_mini/BepInEx/interop). The inner BCL-only projects (Abstractions / Wire / Application / Analyzers) build without these paths; Infrastructure/Host need them.

No game install? The repo commits API-only reference stubs in refs/ (regenerated by tools/gen-refs.sh), and CI builds the whole solution against them:

dotnet build src/Stellar.sln -c Release -p:GameInterop=$PWD/refs -p:BepInExCore=$PWD/refs

The release bundle is built the same way (tools/release/build-bundle.sh); the game supplies the real assemblies at runtime.

4. Deploy

The framework is seven files in <game_mini>/BepInEx/plugins/Stellar.Framework/: Stellar.Host, Stellar.Infrastructure, Stellar.Application, Stellar.Abstractions, Stellar.Wire and Stellar.PluginContracts (.dll), plus ZstdSharp.dll. Each is in its own project’s src/<Project>/bin/Release/ (ZstdSharp.dll is next to Stellar.Infrastructure.dll). Don’t leave out Stellar.PluginContracts.dll: plugins that cooperate through it fail to load without it.

Windows: copy those seven DLLs into <game_mini>\BepInEx\plugins\Stellar.Framework\.
Linux: tools/install-stellar.sh builds and copies the same set. It is written for the maintainers’ checkout, so point it at your game and skip the plugin part: GAME_RELEASE=<game_mini> STELLAR_FRAMEWORK_ONLY=1 DOTNET=dotnet tools/install-stellar.sh. It first runs a plain dotnet build src/Stellar.sln, with no -p: paths, so that build only finds the interop if it sits in the default .local/interop and .local/bepinex/core folders at the repo root. Otherwise build as in step 3 and add SKIP_BUILD=1. Its optional mode argument (prod default, test, perf, vanilla) also rewrites <game_mini>/stellar_perf.flags and a few BepInEx.cfg logging keys. vanilla just switches BepInEx off.

Never leave a backup copy (for example Stellar.Framework.bak) inside BepInEx/plugins/. BepInEx scans that folder recursively, and when two copies share a version it loads one of them arbitrarily.

5. Add plugins

Plugins are separate C# DLLs (kept in their own repository — plugin code is not part of this framework repo). Drop a built plugin into its own subfolder:

<game_mini>/stellar/plugins/<your-plugin>/<YourPlugin>.dll

The framework scans stellar/plugins/**/*.dll at startup, finds the non-abstract IStellarPlugin type with a public (IPluginServices) constructor, and loads it. Keep exactly one copy of each plugin: two folders holding the same plugin (even ones that differ only in letter case, like combatmeter/ and CombatMeter/) load only the first one found, and the log says duplicate plugin id. The launcher uses lowercase folder names. To write your own, see the developer guide.

6. Run and verify

Launch the game. On a successful boot the BepInEx log shows [Stellar] lines (including diagnostics=ON|OFF). Set the env var STELLAR_DIAGNOSTICS=1 for verbose per-event logging when investigating an issue (read once at startup — restart to change it). Set it via System environment variables on Windows, or your launcher’s per-game env vars on Linux. A DIAGNOSTICS line in <game_mini>/stellar_perf.flags does the same (install-stellar.sh test writes it).

Troubleshooting

Symptom	Check
No `[Stellar]` lines in the log	Windows: is `winhttp.dll` next to the game exe? Linux: is `WINEDLLOVERRIDES=winhttp=n,b` set? Did BepInEx generate `BepInEx/interop/`?
Build error: `Il2CppInterop` / `UnityEngine` not found	The assemblies aren’t where `GameInterop` / `BepInExCore` point. Launch the game once to generate them, or build against the committed stubs (`-p:GameInterop=$PWD/refs -p:BepInExCore=$PWD/refs`).
No `LogOutput.log`	BepInEx disk logging is off (`install-bepinex.sh` turns it off). Set `Enabled = true` under `[Logging.Disk]` in `BepInEx/config/BepInEx.cfg`.
Plugin doesn’t load	Is the DLL under `stellar/plugins/`? Does it have a non-abstract `IStellarPlugin` with a public `(IPluginServices)` constructor? Search the log for `[PluginHost]` and `duplicate plugin id`.
Nothing works after a game patch	A new game build can move the types the framework binds to. Wait for a compatibility update.

The log at <game_mini>/BepInEx/LogOutput.log is the first place to look for anything.