modwright 0.1.0

package/knowledge/subnautica2/modding.state.yaml

@@ -0,0 +1,210 @@
+game: subnautica2
+topic: modding.state
+title: Subnautica 2 modding — official stance, community toolchain, distribution
+facts:
+  - id: subnautica2.modding.no-official-mod-support-announced
+    claim: As of 2026-09-11, nearly four months after Early Access launch, Unknown Worlds and Krafton
+      have announced no official mod support, no modkit, no Steam Workshop and no mod.io integration
+      for Subnautica 2.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: "Negative result across four places such a statement would appear, all read 2026-09-11: the
+      Steam store page (https://store.steampowered.com/app/1962700/ — no mention of Workshop, mod
+      support or UGC anywhere, including the Early Access box); Unknown Worlds' own EA 1.1 post
+      (https://unknownworlds.com/en/news/subnautica-2-adaptive-measures-update); the Update History
+      wiki covering all eight releases (https://wiki.subnautica.com/sn2/Update_History); and the
+      shipping build itself, which mounts no mod loader."
+    tags:
+      - official
+      - mod-support
+      - modkit
+      - workshop
+      - modio
+      - absent
+      - stance
+    detail: 'There is a reported qualifier that could NOT be read first-hand: an Unknown Worlds
+      help-centre article "Will there be any mod support?"
+      (https://support.subnautica.com/hc/en-us/articles/57020140859929-Will-there-be-any-mod-support,
+      reportedly last updated 2026-04-16) is said to state that official modding support will not be
+      available initially but that they would like to consider it for future releases. That page
+      returns HTTP 403 to automated fetches on every attempt, so the wording is a search-snippet
+      paraphrase and must not be quoted as a citation until a human opens it. Separately, no source
+      says mods are DISALLOWED; the EULA was not examined. Read this as "nothing announced", not as
+      a prohibition.'
+  - id: subnautica2.modding.developer-tolerates-mods-in-patch-notes
+    claim: Unknown Worlds acknowledges and tolerates community mods in its own patch notes. The hotfix
+      posts carry, verbatim, "If you play Subnautica 2 with mods, please temporarily disable,
+      remove, or uninstall them before launching the game following the hotfix."
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: https://unknownworlds.com/en/news/subnautica-2-buddy-system-hotfix-1 ("Subnautica 2 Early
+      Access Buddy System Hotfix 1", dated 09.01.26), read first-hand 2026-09-11; the advisory
+      appears in a dedicated section near the end of the article.
+    tags:
+      - official
+      - stance
+      - mods
+      - patch-notes
+      - compatibility
+      - breakage
+    detail: "The passage continues that community mods will not be updated for compatibility with the
+      hotfix and may cause crashes on launch, and that players can re-enable them once mod creators
+      have updated. Read it as a crash-avoidance advisory, NOT an anti-mod or anti-cheat statement:
+      it assumes a mod scene exists and that mod authors will ship compatibility updates. It also
+      confirms from the developer's own mouth that mods break on every patch, which with a roughly
+      six-week update cadence (subnautica2.game.release-cadence-and-current-build) is the steady
+      state rather than an exception — a compat rule should treat it as `warn`, not `block`. Note
+      the advisory is not universal: the EA 1.2 \"Buddy System\" feature post (2026-08-19) mentions
+      mods nowhere."
+  - id: subnautica2.modding.community-org-and-modkit
+    claim: An unofficial modding organisation, `Subnautica2Modding` (distinct from the first game's
+      `SubnauticaModding`), formed at launch and maintains an unofficial modkit —
+      `Subnautica2Modding/Subnautica2-Project`, MIT licensed, built on a custom build of Unreal
+      Engine 5.6 about 10 GB smaller than stock, needing roughly 60 GB on disk. Last updated
+      2026-09-07.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: https://github.com/Subnautica2Modding/Subnautica2-Project (README and repository metadata),
+      read first-hand 2026-09-11
+    tags:
+      - modkit
+      - community
+      - unofficial
+      - editor
+      - ue5.6
+      - authoring
+    detail: "The modkit contains NO game source: verbatim, \"All code that exists in the project are
+      'stubs'—dummy code that defines the signature of game code\", and it loads the user's own
+      installed cooked assets read-only, so it requires the game installed. Its companion
+      documentation site is https://subnautica2modding.github.io/ (\"This site provides guides,
+      references, and tutorials for creating mods for Subnautica 2\", last updated 2026-06-08),
+      which documents four mod types — Lua, C++/scripting, asset replacement and blueprint script —
+      and names UE4SS, FModel, Visual Studio, VS Code, Git, Unreal Engine and Rust as the toolchain.
+      The Subnautica 2 modding Discord invite is the same as the first game's, so the two
+      communities share a server."
+  - id: subnautica2.modding.two-mod-paths-one-needs-no-loader
+    claim: The modkit offers two mod paths. Blueprint mods are packaged as pak chunks and REQUIRE an
+      external loader such as UE4SS. Plugin mods (content-only DLC plugins) are "installed to a
+      location in the game that the engine will load without any external/third party mod loader
+      required".
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: https://github.com/Subnautica2Modding/Subnautica2-Project README, read first-hand 2026-09-11
+    tags:
+      - modkit
+      - blueprint
+      - plugin
+      - dlc
+      - loader
+      - anticheat
+      - strategy
+    detail: "The loader-free plugin-mod path is the strategically important one: with no DLL injection
+      it side-steps both the unresolved anti-cheat question
+      (subnautica2.game.eos-anticheat-present-but-not-engaged) and UE4SS's rolling-prerelease
+      version problem (subnautica2.ue4ss.ue56-only-in-experimental). It covers items, crafting
+      recipes, biomods, scannables, buildings, databank entries and story goals — i.e. data-asset
+      content rather than new logic. Blueprint mods cover custom fauna, flora, biomes, items and
+      recipes, and are packaged with a plugin called SN2 Mod Tools; plugin mods are packaged with
+      Alpakit."
+  - id: subnautica2.modding.logicmods-is-folder-per-mod
+    claim: Subnautica 2's blueprint mods install as one FOLDER per mod under
+      `<install>\Subnautica2\Subnautica2\Content\Paks\LogicMods\`, containing the full IoStore
+      triplet named after the folder — `MyMod.pak`, `MyMod.utoc` and `MyMod.ucas`. Plugin mods
+      install to `Mods/` under the game directory.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: https://github.com/Subnautica2Modding/Subnautica2-Project README, read first-hand 2026-09-11
+      — verbatim, "Navigate to `<steam install>\Subnautica2\Subnautica2\Content\Paks\LogicMods\` and
+      create a folder for your mod", with packaged file names required to match the mod folder name.
+    tags:
+      - logicmods
+      - paths
+      - modroot
+      - triplet
+      - iostore
+      - layout
+      - deploy
+    detail: "This differs from the generic UE4SS description of LogicMods, which has bare `.pak` files
+      sitting directly in the directory (subnautica2.ue4ss.logicmods-blueprint-path) — the
+      folder-per-mod shape and the full triplet are a Subnautica 2 specific, and follow from the
+      game being IoStore-only. Two validator rules fall straight out: the triplet must be complete
+      (a missing `.ucas` is a silent no-op) and the file basenames must equal the folder name. One
+      caveat to carry: the README writes the plugin-mod path as `<game install dir>/Subnautica
+      2/Mods/` with a space, while every path observed in the game's own log spells it `Subnautica2`
+      with none; treat that segment as unconfirmed until checked on a real install."
+  - id: subnautica2.modding.ue4ss-fork-archived-upstream-covers-it
+    claim: A game-specific UE4SS fork, `Subnautica2Modding/Subnautica2-UE4SS`, shipped within weeks of
+      launch (1.0.0-pre.1 on 2026-05-09, 1.0.0 on 2026-05-27) and was then ARCHIVED on 2026-06-10,
+      its release note saying the fork may no longer be necessary and directing users to upstream
+      UE4SS.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: https://github.com/Subnautica2Modding/Subnautica2-UE4SS and its releases, read 2026-09-11
+    tags:
+      - ue4ss
+      - fork
+      - archived
+      - loader
+      - upstream
+      - community
+    detail: "This is a positive signal, not abandonment: it means Subnautica 2 is covered by upstream
+      UE4SS with no game-specific fork to track. But \"upstream\" here means `experimental-latest`
+      specifically, since UE 5.6 support exists nowhere else
+      (subnautica2.ue4ss.ue56-only-in-experimental). Corroboration comes from an unrelated
+      direction: Nexus Mods' Vortex extension for the game routes UE4SS Lua mods to
+      `Binaries/Win64/ue4ss/Mods/`, which is the UE4SS EXPERIMENTAL install layout, not the stable
+      one (subnautica2.ue4ss.install-layout-stable-vs-experimental)."
+  - id: subnautica2.modding.distribution-channels
+    claim: Subnautica 2 mods are distributed on Nexus Mods (with a Vortex game extension) and CurseForge
+      (~100 projects). Thunderstore does NOT host a Subnautica 2 community, in contrast to the first
+      game.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: Nexus support established WITHOUT fetching nexusmods.com, via
+      https://github.com/Nexus-Mods/game-subnautica2 ("Vortex 2.0+ game extension for Subnautica 2
+      (UE5 / UE4SS)", repo archived 2026-06-16); https://www.curseforge.com/subnautica-2 (categories
+      Mods, Blueprints, UE4SS Mods, Configs); https://thunderstore.io/c/subnautica-2/ returns 404
+      (confirmed negative). All read 2026-09-11.
+    tags:
+      - distribution
+      - nexus
+      - vortex
+      - curseforge
+      - thunderstore
+      - modio
+    detail: "The Vortex extension is also a useful source for install paths, since it must know them:
+      pak mods → `Content/Paks/`, LogicMods → `Content/Paks/LogicMods/`, UE4SS Lua →
+      `Binaries/Win64/ue4ss/Mods/`, IoStore `.utoc`/`.ucas` → `Content/Paks/`, plus root and
+      Content/Config folder mods. It auto-discovers Steam app 1962700, an Epic catalog item, and
+      Xbox/Game Pass — and records that Xbox builds use `WinGDK` in place of `Win64` in the binaries
+      path. No mod.io integration was found for this game, consistent with the shipping build making
+      no `api.mod.io` requests (subnautica2.modding.no-official-mod-support-announced)."
+  - id: subnautica2.modding.nothing-transfers-from-subnautica-1
+    claim: Nothing mechanical transfers from the first Subnautica's modding model. The original is
+      Unity/Mono, loaded by BepInEx 5 with Nautilus as the modding API; the sequel is Unreal Engine
+      5.6.1 with UE4SS or loader-free DLC plugins. The only thing the two share is the community and
+      its Discord.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: "Subnautica 1 side, all read 2026-09-11: Tobey's BepInEx Pack
+      (https://github.com/toebeann/BepInEx.Subnautica, latest v5.4.23-pack.3.1.1, 2025-05-26,
+      bundling BepInEx 5.4.23.5 — the Mono line; BepInEx 6 is the IL2CPP line); Nautilus
+      (https://github.com/SubnauticaModding/Nautilus, \"a continuation of SMLHelper with an improved
+      codebase\"); QModManager (https://github.com/SubnauticaModding/QModManager, final release
+      4.4.4 on 2024-10-31, repo archived 2026-05-13, \"QModManager is no longer supported. We're
+      migrating to BepInEx.\")."
+    tags:
+      - subnautica1
+      - bepinex
+      - nautilus
+      - qmodmanager
+      - contrast
+      - unity
+    detail: Two premises worth correcting because they circulate widely. First,
+      `subnauticamodding.github.io` is NOT a wiki — its root is a 404 and the domain hosts the
+      Nautilus docfx API docs at `/Nautilus/` (working entry point
+      `/Nautilus/guides/dev-setup.html`); the Subnautica Modding wiki is at
+      subnauticamodding.wiki.gg. Second, `mod.json` is not a BepInEx concept — it belongs to the
+      archived QModManager, and a modern Subnautica 1 mod has no manifest file at all, taking its
+      identity from the `[BepInPlugin]` attribute on a DLL in `Subnautica\BepInEx\plugins\`. Do not
+      let the shared franchise name imply shared mechanics.

package/knowledge/subnautica2/ue5.containers.yaml

@@ -0,0 +1,72 @@
+game: subnautica2
+topic: ue5.containers
+title: what a packed Unreal container reveals from its header and footer alone
+facts:
+  - id: subnautica2.ue5.pak-footer-and-index-head
+    claim: A legacy `.pak` ends with a footer whose fixed core is, in order, the little-endian magic
+      0x5A6F12E1, the version major (u32, 1 to 11), the index offset (u64), the index size (u64) and
+      a 20-byte hash; version 4 and up put an `encrypted` byte before the magic, 7 and up a 16-byte
+      encryption key GUID before that, 9 adds a `frozen` byte after the hash, and 8 and up append
+      four (8A) or five (8B and later) 32-byte compression-method names. The index the footer points
+      at begins with the mount point as an Unreal FString, so the mount point is readable without
+      unpacking anything unless the index is encrypted.
+    status: community
+    source: repak/src/footer.rs `Footer::read` (the field order and the version-gated fields);
+      repak/src/lib.rs `Version::size()` (the same arithmetic) and `VersionMajor` (Unknown 0 ..
+      Fnv64BugFix 11); repak/src/pak.rs `Index::read` — `let mount_point = index.read_string()?` as
+      the first read after seeking to `footer.index_offset`
+    tags:
+      - pak
+      - footer
+      - magic
+      - version
+      - index
+      - mount-point
+      - repak
+      - format
+      - validator
+    detail: "`src/surfaces/subnautica2/paks.ts` scans the last 256 bytes for the magic and validates the
+      index bounds behind it rather than trial-reading each version's footer size as repak does; the
+      effect is the same. `subnautica2.paks.mount-point` compares the string it finds with
+      `../../../` (`subnautica2.game.pak-mount-point`)."
+    related:
+      - subnautica2.game.pak-mount-point
+      - subnautica2.ue5.repak-is-legacy-pak-only
+  - id: subnautica2.ue5.fstring-encoding
+    claim: "An Unreal FString on disk is an i32 length followed by the characters: a positive length
+      means that many single-byte characters including a terminating NUL, a negative length means
+      that many UTF-16LE code units including the terminator."
+    status: community
+    source: repak/src/ext.rs `read_string` — `let len = self.read_i32::<LE>()?; if len < 0 { ...
+      read_u16 ... String::from_utf16 } else { ... }`
+    tags:
+      - fstring
+      - encoding
+      - utf16
+      - pak
+      - format
+  - id: subnautica2.ue5.utoc-header
+    claim: An IoStore `.utoc` begins with the 16-byte magic `-==--==--==--==-`, then the TOC version as
+      one byte (Invalid 0, Initial 1, DirectoryIndex 2, PartitionSize 3, PerfectHash 4,
+      PerfectHashWithOverflow 5, OnDemandMetaData 6, RemovedOnDemandMetaData 7,
+      ReplaceIoChunkHashWithIoHash 8), three reserved bytes, the header size (u32) and the TOC entry
+      count (u32), all little-endian.
+    status: community
+    source: 'retoc src/lib.rs — `struct FIoStoreTocHeader { toc_magic: [u8; 16], version:
+      EIoStoreTocVersion, reserved0: u8, reserved1: u16, toc_header_size: u32, toc_entry_count: u32,
+      ... }`, `const MAGIC: [u8; 16] = *b"-==--==--==--==-"`, and the `EIoStoreTocVersion` enum in
+      declaration order'
+    tags:
+      - utoc
+      - iostore
+      - toc
+      - magic
+      - version
+      - retoc
+      - format
+      - validator
+    detail: Enough for `subnautica2.utoc.header` to tell a container from a renamed file and to notice
+      an empty one; which TOC version the 5.6.1 launch build writes has not been read from disk (the
+      game is not installed here), so the rule accepts any non-zero version.
+    related:
+      - subnautica2.ue5.iostore-utoc-ucas-split

package/knowledge/subnautica2/ue5.paks.yaml

@@ -0,0 +1,203 @@
+game: subnautica2
+topic: ue5.paks
+title: Unreal Engine 5 packaging — paks, IoStore containers, load order, signing
+facts:
+  - id: subnautica2.ue5.iostore-utoc-ucas-split
+    claim: With IoStore (the Zen Loader) enabled, UE5 packages all package data, bulk data and shader
+      data into `.utoc` + `.ucas` container pairs. The `.utoc` describes the container — chunk size
+      and offset, compression format, and whether chunks are encrypted — and the `.ucas` holds the
+      actual data.
+    status: community
+    source: https://dev.epicgames.com/documentation/en-us/unreal-engine/zen-loader-in-unreal-engine
+      ("Zen Loader in Unreal Engine"), read 2026-09-11
+    tags:
+      - iostore
+      - zen
+      - utoc
+      - ucas
+      - packaging
+      - ue5
+      - generic
+    detail: "The same page documents that IoStore is switched off by setting the `bUseIoStore` boolean
+      to `False`. Practical consequence for modding: on a game shipped with IoStore, a mod that
+      provides only a legacy `.pak` for content the Zen Loader expects in a container will mount
+      without error and deliver nothing. Converting between the two forms is what `retoc` exists for
+      (subnautica2.ue5.retoc-to-zen-to-legacy)."
+  - id: subnautica2.ue5.cooked-asset-triplet
+    claim: A cooked UE asset is split across `.uasset` and possibly `.uexp` and `.ubulk` files, and all
+      of them must be copied together for the asset to work.
+    status: community
+    source: https://dev.epicgames.com/documentation/en-us/unreal-engine/working-with-cooked-content-in-the-unreal-engine
+      ("Working with Cooked Content in the Unreal Engine"), read 2026-09-11
+    tags:
+      - cooked
+      - uasset
+      - uexp
+      - ubulk
+      - assets
+      - ue5
+      - generic
+    detail: "Epic states only *that* the split happens, and notes the page \"currently only applies to
+      content for the Windows platform\". What each file holds is NOT Epic-documented: the usual
+      breakdown — `.uasset` the package header, `.uexp` the serialized export data, `.ubulk`
+      streamable bulk data — comes from UEViewer's FAQ
+      (https://github.com/gildor2/UEViewer/blob/master/Docs/FAQ.md), which says the engine \"strips
+      package header (which is in .uasset) from data — which is in .uexp file\", and that bulk data
+      is \"stored either at the end of uasset file, or in separate ubulk file\". Cite that as
+      community, not Epic."
+  - id: subnautica2.ue5.patch-pak-p-suffix
+    claim: 'A `_p` suffix on a pak filename gives it mount priority over other paks. Epic documents
+      this: "To prioritize patches, the mounting system uses a `_p` at the end of the filename to
+      determine that it gets priority over other PAK files", and the file "can be renamed, but you
+      need to include the `_p.pak` at the end of the file name".'
+    status: community
+    source: https://dev.epicgames.com/documentation/unreal-engine/how-to-create-a-patch-in-unreal-engine
+      ("How to Create a Patch in Unreal Engine"), read 2026-09-11
+    tags:
+      - pak
+      - load-order
+      - priority
+      - patch
+      - _p
+      - ue5
+      - generic
+    detail: The same page states a patch pak "will automatically be mounted when it is located on the
+      device in any of the PAK search directories set in `FPakPlatformFile::GetPakFolders`". This is
+      the one Epic-documented load priority mechanism and should be preferred in writing over the
+      `~mods` convention wherever both would work.
+  - id: subnautica2.ue5.tilde-mods-is-a-convention
+    claim: "`Content/Paks/~mods/` is a COMMUNITY convention, not an Epic feature. Epic documents no
+      `~mods` folder anywhere. It works only because `~` sorts late in the alphabetical scan of the
+      pak search directories, so paks there mount later and win — the same ordering mechanism the
+      documented `_p` suffix exploits by a different route."
+    status: community
+    source: 'Negative result: searching dev.epicgames.com for "~mods" returns nothing (checked
+      2026-09-11). The mechanism is Epic-documented at
+      https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/PakFile/FPakPlatformFile
+      (`GetPakFolders`, `GetPakOrderFromPakFilePath`, `Mount`), read 2026-09-11.'
+    tags:
+      - tilde-mods
+      - load-order
+      - convention
+      - pak
+      - ue5
+      - generic
+      - caveat
+    detail: "Within `~mods`, ordering is by filename and later wins. Because it is a convention rather
+      than a feature, whether any particular game honours it must be confirmed per game rather than
+      assumed — for Subnautica 2 that is an open question: the game's own unofficial modkit routes
+      mods to `Content/Paks/LogicMods/` and `Mods/` and never mentions `~mods`."
+  - id: subnautica2.ue5.mount-order-and-mount-point
+    claim: "`FPakPlatformFile::Mount(InPakFilename, PakOrder, InPath, ...)` takes a mount priority
+      (`PakOrder`) and a mount point (`InPath`, \"Path to mount the pak at\"). The engine's built-in
+      default ordering is, per its own doc comment, \"game main pak -> game content -> engine
+      content -> saved dir\"."
+    status: community
+    source: https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/PakFile/FPakPlatformFile
+      (`Mount`, `GetPakOrderFromPakFilePath`), read 2026-09-11
+    tags:
+      - mount
+      - mount-point
+      - load-order
+      - pak
+      - ue5
+      - generic
+    detail: "The mount point is the load-bearing part for mod authoring: a pak built with the wrong
+      mount point mounts cleanly and resolves its files to the wrong virtual paths, so nothing in it
+      is ever found and nothing is logged. The engine-root-relative `../../../` is the usual correct
+      value for game content and is also `repak`'s default
+      (subnautica2.ue5.repak-is-legacy-pak-only). Epic's API doc adds that in most cases `Mount`
+      \"should not be called directly. Instead use the mounting delegates in `FCoreDelegates`.\""
+  - id: subnautica2.ue5.pak-signing-and-encryption-settings
+    claim: 'Pak signing and encryption are project settings, exposed by `UCryptoKeysSettings`:
+      `bEnablePakSigning` ("Enable signing of pak files, to prevent tampering of the data"),
+      `bEncryptPakIndex`, `bEncryptUAssetFiles`, `bEncryptAllAssetFiles`, `EncryptionKey`, and the
+      RSA `SigningModulus` / `SigningPrivateExponent` / `SigningPublicExponent`.'
+    status: community
+    source: https://dev.epicgames.com/documentation/unreal-engine/API/Plugins/CryptoKeys/UCryptoKeysSettings,
+      read 2026-09-11; `FPakSignatureFile` ("Structure which describes the content of the pak `.sig`
+      files") at
+      https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/PakFile/FPakSignatureFile
+    tags:
+      - signing
+      - encryption
+      - crypto
+      - sig
+      - security
+      - ue5
+      - generic
+    detail: When signing is on, the build emits `.sig` files holding SHA1 chunk hashes and an RSA
+      signature, and a mod pak that does not satisfy them is rejected — the most likely hard blocker
+      to pak modding on any given title. Runtime AES keys are registered through
+      `FPakPlatformFile::RegisterEncryptionKey`. Note that `crypto.json` and UnrealPak's
+      `-cryptokeys=` flag, which every tooling guide uses, are community-documented and appear
+      nowhere in Epic's docs. An all-zero `SignatureHash` in the log's TOC line is how an unsigned
+      container presents.
+  - id: subnautica2.ue5.log-location-and-verbosity-ladder
+    claim: A UE game writes its logs to `<Project>/Saved/Logs`, keeping previous sessions alongside the
+      current one. The verbosity ladder is Fatal, Error, Warning, Display, Log, Verbose,
+      VeryVerbose; Display goes to console and file, `Log` goes only to the log file, and
+      Verbose/VeryVerbose only when explicitly enabled.
+    status: community
+    source: https://dev.epicgames.com/documentation/en-us/unreal-engine/logging-in-unreal-engine
+      ("Logging in Unreal Engine"), read 2026-09-11
+    tags:
+      - logs
+      - saved
+      - verbosity
+      - ue5
+      - generic
+      - triage
+    detail: For a packaged Windows game the directory resolves under
+      `%LOCALAPPDATA%\<ProjectName>\Saved\Logs`. Epic documents the location and the ladder but
+      neither the log line format nor the backup filename pattern — see
+      subnautica2.ue5.log-line-format.
+  - id: subnautica2.ue5.log-line-format
+    claim: "UE log lines are `[YYYY.MM.DD-HH.MM.SS:mmm][frame]LogCategory: Verbosity: message`, with the
+      frame counter space-padded to three columns — but the verbosity token is OMITTED for the
+      default `Log` level, and the whole bracketed prefix can be absent."
+    status: community
+    source: "Format not documented by Epic. Line shape from
+      https://nerivec.github.io/old-ue4-wiki/pages/logs-printing-messages-to-yourself-during-runtim\
+      e.html and from real logs; the omitted-verbosity and absent-prefix cases were both observed
+      directly (a real Epic-hosted UE 5.3 Lyra log has every line bare, e.g. `LogInit: Display:
+      Running engine for game: LyraStarterGame`, under a `Log file open, 09/15/23 23:30:49` header).
+      Read 2026-09-11."
+    tags:
+      - logs
+      - format
+      - parsing
+      - gotcha
+      - ue5
+      - generic
+      - signatures
+    detail: "Both exceptions are traps for a signature classifier. A pattern requiring `Category:
+      Verbosity:` misses every default-level line, which is most of them; a pattern anchored on a
+      timestamp misses any unprefixed line. The prefix is suppressed by `-NoLogTimes`, and is also
+      simply absent from the head of a real shipping log before the timestamped logger starts — on
+      Subnautica 2 that is the first ~520 lines, which is exactly where the pak mounts and plugin
+      list are (subnautica2.game.log-head-has-no-timestamps). ModWright's existing `PRE`
+      construction in src/surfaces/cyberpunk2077/logs.ts — zero or more optional bracketed fields,
+      anchored to line start — handles both cases."
+  - id: subnautica2.ue5.log-backup-filename-stamp-order
+    claim: A UE game rotates the previous session's log to
+      `<ProjectName>-backup-YYYY.MM.DD-HH.MM.SS.log` in the same `Saved/Logs` directory — year, then
+      MONTH, then day.
+    status: community
+    verified_on: 0.10.0 (CL 113109)
+    source: "Not documented by Epic; community sources disagree, with at least one rendering the pattern
+      day-before-month. Settled empirically against real files: a Subnautica 2 session on 14 May
+      2026 produced `Subnautica2-backup-2026.05.14-17.45.04.log` (local artifacts 2026-09-11), which
+      is unambiguous because 14 cannot be a month."
+    tags:
+      - logs
+      - rotation
+      - backup
+      - filename
+      - ue5
+      - generic
+      - triage
+    detail: One new file per launch, which means each run's log carries a fresh creation time —
+      friendlier to ModWright's offsetKeys-based incremental triage than a log truncated and
+      rewritten in place. The settings that control it, `bBackupLogFiles` and `LogFileBackupCount`,
+      are likewise community-sourced rather than Epic-documented.

package/knowledge/subnautica2/ue5.tooling.yaml

@@ -0,0 +1,175 @@
+game: subnautica2
+topic: ue5.tooling
+title: Unreal Engine 5 asset and packaging tooling — mappings, FModel, UAssetAPI, repak, retoc
+facts:
+  - id: subnautica2.ue5.usmap-requires-a-running-game
+    claim: UE5 cooks properties unversioned, so a cooked asset carries no property names or types and
+      cannot be deserialized without a `.usmap` mappings file supplying the reflection schema. Every
+      route to a `.usmap` for a game that ships without one runs a dumper against the LIVE process.
+    status: community
+    source: "Dumpers: UE4SS (https://docs.ue4ss.com/dev/feature-overview/dumpers.html, `Ctrl + Numpad
+      6`), Dumper-7, and UnrealMappingsDumper (\"A dumper that generates mappings (.usmap) files for
+      datamining Unreal Engine games\", https://github.com/TheNaeem/UnrealMappingsDumper). The
+      consuming requirement is stated by UAssetAPI (\"Reading capability for the unofficial `.usmap`
+      format to parse ambiguous and unversioned properties\", https://github.com/atenfyr/UAssetAPI)
+      and by FModel's Local Mapping File setting. All read 2026-09-11."
+    tags:
+      - usmap
+      - mappings
+      - unversioned
+      - assets
+      - blocker
+      - ue5
+      - generic
+    detail: "This is the hard dependency that decides what can be built for a UE5 game WITHOUT the game
+      installed: nothing at asset level. Log parsing, packaging-shape validators, install detection,
+      tool location and load-order parsing all work from documentation and filesystem shape; asset
+      conversion, a deep index and any asset-content validator do not, because they need mappings,
+      which need a running game. The newest mappings format version referenced in tooling is v4
+      (`ExplicitEnumValues`). A mappings file older than the installed game build is the standard
+      cause of garbage-looking property names."
+  - id: subnautica2.ue5.fmodel-is-a-gui
+    claim: FModel is "an archive explorer for Unreal Engine games that uses CUE4Parse as its core
+      parsing library" — a C#/.NET WPF desktop application with no documented CLI. Latest release is
+      "FModel Aug 2026" (tag `aug-2026`), published 2026-08-02.
+    status: community
+    source: https://github.com/4sval/FModel (README) and its releases, read 2026-09-11. Note fmodel.app
+      returns HTTP 403 to automated fetches, so everything here is from the repository, its wiki and
+      the releases feed.
+    tags:
+      - fmodel
+      - gui
+      - browsing
+      - cue4parse
+      - tooling
+      - ue5
+      - generic
+    detail: "Being a GUI is the operative fact for ModWright: `ToolSpec` in src/core/toolchain/specs.ts
+      exists for CLIs the server shells out to, so FModel belongs in a surface's `guidance` as the
+      human's browsing tool, the same way WolvenKit's GUI is not a spec while WolvenKit.CLI is. Two
+      settings matter to anyone using it: the mappings file goes in Settings → General → \"Local
+      Mapping File\", and the UE Version setting is described by FModel's own wiki as \"the most
+      important setting of all\" — a wrong value produces archive and package errors that look like
+      corruption. AES keys go under Directory → AES. It exports meshes as PSK/PSKX, glTF and
+      UEFormat, textures as PNG/TGA/WebP, plus raw data and JSON. The project moved from semver
+      (last was v4.4.4, 2024-10-20) to date-named releases."
+  - id: subnautica2.ue5.uassetapi-json-round-trip
+    claim: UAssetAPI provides "JSON export and import to a proprietary format that maintains binary
+      equality" — the Unreal analogue of WolvenKit's cr2w↔json round trip, with a stronger
+      guarantee. Engine support spans roughly UE 4.13 to 5.7, so UE 5.6 is covered. Latest release
+      v1.1.0, 2026-05-01.
+    status: community
+    source: https://github.com/atenfyr/UAssetAPI (README) and
+      https://github.com/atenfyr/UAssetGUI/releases/tag/v1.1.0, read 2026-09-11
+    tags:
+      - uassetapi
+      - uassetgui
+      - json
+      - roundtrip
+      - converter
+      - ue5
+      - generic
+    detail: "Binary equality is a stronger promise than ModWright's existing converters make, and it
+      fits core/text's round-trip verification model directly. The v1.1.0 notes add two things that
+      matter: UE 5.6 and 5.7 support, and \"support for opening and saving .utoc/.ucas containers
+      directly in UAssetGUI through built-in integration with retoc\" — so the GUI can now
+      round-trip IoStore containers without a separate retoc invocation. Also added `.usmap` v4
+      support. UAssetGUI is the hand-editing front end, \"A tool designed for low-level examination
+      and modification of Unreal Engine game assets by hand\", with a CLI alongside the GUI."
+  - id: subnautica2.ue5.no-node-path-for-ue-assets
+    claim: There is no Node or TypeScript path for reading and writing UE5 cooked assets. UAssetAPI is
+      .NET ("A low-level .NET library for reading and writing Unreal Engine game assets"), UAssetGUI
+      needs the .NET 10 SDK to build, CUE4Parse (FModel's engine) is also C#, and repak and retoc
+      are Rust. Any ModWright converter must shell out to an external binary.
+    status: community
+    source: https://github.com/atenfyr/UAssetAPI, https://github.com/atenfyr/UAssetGUI (build
+      requirements), https://github.com/4sval/FModel, https://github.com/trumank/repak,
+      https://github.com/trumank/retoc — all read 2026-09-11
+    tags:
+      - node
+      - dotnet
+      - rust
+      - converter
+      - architecture
+      - ue5
+      - generic
+    detail: "Not a problem architecturally: it is exactly how the two shipped surfaces already work,
+      shelling out to divine.exe and WolvenKit.CLI.exe through core/toolchain. The one genuinely new
+      wrinkle relative to those is that a UE converter takes a `.usmap` mappings file as a required
+      INPUT, so the registry entry needs a mappings path and a missing or stale mappings file must
+      be a first-class error rather than a silent misparse."
+  - id: subnautica2.ue5.repak-is-legacy-pak-only
+    claim: repak is a Rust library and CLI for legacy `.pak` files only — it has NO IoStore support. It
+      handles pak versions 2 through 11, i.e. UE 4.0 through UE 5.3. Latest release v0.2.3,
+      2026-01-02.
+    status: community
+    source: https://github.com/trumank/repak (README, CLI subcommands and version table) and its
+      releases, read 2026-09-11
+    tags:
+      - repak
+      - pak
+      - rust
+      - packaging
+      - tooling
+      - ue5
+      - generic
+      - limitation
+    detail: Subcommands are `info`, `list`, `hash-list`, `unpack`, `pack` and `get`. It reads
+      Zlib/Gzip/Zstd but CANNOT write compressed paks, and can read but not write an encrypted index
+      (`-a/--aes-key`, base64 or hex). Its default mount point is `../../../`, which its README
+      explicitly contrasts with UnrealPak's default — convenient, since that is the correct value
+      for game content. On a UE 5.4+ IoStore game repak alone is insufficient and is only the
+      legacy-pak half of a repak+retoc pipeline. Its `list` output is the natural analogue of
+      Cyberpunk's resource listing for index building.
+  - id: subnautica2.ue5.retoc-to-zen-to-legacy
+    claim: 'retoc is the IoStore tool: "CLI tool for packing/unpacking Unreal Engine IoStore containers
+      (.utoc/.ucas) as well as converting between Zen assets and Legacy assets". `to-legacy`
+      converts Zen assets and shaders to a legacy `.pak`; `to-zen` converts the other way, which is
+      what produces something a UE 5.4+ IoStore game will actually mount. Latest release v0.1.5,
+      2026-01-02.'
+    status: community
+    source: https://github.com/trumank/retoc (README, subcommand list) and its releases, read 2026-09-11
+    tags:
+      - retoc
+      - iostore
+      - utoc
+      - ucas
+      - zen
+      - packaging
+      - tooling
+      - ue5
+      - generic
+    detail: The other subcommands are `manifest`, `info`, `list`, `verify`, `unpack`, `unpack-raw`,
+      `pack-raw`, `get`, `dump-test`, `gen-script-objects` and `print-script-objects`.
+      `gen-script-objects` matters because a Zen container must resolve its imports against the
+      game's script-object reflection table. Flags include `--aes-key`, `--version` (target engine,
+      e.g. `UE5_4`), `--override-container-header-version` and `--override-toc-version`. UE 5.3 and
+      newer are fully supported; earlier versions can produce incomplete dependency data. The
+      working pipeline for a modern IoStore game is therefore `retoc to-legacy` → edit via
+      UAssetAPI's JSON round trip → `retoc to-zen`.
+  - id: subnautica2.ue5.unrealpak-cannot-do-iostore
+    claim: UnrealPak, which ships with the engine, produces only legacy `.pak` files and neither reads
+      nor writes `.utoc`/`.ucas`; IoStore containers come from the separate `IoStoreUtilities` path
+      during staging. On an IoStore-only game it is not the packaging tool.
+    status: community
+    source: Epic documents only the entry point, `PakFileUtilities::ExecuteUnrealPak` ("Application
+      entry point") at
+      https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Developer/PakFileUtilities,
+      and the `IoStoreUtilities` module separately at
+      https://dev.epicgames.com/documentation/unreal-engine/API/Developer/IoStoreUtilities. Read
+      2026-09-11.
+    tags:
+      - unrealpak
+      - pak
+      - iostore
+      - packaging
+      - limitation
+      - ue5
+      - generic
+    detail: UnrealPak's flag list is NOT on Epic's documentation site; the commonly-cited transcription
+      of its `-help` output is from UE 4.22 and flags may have drifted. Response-file syntax is one
+      line per entry, `"<source path>" "<mounted path>" [-compress]`, invoked as `UnrealPak.exe
+      PakFile.pak -Create=ResponseFile.txt`. Do not write a ModWright ToolSpec `versionArgs` for it,
+      or for repak or retoc, on the strength of convention — src/core/toolchain/specs.ts's standing
+      rule is that a version flag is only recorded after it has been checked against the tool itself
+      or its own source.