modwright 0.1.0

package/dist/surfaces/nivalisnights/logs.js

@@ -0,0 +1,473 @@
+const BE788 = "https://github.com/BepInEx/BepInEx/blob/5b766a3b7f6c164d4798924a93f3acf4db769d06";
+const CHAINLOADER = `${BE788}/BepInEx.Core/Bootstrap/BaseChainloader.cs`;
+const INTEROP = `${BE788}/Runtimes/Unity/BepInEx.Unity.IL2CPP/Il2CppInteropManager.cs`;
+const REAL_BEPINEX = "test/fixtures/logs/nivalisnights/real/LogOutput.head.log (field 2026-10-03)";
+const REAL_PLAYER = "test/fixtures/logs/nivalisnights/real/Player.excerpt.log (field 2026-10-03)";
+const LITERALS = "global-metadata.dat string literals";
+const PRE = String.raw `^\[(?<level>Fatal|Error|Warning|Message|Info|Debug)\s*:\s*(?<source>.+?)\] `;
+function re(body) {
+    return new RegExp(PRE + body);
+}
+const BEPINEX = [
+    {
+        id: "nivalisnights.bepinex.version-banner",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `BepInEx (?<version>\d[\w.\-+]*) - (?<process>.+?)(?: \(|$)`),
+        explain: "BepInEx started and named its build and the process it attached to. The community's tested build is 6.0.0-be.788.",
+        seenIn: [CHAINLOADER, REAL_BEPINEX],
+        extract: ["version", "process"],
+    },
+    {
+        id: "nivalisnights.bepinex.unity-banner",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `Running under Unity v?(?<unity>[\w.]+)`),
+        explain: "The Unity version BepInEx detected (2020.3.44f1 for this game); interop and AssetBundles are bound to it.",
+        seenIn: [REAL_BEPINEX],
+        extract: ["unity"],
+    },
+    {
+        id: "nivalisnights.bepinex.runtime",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `Runtime version: (?<runtime>[\w.]+)`),
+        explain: "The .NET runtime BepInEx's IL2CPP build hosts plugins on (its own dotnet/ folder); plugins must target net6.0.",
+        seenIn: [REAL_BEPINEX],
+        extract: ["runtime"],
+    },
+    {
+        id: "nivalisnights.bepinex.plugin-count",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `(?<count>\d+) plugins? to load`),
+        explain: "How many plugins the chainloader found to load this run.",
+        seenIn: [CHAINLOADER, REAL_BEPINEX],
+        extract: ["count"],
+    },
+    {
+        id: "nivalisnights.bepinex.plugin-loaded",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `Loading \[(?<plugin>.+) (?<version>[^\s\]]+)\]$`),
+        explain: "One per plugin the chainloader loads, in dependency order; the roll-call of what is live.",
+        seenIn: [CHAINLOADER, REAL_BEPINEX],
+        extract: ["plugin", "version"],
+    },
+    {
+        id: "nivalisnights.bepinex.chainloader-complete",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "success",
+        pattern: re(String.raw `Chainloader startup complete`),
+        explain: "Every plugin that was going to load has loaded. A plugin's runtime exceptions land in Player.log, not here.",
+        seenIn: [CHAINLOADER, REAL_BEPINEX],
+    },
+    {
+        id: "nivalisnights.bepinex.missing-dependency",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "order",
+        pattern: re(String.raw `Could not load \[(?<plugin>.+?)\] because it has missing dependencies: (?<missing>.+?)(?:\. Install the listed plugin\(s\) and restart the game\.)?$`),
+        explain: "A plugin declared a hard dependency that is not installed; the plugin is skipped.",
+        hint: "Install the listed dependency (the name is its plugin GUID). Some Nivalis Nights mods need BepInEx.Utility.IL2CPP from GitHub.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "missing"],
+    },
+    {
+        id: "nivalisnights.bepinex.incompatible-version",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "version",
+        pattern: re(String.raw `Could not load \[(?<plugin>.+?)\] because the following dependencies are installed with an incompatible version: (?<deps>.+?)(?:\. Update the listed plugin\(s\).*)?$`),
+        explain: "A dependency is installed but outside the version range the plugin declares; the plugin is skipped.",
+        hint: "Update the listed dependency to a version in the stated range.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "deps"],
+    },
+    {
+        id: "nivalisnights.bepinex.dependency-cascade",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "order",
+        pattern: re(String.raw `Skipping \[(?<plugin>.+?)\] because it has a dependency that was not loaded`),
+        explain: "A plugin was skipped because one it depends on failed earlier; fix the first failure and this one clears.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin"],
+    },
+    {
+        id: "nivalisnights.bepinex.wrong-bepinex-version",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "version",
+        pattern: re(String.raw `Plugin \[(?<plugin>.+?)\] targets a wrong version of BepInEx \((?<targeted>[\w.]+)\) and might not work until you update`),
+        explain: "The plugin references a different BepInEx.Core than the one installed; it still loads, and may or may not work.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "targeted"],
+    },
+    {
+        id: "nivalisnights.bepinex.similar-guid",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "order",
+        pattern: re(String.raw `Skipping \[(?<plugin>.+?)\] because a plugin with a similar GUID \(\[(?<loaded>.+?)\]\) has been already loaded`),
+        explain: "Two plugins' GUIDs differ only in case or punctuation; BepInEx 6 keeps the first and drops this one.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "loaded"],
+    },
+    {
+        id: "nivalisnights.bepinex.duplicate-guid",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "order",
+        pattern: re(String.raw `Skipping \[(?<plugin>.+?)\] because a newer version exists \((?<newer>.+?)\)`),
+        explain: "Two copies of one plugin GUID are installed; the older is dropped. Usually an update extracted beside the old folder instead of over it.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "newer"],
+    },
+    {
+        id: "nivalisnights.bepinex.process-filtered",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `Skipping \[(?<plugin>.+?)\] because of process filters \((?<filters>.+?)\)`),
+        explain: "The plugin declares it runs only in another process and was skipped on purpose; it was likely built for a different game.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin", "filters"],
+    },
+    {
+        id: "nivalisnights.bepinex.plugin-load-error",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "load",
+        pattern: re(String.raw `Error loading \[(?<plugin>.+?)\]\s*:`),
+        explain: "The plugin threw while loading; the exception follows. After a game update this is usually a type or method the interop no longer has.",
+        hint: "Check the plugin's page for a build matching the current game update.",
+        seenIn: [CHAINLOADER],
+        extract: ["plugin"],
+    },
+    {
+        id: "nivalisnights.bepinex.metadata-rejected",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "load",
+        pattern: re(String.raw `Skipping (?:over )?type \[(?<type>.+?)\] (?:as no metadata attribute is specified|because its (?<field>GUID|version|name))`),
+        explain: "A plugin class's [BepInPlugin] attribute is missing or malformed (GUID, version or name), so BepInEx does not treat it as a plugin.",
+        seenIn: [CHAINLOADER],
+        extract: ["type", "field"],
+    },
+    {
+        id: "nivalisnights.bepinex.loading-failed",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "crash",
+        pattern: re(String.raw `Error occurred loading plugins:`),
+        explain: "The chainloader itself failed while loading plugins; what loaded before the failure is all that is live.",
+        seenIn: [CHAINLOADER],
+    },
+    {
+        id: "nivalisnights.bepinex.interop-generating",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `Generating interop assemblies`),
+        explain: "BepInEx is building its interop assemblies from GameAssembly.dll: on the first launch after installing, and after every game update. It took about 25 s on this game; the game sits at a black screen meanwhile.",
+        seenIn: [INTEROP],
+    },
+    {
+        id: "nivalisnights.bepinex.interop-outdated",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "version",
+        pattern: re(String.raw `Detected outdated interop assemblies, will regenerate them now`),
+        explain: "GameAssembly.dll changed since the interop was built: the game updated. Interop regenerates by itself; plugins compiled against the old build may now fail.",
+        hint: "Watch this run's plugin errors; the game patches often (two updates in its first four days).",
+        seenIn: [INTEROP],
+    },
+    {
+        id: "nivalisnights.bepinex.interop-possibly-outdated",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "version",
+        pattern: re(String.raw `Interop assemblies are possibly out of date`),
+        explain: "BepInEx could not confirm the interop matches the game binary and did not regenerate; plugins may bind to a stale API.",
+        hint: "Delete BepInEx/interop and BepInEx/cache and launch once to regenerate.",
+        seenIn: [INTEROP],
+    },
+    {
+        id: "nivalisnights.bepinex.interop-failed",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "crash",
+        pattern: re(String.raw `Failed to generate Il2Cpp interop assemblies:`),
+        explain: "Interop generation failed, so no plugin can load. The usual causes are the Unity base-library download (first launch needs network access) and a Cpp2IL failure on a new game build.",
+        hint: "Check the lines just above for the download or Cpp2IL error. Offline, place the unity-libs .zip for 2020.3.44 in BepInEx/unity-libs by hand.",
+        seenIn: [INTEROP],
+    },
+    {
+        id: "nivalisnights.bepinex.unity-libs-download",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "info",
+        category: "load",
+        pattern: re(String.raw `Downloading unity base libraries from (?<url>\S+)`),
+        explain: "First-launch step: BepInEx downloads Unity base libraries to build interop, so the first launch after installing needs network access.",
+        seenIn: [INTEROP],
+        extract: ["url"],
+    },
+    {
+        id: "nivalisnights.bepinex.unity-libs-download-failed",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "resource",
+        pattern: /Failed to download Unity base libraries for Unity (?<unity>\S+) from (?<url>\S+?):/,
+        explain: "The Unity base-library download failed, so interop cannot be generated and nothing loads.",
+        hint: "Retry with network access, or place the base-libraries .zip for this Unity version in BepInEx/unity-libs.",
+        seenIn: [INTEROP],
+        extract: ["unity", "url"],
+    },
+    {
+        id: "nivalisnights.harmony.target-not-found",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "warn",
+        category: "resource",
+        pattern: re(String.raw `AccessTools\.\w+: Could not find (?<kind>method|field|property|type) (?<target>.+)$`),
+        explain: "A plugin's patch reached for a game member that does not exist in this build, usually after a game update; that patch silently does nothing.",
+        hint: "The plugin needs an update for the current game version.",
+        seenIn: ["HarmonyX AccessTools; HarmonyX 2.10.2 ships in BE #788"],
+        extract: ["kind", "target"],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.harmony.undefined-target-method",
+        game: "nivalisnights",
+        sources: ["bepinex"],
+        severity: "error",
+        category: "resource",
+        pattern: re(String.raw `(?:[\w.]*Exception: )?Undefined target method for patch method (?<patch>.+)$`),
+        explain: "A Harmony patch declares a target this game build does not have; the patch is not applied and that plugin's feature is missing.",
+        hint: "The plugin needs an update for the current game version.",
+        seenIn: ["HarmonyX PatchClassProcessor; HarmonyX 2.10.2 ships in BE #788"],
+        extract: ["patch"],
+        systemImpact: false,
+    },
+];
+const PLAYER = [
+    {
+        id: "nivalisnights.player.engine-version",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "version",
+        pattern: /^Initialize engine version: (?<unity>\S+)/,
+        explain: "The first line of a run: the Unity version the game starts on.",
+        seenIn: [REAL_PLAYER],
+        extract: ["unity"],
+    },
+    {
+        id: "nivalisnights.player.dev-mode",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "load",
+        pattern: /^isDevMode:(?<value>True|False)\b/,
+        explain: "The game's own developer-mode check. It logs inside the getter before any Harmony postfix runs, so 'False' does not mean a plugin's forced dev mode failed; the plugin's own log line is the authority.",
+        seenIn: [LITERALS, REAL_PLAYER],
+        extract: ["value"],
+    },
+    {
+        id: "nivalisnights.player.scene-loaded",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "success",
+        pattern: /^GameSceneManager - (?<from>.*?) -> (?<to>\S+) \| Total Unloading\/Loading Duration: (?<seconds>[\d.]+) seconds/,
+        explain: "A scene finished loading; the empty 'from' is the first load after start.",
+        seenIn: [REAL_PLAYER],
+        extract: ["from", "to", "seconds"],
+    },
+    {
+        id: "nivalisnights.player.save-loading",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "load",
+        pattern: /^Loading save file (?<save>\S+) @Scene:(?<scene>\d+)/,
+        explain: "A save began loading; the scene number is its build index.",
+        seenIn: [LITERALS, REAL_PLAYER],
+        extract: ["save", "scene"],
+    },
+    {
+        id: "nivalisnights.player.save-loaded",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "success",
+        pattern: /^Completed loading save (?<path>.+)$/,
+        explain: "A save loaded to the end without the loader quitting the game.",
+        seenIn: [LITERALS, REAL_PLAYER],
+        extract: ["path"],
+    },
+    {
+        id: "nivalisnights.player.save-written",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "success",
+        pattern: /^Completed saving save (?<path>.+)$/,
+        explain: "A save was written and moved into place.",
+        seenIn: [LITERALS, REAL_PLAYER],
+        extract: ["path"],
+    },
+    {
+        id: "nivalisnights.player.unknown-save-packet",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "error",
+        category: "resource",
+        pattern: /^No packet found for guid (?<guid>.+)$/,
+        explain: "The save holds a manager packet this game does not know, and the loader cannot skip it: everything after it in the save reads wrong. Either a mod that added its own save packet was removed, or the save is from a different game build.",
+        hint: "Reinstall the mod that wrote the packet, or restore the save from a backup taken before it. A mod should keep its state in a sidecar file, never a packet.",
+        seenIn: [LITERALS],
+        extract: ["guid"],
+    },
+    {
+        id: "nivalisnights.player.unknown-prefab",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "warn",
+        category: "resource",
+        pattern: /^Cannot find prefab with id (?<id>\S+)/,
+        explain: "A saved world object names a prefab this build does not have; the loader skips that object. Usually residue of a removed mod's placed object.",
+        seenIn: [LITERALS],
+        extract: ["id"],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.player.same-scene-twice",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "warn",
+        category: "load",
+        pattern: /^GameSceneManager - Loading the same scene twice!/,
+        explain: "A scene load was requested for the scene already loading; often a plugin calling travel or LoadArea during a transition.",
+        seenIn: [LITERALS],
+    },
+    {
+        id: "nivalisnights.player.level-loading-timeout",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "error",
+        category: "load",
+        pattern: /^GameSceneManager LevelLoadingIsBlocked timeout!/,
+        explain: "A scene load waited too long on something blocking it; the game may hang at the transition.",
+        seenIn: [LITERALS],
+    },
+    {
+        id: "nivalisnights.player.nnue-download-failed",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "warn",
+        category: "resource",
+        pattern: /^Failed to download NNUE file: /,
+        explain: "The chess engine's network file was missing from StreamingAssets and the game's download fallback failed; the chess minigame has no engine.",
+        hint: "Verify the game files in Steam to restore StreamingAssets/nn-0000000000a0.nnue.",
+        seenIn: [LITERALS],
+    },
+    {
+        id: "nivalisnights.player.dev-token-rejected",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "load",
+        pattern: /^ValidatePayload DateTime (?<what>expired|failed)/,
+        explain: "settings.ini holds a developer token that did not validate. The token is RSA-signed by the studio and cannot be made locally; a plugin forces dev mode instead.",
+        seenIn: [LITERALS],
+        extract: ["what"],
+    },
+    {
+        id: "nivalisnights.player.vanilla-chair",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "script",
+        pattern: /can't stand from chair anywhere!$/,
+        explain: "Known vanilla noise (logged at error level by the unmodded game): an NPC could not find a place to stand up. Not caused by mods.",
+        seenIn: [LITERALS, REAL_PLAYER],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.player.vanilla-pooled-element",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "script",
+        pattern: /^Pooled element .+ should not be destroyed, but released back to the pool instead!/,
+        explain: "Known vanilla noise (logged at error level by the unmodded game): an object-pool misuse inside the game. Not caused by mods.",
+        seenIn: [LITERALS],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.player.vanilla-venue-order",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "script",
+        pattern: /VenueOrderReference[.:]get_Order\b/,
+        explain: "Known vanilla noise: a NullReferenceException from the staff task queue (VenueOrderReference.get_Order, during LateUpdate) seen in an unmodded launch-week log. Not caused by mods unless a mod changes staff tasks.",
+        seenIn: ["ModWright research"],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.player.singleton-after-quit",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "load",
+        pattern: /^\[Singleton\] Instance '(?<type>[^']+)' already destroyed on application quit/,
+        explain: "Normal at quit: a manager was asked for after shutdown began.",
+        seenIn: [REAL_PLAYER],
+        extract: ["type"],
+        systemImpact: false,
+    },
+    {
+        id: "nivalisnights.player.dotween-safe-mode",
+        game: "nivalisnights",
+        sources: ["player", "player-prev"],
+        severity: "info",
+        category: "script",
+        pattern: /DOTween's safe mode captured (?<count>\d+) errors/,
+        explain: "DOTween's end-of-session summary of tween errors it swallowed; the unmodded game reports these too.",
+        seenIn: ["ModWright research"],
+        extract: ["count"],
+        systemImpact: false,
+    },
+];
+export const SIGNATURES = [...BEPINEX, ...PLAYER];

package/dist/surfaces/nivalisnights/surface.js

@@ -0,0 +1,195 @@
+import * as path from "node:path";
+import { homePath, pathExists, readTextIfExists } from "../../core/fsutil.js";
+import { findInSteam } from "../../core/steam.js";
+import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
+import { GAME_EXE, nivalisCompat } from "./compat.js";
+import { nivalisIndex } from "./index/index.js";
+import { SIGNATURES } from "./logs.js";
+export const nivalisnights = {
+    id: "nivalisnights",
+    name: "Nivalis Nights",
+    aliases: ["nivalis", "nivalis nights", "nn"],
+    summary: "Unity IL2CPP with BepInEx 6 bleeding-edge (Unity.IL2CPP, #788): net6.0 plugin assemblies under " +
+        "BepInEx/plugins, HarmonyX patches against generated interop; MelonLoader builds also exist. No official mod support.",
+    async detect() {
+        const installs = [];
+        const override = process.env.MODWRIGHT_NIVALISNIGHTS_ROOT;
+        if (override && (await pathExists(override)))
+            installs.push({ gameId: "nivalisnights", root: override, source: "env" });
+        for (const root of await findInSteam(["Nivalis Nights"])) {
+            if (await isInstall(root))
+                installs.push({ gameId: "nivalisnights", root, source: "steam" });
+        }
+        return dedupeByRoot(installs);
+    },
+    modRoots(install) {
+        const bepinex = path.join(install.root, "BepInEx");
+        return roots([
+            {
+                id: "plugins",
+                label: "BepInEx plugins",
+                path: path.join(bepinex, "plugins"),
+                layout: "directory",
+                conflictScope: "isolated",
+                notes: "Each mod in its own subdirectory; loose .dlls directly in plugins/ load too, and most Nivalis " +
+                    "Nights mods install that way. Collisions are on plugin GUID, not path: BepInEx 6 drops a " +
+                    "duplicate or near-duplicate GUID with a 'Skipping [...]' line. Plugins must be built for the " +
+                    "Unity.IL2CPP runtime (BasePlugin, net6.0); a BepInEx 5 or Mono plugin does not load.",
+            },
+            {
+                id: "patchers",
+                label: "BepInEx preloader patchers",
+                path: path.join(bepinex, "patchers"),
+                layout: "directory",
+                conflictScope: "isolated",
+                notes: "Preloader patchers; none of the community mods seen so far ship one.",
+            },
+            {
+                id: "config",
+                label: "BepInEx config",
+                path: path.join(bepinex, "config"),
+                layout: "flat",
+                conflictScope: "merged",
+                notes: "One <GUID>.cfg per plugin plus BepInEx.cfg, written by BepInEx at runtime.",
+            },
+            {
+                id: "core",
+                label: "BepInEx core",
+                path: path.join(bepinex, "core"),
+                layout: "flat",
+                conflictScope: "merged",
+                notes: "BepInEx, HarmonyX and Il2CppInterop assemblies. Listed so a mod wrongly shipping into it is visible; never a deploy target.",
+            },
+            {
+                id: "interop",
+                label: "BepInEx generated interop",
+                path: path.join(bepinex, "interop"),
+                layout: "flat",
+                conflictScope: "merged",
+                notes: "Generated from GameAssembly.dll on the first launch and after each game update (about 25 s). " +
+                    "Plugins compile against these; never a deploy target. Deleting the folder with BepInEx/cache " +
+                    "forces a rebuild.",
+            },
+            {
+                id: "loader",
+                label: "Loader files beside the executable",
+                path: install.root,
+                layout: "flat",
+                conflictScope: "merged",
+                notes: "BepInEx's winhttp.dll, doorstop_config.ini, .doorstop_version and dotnet/ (its own .NET 6 " +
+                    "runtime); MelonLoader's version.dll. Where 'which loader is installed' is answered.",
+            },
+            {
+                id: "melon-mods",
+                label: "MelonLoader mods",
+                path: path.join(install.root, "Mods"),
+                layout: "file",
+                extensions: [".dll"],
+                conflictScope: "isolated",
+                notes: "MelonLoader's mods folder, for mods that ship a MelonLoader build. Install one loader, not both.",
+            },
+        ]);
+    },
+    logs(install) {
+        const userDir = (file) => homePath("AppData", "LocalLow", "ION LANDS", "Nivalis Nights", file);
+        return logs([
+            {
+                id: "bepinex",
+                label: "BepInEx LogOutput.log",
+                candidates: [path.join(install.root, "BepInEx", "LogOutput.log")],
+                rootId: "plugins",
+                notes: "One file per run, '[Level  :    Source] message' lines with no timestamp. Holds the chainloader's " +
+                    "roll-call and plugin errors, plus interop generation on a first launch or after a game update. " +
+                    "A plugin's runtime exceptions land in Player.log instead.",
+            },
+            {
+                id: "player",
+                label: "Unity Player.log",
+                candidates: [userDir("Player.log")],
+                notes: "The game's own log: scene loads, saves, the game's errors and plugin exceptions. Every message " +
+                    "line is followed by its managed stack. Several error lines are vanilla noise and are tagged so.",
+            },
+            {
+                id: "player-prev",
+                label: "Unity Player-prev.log (the previous run)",
+                candidates: [userDir("Player-prev.log")],
+                notes: "Unity rotates Player.log on launch; after a crash the evidence is here once the game is restarted.",
+            },
+            {
+                id: "melonloader",
+                label: "MelonLoader Latest.log",
+                candidates: [path.join(install.root, "MelonLoader", "Latest.log")],
+                rootId: "melon-mods",
+                notes: "Only with MelonLoader installed. Its line format has not been seen on this machine, so no signatures read it yet.",
+            },
+        ]);
+    },
+    async explainMissing(install) {
+        const reasons = {};
+        if (!(await pathExists(path.join(install.root, "winhttp.dll")))) {
+            reasons.bepinex = "winhttp.dll was not found beside the executable: BepInEx is not installed here, so no LogOutput.log can exist. The community's build is BepInEx 6 bleeding-edge #788, Unity.IL2CPP.";
+        }
+        else {
+            const cfg = await readTextIfExists(path.join(install.root, "BepInEx", "config", "BepInEx.cfg"));
+            if (cfg === undefined)
+                reasons.bepinex = "BepInEx/config/BepInEx.cfg does not exist yet: BepInEx creates it on its first launch, so the loader has not run since it was installed.";
+            else if (diskLoggingDisabled(cfg))
+                reasons.bepinex = "[Logging.Disk] Enabled = false in BepInEx/config/BepInEx.cfg: the loader runs but writes no LogOutput.log. Set it to true.";
+        }
+        const userDir = homePath("AppData", "LocalLow", "ION LANDS", "Nivalis Nights");
+        if (!(await pathExists(userDir))) {
+            reasons.player = `${userDir} does not exist: the game has not been run under this Windows account.`;
+            reasons["player-prev"] = reasons.player;
+        }
+        else {
+            reasons["player-prev"] = "Unity writes Player-prev.log only once the game has been launched a second time.";
+        }
+        if (!(await pathExists(path.join(install.root, "MelonLoader")))) {
+            reasons.melonloader = "MelonLoader is not installed (it is optional here; BepInEx is the community default).";
+        }
+        return reasons;
+    },
+    logSignatures: SIGNATURES,
+    compat: nivalisCompat,
+    index: nivalisIndex,
+    toolNeeds: [
+        { feature: "index", tools: ["cpp2il", "unitypy-python"], note: "build_index rebuilds dummy assemblies with Cpp2IL and decodes Resources/ with a UnityPy Python." },
+        { feature: "build", tools: ["dotnet"], note: "dotnet build compiles net6.0 BepInEx IL2CPP plugins." },
+    ],
+    processNames: [GAME_EXE],
+    guidance: "A Unity IL2CPP game: mods are BepInEx 6 bleeding-edge plugins (the Unity.IL2CPP build; #788 is " +
+        "what the community and ModWright tested), net6.0 assemblies subclassing BasePlugin and patching " +
+        "with HarmonyX against BepInEx/interop. BepInEx 5 and Mono-style plugins do not load. Install " +
+        "order matters: install BepInEx, launch once to the main menu (interop generation, about 25 s, " +
+        "needs network for the Unity base libraries), close, then add plugins. Some mods ship a " +
+        "MelonLoader build instead; install one loader, not both. The game patches often, and each " +
+        "update regenerates interop and can break plugins, so check build ids before blaming a mod. " +
+        "Saves are Easy Save 2 binary files in %USERPROFILE%/AppData/LocalLow/ION LANDS/Nivalis Nights; " +
+        "the loader cannot skip an unknown packet, so a mod must keep its own state in a sidecar file " +
+        "beside the save, never as a new packet. Steam Cloud syncs only .sav and .png, so sidecars stay " +
+        "local. A plugin can force the studio's developer mode (DevMode.IsDevMode) and open its " +
+        "Developer Options window; Player.log's 'isDevMode:False' line is printed before that override " +
+        "and is not evidence it failed.",
+};
+export async function isInstall(root) {
+    return (await pathExists(path.join(root, GAME_EXE))) || (await pathExists(path.join(root, "Nivalis Nights_Data")));
+}
+export function diskLoggingDisabled(cfgText) {
+    let section = "";
+    for (const raw of cfgText.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const sec = /^\[(.+)\]$/.exec(line);
+        if (sec) {
+            section = sec[1].trim().toLowerCase();
+            continue;
+        }
+        if (section !== "logging.disk")
+            continue;
+        const m = /^enabled\s*=\s*(\w+)/i.exec(line);
+        if (m)
+            return m[1].toLowerCase() === "false";
+    }
+    return false;
+}