modwright 0.1.0

package/knowledge/valheim/install.layout.yaml

@@ -0,0 +1,216 @@
+game: valheim
+topic: install.layout
+title: Valheim install detection, folder layout, and the dedicated server as a second install kind
+facts:
+  - id: valheim.install.layout.steam-app-ids
+    claim: Valheim is Steam app `892970` and the Valheim dedicated server is a separate Steam app,
+      `896660`; Thunderstore's ecosystem schema lists both under the same `valheim` community, plus
+      an Xbox Game Pass distribution identified as `CoffeeStainStudios.Valheim`.
+    status: community
+    source: https://github.com/thunderstore-io/ecosystem-schema/blob/main/games/data/generated/valheim.yml,
+      the `distributions` list
+    tags:
+      - install
+      - steam
+      - appid
+      - dedicated-server
+      - xbox
+      - detect
+    detail: A ModWright `detect` must therefore return up to three install kinds, not one. The client
+      and the server are different apps with different folder names, different data folders and
+      different executables, but the same BepInEx install procedure.
+  - id: valheim.install.layout.steam-folder-names
+    claim: The Steam `steamapps/common` folder is `Valheim` for the client and `Valheim dedicated
+      server` for the server (note the lowercase words); the corresponding Unity data folders are
+      `valheim_Data` and `valheim_server_Data`.
+    status: community
+    source: https://github.com/thunderstore-io/ecosystem-schema/blob/main/games/data/generated/valheim.yml,
+      `steamFolderName` and `dataFolderName` on both r2modman entries
+    tags:
+      - install
+      - steam
+      - folder-name
+      - detect
+      - dedicated-server
+    detail: '`findInSteam(["Valheim", "Valheim dedicated server"])` covers both in one call, and the two
+      are distinguished after the fact by which data folder exists.'
+  - id: valheim.install.layout.executable-names
+    claim: The client executables are `valheim.exe` (Windows) and `valheim.x86_64` (Linux); the
+      dedicated server's are `valheim_server.exe` and `valheim_server.x86_64`.
+    status: community
+    source: https://github.com/thunderstore-io/ecosystem-schema/blob/main/games/data/generated/valheim.yml,
+      the `exeNames` lists on both r2modman entries
+    tags:
+      - install
+      - executable
+      - processname
+      - dedicated-server
+    detail: "`GameSurface.processNames` should carry both Windows names, because ModWright's game-exit
+      wait in `core/deploy` must recognise a running dedicated server as much as a running client."
+  - id: valheim.install.layout.msbuild-install-resolution-order
+    claim: "The Valheim-Modding org's shared `Paths.props` resolves the install in this order on
+      Windows: the `VALHEIM_INSTALL` property/environment variable if it points at an existing
+      directory, then the registry value `InstallLocation` under
+      `HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Steam App 892970`, then
+      `<SteamPath>\\steamapps\\common\\Valheim` where `SteamPath` comes from
+      `HKCU\\SOFTWARE\\Valve\\Steam`, then `C:\\Program Files\\Steam\\steamapps\\common\\Valheim`,
+      then `C:\\Program Files (x86)\\Steam\\steamapps\\common\\Valheim`."
+    status: community
+    source: https://github.com/Valheim-Modding/CommonPackages/blob/master/Paths.props, the Windows_NT
+      `<When>` block
+    tags:
+      - install
+      - detect
+      - registry
+      - msbuild
+      - valheim-install
+      - steam
+    detail: Two things ModWright can reuse directly. The `Steam App 892970` uninstall key is a per-app
+      install path Steam itself writes, so it finds an install in a library folder that
+      `libraryfolders.vdf` parsing might miss. And `VALHEIM_INSTALL` is the variable every Valheim
+      plugin project already sets, so a Valheim surface should honour it alongside its own
+      `MODWRIGHT_VALHEIM_ROOT`.
+  - id: valheim.install.layout.msbuild-bepinex-path-default
+    claim: "`Paths.props` derives `BEPINEX_PATH` as `$(VALHEIM_INSTALL)\\BepInEx` whenever
+      `BEPINEX_PATH` is unset, i.e. the convention is that BepInEx is installed into the game
+      directory itself rather than beside it."
+    status: community
+    source: https://github.com/Valheim-Modding/CommonPackages/blob/master/Paths.props, the final
+      `<PropertyGroup Condition="$(BEPINEX_PATH)==''...">`
+    tags:
+      - install
+      - bepinex
+      - path
+      - msbuild
+  - id: valheim.install.layout.linux-mac-install-paths
+    claim: On non-Windows, `Paths.props` defaults `VALHEIM_INSTALL` to
+      `$(HOME)/.steam/steam/steamapps/common/Valheim` and then `$(HOME)/Library/Application
+      Support/Steam/steamapps/common/Valheim/Contents/MacOS`.
+    status: community
+    source: https://github.com/Valheim-Modding/CommonPackages/blob/master/Paths.props, the Unix/OSX
+      `<When>` block
+    tags:
+      - install
+      - linux
+      - macos
+      - path
+    detail: The macOS path ends in `Contents/MacOS`, a bundle-internal directory — a surface that
+      appends `valheim_Data` to a bare app-bundle path on macOS will miss.
+  - id: valheim.install.layout.assemblies-under-managed
+    claim: Plugin projects reference the game's managed assemblies from `valheim_Data\Managed\` —
+      `UnityEngine.dll` directly, and `assembly_valheim` from a
+      `valheim_Data\Managed\publicized_assemblies\` subfolder produced locally by a publicizer,
+      never shipped.
+    status: community
+    source: https://github.com/Valheim-Modding/Wiki/wiki/Best-Practices, section "Referencing Assemblies"
+    tags:
+      - assemblies
+      - managed
+      - publicized
+      - reference
+      - valheim-data
+    detail: The page's stated rule is "You only need to publicize the assemblies you are referencing
+      directly in your code", and that Unity assemblies do not normally need publicizing — only the
+      Valheim ones.
+  - id: valheim.install.layout.managed-assembly-set
+    claim: The `assembly_*.dll` set a plugin project can reference is exactly eight files —
+      `assembly_valheim`, `assembly_utils`, `assembly_guiutils`, `assembly_postprocessing`,
+      `assembly_googleanalytics`, `assembly_sunshafts`, `assembly_lux` and
+      `assembly_simplemeshcombine` — plus two non-`assembly_` game DLLs Jötunn also publicizes,
+      `SoftReferenceableAssets.dll` and `gui_framework.dll`.
+    status: community
+    source: https://github.com/Valheim-Modding/Jotunn/blob/dev/JotunnLib/BuildProps/JotunnLibRefsCorlib.props
+      (the `*_publicized.dll` reference list) and
+      https://github.com/Valheim-Modding/Jotunn/blob/dev/JotunnBuildTask/JotunnBuildTask.cs
+      (`GetFiles(managedFolder, "assembly_*.dll")` plus the two explicit extras)
+    tags:
+      - assemblies
+      - managed
+      - publicize
+      - reference
+      - jotunn
+    detail: The build task globs rather than hardcodes the `assembly_*` set, so the eight names above
+      are what the current install actually ships rather than a fixed contract.
+      `SoftReferenceableAssets.dll` being on the list is the code-side counterpart of the asset
+      system Iron Gate introduced in 0.217.40.
+  - id: valheim.install.layout.data-folder-casing-differs-by-platform
+    claim: The client data folder is spelled `Valheim_Data` on Windows and `valheim_Data` on Linux;
+      Jötunn's build task says so in a comment and probes both spellings, because "Both spellings
+      resolve on the case-insensitive filesystems of Windows and macOS, so a case-sensitive lookup
+      only ever fails on Linux". The server folder is `valheim_server_Data` on every platform.
+    status: community
+    source: https://github.com/Valheim-Modding/Jotunn/blob/dev/JotunnBuildTask/JotunnBuildTask.cs
+      (`ValheimData` / `ValheimServerData` constants and the comment above them)
+    tags:
+      - install
+      - data-folder
+      - casing
+      - linux
+      - detect
+    detail: Thunderstore's ecosystem schema records the lowercase `valheim_Data`. Both are right on
+      Windows; a surface should compare case-insensitively and never branch on the spelling.
+  - id: valheim.install.layout.dedicated-server-arguments
+    claim: "Iron Gate documents the dedicated server's arguments: `-name`, `-port` (which uses the given
+      port *and* port+1; default 2456-2457), `-world`, `-password`, `-savedir`, `-public 1`,
+      `-logFile`, `-saveinterval`, `-backups`, `-backupshort`, `-backuplong`, `-crossplay`,
+      `-instanceid`, `-preset`, `-modifier` and `-setkey`. The default save path that `-savedir`
+      overrides is `%USERPROFILE%/AppData/LocalLow/IronGate/Valheim` on Windows and
+      `~/.config/unity3d/IronGate/Valheim` on Linux."
+    status: community
+    source: https://valheim.com/support/a-guide-to-dedicated-servers
+    tags:
+      - dedicated-server
+      - arguments
+      - savedir
+      - port
+      - path
+      - crossplay
+    detail: Two things ModWright can use. `-savedir` means the server's data directory is not a fixed
+      path, so a log or permission-file location must be derived from the launch arguments where
+      they are known and reported as undetermined where they are not. And the Linux default is under
+      `~/.config/unity3d/`, not LocalLow — the same company/product pair, a different Unity
+      convention.
+  - id: valheim.install.layout.server-permission-files
+    claim: The dedicated server's `adminlist.txt`, `bannedlist.txt` and `permittedlist.txt` live in the
+      default save path (or wherever `-savedir` points), and each entry is a Platform User ID
+      written as `[Platform]_[User ID]`.
+    status: community
+    source: https://valheim.com/support/a-guide-to-dedicated-servers
+    tags:
+      - dedicated-server
+      - adminlist
+      - permissions
+      - path
+      - config
+    detail: Relevant to Jötunn's config sync, whose `IsAdminOnly` enforcement keys on whether the
+      connecting player is an admin — which is decided by `adminlist.txt` on the server, not by
+      anything on the client.
+  - id: valheim.install.layout.bepinex-installs-at-server-top-level
+    claim: "On the dedicated server BepInEx installs exactly as on the client: the BepInEx pack's extra
+      top-level files (not just the `BepInEx` folder) must be placed at the top level of the server
+      install, and the server's log is `BepInEx/LogOutput.log` relative to that same root."
+    status: community
+    source: https://github.com/Valheim-Modding/Wiki/wiki/Server-Troubleshooting
+    tags:
+      - dedicated-server
+      - bepinex
+      - install
+      - logoutput
+    detail: The page's diagnostic is that if no `BepInEx/LogOutput.log` is generated after deleting it
+      and restarting, no mods loaded at all — the same zero-byte/absent-log signal ModWright already
+      models for other games' loaders.
+  - id: valheim.install.layout.server-vs-client-mod-split
+    claim: Valheim mods divide into server-side, client-side and both-sides; the community's own
+      troubleshooting guidance is to check a mod's Thunderstore tags to learn which, because a
+      client-only mod does not need to be on the server and a server-side mod does nothing if only
+      the client has it.
+    status: community
+    source: https://github.com/Valheim-Modding/Wiki/wiki/Server-Troubleshooting
+    tags:
+      - dedicated-server
+      - client
+      - deploy
+      - mod-model
+    detail: "This is why a Valheim surface's deploy targets cannot be a single root: the same built DLL
+      may need to land in two different installs, and which ones is a property of the mod, not of
+      the game."

package/knowledge/valheim/jotunn.library.yaml

@@ -0,0 +1,334 @@
+game: valheim
+topic: jotunn.library
+title: Jötunn, the Valheim modding library — managers, config sync, network compatibility, and its
+  mod stub
+facts:
+  - id: valheim.jotunn.library.what-it-is-and-version
+    claim: Jötunn ("the Valheim Library") is a BepInEx-hosted C# library that gives Valheim mods a
+      curated set of helpers for custom content and network consistency; the current release is
+      2.30.0, published 2026-09-09, whose notes say it "Updated the majority of systems for Valheim
+      1.0.7" and that piece categories are incomplete because Valheim overhauled that system.
+    status: community
+    source: https://valheim-modding.github.io/Jotunn/ ;
+      https://github.com/Valheim-Modding/Jotunn/releases (v2.30.0, 2026-09-09)
+    tags:
+      - jotunn
+      - library
+      - version
+      - valheim-1.0
+    detail: Jötunn shipped a 1.0-compatible release the same day Valheim 1.0 launched, which is the
+      practical reason a Valheim surface's compat matrix has to treat Jötunn version, BepInEx pack
+      version and game version as three independent axes.
+  - id: valheim.jotunn.library.depends-on-the-valheim-bepinex-pack
+    claim: Jötunn's Thunderstore manifest declares exactly one dependency,
+      `denikson-BepInExPack_Valheim-5.4.2333`, and its guide states plainly that the Thunderstore
+      pack must be used because "a release from Github may not work properly".
+    status: community
+    source: https://thunderstore.io/api/experimental/package/ValheimModding/Jotunn/ ;
+      https://valheim-modding.github.io/Jotunn/guides/guide.html
+    tags:
+      - jotunn
+      - bepinex
+      - dependency
+      - bepinexpack
+      - compat
+    detail: "This is a real compat rule, not advice: stock BepInEx is not configured for Valheim's entry
+      point, so \"BepInEx is installed\" is not sufficient — a Valheim compat surface must
+      distinguish the pack from stock BepInEx."
+  - id: valheim.jotunn.library.manager-classes
+    claim: "Jötunn's public surface is a set of static managers in the `Jotunn.Managers` namespace:
+      AssetManager, CommandManager, CreatureManager, DungeonManager, GUIManager, InputManager,
+      ItemManager, KeyHintManager, KitbashManager, LocalizationManager, MinimapManager,
+      NetworkManager, PieceManager, PrefabManager, RenderManager, SkillManager,
+      SynchronizationManager, UndoManager and ZoneManager."
+    status: community
+    source: https://valheim-modding.github.io/Jotunn/api/Jotunn.Managers.html
+    tags:
+      - jotunn
+      - managers
+      - api
+      - scaffold
+    detail: There is no `ConfigManager`, `RecipeManager`, `PieceTableManager` or `StatusEffectManager` —
+      config sync lives in `SynchronizationManager`, and recipes, piece tables and status effects
+      are handled through ItemManager, PieceManager and PrefabManager. A scaffold that emits a call
+      to a manager that does not exist produces a compile error, so the manager list is exactly the
+      kind of thing a validator should check against.
+  - id: valheim.jotunn.library.assetmanager-soft-referenceable
+    claim: Jötunn's `AssetManager` exists specifically to interact with Valheim's
+      "SoftReferenceableAssets" system, the custom asset-management layer Iron Gate introduced in
+      0.217.40 that loads assets through AssetBundles instead of keeping everything in memory.
+    status: community
+    source: https://valheim-modding.github.io/Jotunn/api/Jotunn.Managers.html ;
+      https://valheim.com/support/modding-faq-for-the-asset-bundle-update-0-217-40/
+    tags:
+      - jotunn
+      - assets
+      - softreferenceableassets
+      - assetbundle
+      - index
+    detail: "Iron Gate's own FAQ is the primary source for the system and says the quiet part directly:
+      \"if your mod relies on a certain asset having a certain path, it's likely that an update will
+      break your mod\", and to use AssetIDs instead because they \"will always stay the same for
+      each asset even if it's moved or renamed\". That is the strongest argument for a ModWright
+      vanilla index keyed on AssetIDs rather than paths."
+  - id: valheim.jotunn.library.jotunndoc-publishes-a-vanilla-index
+    claim: "Jötunn ships a generated, machine-readable dump of the vanilla game's content, committed in
+      the repository under `JotunnLib/Documentation/data/` and published at
+      `https://valheim-modding.github.io/Jotunn/data/`: prefab, item, piece, piece-table, recipe,
+      status-effect, location, vegetation, RPC, sprite, character, material, mesh and shader lists
+      plus localization tables for English and ~40 other languages. Each file's header names the
+      game version it was generated from — `prefab-list.md` and `item-list.md` say Valheim 1.0.7,
+      `piece-list.md` says 1.0.12 — and the generator is Jötunn's own JotunnDoc mod."
+    status: community
+    source: 'https://github.com/Valheim-Modding/Jotunn/tree/dev/JotunnLib/Documentation/data (file
+      headers read directly: "This file is automatically generated from Valheim 1.0.7 using the
+      JotunnDoc mod found on our GitHub"); generator at
+      https://github.com/Valheim-Modding/Jotunn/tree/dev/JotunnDoc'
+    tags:
+      - jotunn
+      - jotunndoc
+      - index
+      - prefabs
+      - items
+      - assetid
+      - vanilla
+    detail: "This is the single most consequential find for ModWright's `index` subsystem on this game:
+      a vanilla index can be built **without the game installed**, by parsing markdown tables out of
+      a public repository. The prefab table's columns are `Name | AssetID | Token | English Name |
+      Components | Components in Children` and the item table's are `Item | AssetID | Token |
+      English Name | Type | Description` — so the index carries exactly the AssetIDs Iron Gate's own
+      FAQ says to key on, plus the localization token and the component list. `prefab-list.md` alone
+      is 1.3 MB. The caveat is that the files are regenerated by hand when a maintainer runs
+      JotunnDoc, so different tables can be stamped with different game versions at the same time —
+      the version must be read per-file from its header, never assumed uniform."
+  - id: valheim.jotunn.library.isadminonly-config-sync
+    claim: Jötunn enforces server-side config by binding a BepInEx `ConfigEntry` with a
+      `Jotunn.Utils.ConfigurationManagerAttributes` instance whose `IsAdminOnly` is true; every
+      client connecting to that server receives the server's values, and "Local settings will be
+      overriden by the servers values as long as the client is connected to that server". In
+      single-player the player is always considered admin.
+    status: community
+    source: https://valheim-modding.github.io/Jotunn/tutorials/config.html
+    tags:
+      - jotunn
+      - config
+      - sync
+      - isadminonly
+      - server
+      - admin
+    detail: "A consequence for any ModWright deploy or verification story: a value read out of
+      `BepInEx/config/<GUID>.cfg` on a client is not necessarily the value in force. Only default
+      mod configs sync automatically; a custom config file must be registered with the
+      SynchronizationManager and still needs `IsAdminOnly` per entry."
+  - id: valheim.jotunn.library.networkcompatibility-attribute
+    claim: "`Jotunn.Utils.NetworkCompatibilityAttribute` is applied to an assembly or a class as
+      `[NetworkCompatibility(CompatibilityLevel, VersionStrictness)]`; `CompatibilityLevel` is one
+      of NotEnforced, VersionCheckOnly, EveryoneMustHaveMod, ClientMustHaveMod, ServerMustHaveMod,
+      and `VersionStrictness` is one of None, Major, Minor, Patch."
+    status: community
+    source: https://valheim-modding.github.io/Jotunn/api/Jotunn.Utils.NetworkCompatibilityAttribute.html
+      ; https://valheim-modding.github.io/Jotunn/api/Jotunn.Utils.CompatibilityLevel.html ;
+      https://valheim-modding.github.io/Jotunn/api/Jotunn.Utils.VersionStrictness.html
+    tags:
+      - jotunn
+      - networkcompatibility
+      - multiplayer
+      - version
+      - attribute
+      - validator
+    detail: The tutorial page omits `None` from VersionStrictness; the API reference lists all four. A
+      static validator reading a plugin's source can check that the attribute's arguments are
+      members of these two enums, and that a mod declaring EveryoneMustHaveMod is deployed to both
+      the client and the server install.
+  - id: valheim.jotunn.library.mismatch-panel-strings
+    claim: A Jötunn version or install mismatch disconnects the client into a panel whose section
+      headers are localized as "Failed Connection:", "Valheim Version Error:", "Missing Mods:", "Mod
+      Updates Needed:", "Mod Downgrades Needed:", "Additional Mods Loaded:" and "Further Steps:",
+      with per-mod lines such as "$1 $2 was not loaded on your game" and "Please update $1 to
+      version $2".
+    status: community
+    source: https://github.com/Valheim-Modding/Jotunn/blob/dev/JotunnLib/Localization/English.json (keys
+      `mod_compat_*`), rendered by `JotunnLib/Utils/ModCompatibility/ModCompatibility.cs`
+      `CreateErrorMessage`
+    tags:
+      - jotunn
+      - mismatch
+      - multiplayer
+      - error-message
+      - triage
+    detail: The panel's own "Further Steps" text tells the user that this check only covers Jötunn mods
+      and to read `BepInEx/LogOutput.log` on both sides for other disconnects — i.e. Jötunn itself
+      points at the file ModWright would triage. A client without Jötunn gets Valheim's own
+      "Incompatible Version" message instead, which carries none of this detail.
+  - id: valheim.jotunn.library.modstub-shape
+    claim: "`JotunnModStub` is the org's mod skeleton: a C# plugin project targeting `net48` with a
+      `JotunnLib` PackageReference, a sibling Unity project stub, an `Environment.props` the author
+      creates to define `VALHEIM_INSTALL`, and `DoPrebuild.props` whose `ExecutePrebuild` flag turns
+      on automatic generation of publicized assemblies."
+    status: community
+    source: https://github.com/Valheim-Modding/JotunnModStub (README,
+      `JotunnModStub/JotunnModStub.csproj`, `DoPrebuild.props`)
+    tags:
+      - jotunn
+      - template
+      - scaffold
+      - msbuild
+      - net48
+      - publicize
+      - dotnet
+    detail: The stub's `JotunnLib` PackageReference is pinned to 2.27.1 while the current release is
+      2.30.0, so "scaffold from the stub" and "scaffold at the current Jötunn version" are not the
+      same thing.
+  - id: valheim.jotunn.library.modstub-post-build-deploy
+    claim: "The stub's post-build step runs `scripts/publish.ps1` (or `publish.sh`) with the build
+      configuration: a Debug build copies the built `.dll` and its `.dll.mdb` into
+      `$(MOD_DEPLOYPATH)`, defaulting to `$(VALHEIM_INSTALL)\\BepInEx\\plugins`, while a Release
+      build produces a Thunderstore-ready zip under the project's `Packages` folder."
+    status: community
+    source: https://github.com/Valheim-Modding/JotunnModStub/blob/master/JotunnModStub/JotunnModStub.csproj
+      (`JotunnPostBuildTaskWin` / `JotunnPostBuildTaskUnix`) and the repo README
+    tags:
+      - jotunn
+      - deploy
+      - build
+      - msbuild
+      - thunderstore
+      - packaging
+    detail: "This is precisely the deploy-and-package step ModWright's `core/build` and `core/deploy`
+      already model, done today by an MSBuild target and a PowerShell script. A Valheim surface
+      should treat it as prior art to match, not to wrap: the interesting part is that Debug and
+      Release have different destinations, which is exactly ModWright's `variant` concept."
+  - id: valheim.jotunn.library.publicizer-is-vendored-not-a-separate-repo
+    claim: There is no publicizer repository in the Valheim-Modding organisation; the publicizer is
+      vendored inside Jötunn as `JotunnBuildTask/AssemblyPublicizer.cs`, and the community wiki's
+      manual route points at the third-party CabbageCrow AssemblyPublicizer instead.
+    status: community
+    source: https://github.com/Valheim-Modding/Jotunn/tree/dev/JotunnBuildTask ;
+      https://github.com/Valheim-Modding?tab=repositories ;
+      https://github.com/Valheim-Modding/Wiki/wiki/Best-Practices
+    tags:
+      - publicize
+      - assemblies
+      - jotunn
+      - buildtask
+      - toolchain
+    detail: Jötunn's build task globs the Managed folder for `assembly_*.dll` plus
+      `SoftReferenceableAssets.dll` and `gui_framework.dll`, finds Managed under either
+      `Valheim_Data` or `valheim_server_Data`, and writes `{OriginalName}_publicized.dll` into a
+      `publicized_assemblies` subfolder.
+  - id: valheim.jotunn.library.no-redistribution-of-game-assemblies
+    claim: "The project's stated norm on game assemblies is in the JotunnModStub README: \"These
+      assembly files are copyrighted material and you can theoretically get into trouble when you
+      distribute them in your github repository\", which is why the Unity project folder ships a
+      `.gitignore` the author is told to keep."
+    status: community
+    source: https://github.com/Valheim-Modding/JotunnModStub (README, Unity setup step 5)
+    tags:
+      - legal
+      - assemblies
+      - redistribution
+      - norm
+      - publicize
+    detail: The design consequence is Jötunn's asset-mocking system, documented as a way to "Duplicate
+      and modify Assets without the need to include copyrighted content in your plugin"
+      (https://valheim-modding.github.io/Jotunn/tutorials/asset-mocking.html). No stronger
+      licence-level clause about game-assembly redistribution was found on the Jötunn docs site or
+      repository.
+  - id: valheim.jotunn.library.jotunndoc-table-shapes
+    claim: "The JotunnDoc dumps live in subfolders of `JotunnLib/Documentation/data/` (`prefabs/` with
+      prefab, character, material, mesh and shader lists; `objects/` with item and recipe lists;
+      `pieces/` with piece and piece-table lists; `status-effects/`, `zones/` (location,
+      vegetation), `rpc/`, `gui/` (sprite), `input/`, `localization/`), every list named
+      `<kind>-list.md`. Each file opens with a title, a sentence and \"This file is automatically
+      generated from Valheim <version> using the JotunnDoc mod found on our GitHub\", then pipe
+      tables whose first column is the object's name; prefabs, items and pieces also carry
+      `AssetID`, `Token` and `English Name` columns, list-valued cells are `<ul><li>..</li></ul>`
+      (or `<dl><dd>..</dd></dl>`) HTML, and the piece and location lists are split into `## <group>`
+      sections. Three details bite a parser: the name column is written `Name<br><img
+      src=\"../../images/..\">` in the item, piece, location, character and vegetation lists, so the
+      raw cell is not the name; a long list is emitted in several chunks with the header repeated
+      after a blank line (the item list in 3, the prefab list in 4, mesh and material in 2), so one
+      file yields several tables; and the mesh list spells its key column `Asset ID`, not `AssetID`.
+      Versions disagree across the set — on the dev branch most lists say 1.0.7, the piece list says
+      1.0.12 and the input list still says 0.221.12."
+    status: community
+    source: "https://github.com/Valheim-Modding/Jotunn/tree/dev/JotunnLib/Documentation (directory
+      listing and all sixteen `*-list.md` files under data/, read 2026-09-11: e.g.
+      prefabs/prefab-list.md \"|Name |AssetID |Token |English Name |Components |Components in
+      Children |\", objects/item-list.md \"|Item |AssetID |Token |English Name |Type |Description
+      |\" whose first cell reads \"Acorn<br><img src=../../images/items/Acorn.png>\",
+      prefabs/mesh-list.md \"|SoftReference Name |Asset ID |Internal Object Name |\",
+      input/input-list.md's \"generated from Valheim 0.221.12\" header)"
+    tags:
+      - jotunn
+      - jotunndoc
+      - index
+      - markdown
+      - table
+      - assetid
+      - token
+      - version
+    detail: "`src/surfaces/valheim/index/` builds ModWright's Valheim index from exactly this shape, one
+      `jotunn_table` row per table with the file's stated version and one `entry` per row keyed on
+      AssetID, name and token, so a lookup can say which game version its answer was dumped from.
+      Parsed over the dev-branch files that is 66 tables and 15,186 rows from sixteen lists — prefab
+      4,810, mesh 3,191, sprite 2,015, material 1,696, item 1,517, piece 549, recipe 478, location
+      213 in 41 `##` groups, vegetation 213, character 162, shader 106, input 100, status-effect 96,
+      language 36, piece-table 4, and rpc 0 (its table has a header and no rows). The location,
+      vegetation, sprite, shader, language, input, piece-table and RPC lists have no AssetID column
+      and are indexed by name only."
+    related:
+      - valheim.jotunn.library.jotunndoc-publishes-a-vanilla-index
+  - id: valheim.jotunn.library.references-are-by-prefab-name-and-token
+    claim: "Jötunn's tutorials reference vanilla content by name string: a `CustomItem` or `CustomPiece`
+      clones an existing prefab by its name (`new CustomItem(\"EvilSword\", \"SwordBlackmetal\",
+      config)`, `new CustomPiece(\"our_rug_deer\", \"rug_deer\", rug)`), a recipe names the item it
+      crafts and the items it needs (`meatConfig.Item = \"CookedMeat\"; // Name of the item prefab
+      to be crafted`, `AddRequirement(\"Wood\", 1, 2)`; `RequirementConfig.Item` is documented as
+      \"Name of the item prefab of this requirement\"), a piece names its table (`PieceTable =
+      PieceTables.Hammer`, or a string — the blueprint-rune example assigns its own
+      `\"_BlueprintTestTable\"`), and display strings are `$`-prefixed localization tokens
+      (`\"$item_evilsword\"`) registered without the `$` (`AddTranslation(\"English\", new
+      Dictionary<string, string> { {\"item_evilsword\", \"Sword of Darkness\"} })`). The tutorials
+      say of both a clone source and a recipe's items: \"You must only use names of existing
+      prefabs. This can be prefabs you created, that have already been registered by another mod, or
+      that already exist in the game.\" When no translation for a token exists, \"the word to
+      translate will be fed to Valheim's own Translation class\" — so a token neither the mod nor
+      the game defines reaches the player unresolved."
+    status: community
+    source: "https://valheim-modding.github.io/Jotunn/tutorials/items.html (the EvilSword example, the
+      AssetBundle overload `new CustomItem(BlueprintRuneBundle, \"BlueprintTestRune\", fixReference:
+      false, runeConfig)`, and \"You must only use names of existing prefabs\");
+      https://valheim-modding.github.io/Jotunn/tutorials/pieces.html (the rug example, `PieceTable`,
+      `AddRequirement`, and `new CustomPieceTable(BlueprintRuneBundle, \"_BlueprintTestTable\",
+      runeTable)` followed by `makeConfig.PieceTable = \"_BlueprintTestTable\"`);
+      https://valheim-modding.github.io/Jotunn/tutorials/recipes.html (`meatConfig.Item =
+      \"CookedMeat\"` and the requirement rule);
+      https://valheim-modding.github.io/Jotunn/api/Jotunn.Configs.RequirementConfig.html (`Item`:
+      \"Name of the item prefab of this requirement\");
+      https://valheim-modding.github.io/Jotunn/api/Jotunn.Entities.CustomLocalization.html (the
+      three `AddTranslation` overloads: language plus dictionary, key plus text, and language plus
+      key plus text); https://valheim-modding.github.io/Jotunn/tutorials/localization.html
+      (\"language tokens are prefixed with a `$`\", \"the translation keys should not be prefixed
+      with a `$`\", the `Translations/{LanguageName}/{anyname}.json` layout, and the fallback to
+      Valheim's Translation class); all read 2026-09-11"
+    tags:
+      - jotunn
+      - prefab
+      - clone
+      - requirement
+      - piecetable
+      - token
+      - localization
+      - validator
+      - index
+    detail: "`valheim.plugins.vanilla-references` scans exactly these literal shapes and resolves each
+      against the JotunnDoc index or the project's own declarations — which include the names the
+      mod itself creates: a `CustomItem`/`CustomPiece` clone name, the asset name of the AssetBundle
+      constructor overload, a `CreateClonedPrefab` or `CreateEmptyPrefab` name, a `CustomPieceTable`
+      name, and every `AddTranslation` key. A name built from an expression, a constant from another
+      file, or a prefab registered by another mod is not seen or not resolvable, which is why every
+      miss is a warning."
+    related:
+      - valheim.jotunn.library.manager-classes
+      - valheim.jotunn.library.jotunndoc-publishes-a-vanilla-index