Burglin' Gnomes: finalize fix, docs, and BepInEx install support

Final tuned values baked in as defaults: HudScale=0.8, WorldLabelScale=0.8.

- install.sh gains METHOD=bepinex: installs BepInEx from vendor + the prebuilt
  plugin, with a matching uninstall that leaves BepInEx/ alone (other mods may
  depend on it). Success banner is now method-aware.
- Ship the prebuilt plugin DLL so users don't need a .NET SDK.
- Per-game README documenting why the camera is deliberately untouched
  (orthographic, constant orthographicSize = already Hor+), the two-canvas UI
  problem, tuning, and where the plugin log actually lives.
- Root README lists both games and both fix methods.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-21 16:33:56 -04:00
co-authored by Claude Opus 4.8
parent ed2e0016ba
commit 59ee13de9d
6 changed files with 162 additions and 23 deletions
+98
View File
@@ -0,0 +1,98 @@
# Burglin' Gnomes — UltraWide Fix
**Confirmed working at 5120×1440 (32:9) on Proton.**
- **Engine:** Unity 6 (6000.0.62f1), Mono backend, URP + Cinemachine
- **Steam AppID:** 3844970
- **Executable:** `Gnomium.exe`
- **Method:** BepInEx plugin (no DRM, no memory patching needed)
## What it fixes — and what it deliberately doesn't
**The camera is already correct.** It's *orthographic* with a constant `orthographicSize` of 5.0, so a wider display genuinely shows more world (visible width 17.8 → 35.6 going 16:9 → 32:9). That's textbook Hor+, and this fix does not touch it. `fieldOfView` reads 60 at every resolution simply because orthographic cameras don't use it — a red herring if you go looking.
**The problem is entirely UI**, in two separate places needing two different levers:
| Canvas | Problem | Lever |
|---|---|---|
| HUD (`ScreenSpaceOverlay` + `ScaleWithScreenSize`) | Ships `matchWidthOrHeight = 0.453` (width-biased). At 5120px that yields scaleFactor **1.948** — a ballooned HUD with overlapping bottom/centre text. | `match = 1` (scale by height) + raise `referenceResolution.y`, shrinking the HUD *and* giving the layout more logical room |
| In-world labels (`WorldSpace`, e.g. `NamePlate`) | At 32:9 you see twice as much world, so far more labels are on screen and can collide | Canvas `transform.localScale` |
> **Gotcha:** `CanvasScaler.scaleFactor` does nothing on a WorldSpace canvas — `CanvasScaler.HandleWorldCanvas()` overwrites it with `dynamicPixelsPerUnit` every frame. Scaling the transform is the only thing that works.
## Install (Linux / Proton)
```bash
./install.sh BurglinGnomes
```
Then **required** — Steam → Properties → Launch Options:
```
WINEDLLOVERRIDES="winhttp=n,b" %command%
```
Without it Proton ignores BepInEx's `winhttp.dll` loader and the plugin never runs.
## Install (Windows)
Extract the release zip into the game folder (next to `Gnomium.exe`). No launch option needed.
## Tuning
Config is generated on first launch:
```
<game>/BepInEx/config/com.programmingpug.burglingnomes.ultrawidefix.cfg
```
**Edits apply live (~2s) — no restart.** BepInEx doesn't reload config on its own, so the plugin watches the file's mtime and calls `Config.Reload()` itself.
| Setting | Default | Notes |
|---|---|---|
| `HudScale` | `0.8` | HUD size. Lower = smaller HUD *and* more layout room (cures overlapping text) |
| `WorldLabelScale` | `0.8` | In-world nameplate size |
| `MatchWidthOrHeight` | `1.0` | **Leave at 1.** Lower re-introduces width scaling and cramps the layout vertically |
| `DesignHeight` | `1080` | The game's design height; don't change |
| `Verbose` | `false` | Log every canvas adjustment |
`HudScale` → resulting HUD scale at 5120×1440 (stock is 1.333):
| HudScale | 1.0 | 0.85 | **0.8** | 0.6 |
|---|---|---|---|---|
| scale | 1.333 | 1.133 | **1.067** | 0.800 |
## Verifying it works
```
<game>/BepInEx/LogOutput.log
```
That's the plugin's log — **not** UnityExplorer's in-game Log window, which only shows Unity `Debug.Log`. You should see:
```
Burglin' Gnomes UltraWide Fix 1.0.0 loaded.
HUD 'Canvas' ref (1920.00, 1080.00) -> (1920.00, 1350.00) match=1 => scale=1.067
World 'NamePlate' localScale (1.00, 1.00, 1.00) -> (0.80, 0.80, 0.80)
```
If a line is absent, that adjustment didn't happen.
## Uninstall
```bash
./install.sh BurglinGnomes uninstall
```
Removes the loader and plugin. `BepInEx/` is left in place in case other mods use it.
## Building the plugin from source
Prebuilt `BurglinGnomes.UltraWideFix.dll` ships here, so this is only needed if you change it:
```bash
cd plugin
dotnet build -c Release -p:GameDir="/path/to/Burglin' Gnomes"
```
Requires the .NET SDK; it references the game's own assemblies and redistributes none of them.