modwright 0.1.0

package/knowledge/eldenring/toolchain.cli.yaml

@@ -0,0 +1,256 @@
+game: eldenring
+topic: toolchain.cli
+title: which elden ring tools can run unattended, and which cannot
+facts:
+  - id: eldenring.toolchain.witchybnd-has-a-real-headless-mode
+    claim: WitchyBND is the unpack/repack CLI for Elden Ring binder and texture formats and it supports
+      genuine unattended use — `-p/--passive` suppresses every prompt and delay, `-s/--silent`
+      suppresses console output and implies passive, and `-u/--unpack` or `-r/--repack` pin the
+      direction so it cannot guess wrong.
+    status: community
+    source: "`public class CliOptions` in
+      https://github.com/ividyon/WitchyBND/blob/main/WitchyBND/Configuration.cs — `-p, --passive`
+      \"Will not prompt the user for any input or cause any delays. Suited for automatic execution
+      in scripts.\"; `-s, --silent` \"Will not print any console output. Inherently sets 'passive'
+      to true.\"; `-u, --unpack` \"Only perform unpack processing, no repacking.\"; `-r, --repack`
+      \"Only perform repack processing, no unpacking.\"; also `-c, --recursive`, `-d, --dcx`, `-f,
+      --flexible`, `-l, --location`, `-v, --version`"
+    tags:
+      - witchybnd
+      - cli
+      - unattended
+      - passive
+      - silent
+      - toolchain
+      - flags
+    detail: Note the flag trap - `-c` is `--recursive`, not a "cli mode" switch; there is no `--cli`.
+      The Explorer context-menu integration lives in a separate opt-in assembly, so nothing forces
+      an interactive screen. Latest release at the time of writing is 3.0.1.0 (2026-07-06), with
+      both win-x64 and linux-x64 builds, licensed GPL v3. README format list - "DCX, FFXBND, BND3,
+      BND4, BXF3, BXF4, FFXDLSE, FMG, GPARAM, LUAGNL, LUAINFO, TPF, Zero3, FXR1, FXR3, MATBIN, MTD,
+      PARAM, MQB, and ENTRYFILELIST".
+  - id: eldenring.toolchain.witchybnd-xml-is-the-text-converter
+    claim: "WitchyBND's round trip is the Elden Ring equivalent of WolvenKit's cr2w-to-json and divine's
+      lsf-to-lsx: unpacking a binder writes a sidecar manifest named `_witchy-<tag>.xml` beside the
+      extracted entries, and repacking reads it back. For a regulation/PARAMBND4 the sidecar is
+      `_witchy-bnd4.xml`."
+    status: community
+    source: '`GetFolderXmlFilename` in WitchyBND/Parsers/WFolderParser.cs returns
+      `$"_witchy-{name}.xml"`; WitchyBND/Parsers/Binder/WPARAMBND4.cs calls it with "bnd4"; the
+      README shows the same pattern for other formats (`_witchy-anibnd4.xml`, `_witchy-tae.xml`)'
+    tags:
+      - witchybnd
+      - xml
+      - roundtrip
+      - convert
+      - sidecar
+      - text-converter
+    detail: "The sidecar is not cosmetic — it carries the binder's `<version>` element and, for a
+      regulation, the regulation version, and repack validates against them. That makes a deleted or
+      hand-edited sidecar a real failure mode and a good validator target: a staged binder directory
+      with no `_witchy-*.xml` cannot be repacked at all."
+  - id: eldenring.toolchain.witchybnd-handles-regulation-encryption-itself
+    claim: WitchyBND detects a regulation.bin by filename and routes it through a dedicated PARAMBND4
+      parser that decrypts on unpack and re-encrypts on repack, and it refuses to repack a
+      regulation whose version is newer than the newest paramdef it bundles. So encryption is not a
+      step the caller has to implement.
+    status: community
+    source: WitchyBND/Parsers/Binder/WPARAMBND4.cs detects a filename containing "regulation" and ending
+      ".bin" and dispatches to the regulation decryptor/encryptor; WitchyBND's changelog for
+      v2.1.1.0 — "Repacking PARAMBND4 will now perform a dry PARAM unpack attempt on all constituent
+      PARAM files, to catch user errors attempting to pack outdated PARAMs into new regulation
+      versions" and "Repacking PARAMBND4 will now fail if the regulation version exceeds the latest
+      known regulation version in Paramdex"
+    tags:
+      - witchybnd
+      - regulation
+      - encryption
+      - paramdex
+      - version
+      - guard
+    detail: WitchyBND ships its own vendored Paramdex under WitchyBND/Assets/Paramdex/ER/ with Defs,
+      Names, Meta, Tdfs and an Upgrader/version.txt naming the newest regulation it knows. Reading
+      that file is a cheap, install-free way for `check_toolchain` to report which regulation
+      versions the installed WitchyBND can actually round-trip — a version axis no `--version` flag
+      exposes.
+  - id: eldenring.toolchain.dsmsportable-is-the-only-unattended-param-editor
+    claim: DSMSPortable is the one command-line tool that edits and merges Elden Ring params unattended.
+      It takes regulation.bin as its positional argument, defaults to Elden Ring, applies CSV or
+      mass-edit scripts, exports and diffs params, and has separate merge modes for FMG, TPF,
+      layout, HKS, EMEVD, BND and TAE files.
+    status: community
+    source: 'DSMSPortable/Program.cs usage output at https://github.com/mountlover/DSMSPortable —
+      "Usage: DSMSPortable [paramfile] [-G gametype] [-P gamepath] [-U oldvanillaparams] [-C2M ...]
+      [-R paramname:query ...] [-C csvfile ...] [-M[+] masseditfile ...] [-X paramname[:query] ...]
+      [-D diffparamfile] [-O outputpath]"; "paramfile — Path to regulation.bin file (or respective
+      param file for other FromSoft games) to modify"; "-G gametype ... The default is Elden Ring";
+      plus `--fmgentry`, `--fmgmerge`, `--layoutmerge`, `--texturemerge`, `--animerge`,
+      `--animdiff`, `--bndmerge`, `--bnddiff`, `--hksmerge`, `--emevdmerge`, `--emevddiff`'
+    tags:
+      - dsmsportable
+      - cli
+      - unattended
+      - merge
+      - massedit
+      - regulation
+      - build
+    detail: Its README is mostly a numbered exit-code table (0 success through 20 "Massedit parse
+      error", with a negative code for ".NET not installed"), which is exactly what a toolchain
+      adapter needs to classify a failure rather than just reporting non-zero. Program.cs carries
+      `VERSION = "1.9"`. Two cautions - it needs the .NET 6 Desktop Runtime, and it is unmaintained
+      and absent from the community wiki's tool database, so it is a viable but low-adoption
+      dependency rather than a safe default.
+  - id: eldenring.toolchain.every-other-editor-is-gui-only
+    claim: Smithbox, DSMapStudio, UXM Selective Unpack and DSAnimStudio are all GUI applications with no
+      documented command line. ModWright cannot drive any of them; it can only check what they
+      produced.
+    status: community
+    source: https://github.com/vawser/Smithbox README Usage section ("Once installed, click the
+      Smithbox.Vulkan.exe to launch the fully featured version of Smithbox") and its Requirements
+      section (a Vulkan 1.3 GPU); https://github.com/Nordgaren/UXM-Selective-Unpack README, which
+      describes only buttons ("The Unpack button will extract all files from the game archives,
+      unless you select files in the \"View Files\" menu"; "The Patch button will modify the
+      executable"; "the Restore button will restore the original executable and delete the extracted
+      files")
+    tags:
+      - smithbox
+      - dsmapstudio
+      - uxm
+      - dsanimstudio
+      - gui
+      - scope
+      - boundary
+    detail: This is the single biggest structural difference from the Cyberpunk and BG3 surfaces, where
+      WolvenKit CLI and divine cover most of the pipeline. Here the scriptable surface is exactly
+      two tools — WitchyBND and DSMSPortable — and everything else is a person at a keyboard. A
+      surface that claims otherwise will produce build steps that cannot run.
+  - id: eldenring.toolchain.souls-formats-is-a-library-not-a-cli
+    claim: SoulsFormats, the C# library every one of these tools is built on, ships no command-line
+      interface — it is a .NET library, GPL-3.0, and the original repository has been archived since
+      2025-05-26. The maintained continuation is soulsmods/SoulsFormatsNEXT, which is where Elden
+      Ring map support lives.
+    status: community
+    source: https://github.com/JKAnderson/SoulsFormats — archive banner dated May 26, 2025; README "A
+      .NET library for reading and writing various FromSoftware file formats, targeting .NET
+      Framework 4.6.2 and .NET Standard 2.1. Dark Souls, Demon's Souls, Bloodborne, and Sekiro are
+      the main focus, but other From games may be supported to varying degrees."; the repository's
+      top level is a solution and a library project with no console project
+    tags:
+      - soulsformats
+      - library
+      - license
+      - gpl
+      - archived
+      - soulsformatsnext
+    detail: The archived repository's MSB support stops at MSB1/2/3/B/D/N/S — there is no MSBE, so Elden
+      Ring map reading is not in it. SoulsFormatsNEXT adds Formats/MSB/MSBE/ and names Elden Ring in
+      its supported list. Both are GPL-3.0 libraries, so ModWright's only sound relationship with
+      either is to shell out to a tool that embeds them, the way it already shells out to divine and
+      WolvenKit CLI rather than linking them.
+  - id: eldenring.toolchain.uxm-patching-is-the-other-deploy-target-and-it-is-destructive
+    claim: The alternative to a loader overlay is UXM Selective Unpack, which extracts the archives to
+      loose files and patches eldenring.exe to read them. It is destructive and mutually exclusive
+      with online play, and unpacking without patching, or patching without unpacking, breaks the
+      game.
+    status: community
+    source: https://github.com/Nordgaren/UXM-Selective-Unpack README — "Enables file modding for DS1,
+      DS2, SotFS, DS3, Sekiro and Elden Ring by unpacking game archives and patching the executable
+      to load loose files instead."; "Patching the executable without also unpacking the archives
+      will crash the game, so make sure you do both."; and, under Elden Ring, "You cannot play
+      online with an modified exe, so you cannot go online with an unpacked game (Nor can you go
+      online with Mod Engine 2)"
+    tags:
+      - uxm
+      - unpack
+      - patch
+      - deploy
+      - destructive
+      - online
+      - restore
+    detail: There is a documented way back — "the Restore button will restore the original executable
+      and delete the extracted files" — which makes this reversible but not cheap. DSMapStudio's
+      README requires this path for Elden Ring ("Use UXM Selective Unpack to extract the game
+      files... at least the map, asset, chr, and msg directories are needed for basic editor
+      usage"), whereas Smithbox says "You no longer need to unpack a game for any of the editors"
+      and points at Nuxe if you do. A deploy target this coarse is a poor default; the loader
+      overlay should be the primary one.
+  - id: eldenring.toolchain.dsmsportable-exit-code-table
+    claim: "DSMSPortable's exit codes are documented in full: below 0 \".NET not installed\", 1
+      Unhandled Exception, 2 Unhandled Exception processing arguments, 3 No gamepath specified, 4
+      Could not resolve output path, 5 Unrecognized argument switch, 6 Failed to read TAE file, 7
+      Timed out loading param files, 8 Failed to save/overwrite file, 9 Failed to save param file,
+      10 Failed to generate temporary files, 11 Invalid FMG file specified, 12 XML parsing error, 13
+      Invalid in-line FMG entry, 14 Invalid sblytbnd file specified, 15 Invalid TPF file specified,
+      16 Invalid BND file specified, 17 Invalid HKS/Lua file specified, 18 Invalid msgbnd file
+      specified, 19 Invalid anibnd file specified, 20 Massedit parse error."
+    status: community
+    source: https://github.com/mountlover/DSMSPortable README.md, "DSMSPortable Error Codes" (read
+      2026-09-11), and its Requirements section naming the .NET 6.0 Desktop Runtime
+    tags:
+      - dsmsportable
+      - exit-code
+      - cli
+      - toolchain
+      - adapter
+      - dotnet
+    detail: '`src/surfaces/eldenring/tools.ts` carries the table as DSMSPORTABLE_EXIT_CODES with
+      `explainDsmsPortableExit`, so a build step can say "No gamepath specified" rather than "exit
+      3". A negative code on a fresh machine means the runtime, not the arguments.'
+    related:
+      - eldenring.toolchain.dsmsportable-is-the-only-unattended-param-editor
+  - id: eldenring.toolchain.witchybnd-version-flag-prints-the-assembly-version
+    claim: "`WitchyBND -v` (also `--version`) prints `WitchyBND v<assembly version>`, e.g. `WitchyBND
+      v3.0.1.0`, four components from the .NET assembly rather than the release tag."
+    status: community
+    source: WitchyBND/Program.cs — `if (opt.Version) ... _output.WriteLine($"{assembly.GetName().Name}
+      v{assembly.GetName().Version.ToString()}"`; Configuration.cs `[Option('v', "version", HelpText
+      = "Display version information.")]`
+    tags:
+      - witchybnd
+      - version
+      - cli
+      - toolchain
+      - flag
+    detail: The toolchain spec `witchybnd` probes with `-v` and matches the printed `WitchyBND v` prefix
+      followed by the dotted number; the regulation-version axis
+      (Assets/Paramdex/ER/Upgrader/version.txt) is a different number and is read separately.
+    related:
+      - eldenring.toolchain.witchybnd-has-a-real-headless-mode
+  - id: eldenring.toolchain.witchybnd-sidecar-shape
+    claim: WitchyBND unpacks a binder into a folder named after the file with its dots replaced by
+      dashes (`c0000.anibnd.dcx` becomes `c0000-anibnd-dcx`; a name with no dot gains `-unpacked`)
+      and writes `_witchy-<tag>.xml` inside it, `<bnd4>` for a BND4 with `<version>`, `<format>`,
+      `<bigendian>`, `<bitbigendian>`, `<unicode>`, `<extended>`, `<unk04>`, `<unk05>`, an optional
+      `<root>` (the common path prefix it stripped) and `<compression>`, then `<files>` of `<file>`
+      elements each carrying `<flags>`, `<id>`, `<path>` and, when two entries share a path, a
+      `<suffix>` such as ` (2)` that the on-disk file carries before its extension. Alongside those
+      the manifest carries `<filename>` (and `<sourcePath>` when unpacked recursively), which is
+      where repack writes the rebuilt binder. Repack reads `<version>` and `<filename>`
+      unconditionally and stops with "File not found" on any entry missing from the folder; files
+      not named in the sidecar are not packed.
+    status: community
+    source: WitchyBND/Parsers/WFolderParser.cs `GetUnpackDestPath` (`fileName.Replace('.', '-')`,
+      `-unpacked`), `GetFolderXmlFilename` (`$"_witchy-{name}.xml"`), `IsUnpacked` (the root tag
+      check), `GetRepackDestPath` ("XML does not have filename."); WitchyBND/Parsers/WParser.cs
+      `PrepareXmlManifest` and `AddLocationToXml` (`<compression>`, `<filename>`, `<sourcePath>`,
+      `<root>`); WitchyBND/Parsers/Binder/WBND4.cs `Unpack` (the element list) and `Repack`
+      (`xml.Element("version")!.Value`); WitchyBND/Parsers/WBinderParser.cs `WriteBinderFiles`
+      (`<file>` with flags, id, path, suffix) and `ReadBinderFiles` (`OSPath.Combine(srcDirPath,
+      dir, stem + suffix + ext)`, `File not found`)
+    tags:
+      - witchybnd
+      - sidecar
+      - xml
+      - unpack
+      - repack
+      - naming
+      - validator
+    detail: This is what `eldenring.binders.sidecar-entries` and `eldenring.binders.unpacked-in-package`
+      rest on. The folder-name test for "looks like an unpack folder" is a heuristic on that naming;
+      the sidecar's presence is the real evidence, and the rule says which of the two it saw. "Packs
+      only what the sidecar names" holds for the plain binder parsers (`bnd4`, `bnd3`, `bxf4`,
+      `bxf3`); WitchyBND's special modes write their own tag and folder suffix
+      (`_witchy-anibnd4.xml` in a `-wanibnd` folder) and repack the animation files they find by
+      scanning it, so the stray-file check is scoped to the four plain tags.
+    related:
+      - eldenring.toolchain.witchybnd-xml-is-the-text-converter

package/knowledge/nivalisnights/modding.runtime.yaml

@@ -0,0 +1,157 @@
+game: nivalisnights
+topic: modding.runtime
+title: Nivalis Nights modding at runtime — BepInEx 6 IL2CPP, the studio's developer mode, saves and
+  sidecars, and decoding the build's assets
+facts:
+  - id: nivalisnights.modding.runtime.bepinex-be788-il2cpp-loads-plugins
+    claim: "BepInEx 6 bleeding-edge #788 in its Unity.IL2CPP build loads plugins on Nivalis Nights: a
+      net6.0 `BasePlugin` compiled against `BepInEx/core` and the generated `BepInEx/interop` loads,
+      and its HarmonyX patches on game methods fire."
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - bepinex
+      - il2cpp
+      - loader
+      - harmony
+      - interop
+      - plugins
+    detail: The first launch after installing downloaded the Unity base libraries from
+      unity.bepinex.dev, ran Cpp2IL and generated 125 interop assemblies in about 25 s at a black
+      screen, so it needs network access. Patches on GameSceneManager.LoadArea and the
+      PlayerInventory.Money setter fired. The installed .NET 8 SDK built the net6.0 plugin after
+      fetching the 6.0.36 reference pack.
+  - id: nivalisnights.modding.runtime.devmode-postfix-opens-developer-options
+    claim: A Harmony postfix forcing `Nivalis.DevOptions.DevMode.IsDevMode` to true, applied in the
+      plugin's `Load()`, populates the studio's Developer Options catalogue, and
+      `DevOptionMenuRevised.Instance.Open()` shows its window from the main menu. Esc closes it.
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - devmode
+      - developer-options
+      - harmony
+      - bridge
+      - cheats
+    detail: The catalogue held 58 options on this build (55 on 25603526). The probe read their display
+      names and shortcuts at runtime from DevOptionMenuRevised._methodDisplayString, e.g. F3 'Toggle
+      UI Shown' and F11 'Toggle No Clip'. The postfix must be in place before the _Global scene's UI
+      loads, because the menu's Awake builds the catalogue once. Opening through Instance.Open()
+      bypasses the Ctrl+Shift+F12 hotkey and the BuildDeveloperOptionsEnabled asset flag.
+  - id: nivalisnights.modding.runtime.isdevmode-log-line-precedes-postfix
+    claim: "`Player.log` prints `isDevMode:False` even while a plugin's postfix has forced developer
+      mode on, because the game logs inside the getter before the postfix changes the return value;
+      that line is no evidence the force failed."
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - devmode
+      - logs
+      - triage
+      - player-log
+  - id: nivalisnights.modding.runtime.articy-script-runner-returns-run-success
+    claim: "`Nivalis.Dialogue.ArticyScriptRunner.DoArticyScript(string)` returns whether the script ran,
+      not the expression's value. To read a story variable, use
+      `ArticyDatabase.DefaultGlobalVariables.Variables`, a name-to-value dictionary."
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - articy
+      - story-variables
+      - bridge
+      - scripting
+    detail: "'Ava.ControlRoomUnlocked == false' returned True while the variable read True, and the
+      variable was unchanged afterwards. The dictionary held 1,822 variables on this build."
+  - id: nivalisnights.modding.runtime.save-sidecar-round-trip
+    claim: "A plugin can keep its own state beside a save: a file written from a
+      `SerializationManager.Save(string, bool)` postfix as
+      `<persistentDataPath>/<saveName>.modwright.json` and read back from a
+      `SerializationManager.Load(string)` prefix survives a save and reload, with no errors from the
+      game's save loader."
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - saves
+      - sidecar
+      - persistence
+      - mod-state
+    related:
+      - id: nivalisnights.modding.runtime.save-loader-cannot-skip-unknown-packet
+        detail: the reason mod state belongs in a sidecar and never in a new save packet
+  - id: nivalisnights.modding.runtime.steam-cloud-syncs-only-sav-and-png
+    claim: Steam Auto-Cloud for Nivalis Nights tracks only `.sav` and `.png` files in the save folder,
+      so a mod's sidecar file next to a save stays on the machine and does not follow the player to
+      another PC.
+    status: verified
+    verified_on: "25680465"
+    source: ModWright field verification
+    tags:
+      - saves
+      - steam-cloud
+      - sidecar
+  - id: nivalisnights.modding.runtime.save-loader-cannot-skip-unknown-packet
+    claim: The save loader (`ManagersSave.Load`) cannot skip a manager packet it does not recognise. It
+      logs `No packet found for guid <id>` and reads on from the wrong place, so a mod must never
+      add a save packet.
+    status: inferred
+    source: ModWright research
+    tags:
+      - saves
+      - packets
+      - compatibility
+      - uninstall
+    detail: "Packets carry a length-prefixed id and no length field, so the bytes after an unknown id
+      cannot be stepped over. Ghost blocks are different: they carry int64 absolute end offsets and
+      an unknown prefab is skipped. This was read from code; no save with an unknown packet has been
+      loaded."
+  - id: nivalisnights.modding.runtime.stripped-typetrees-decode-with-attribute-dummy-dlls
+    claim: The build's MonoBehaviour and ScriptableObject fields decode with UnityPy only through type
+      trees generated from Cpp2IL dummy DLLs made with `--use-processor
+      attributeanalyzer,attributeinjector`. TypeTreeGeneratorAPI's own IL2CPP loader fails on this
+      build, and the generated base nodes put `m_Script` 3 bytes off.
+    status: inferred
+    source: ModWright research
+    tags:
+      - index
+      - unitypy
+      - cpp2il
+      - typetrees
+      - il2cpp
+    detail: "Measured by the index build rather than observed in the engine. load_il2cpp fails with
+      'Sequence contains no matching element'. Without the attribute processors, private
+      [SerializeField] fields are missing. m_Script is read from the raw bytes instead: FileID int32
+      at 16, PathID int64 at 20. On build 25680465 every definition in the default folders decoded,
+      including the 1,589 NPCs reached through PeopleDatabase."
+  - id: nivalisnights.modding.runtime.serializereference-folders-do-not-decode
+    claim: The `quests`, `skills`, `ghosts` and `backgroundnpcconversations` Resources folders do not
+      decode through generated type trees. Their `[SerializeReference]` polymorphic fields either
+      fail ('Failed to get ref type node') or make the generator run away.
+    status: inferred
+    source: ModWright research
+    tags:
+      - index
+      - serializereference
+      - quests
+      - skills
+      - unitypy
+    detail: The quests decode passed 12 GB of memory before it was killed. newsarticles fail
+      differently, with a consistent 44-byte shortfall. The index lists all five as not indexed,
+      with these reasons.
+  - id: nivalisnights.modding.runtime.bepinex6-chainloader-wording
+    claim: BepInEx 6's chainloader words its lines differently from BepInEx 5. It writes `1 plugin to
+      load`, not `1 plugin(s) to load`, and `Error loading [x]:` with no space before the colon. It
+      also reworded both dependency errors. BepInEx 5 log patterns miss these lines.
+    status: inferred
+    source: BepInEx at 5b766a3, BepInEx.Core/Bootstrap/BaseChainloader.cs;
+      test/fixtures/logs/nivalisnights/real/LogOutput.head.log
+    tags:
+      - bepinex
+      - logs
+      - triage
+      - signatures
+    detail: The banner, plugin count and roll-call lines also match the real log from the field run.

package/knowledge/skyrimse/archives.bsa.yaml

@@ -0,0 +1,212 @@
+game: skyrimse
+topic: archives.bsa
+title: BSA archives — the v105 format, and how an archive gets loaded at all
+facts:
+  - id: sse.archives.bsa.version-105
+    claim: Skyrim Special Edition uses BSA version 105 (0x69). Skyrim LE uses 104 (0x68) and Oblivion
+      103 (0x67). The version field is a uint32 at offset 4 of a 36-byte header that begins with the
+      literal "BSA\0".
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format", the intro and the Header table's version row
+      ("Currently 104 (0x68) for Skyrim or 105 (0x69) for Skyrim Special Edition"); the same mapping
+      appears in Ryan-rsm-McKenzie/bsa include/bsa/tes4.hpp
+    tags:
+      - bsa
+      - archive
+      - version
+      - byte-layout
+      - parser
+    detail: UESP's stated reason for the split - "Bethesda serializes structs directly, including
+      undefined padding bits" - explains why the difference is purely in the folder record's
+      padding.
+  - id: sse.archives.bsa.v105-uses-lz4
+    claim: A compressed file block in a v105 (Skyrim SE) archive is a uint32 original size followed by
+      LZ4-compressed data. v104 (Skyrim LE) uses zlib for the same block.
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format", section "Compressed File block" ("File data
+      that has been compressed with zlib (v104) or LZ4 (v105)"); Ryan-rsm-McKenzie/bsa
+      include/bsa/tes4.hpp ("The v105 format uses lz4")
+    tags:
+      - bsa
+      - archive
+      - compression
+      - lz4
+      - zlib
+      - parser
+  - id: sse.archives.bsa.folder-record-is-24-bytes-in-v105
+    claim: The v104 to v105 structural difference is the folder record. v104's is 16 bytes (8-byte name
+      hash, uint32 count, uint32 offset); v105's is 24, inserting a uint32 padding after count and
+      another after offset. The folder offset needs totalFileNameLength subtracted to become a real
+      file offset.
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format", section "Folder Record"
+    tags:
+      - bsa
+      - archive
+      - byte-layout
+      - parser
+      - v104-vs-v105
+    detail: The file record stays 16 bytes in both (8-byte hash, uint32 size, uint32 offset). Folders
+      and files must be sorted by their 64-bit hash values.
+  - id: sse.archives.bsa.compressed-flag-means-default-not-all
+    claim: Archive flag 0x4 ("Compressed Archive") does not mean every file is compressed; it means
+      files are compressed by default. Bit 30 (0x40000000) of a file record's size field inverts
+      that default for the individual file.
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format", the archiveFlags table ("This does not mean
+      all files are compressed. It means they are compressed by default") and the File Record
+      section
+    tags:
+      - bsa
+      - archive
+      - compression
+      - flags
+      - parser
+      - gotcha
+    detail: A reader that assumes the archive flag applies uniformly will decompress uncompressed data
+      on any archive with mixed content.
+  - id: sse.archives.bsa.directory-and-file-name-flags-are-required
+    claim: Archive flags 0x1 (Include Directory Names) and 0x2 (Include File Names) are set in every
+      official BSA, and UESP notes for each that the game may not load a BSA without the bit set.
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format", archiveFlags table, bits 1 and 2
+    tags:
+      - bsa
+      - archive
+      - flags
+      - validation
+    detail: Other archiveFlags of note - 0x40 Xbox360 (all numbers and hashes big-endian), 0x100 Embed
+      File Names, 0x200 XMem codec (Xbox 360 only, requires 0x4). fileFlags is a separate
+      content-type mask - 0x1 Meshes, 0x2 Textures, 0x4 Menus, 0x8 Sounds, 0x10 Voices, 0x20
+      Shaders, 0x40 Trees, 0x80 Fonts, 0x100 Miscellaneous.
+  - id: sse.archives.bsa.two-ini-keys-under-archive-section
+    claim: The archive list lives in skyrim.ini under the [Archive] section in TWO keys,
+      SResourceArchiveList and SResourceArchiveList2. The second exists because the value is capped
+      - a joined list longer than 255 characters is split at the last comma before position 256.
+    status: community
+    source: ModOrganizer2/modorganizer-game_skyrimse src/skyrimsedataarchives.cpp
+      (SkyrimSEDataArchives::archives reads both keys; writeArchiveList performs the split);
+      modorganizer-game_gamebryo src/gamebryo/gamebryodataarchives.cpp getArchivesFromKey, which
+      passes the literal section name L"Archive" to GetPrivateProfileStringW
+    tags:
+      - bsa
+      - archive
+      - ini
+      - skyrim-ini
+      - sresourcearchivelist
+      - gotcha
+    detail: Reading only the first key silently misses every archive in a long list's tail. MO2 reads
+      skyrim.ini from the profile directory when profile-specific INI files are enabled, and from
+      Documents\My Games\<name> otherwise.
+  - id: sse.archives.bsa.seventeen-vanilla-archives
+    claim: Skyrim SE ships seventeen vanilla archives - Skyrim - Textures0 through Textures8, Meshes0
+      and Meshes1, Voices_en0, Sounds, Interface, Animations, Shaders and Misc.
+    status: community
+    source: ModOrganizer2/modorganizer-game_skyrimse src/skyrimsedataarchives.cpp,
+      SkyrimSEDataArchives::vanillaArchives
+    tags:
+      - bsa
+      - archive
+      - vanilla
+      - inventory
+  - id: sse.archives.bsa.bsarch-is-part-of-xedit
+    claim: BSArch, the command-line BSA packer, lives inside the xEdit repository at Tools/BSArchive and
+      is what xEdit itself uses - xEdit's own .bsa/.ba2 code was replaced by BSArch's.
+    status: community
+    source: github.com/TES5Edit/TES5Edit Tools/BSArchive/bsarch.dpr (program bsarch; {$APPTYPE CONSOLE}
+      sVersion = '0.7', MPL 1.1); whatsnew.md ("xEdit specific code for .bsa/.ba2 has been
+      completely replaced with the code from BSArch")
+    tags:
+      - bsa
+      - bsarch
+      - toolchain
+      - xedit
+      - packing
+  - id: sse.archives.bsa.bsarch-pack-syntax
+    claim: BSArch packs a Skyrim SE archive with `bsarch pack <folder> <archive.bsa> -sse [-z] [-share]
+      [-mt]`, where -sse selects the v105 format, -z compresses, -share deduplicates
+      binary-identical files and -mt runs multi-threaded.
+    status: community
+    source: github.com/TES5Edit/TES5Edit Tools/BSArchive/bsarch.dpr, the help text, whose SSE example is
+      `bsarch pack "d:\my mod\data" "d:\my mod\data\new.bsa" -sse -z`
+    tags:
+      - bsa
+      - bsarch
+      - cli
+      - packing
+      - build-step
+      - toolchain
+    detail: The -af and -ff flag overrides apply to "Oblivion, Fallout 3/NV and Skyrim LE archives
+      only". BSArch's exit code is 1 only on an unhandled exception - there are no granular codes.
+  - id: sse.archives.bsa.compressed-archives-break-sound
+    claim: Sounds and voices do not work in compressed archives in any Bethesda game. A single sound or
+      voice file among thousands forces the whole archive to be uncompressed.
+    status: community
+    source: github.com/TES5Edit/TES5Edit Tools/BSArchive/bsarch.dpr, the -z parameter's help text ("Keep
+      in mind that sounds and voices don't work in compressed archives in all Bethesda games! Even
+      if your archive contains a single sound/voice file out of thousands, it must be
+      uncompressed.")
+    tags:
+      - bsa
+      - compression
+      - audio
+      - gotcha
+      - build-step
+      - validator
+    detail: A build step that packs with -z should refuse, or warn, when the staged tree contains
+      anything under sound/ or a .fuz/.xwm/.wav file. The symptom in game is silence, not an error.
+  - id: sse.archives.bsa.file-record-blocks-and-name-block
+    claim: "After the folder records come the file record blocks, one per folder in folder-record order:
+      a bzstring folder name (a length byte, the lower-case backslash-separated name, a terminating
+      \\0) when archive flag 0x1 is set, then that folder's 16-byte file records (8-byte name hash,
+      uint32 size, uint32 offset from the start of the file). Then, when flag 0x2 is set, the file
+      name block: every file's lower-case name with no path, \\0-terminated, in the same order as
+      the records. The folder record's offset field is the block's offset plus totalFileNameLength."
+    status: community
+    source: en.uesp.net "Skyrim Mod:Archive File Format" (read 2026-09-11), sections "File Record
+      blocks" ("name | bzstring | Name of the folder. Only present if Bit 1 of archiveFlags is
+      set."), "File Record" ("offset ... is offset from file byte zero (start), NOT from this
+      location"), "File Name block" ("If archive flag 0x2 is not set, this block is omitted. A block
+      of lower case file names, one after another, each ending in a \0. They are ordered in the same
+      order as those generated with the file folder block contents"), and "Folder Record" ("Subtract
+      totalFileNameLength to get the actual offset within the file.")
+    tags:
+      - bsa
+      - archive
+      - byte-layout
+      - parser
+      - names
+    detail: With both name flags set (every official archive), the whole table is a deterministic length
+      from the header alone (header, folder records, the folder names plus one length byte each, the
+      file records, the file names), so a reader can fetch exactly the table and never the payloads.
+      The page was readable on 2026-09-11 without the Cloudflare challenge met earlier in ModWright
+      research; the same-base-name loading rule is still not on it.
+  - id: sse.archives.bsa.name-hash-algorithm
+    claim: "A record's 64-bit hash is the Tes4/Tes5 pair: the name lower-cased with forward slashes made
+      backslashes; for a file, split at the last dot into root and extension. The low 32 bits are
+      (last root char) | (second-last root char << 8, when the root is longer than two) | (root
+      length << 16) | (first root char << 24), with 0x80 (.kf), 0x8000 (.nif), 0x8080 (.dds) or
+      0x80000000 (.wav) set on top for those four extensions. The high 32 bits are the sum of two
+      folds with multiplier 0x1003f: over the root's characters from the second to the third-last,
+      and over the extension including its dot. A folder hashes whole, with no extension split and
+      no leading or trailing slash."
+    status: community
+    source: "en.uesp.net \"Oblivion Mod:Hash Calculation\" (read 2026-09-11): the Overview (\"The hash
+      cannot be calculated using / (forward slashes) or upper case characters ... Folder hash values
+      must not include leading or trailing slashes ... The extension must include the '.'\") and its
+      Python and C implementations, which agree on these four extensions; the transcription follows
+      the Python, which compares the whole extension string, rather than the C, which loads four
+      bytes at the dot and so would also set the bit for a longer extension beginning \".nif\",
+      \".dds\" or \".wav\"; the reference Python was run to produce the test vectors in
+      test/unit/skyrimse/archive-records.test.ts"
+    tags:
+      - bsa
+      - archive
+      - hash
+      - parser
+      - validator
+    detail: "This is what lets a validator check every record's hash against the name the archive
+      carries for it, with no game: a hash that is not its name's (a tool that hashed a
+      differently-cased or slash-separated name) leaves the entry unreachable by name. UESP's
+      \"Files and Dirs order\" section adds that folders and files must be sorted by these hash
+      values."