modwright 0.1.0

package/knowledge/valheim/bepinex.plugins.yaml

@@ -0,0 +1,251 @@
+game: valheim
+topic: bepinex.plugins
+title: The BepInEx 5 plugin contract — metadata attributes, dependency-ordered loading, and how a
+  plugin fails
+facts:
+  - id: valheim.bepinex.plugins.bepinplugin-attribute-contract
+    claim: A plugin is a class inheriting `BepInEx.BaseUnityPlugin` (itself a Unity `MonoBehaviour`, so
+      `Awake`/`Update` are the entry points) carrying `[BepInPlugin(GUID, Name, Version)]`. Without
+      the attribute BepInEx ignores the type entirely. The GUID must be unique and match
+      `^[a-zA-Z0-9\._\-]+$`; reverse-domain notation is the recommended form. The version string is
+      parsed with `System.Version`, i.e. `major.minor[.build[.revision]]`.
+    status: community
+    source: https://docs.bepinex.dev/v5.4.11/articles/dev_guide/plugin_tutorial/2_plugin_start.html ;
+      GUID regex from BepInEx v5-lts `Chainloader.allowedGuidRegex`
+    tags:
+      - bepinex
+      - plugin
+      - bepinplugin
+      - guid
+      - version
+      - validator
+    detail: "Three of these are checkable by a static validator against a plugin's own source before it
+      is ever built: the attribute is present, the GUID matches the regex, and the version parses.
+      BepInEx logs \"Skipping type [...] because its GUID [...] is of an illegal format.\" and
+      \"Skipping type [...] because its version is invalid.\" for the other two cases, at Warning
+      level, with no other symptom."
+  - id: valheim.bepinex.plugins.valheim-pack-allows-semver-versions
+    claim: "Stock BepInEx 5 rejects a plugin whose version string is a full SemVer with a pre-release
+      suffix such as `1.2.0-beta.1`, because `System.Version` cannot parse it. BepInExPack_Valheim
+      patches this: its README lists \"Plugins can use semver version strings like `1.2.0-beta.1`.
+      Base BepInEx 5 throws those plugins out with an 'invalid version' warning.\""
+    status: community
+    source: https://thunderstore.io/c/valheim/p/denikson/BepInExPack_Valheim/ (README, the list of
+      deviations from upstream BepInEx)
+    tags:
+      - bepinex
+      - bepinexpack
+      - version
+      - semver
+      - validator
+      - valheim-specific
+    detail: A validator that enforces the stock `System.Version` rule on a Valheim plugin would be
+      wrong. This is one of the concrete places where "Valheim runs BepInEx" and "Valheim runs the
+      Valheim BepInEx pack" give different answers, which is why the pack has to be its own compat
+      component.
+  - id: valheim.bepinex.plugins.dependency-attributes
+    claim: '`[BepInDependency(guid, DependencyFlags)]` declares a dependency, with
+      `DependencyFlags.HardDependency` (the constructor default) or `SoftDependency`; a second
+      overload takes a minimum version string and is always treated as hard.
+      `[BepInProcess("name.exe")]` restricts the plugin to named executables,
+      `[BepInIncompatibility(guid)]` refuses to load alongside another plugin. All three allow
+      multiple applications.'
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Contract/Attributes.cs`; the Hard/Soft semantics are also stated at
+      https://docs.bepinex.dev/v5.4.11/articles/dev_guide/plugin_tutorial/2_plugin_start.html
+    tags:
+      - bepinex
+      - plugin
+      - bepindependency
+      - bepinprocess
+      - bepinincompatibility
+      - load-order
+    detail: "`[BepInProcess]` matters more than usual for Valheim because the client and dedicated
+      server are different executables — a plugin can declare itself client-only or server-only in
+      the metadata itself, which a validator can cross-check against where a project deploys it."
+  - id: valheim.bepinex.plugins.load-order-is-a-topological-sort
+    claim: BepInEx has no load-order file. The order is a depth-first topological sort of the dependency
+      graph, seeded from a case-insensitive `SortedDictionary` so that unordered plugins come out
+      alphabetically and deterministically; the in-source comment is "We use a sorted dictionary to
+      ensure consistent load order". Both hard and soft dependencies feed the sort, so a soft
+      dependency still orders the load and the flag only decides whether a missing one is fatal.
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Bootstrap/Chainloader.cs` (`Utility.TopologicalSort` over
+      `dependencyDict`) and `BepInEx/Utility.cs`
+    tags:
+      - bepinex
+      - load-order
+      - topological-sort
+      - dependency
+      - deterministic
+    detail: 'This is the single most consequential difference from every game ModWright currently
+      supports: there is nothing for `loadOrderFile` or `diffLoadOrder` to read, and a `load_order`
+      answer can only be derived by reading metadata out of the plugin assemblies or by reading the
+      order the log actually reported. A dependency cycle throws `Exception("Cyclic Dependency:\r\n
+      - node...")` rather than degrading.'
+  - id: valheim.bepinex.plugins.duplicate-guid-highest-version-wins
+    claim: When two loaded assemblies declare the same plugin GUID, BepInEx groups by GUID, orders by
+      version descending, keeps the highest and logs "Skipping [Name Version] because a newer
+      version exists (Name Version)" at Warning for each loser.
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Bootstrap/Chainloader.cs`
+    tags:
+      - bepinex
+      - duplicate
+      - guid
+      - version
+      - conflict
+      - signature
+    detail: "This is why `conflictScope` for `BepInEx/plugins` is subtle: two mods in separate
+      subfolders never collide on file paths, so the directory layout is genuinely isolated, but
+      they can still collide on GUID, which no filesystem diff can see. The honest answer is
+      `isolated` plus a note saying the real collision axis is the GUID."
+  - id: valheim.bepinex.plugins.missing-hard-dependency-lines
+    claim: 'A missing hard dependency produces, at Error, "Could not load [Name Version] because it has
+      missing dependencies: <guid>" (or "<guid> (v<version> or newer)" when a minimum was declared),
+      and the plugin is never instantiated. Anything that hard-depends on *that* plugin then gets,
+      at Warning, "Skipping [Name Version] because it has a dependency that was not loaded. See
+      previous errors for details." A missing soft dependency produces no message at all.'
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Bootstrap/Chainloader.cs`, the `Start()` dependency pass
+    tags:
+      - bepinex
+      - dependency
+      - failure-mode
+      - signature
+      - log
+      - cascade
+    detail: "The cascade is the useful part for triage: one Error line names the real root cause, and
+      every Warning line after it is collateral. A triage verdict that ranks these equally will bury
+      the finding that matters. The same three strings are also appended to the public
+      `Chainloader.DependencyErrors` list, which is how in-game reporter mods surface them."
+  - id: valheim.bepinex.plugins.other-load-failure-lines
+    claim: 'The remaining chainloader failure literals are "Could not load [...] because it is
+      incompatible with: <guids>" (Error), "Plugin [...] targets a wrong version of BepInEx
+      (<version>) and might not work until you update" (Warning, non-blocking), "Skipping [...]
+      because of process filters (<exe names>)" (Warning), "Error loading [...] : <exception
+      message>" (Error) and "Error occurred starting the game" (Fatal).'
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Bootstrap/Chainloader.cs`
+    tags:
+      - bepinex
+      - failure-mode
+      - signature
+      - log
+      - version
+    detail: "\"targets a wrong version of BepInEx\" is a warning and does not block loading — it fires
+      when the plugin's referenced BepInEx assembly differs in major version, or is newer in minor
+      or build. Treating it as a blocker would be wrong; treating it as noise hides the most common
+      post-update breakage warning."
+  - id: valheim.bepinex.plugins.stale-assembly-exceptions-are-invisible-by-default
+    claim: "A plugin compiled against an older game assembly typically fails with an ordinary .NET
+      `MissingMethodException`/`TypeLoadException`, for which BepInEx defines no message of its own.
+      If it surfaces during type enumeration the log shows only the one-line \"Error loading [...] :
+      <message>\", because the detail (`TypeLoader.TypeLoadExceptionToString`, enumerating every
+      `LoaderException` and any `Fusion Log:` block) is logged at Debug, which the default
+      `[Logging.Disk] LogLevels` excludes. If it surfaces later — inside `Awake`, or on the first
+      call into a stale reference — it goes to Unity's logger and reaches `LogOutput.log` only if
+      `[Logging.Disk] WriteUnityLog` is turned on, which by default it is not."
+    status: inferred
+    source: BepInEx v5-lts `BepInEx/Bootstrap/TypeLoader.cs` and `BepInEx/Bootstrap/Chainloader.cs` (the
+      `LogDebug` calls after `Error loading`, and the `ConfigDiskWriteUnityLog` default of `false`)
+    tags:
+      - bepinex
+      - missingmethodexception
+      - typeloadexception
+      - game-update
+      - log
+      - failure-mode
+    detail: "This is the most important triage fact on the whole game: after a Valheim update, the
+      default configuration produces a `LogOutput.log` that looks nearly clean while the game is
+      visibly broken, and the actual stack trace is in Valheim's own `Player.log` instead.
+      ModWright's correct move is to declare both files as log sources and, on seeing a bare \"Error
+      loading [...]\" with no detail, to say so and recommend widening `LogLevels` rather than
+      guessing the cause."
+  - id: valheim.bepinex.plugins.harmony-version-and-patch-shape
+    claim: BepInEx 5.4.23.5 ships HarmonyX 2.9.0 (plus Mono.Cecil and MonoMod.RuntimeDetour); patches
+      are declared with `[HarmonyPatch(typeof(T), nameof(T.Method))]` on a class whose `Prefix`,
+      `Postfix` and `Transpiler` static methods are found by name, and applied with `new
+      Harmony("id").PatchAll()` or `Harmony.CreateAndPatchAll(assembly, id)`.
+    status: community
+    source: https://github.com/BepInEx/BepInEx/blob/v5.4.23.5/BepInEx/BepInEx.csproj (the HarmonyX 2.9.0
+      PackageReference); https://harmony.pardeike.net/v2/articles/patching-prefix.html ;
+      https://docs.bepinex.dev/articles/dev_guide/runtime_patching.html
+    tags:
+      - harmony
+      - harmonyx
+      - patch
+      - prefix
+      - postfix
+      - transpiler
+      - version
+    detail: 'The Valheim-Modding wiki independently records the same assembly version as the one a
+      plugin project references — "0Harmony, Version=2.9.0.0" from `BepInEx\core\0Harmony.dll`
+      (https://github.com/Valheim-Modding/Wiki/wiki/Best-Practices). The parameterless `PatchAll()`
+      carries a documented hazard: it resolves the calling assembly via `StackTrace.GetFrame(1)`,
+      which inlining can get wrong, so `PatchAll(Assembly.GetExecutingAssembly())` is the safe
+      form.'
+  - id: valheim.bepinex.plugins.harmonyx-runs-every-prefix-even-after-a-false
+    claim: 'HarmonyX deliberately differs from stock Harmony on prefix cancellation: in stock Harmony
+      the first prefix returning false skips the remaining prefixes and the original, whereas in
+      HarmonyX "cancelling running a prefix will not cancel running the subsequent prefixes" — every
+      prefix still runs. The HarmonyX-only injected `bool __runOriginal` parameter is the documented
+      way for a later prefix to notice that a skip was requested.'
+    status: community
+    source: https://github.com/BepInEx/HarmonyX/wiki/Difference-between-Harmony-and-HarmonyX, section
+      "All prefix patchers are always run even if original method is skipped"; stock behaviour from
+      https://harmony.pardeike.net/v2/articles/patching-prefix.html
+    tags:
+      - harmonyx
+      - harmony
+      - prefix
+      - conflict
+      - silent-failure
+      - multiplayer
+    detail: The page opens with "Note that these are not bugs! All items listed here are intentional
+      changes". There is **no log line** for this — two mods patching the same method with
+      cancelling prefixes behave differently on Valheim than the Harmony documentation says,
+      silently. It cannot be detected by a log signature, only by knowing it, which makes it a
+      knowledge-base fact rather than a triage rule.
+  - id: valheim.bepinex.plugins.patch-target-gone-after-an-update
+    claim: 'When a patched method no longer exists after a game update, the two observable signatures
+      are a HarmonyX Warning from AccessTools — "AccessTools.Method: Could not find method for type
+      <type> and name <name> and parameters <params>" (and the DeclaredMethod / Field / Property /
+      TypeByName variants) — and an `ArgumentException: Undefined target method for patch method
+      <signature>` thrown out of `PatchClassProcessor`, which in a normal plugin surfaces from
+      `Awake` as a Unity exception rather than as a chainloader error.'
+    status: inferred
+    source: HarmonyX v2.9.0 `Harmony/Tools/AccessTools.cs` and `Harmony/Public/PatchClassProcessor.cs`;
+      the BepInEx-side channel mapping is `BepInEx/Logging/HarmonyLogSource.cs`
+    tags:
+      - harmony
+      - harmonyx
+      - game-update
+      - failure-mode
+      - signature
+      - accesstools
+    detail: "The Valheim-Modding wiki's own troubleshooting page quotes both shapes from real logs —
+      \"[Warning: HarmonyX] AccessTools.DeclaredMethod: Could not find method for type InventoryGui
+      and name Show and parameters (Container)\" and \"[Error : Unity Log] ArgumentException:
+      Undefined target method...\" — which is independent confirmation that these are the lines
+      users actually see (https://github.com/Valheim-Modding/Wiki/wiki/Client-Troubleshooting).
+      HarmonyX's `[Harmony.Logger] LogChannels` defaults to `Warn, Error`, so the AccessTools
+      warning does reach the disk log by default while Harmony's own Info-channel startup banner
+      does not."
+  - id: valheim.bepinex.plugins.never-unpatchall-with-null
+    claim: The community's standing rule is to never call `UnpatchAll()` with a null parameter — only
+      `UnpatchAll("your.harmony.id")` — and not to call UnpatchAll at all on game shutdown, because
+      doing so risks corrupting saves.
+    status: community
+    source: https://github.com/Valheim-Modding/Wiki/wiki/Best-Practices
+    tags:
+      - harmony
+      - unpatchall
+      - save-corruption
+      - validator
+      - failure-mode
+    detail: 'BepInEx itself logs "[Warning: HarmonyX] UnpatchAll has been called - This will remove ALL
+      HARMONY PATCHES." when it happens, which the Client-Troubleshooting page quotes as a line to
+      look for. That makes this both a source-level validator (flag a null-argument UnpatchAll call)
+      and a log signature (flag the warning), and the consequence — a corrupted save — is severe
+      enough to justify both.'

package/knowledge/valheim/game.versions.yaml

@@ -0,0 +1,321 @@
+game: valheim
+topic: game.versions
+title: Valheim's version axis, update cadence, the 1.0 engine upgrade, and where saves and Player.log live
+facts:
+  - id: valheim.game.versions.one-dotted-axis
+    claim: "Valheim has one public version axis and it is the only number Iron Gate uses: three-part
+      patch numbers, `0.217.x`, `0.218.x`, `0.219.x`, `0.220.x`, `0.221.x` through Early Access and
+      `1.0.x` after release. There is no separate marketing name for a build — the biome updates
+      (Ashlands, The Bog Witch, Deep North) are names attached to a numbered patch, not a second
+      version scheme."
+    status: community
+    source: Steam news announcement titles for app 892970 (e.g. "Patch 0.218.15 – Ashlands", "Patch
+      0.219.13 – The Bog Witch", "Patch 0.221.10 – Five Years of Valheim!"),
+      https://store.steampowered.com/news/app/892970
+    tags:
+      - version
+      - axis
+      - patch
+      - knowledge-format
+      - verified-on
+    detail: Under ModWright's version convention, `verified_on` for this game is therefore written on
+      the `1.0.12` form — the same axis the patch notes use. The exe's PE FileVersion is a
+      *different* number (the Unity player version, see below) and must never be substituted for it.
+  - id: valheim.game.versions.current-is-1-0-12
+    claim: Valheim left Early Access on 2026-09-09 with "Valheim 1.0 Has Arrived!", and the most recent
+      patch as of 2026-09-11 is "Hotfix 1.0.10 & 1.0.12", published the same day — 1.0.10 to all
+      platforms and 1.0.12 to Steam only.
+    status: community
+    source: https://valheim.com/news/ and the Steam news feed for app 892970 (announcements dated
+      2026-09-09 and 2026-09-11)
+    tags:
+      - version
+      - release
+      - "1.0"
+      - deep-north
+      - current
+    detail: Two things follow for a surface being brought up today. Every fact about this game is at
+      most two days old, so nothing is settled. And the split between an all-platform 1.0.10 and a
+      Steam-only 1.0.12 means "the current version" is genuinely ambiguous for a few days at a time
+      — a compat rule that pins an exact build will misfire during those windows.
+  - id: valheim.game.versions.cadence-is-slow-with-a-public-test-branch
+    claim: "Iron Gate's cadence is a handful of patches a year, each typically preceded by a named
+      \"(Public Test)\" release: 0.217.46 (2024-04-10), 0.218.15 – Ashlands (2024-05-14), 0.218.21
+      (2024-08-27), 0.219.13 – The Bog Witch (2024-10-29), 0.219.16 (2024-11-19), 0.220.5
+      (2025-04-01), 0.221.4 – Call To Arms (2025-09-09), 0.221.10 – Five Years of Valheim
+      (2026-02-02), 0.221.12 (2026-02-19), 0.221.13 (Public Test) (2026-05-06), 1.0 (2026-09-09)."
+    status: community
+    source: Steam news announcement titles and dates for app 892970,
+      https://store.steampowered.com/news/app/892970
+    tags:
+      - version
+      - cadence
+      - public-test
+      - beta-branch
+      - patch-history
+    detail: Compared with Cyberpunk 2077 or Baldur's Gate 3 this is a slow cadence with long stable
+      plateaus — 0.220.5 stood for five months, 0.221.12 for seven. The practical consequence is
+      that "every plugin broke" events are rare but total, and the Public Test branch gives modders
+      advance warning, which is the natural trigger for a compat-matrix refresh.
+  - id: valheim.game.versions.1-0-included-a-unity-engine-upgrade
+    claim: The Valheim 1.0 patch notes list "Unity engine upgrade" among the fixes and improvements,
+      alongside a new "Magica cloth system"; the Valheim-Modding wiki's Unity project guide
+      correspondingly instructs modders to install Unity `6000.0.75f1`.
+    status: community
+    source: https://valheim.com/news/valheim-1-0-has-arrived-/ (patch notes, "Fixes & Improvements") ;
+      https://github.com/Valheim-Modding/Wiki/wiki/Valheim-Unity-Project-Guide
+    tags:
+      - unity
+      - engine
+      - version
+      - assetbundle
+      - "1.0"
+      - breaking
+    detail: An engine major-version move is the largest possible breaking change for asset-shipping
+      mods. Note the wiki's own JotunnModStub README still names Unity `2022.3.17f`, so the two
+      Valheim-Modding sources disagree and the correct editor version for 1.0 asset work is not
+      settled by documentation alone.
+  - id: valheim.game.versions.unity-upgrade-history
+    claim: Iron Gate names the Unity version in patch notes only some of the time. The numbered
+      statements are "Updated Unity version to 2022.3.50" in 0.219.13 – The Bog Witch (2024-10-29),
+      "Upgraded Unity engine to 6000.0.46f" in 0.221.4 – Call To Arms (2025-09-09), and "Updated
+      Game Engine to Unity 6000.0.61f1" in 0.221.10 (2026-02-02). Valheim 1.0 (2026-09-09) says only
+      "Unity engine upgrade", with no number.
+    status: community
+    source: Steam news patch notes for app 892970, the four announcements named (retrieved via
+      ISteamNews GetNewsForApp, 2026-09-11)
+    tags:
+      - unity
+      - version
+      - history
+      - patch-notes
+      - assetbundle
+    detail: So Valheim moved from the Unity 2022.3 line to Unity 6 between 2024-10-29 and 2025-09-09,
+      and the last *numbered* engine statement is 6000.0.61f1. Earlier engine moves (the 2019/2020
+      lines) are not in the patch notes at all — 0.207.20, 0.212.7 (Mistlands) and 0.217.14
+      (Hildir's Request) mention no engine version — so that history cannot be reconstructed from
+      Iron Gate's own notes.
+  - id: valheim.game.versions.assetbundles-are-not-forward-compatible
+    claim: Unity's own manual states that AssetBundles built with an older Unity are usually loadable by
+      a newer one but that "Unity doesn't support forward-compatibility of AssetBundles, so you
+      can't load an AssetBundle built with a newer version of Unity into an older version of Unity",
+      and that after large changes between versions a bundle must be rebuilt.
+    status: community
+    source: https://docs.unity3d.com/6000.3/Documentation/Manual/AssetBundlesIntro.html, "Introduction
+      to AssetBundles"
+    tags:
+      - unity
+      - assetbundle
+      - compatibility
+      - version
+      - toolchain
+    detail: "Combined with the upgrade history above, this is why the editor version matters concretely
+      rather than academically: a mod's bundle must be built with an editor no newer than the game's
+      runtime, and every Iron Gate engine bump is a point at which existing bundles can stop
+      loading. The same page notes that bundles built without type trees are the ones that fail
+      hardest across versions."
+  - id: valheim.game.versions.unity-version-readable-from-the-exe
+    claim: "The Unity player version is recoverable without launching the game, because BepInEx itself
+      derives it that way: its \"Running under Unity v...\" line is
+      `FileVersionInfo.GetVersionInfo(<game exe>).FileVersion`. Reading `valheim.exe`'s PE
+      FileVersion therefore answers the Unity-version question from a cold install."
+    status: inferred
+    source: BepInEx v5-lts `BepInEx.Preloader/Preloader.cs`, `GetUnityVersion()`
+    tags:
+      - unity
+      - version
+      - pe
+      - fileversion
+      - detect
+      - compat
+    related:
+      - id: valheim.bepinex.loader.unity-version-is-the-exe-file-version
+        detail: the same mechanism, stated from the loader's side
+  - id: valheim.game.versions.most-mods-broke-at-1-0
+    claim: The Valheim-Modding community's own 1.0 FAQ states that most mods do not work with 1.0
+      because of breaking changes, that update timelines vary from days to months per author, that
+      the old BepInEx pack still loads but should be updated, and that players wanting the pre-1.0
+      game should select `0.221.12 from February 19th` through Steam's beta settings.
+    status: community
+    source: https://github.com/Valheim-Modding/Wiki/wiki/Valheim-1.0-FAQ
+    tags:
+      - "1.0"
+      - breaking
+      - compat
+      - beta-branch
+      - rollback
+    detail: "Iron Gate's own 1.0 FAQ says the same from the publisher's side: there is no official mod
+      support on PC or consoles, no Steam Workshop, and no guarantee any mod will function at 1.0
+      (https://valheim.com/support/valheim-1-0-faq/)."
+  - id: valheim.game.versions.iron-gate-mod-stance
+    claim: Iron Gate's standing public statement on mods, dated 2023-05-29, is that "any creating and
+      using of mods is done at your own risk, and that we can't guarantee that mods will be
+      compatible with newer versions", and that the studio "does not condone locking modded content
+      behind a paywall" and urges authors to keep mods freely available.
+    status: community
+    source: https://valheim.com/news/regarding-mods/
+    tags:
+      - legal
+      - norm
+      - iron-gate
+      - official
+      - paid-mods
+    detail: This post is a tolerance statement, not a licence grant, and it sits alongside a EULA that
+      says the opposite in strict terms — see
+      `valheim.game.versions.eula-prohibits-reverse-engineering`. Iron Gate's stated enforcement
+      line in this post is paywalling and passing mods off as official.
+  - id: valheim.game.versions.eula-prohibits-reverse-engineering
+    claim: "Valheim's EULA (last updated 11 June 2025) explicitly prohibits both decompilation and
+      modification: users must \"do not reverse engineer, decompile, disassemble, decipher or
+      otherwise attempt to derive the source code for any underlying software or other intellectual
+      property used to provide the Game\", and \"do not modify or adapt the Game or hack, merge,
+      translate, creative derivatives from the Game, mimic, disable the Game or tamper with them\"."
+    status: community
+    source: https://valheim.com/eula (last updated 11 June 2025)
+    tags:
+      - legal
+      - eula
+      - decompile
+      - reverse-engineering
+      - modding
+      - norm
+    detail: "The strict letter of the EULA — and of the Steam Subscriber Agreement §2.G, which likewise
+      forbids reverse engineering and derivative works — coexists with Iron Gate's own public
+      statement welcoming mods (`valheim.game.versions.iron-gate-mod-stance`). Both must be
+      recorded; reporting only the tolerance statement would be a materially incomplete answer to
+      anyone asking whether decompiling is sanctioned. Practically, the whole Valheim modding
+      toolchain is built around never redistributing anything game-owned: publicizers ship as
+      patchers that rewrite the user's own local copy, not as assemblies."
+  - id: valheim.game.versions.soft-referenceable-assets-since-0-217-40
+    claim: Since 0.217.40 Valheim loads assets through a custom system Iron Gate calls "Soft
+      Referenceable Assets", backed by AssetBundles, so that Locations and Rooms can be loaded and
+      unloaded dynamically; ObjectDB and ZNetScene were stated as unaffected at the time of that
+      FAQ.
+    status: community
+    source: https://valheim.com/support/modding-faq-for-the-asset-bundle-update-0-217-40/
+    tags:
+      - assets
+      - assetbundle
+      - softreferenceableassets
+      - objectdb
+      - znetscene
+      - index
+    detail: "Iron Gate's own guidance in that FAQ is the design constraint for any ModWright vanilla
+      index: \"if your mod relies on a certain asset having a certain path, it's likely that an
+      update will break your mod\", and mods should key on AssetIDs, which \"will always stay the
+      same for each asset even if it's moved or renamed\". An index keyed on paths would be
+      re-broken by every patch; one keyed on AssetIDs would not."
+  - id: valheim.game.versions.save-locations
+    claim: Valheim's user data lives under `%USERPROFILE%\AppData\LocalLow\IronGate\Valheim`, with
+      character saves as `characters/*.fch` and worlds as `worlds/*.fwl` plus a matching `.db`; each
+      has a `.old` backup sibling (`.fch.old`, `.fwl.old`, `.db.old`).
+    status: community
+    source: https://github.com/ModOrganizer2/modorganizer-basic_games/blob/master/games/game_valheim.py
+      (`GameSavesDirectory`, `ValheimSaveGame`, `ValheimWorldSaveGame.allFiles`, `listSaves`)
+    tags:
+      - saves
+      - worlds
+      - characters
+      - locallow
+      - path
+    detail: MO2's plugin globs only `characters/` and `worlds/`; community save tools glob
+      `worlds_local/` and `characters_local/`, which is where local (as opposed to Steam-cloud)
+      saves have lived since roughly 0.209.8. Treat all four directory names as candidates to probe,
+      not as asserted paths, and see the next fact — the `.db`/`.fwl` pair itself is no longer how
+      1.0 stores a world.
+  - id: valheim.game.versions.1-0-world-saves-are-chunked-folders
+    claim: "Valheim's world save format changed with the new save system introduced in 0.221.13 and
+      shipped in 1.0: \"Worlds will no longer be saved with a .db and a .fwl file, but will instead
+      be saved and stored in separate fo[lders]\", the world is split into chunks and \"only the
+      chunks that have been modified since the last save will be affected\"."
+    status: community
+    source: 'Steam news, "Patch 0.221.13 (Public Test)", app 892970, 2026-05-06; the 1.0 notes restate
+      it as "New save system: Splits world data across chunks to reduce how much data is serialized
+      and written"'
+    tags:
+      - saves
+      - worlds
+      - format
+      - "1.0"
+      - breaking
+      - chunks
+    detail: Any tool that assumes one `<world>.db` per world — which includes every community save
+      manager written before 2026 and MO2's own `ValheimWorldSaveGame.allFiles`, which appends `.db`
+      and `.db.old` — is wrong against a 1.0 world. A Valheim surface should not model save files at
+      all until the new layout has been seen on disk.
+  - id: valheim.game.versions.windows-playerprefs-live-in-the-registry
+    claim: "On Windows there is no `prefs` file under LocalLow: Unity stores PlayerPrefs in the registry
+      under `HKCU\\Software\\<CompanyName>\\<ProductName>`, i.e.
+      `HKCU\\Software\\IronGate\\Valheim`. The `prefs` file exists only on Linux and macOS."
+    status: community
+    source: https://docs.unity3d.com/ScriptReference/PlayerPrefs.html
+    tags:
+      - prefs
+      - playerprefs
+      - registry
+      - windows
+      - unity
+      - path
+    detail: Worth stating because "the prefs file" is a common instruction in Valheim troubleshooting
+      threads written from a Linux perspective, and a surface that declares it as a Windows path
+      will report a permanently missing file.
+  - id: valheim.game.versions.player-log-location
+    claim: Unity writes the player log to
+      `%USERPROFILE%\AppData\LocalLow\<CompanyName>\<ProductName>\Player.log`, which for Valheim is
+      `%USERPROFILE%\AppData\LocalLow\IronGate\Valheim\Player.log` — the same directory as the
+      saves.
+    status: community
+    source: https://docs.unity3d.com/Manual/log-files.html (Unity 6.6 Manual, Player log locations)
+      combined with the IronGate/Valheim company and product names from
+      https://github.com/ModOrganizer2/modorganizer-basic_games/blob/master/games/game_valheim.py
+    tags:
+      - player-log
+      - unity
+      - locallow
+      - log
+      - triage
+    detail: "This is the second half of the triage story: `BepInEx/LogOutput.log` carries the loader's
+      view and, by default, none of the game's own Unity exceptions (`[Logging.Disk] WriteUnityLog`
+      is false), so a plugin that throws inside `Awake` leaves its stack trace here instead. The
+      Unity Manual page consulted does not mention a `Player-prev.log` sibling, so a previous-run
+      log should be treated as a candidate to probe rather than an asserted path."
+  - id: valheim.game.versions.mo2-lists-a-third-steam-app-id
+    claim: ModOrganizer2's Valheim plugin registers three Steam app ids — `892970` (game), `896660`
+      (dedicated server) and `1223920` — and forces `winhttp.dll` to load into `valheim.exe`, with
+      `GameDataPath = ""` meaning the game root itself is the deployment target.
+    status: community
+    source: https://github.com/ModOrganizer2/modorganizer-basic_games/blob/master/games/game_valheim.py
+      (`ValheimGame.GameSteamId`, `_forced_libraries`, `GameDataPath`)
+    tags:
+      - steam
+      - appid
+      - detect
+      - winhttp
+      - mo2
+      - deploy
+    detail: "What app `1223920` is (most plausibly a public-test or demo app) was not established from a
+      primary source in this pass and should not be asserted. The `GameDataPath = \"\"` line is the
+      interesting one: unlike every Bethesda-style game MO2 supports, Valheim's mod tree is rooted
+      at the game directory itself, because the loader files sit beside the executable."
+  - id: valheim.game.versions.mo2-mod-layout-normalisation
+    claim: "MO2's Valheim plugin encodes the community's de-facto archive layout as data: it unfolds a
+      `BepInExPack_Valheim` wrapper directory, accepts `BepInEx`, `doorstop_libs`,
+      `unstripped_corlib`, `.doorstop_version`, `doorstop_config.ini`, `start_game_bepinex.sh`,
+      `start_server_bepinex.sh`, `winhttp.dll` and `changelog.txt` at the root, deletes
+      `manifest.json`, `icon.png`, `*.md`, `*.pdb` and `*.dll.mdb`, and moves loose `*.dll` to
+      `BepInEx/plugins/` and loose `*.cfg` to `BepInEx/config/`."
+    status: community
+    source: https://github.com/ModOrganizer2/modorganizer-basic_games/blob/master/games/game_valheim.py
+      (the `BasicModDataChecker` `GlobPatterns`)
+    tags:
+      - layout
+      - packaging
+      - normalisation
+      - mo2
+      - prior-art
+      - validator
+    detail: Two things ModWright can take directly from this. The `unfold` entry for
+      `BepInExPack_Valheim` is machine-readable confirmation that the extract-the-wrapper-folder
+      mistake is common enough to encode. And the `move` table is a ready-made statement of where a
+      loose file of each type belongs, which is precisely what a packaging validator needs to check
+      against.