modwright 0.1.0

package/knowledge/eldenring/params.paramdef.yaml

@@ -0,0 +1,149 @@
+game: eldenring
+topic: params.paramdef
+title: Paramdex paramdef grammar, and the two text shapes of a param export
+facts:
+  - id: eldenring.paramdef.def-grammar-is-a-c-declaration
+    claim: "A paramdef Field's Def attribute is `<type> <name>[:bits][[n]][ = default]` — the README's
+      \"Bit size and array length are written as in a C declaration\" — over exactly thirteen types:
+      s8 u8 s16 u16 s32 u32 b32 f32 angle32 f64 fixstr fixstrW dummy8. Optional child elements are
+      DisplayName, Enum, Description, DisplayFormat, EditFlags, Minimum, Maximum, Increment and
+      SortID."
+    status: community
+    source: Paramdex README "Writing Paramdefs" (`<Field Def="u16 iconId" />`); a survey of all 194
+      files under ER/Defs on 2026-09-11 (7302 Field elements) found no Def outside that pattern —
+      bitfields only on u8/u16/u32/dummy8, arrays only on dummy8/fixstr/ fixstrW, and defaults
+      combined with both (`u8 opposeTarget:1 = 1`, `dummy8 pad_3[16] = -1`)
+    tags:
+      - paramdef
+      - paramdex
+      - grammar
+      - field
+      - bitfield
+      - array
+      - default
+      - types
+    detail: Every ER def carries `<PARAMDEF XmlVersion="2">`, BigEndian False, Unicode True and
+      FormatVersion 203 (four files 202, four 106); DataVersion ranges 0 to 10. Files begin with a
+      UTF-8 BOM and an XML declaration. `src/surfaces/eldenring/paramdef.ts` parses this grammar and
+      `test/unit/eldenring/paramdef.test.ts` covers each shape with a synthetic def.
+  - id: eldenring.paramdef.def-files-are-named-after-the-param
+    claim: Paramdex's README says def "Filenames are arbitrary; apply based on the included metadata
+      after loading", but every ER def file is in fact named after the param as the editors show it
+      (EquipParamWeapon.xml) while its ParamType element is the internal name
+      (EQUIP_PARAM_WEAPON_ST). A DSMapStudio CSV export is named after the former; a WitchyBND param
+      XML records the latter in its `<type>` element.
+    status: community
+    source: Paramdex README (Defs bullet); ER/Defs listing (EquipParamWeapon.xml,
+      ReinforceParamWeapon.xml, ...); WPARAM.Unpack.cs writes `new XElement("type",
+      param.ParamType)`
+    tags:
+      - paramdef
+      - paramdex
+      - filename
+      - paramtype
+      - csv
+      - xml
+      - lookup
+    detail: "So a def index needs both keys: by ParamType for XML exports and by file stem
+      (case-insensitive) for CSV exports. ModWright's `loadParamdex` builds both."
+  - id: eldenring.paramdef.tdfs-cover-few-of-the-enums
+    claim: Paramdex ships only five tdfs for Elden Ring (GAITEM_CATEGORY, ITEMLOT_ITEMCATEGORY,
+      ItemType, LotItemCategory, SHOP_LINEUP_EQUIPTYPE) while the ER defs reference 242 distinct
+      Enum names over 1303 Enum elements (ATK_PARAM_HIT_TYPE, WEP_TYPE, SP_EFFECT_TYPE, ...). An
+      enum-value check can therefore apply only where a tdf exists, and must stay silent elsewhere
+      rather than guess.
+    status: community
+    source: "`ls ER/Tdfs` (5 files) against `grep -o '<Enum>[^<]*' ER/Defs/*.xml | sort -u` (242 names,
+      1303 elements) on 2026-09-11; Paramdex README: \"Tdfs - paramtdfs provide friendly names for
+      enumerated types. Only officially shipped with Demon's Souls.\""
+    tags:
+      - paramdef
+      - tdf
+      - enum
+      - coverage
+      - validator
+      - limits
+    detail: 'A tdf is three kinds of line: a quoted name, a quoted type, then `"Label","value"` pairs.
+      `eldenring.params.values` reports an enum mismatch as a warn, not a block, because the tdfs
+      lag the game.'
+  - id: eldenring.paramdef.paramdex-has-no-licence-file
+    claim: The Paramdex repository has no LICENSE file, so ModWright does not vendor its defs. The
+      validators read a checkout the project points at (a source of kind `paramdex`, or
+      MODWRIGHT_ELDENRING_PARAMDEX), or the copy an installed WitchyBND ships under
+      Assets/Paramdex/ER.
+    status: community
+    source: Repository root listing of soulsmods/Paramdex (README.md and per-game folders only) on
+      2026-09-11; WitchyBND tree under WitchyBND/Assets/Paramdex/
+    tags:
+      - paramdex
+      - licence
+      - vendoring
+      - distribution
+      - witchybnd
+    detail: "WitchyBND's own vendored copy is the pragmatic default: anyone repacking a regulation
+      already has it beside the exe."
+  - id: eldenring.paramdef.minimum-and-maximum-are-editor-hints
+    claim: "A def field's Minimum and Maximum are editor display bounds, not values the game enforces:
+      they are round numbers rather than type limits, they are absent on thousands of fields, and
+      131 fields carry a Maximum below their own Minimum. A validator should type-check a value
+      (range of s32, width of a bitfield) but not reject it for exceeding Maximum."
+    status: inferred
+    source: Survey of ER/Defs on 2026-09-11 — 5725 Maximum and 3527 Minimum elements over 7302 fields,
+      so Maximum is absent on 1577 and Minimum on 3775; the commonest Maximum values are 1 (1046),
+      999999999 (832), 9999 (539), 99 (380) and 99999999 (320), and 131 fields carry Maximum
+      -294967297; no source states the game reads them
+    tags:
+      - paramdef
+      - minimum
+      - maximum
+      - validator
+      - limits
+  - id: eldenring.params.dsmapstudio-csv-shape
+    claim: A DSMapStudio/Smithbox CSV param export is `ID<d>Name<d><field>...` as a header line, then
+      `<id><d><name><d><value>...` per row, with the delimiter configurable and `,` by default. A
+      null row name is written `null`, a delimiter inside a name is replaced with `-`, and a dummy8
+      byte array is written `[1|2|3]` — which is why `|` is refused as a delimiter. Import
+      recognises a header only if the first line starts with `ID<d>Name`; otherwise the columns are
+      positional.
+    status: community
+    source: DSMapStudio src/StudioCore/ParamEditor/ParamIO.cs — GenerateColumnLabels, GenerateCSV,
+      ApplyCSV (`if (csvLines[0].StartsWith($@"ID{separator}Name"))`); ParamUtils.cs
+      Dummy8Write/Dummy8Read (`"[" + b ... "|" + b`); CFG.cs `_Param_Export_Delimiter = ","` and the
+      `"|"` guard
+    tags:
+      - csv
+      - dsmapstudio
+      - smithbox
+      - export
+      - delimiter
+      - dummy8
+      - format
+    detail: Values are `val.ToString()` of the .NET cell value unless it is a `byte[]`, which goes
+      through Dummy8Write — so a `dummy8` bitfield prints bare and only an array is bracketed.
+      GenerateColumnLabels ends the header with a trailing delimiter; rows do not, though ApplyCSV
+      accepts a row carrying one extra blank trailing column (`csvs.Length == csvLength + 1 &&
+      csvs[csvLength].Trim().Equals("")`). `src/surfaces/eldenring/params.ts` reads this shape.
+  - id: eldenring.params.witchybnd-xml-shape
+    claim: "A WitchyBND param unpack is `<param>` with `<type>` (the ParamType), `<game>`,
+      `<cellStyle>`, `<paramdef>` (its own `<type>`, `<bigEndian>`, `<unicode>`, `<dataVersion>`,
+      `<formatVersion>`), `<fields>` of `<field name type arraylength bitsize sortid>` and `<rows>`
+      of `<row id name|paramdexName>`. Cells are written in one of three styles the tool's setting
+      picks: child `<field name=\"...\">value` elements, attributes named after the field, or one
+      delimited string as the row's text."
+    status: community
+    source: WitchyBND/Parsers/XML/WPARAM/WPARAM.Unpack.cs (the XElement writes, `switch (cellStyle)`
+      with `CellStyle.Element`, `Attribute`, `CSV`); WPARAM.Repack.cs reads them back the same three
+      ways and throws "Row {id} {name} is missing value for cell {fieldName}" when a cell is absent
+      and not a fixstr
+    tags:
+      - xml
+      - witchybnd
+      - unpack
+      - param
+      - cellstyle
+      - format
+    detail: With ParamDefaultValues on, a field carries `defaultValue` and rows omit cells at the
+      default, so an absent cell is not an error on repack. `CellValueToString` brackets every
+      `dummy8` cell, bitfields included (a single byte is written `[n]`), which DSMapStudio does not
+      do. ModWright reads the Element and Attribute styles and counts delimited rows as unread
+      rather than guessing the delimiter.

package/knowledge/eldenring/params.regulation.yaml

@@ -0,0 +1,142 @@
+game: eldenring
+topic: params.regulation
+title: regulation.bin, paramdefs and the central conflict problem
+facts:
+  - id: eldenring.regulation.is-an-aes-encrypted-bnd4-of-params
+    claim: regulation.bin is an AES-256-CBC encrypted BND4 container whose entries are the game's .param
+      tables. The first 16 bytes of the file are the IV in the clear, everything after is
+      ciphertext, and the 32-byte key is published in SoulsFormats. So the file has no readable
+      magic and cannot be inspected without decrypting first.
+    status: community
+    source: https://github.com/JKAnderson/SoulsFormats/blob/master/SoulsFormats/Util/SFUtil.cs
+      (`DecryptERRegulation` reads the file, calls `DecryptByteArray(erRegulationKey, ...)` and
+      returns `BND4.Read(bytes)`; the cipher block sets `cryptor.Mode = CipherMode.CBC`, `KeySize =
+      256`, `BlockSize = 128`, and splits a 16-byte `iv` off the front of the buffer before
+      decrypting the remainder); `erRegulationKey` is a 32-byte literal in the same file
+    tags:
+      - regulation
+      - aes
+      - encryption
+      - bnd4
+      - param
+      - magic
+    detail: Observed locally and consistent with the above - a real modded regulation.bin's first 64
+      bytes are uniform high-entropy noise with no `BND4` and no `DCX\0` anywhere, because bytes
+      0x00-0x0F are the random IV and 0x10 onward is ciphertext. The practical consequence for
+      ModWright is that no cheap header sniff can tell a valid regulation.bin from a corrupt one;
+      that check needs a tool.
+  - id: eldenring.regulation.paramdefs-come-from-paramdex
+    claim: A .param row is a flat record whose field names and types live outside the file, in a
+      paramdef. The community keeps Elden Ring's under `ER/` in soulsmods/Paramdex as XML, split
+      into Defs (field layout), Names (row names) and Tdfs (enum labels). Without a matching def, a
+      param is an untyped blob.
+    status: community
+    source: "https://github.com/soulsmods/Paramdex README (\"A collection of resources for working with
+      params via SoulsFormats and SoulsFormats-derived tools. Three folders are included for each
+      game: Defs - paramdefs required to edit param data, given in XML format... Names - predefined
+      row names, primarily for newer games with names stripped... Tdfs - paramtdfs provide friendly
+      names for enumerated types.\"); the repository's top level carries per-game folders including
+      `ER`"
+    tags:
+      - paramdef
+      - paramdex
+      - defs
+      - names
+      - tdfs
+      - index
+      - schema
+    detail: Paramdex's own README qualifies Elden Ring's provenance - "Paramdefs for SDT, ER, and ACVI
+      are mostly official but have been extended slightly due to updates" - i.e. the defs are close
+      to the shipped ones rather than fully reverse-engineered, which makes them a sound basis for a
+      typed validator. This is the closest Elden Ring equivalent to Cyberpunk's TweakDB schema, and
+      unlike TweakDB it is a plain-text repository ModWright can read with no game installed.
+  - id: eldenring.regulation.conflicts-are-record-level-inside-one-binary
+    claim: Two Elden Ring mods almost always both ship a whole regulation.bin, so at the file level they
+      always conflict and the loader silently picks one. The real conflict is per param row inside
+      that binary, and no loader resolves it — it must be resolved before launch, at build time.
+    status: community
+    source: https://github.com/soulsmods/ModEngine2/blob/main/installer/dist/config_eldenring.toml
+      ("Note that modengine 2 currently has no way to resolve conflicting files including
+      regulation.bin, and thus the mod with the highest priority will have the modded file be loaded
+      in the case of conflict. Some support for merging of params and potentially other assets is
+      considered for a future release."); https://github.com/soulsmods/ModEngine2 README ("this is
+      still restricted to mods that don't replace conflicting files")
+    tags:
+      - conflict
+      - regulation
+      - merge
+      - load-order
+      - build
+      - find-conflicts
+    detail: This inverts ModWright's Skyrim guidance. For Skyrim the advice is that file-level conflict
+      detection under Data/ is noisy because the real conflicts are record-level between plugins;
+      for Elden Ring the file-level conflict is real and total (one file, one winner) *and* the
+      interesting conflict is record-level inside it. A `find_conflicts` that reports "both mods
+      ship regulation.bin" is correct but useless on its own; the useful answer needs the rows.
+  - id: eldenring.regulation.smithbox-merges-by-pasting-rows-between-projects
+    claim: Smithbox's Param Merger combines two mods' regulation edits by loading the other mod as a
+      second project ("aux bank") and pasting its added and/or modified rows into yours, per param.
+      It is implemented as generated mass-edit commands, so the merge semantics are a small,
+      inspectable string language rather than a bespoke algorithm.
+    status: community
+    source: 'src/Smithbox.Program/Editors/Param Editor/Tools/ParamMerger.cs at
+      https://github.com/vawser/Smithbox — `MergeParamsAction()` builds `$"auxparam
+      {ParamMerge_TargetProject.Descriptor.ProjectName} {entry.Key}: added: paste;"` when
+      `ParamMerge_IncludeAdded`, `"... auxmodified: paste;"` when `ParamMerge_IncludeModified`, and
+      `"... !added && auxmodified: paste;"` when only the latter is set'
+    tags:
+      - smithbox
+      - merge
+      - massedit
+      - auxparam
+      - regulation
+      - conflict
+    detail: The community wiki names this as the recommended path - its tool database's "Merging"
+      section lists DSMapStudio with the note "A modding suite that supports Param merging. For ER,
+      Smithbox is recommended", Smithbox itself, and one third-party "PRE-ALPHA WIP Tool that can
+      merge regulation.bins. Use with caution." Smithbox is GUI-only, but because the merge reduces
+      to mass-edit strings the same semantics are reachable headlessly through DSMSPortable's -M/-M+
+      scripts.
+  - id: eldenring.regulation.version-is-its-own-axis
+    claim: Elden Ring publishes two version numbers per patch — an App Ver and a Regulation Ver — and a
+      param mod is pinned to the second. A facts `verified_on` and any compat rule about a
+      regulation must say which axis it means, the way ModWright already separates Cyberpunk's
+      marketing version from its PE FileVersion.
+    status: community
+    source: https://en.bandainamcoent.eu/elden-ring/news/elden-ring-patch-notes-version-117 (dated
+      27/08/2026, headed "App Ver. 1.17 | Regulation Ver. 1.17"); the same two-axis heading appears
+      on the 1.16.1 notes
+    tags:
+      - version
+      - regulation-version
+      - compat
+      - axis
+      - patch
+    detail: "The two numbers have matched on the patches seen here, which makes it easy to conflate
+      them, but they are separate fields in FromSoftware's own notes and the tooling treats them
+      separately: DSMSPortable has a `-U oldvanillaparams` switch whose whole job is upgrading a
+      mod's params from one regulation version to a newer one, reporting the rows it could not carry
+      across, and WitchyBND refuses to repack a regulation whose version exceeds the newest it has
+      paramdefs for."
+  - id: eldenring.regulation.a-vanilla-param-index-needs-the-game
+    claim: A vanilla param index — the Elden Ring answer to ModWright's TweakDB and BG3 stats indexes —
+      is paramdefs from Paramdex applied to the rows in the *game's own* regulation.bin. The defs
+      can be fetched without the game; the row data cannot.
+    status: inferred
+    source: Derived from https://github.com/soulsmods/Paramdex README (defs are field layout and row
+      names only, no values) plus DSMSPortable's usage line at
+      https://github.com/mountlover/DSMSPortable, in which `-P gamepath` is documented as "Path to
+      the main install directory for the selected game, for loading vanilla params" and is required
+      for any diff or upgrade operation
+    tags:
+      - index
+      - vanilla
+      - paramdex
+      - build-index
+      - gamepath
+      - blocked
+    detail: This is the hard boundary on what can be prepared without an install. Field names, types,
+      enums and the row-name lists are all available offline and are enough for a typed "is this
+      field real, is this value in range" validator. Actual vanilla values — what EquipParamWeapon
+      row 1234 currently says — are not, so anything phrased as "compare against vanilla" is blocked
+      on a game install.

package/knowledge/eldenring/saves.online.yaml

@@ -0,0 +1,118 @@
+game: eldenring
+topic: saves.online
+title: saves, steam cloud, anti-cheat and what makes a modded test run safe
+facts:
+  - id: eldenring.saves.one-sl2-per-steam-account-under-appdata
+    claim: Elden Ring keeps one save file, ER0000.sl2, in a folder named after the player's 17-digit
+      SteamID under %APPDATA%\EldenRing\. The game writes an ER0000.sl2.bak alongside it, and Steam
+      Cloud syncs the folder.
+    status: community
+    source: 'https://github.com/ersc-docs/ersc-docs.github.io/blob/main/pages/faq.md, "How can I use my
+      Elden Ring characters in Seamless Coop" — "Click the address line, and enter:
+      `%appdata%/EldenRing/`. Enter the folder that corresponds to your SteamID. It will have a lot
+      of numbers. Copy `ER0000.sl2`, and paste it."'
+    tags:
+      - saves
+      - sl2
+      - appdata
+      - steamid
+      - backup
+      - steam-cloud
+    detail: "Observed locally, where the game itself is no longer installed but the save folder survives
+      - %APPDATA%\\EldenRing\\<steamid64>\\ holds ER0000.sl2 and ER0000.sl2.bak at ~27.6 MB each
+      plus a steam_autocloud.vdf, which is the Steam Cloud manifest. The single-file, cloud-synced,
+      ~28 MB shape is the risk: there is no save slot directory to sandbox, so a modded run and a
+      vanilla run write the same file unless something intervenes, and Steam may then propagate the
+      result off-machine."
+  - id: eldenring.saves.modded-play-needs-a-separate-save-file
+    claim: The established way to keep modded play from touching a real save is to make the game use a
+      different save filename. Seamless Co-op does it with its own extension, defaulting to .co2,
+      and me3 does it with a profile's `savefile` field. Neither moves the save directory.
+    status: community
+    source: "https://github.com/garyttierney/me3/blob/main/docs/configuration-reference.md (\"savefile:
+      This optional field specifies the file name of the savefile the game will use instead of the
+      default one (e.g. `ER0000.sl2` in Elden Ring). It's extremely handy for compartmentalizing
+      modded content to avoid save corruption and multiplayer bans. If a file with that name does
+      not already exist, me3 copies and renames an existing base savefile. The default save
+      directory is unchanged.\");
+      https://github.com/ersc-docs/ersc-docs.github.io/blob/main/pages/faq.md (copy ER0000.sl2 and
+      \"Rename the pasted file `ER0000.co2`\")"
+    tags:
+      - saves
+      - savefile
+      - co2
+      - isolation
+      - safety
+      - testing
+    detail: Seamless Co-op's own guidance goes one step further for stacked mods - it recommends a third
+      extension so that a Mod-Engine-plus-co-op run is separate again from a plain co-op run. For
+      ModWright the practical rule is that any Elden Ring test run must state which save file it
+      will write before it launches anything, and the cheapest way to guarantee it is a `savefile`
+      line in the profile rather than manual file juggling.
+  - id: eldenring.saves.modded-launch-means-eac-never-starts
+    claim: Steam launches start_protected_game.exe, the Easy Anti-Cheat shim; a mod loader launches
+      Game\eldenring.exe directly instead, so EAC never starts. Modded play is therefore offline
+      play, and the absence of the EAC splash screen is the community's own check that a mod
+      installed correctly.
+    status: community
+    source: https://github.com/soulsmods/ModEngine2/blob/main/installer/dist/README.txt ("This includes
+      the game launching with EAC disabled so you can play with mods offline with no fear of being
+      banned."; and on renaming the launcher to "start_protected_game.exe", "game updates will
+      restore the existing exe and overwrite the Mod Engine 2 launcher if you do so");
+      https://github.com/ersc-docs/ersc-docs.github.io/blob/main/pages/how-to-install.md ("return to
+      the `Game` folder, and open `ersc_launcher.exe`. If there is no EAC splash screen on launch,
+      the mod was installed correctly!")
+    tags:
+      - eac
+      - anticheat
+      - offline
+      - launch
+      - ban
+      - start-protected-game
+    detail: 'There is no flag for this in either loader - it is purely a consequence of which executable
+      is started. The same doc names the failure mode when injection does not take: "If you are
+      getting `Inappropriate Activity Detected` after mod launch, that means that it failed to
+      load." That string is a usable triage signature even though it appears on screen rather than
+      in any log.'
+  - id: eldenring.saves.file-mods-are-not-ban-grounds-but-save-edits-may-be
+    claim: The community's own position, stated by the author of the unpacker, is that file mods have
+      never been grounds for a ban in a Souls game, but mods that alter the save may not be safe —
+      and that a modified exe cannot go online at all.
+    status: community
+    source: https://github.com/Nordgaren/UXM-Selective-Unpack README, "Bannability" section — "UXM only
+      edits data within the executable, not code, so anticheat should have no effect on it. File
+      mods in general have never been grounds for a ban in any of the Souls games, but mods that
+      alter your save may not be safe, so please consult your mod author's advice and play offline
+      if using anything dubious." and "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:
+      - ban
+      - anticheat
+      - online
+      - saves
+      - risk
+      - guidance
+    detail: "This is a community position, not a statement from FromSoftware or Bandai Namco, and should
+      be relayed as such. me3 encodes the cautious reading in code: matchmaking is blocked unless a
+      profile opts in, and its CLI help for that opt-in calls it a ban risk outright."
+  - id: eldenring.saves.the-game-writes-no-log-of-its-own
+    claim: No primary source consulted states that Elden Ring writes any log, crash log or dump of its
+      own. Every log worth triaging belongs to the loader or the tooling, not the game, so a
+      log-triage surface here speaks only for the loader.
+    status: community
+    source: Searched without a hit - the community wiki's full page index
+      (http://soulsmodding.wikidot.com/system:list-all-pages) has no crash or log page for Elden
+      Ring, and neither ModEngine2's nor me3's documentation mentions a game-written log. Mod Engine
+      2's README lists "Crash dumps for all users" as its own feature, and me3's changelog describes
+      its own minidump crash handler
+    tags:
+      - logs
+      - crash
+      - triage
+      - gap
+      - not-found
+    detail: The one game-adjacent artefact seen locally is a `crashdumps` folder in the Game directory
+      holding a Crashpad `metadata` file naming three .dmp files — but Crashpad is what Mod Engine 2
+      ships (its distribution has a crashpad/ folder with crashpad_handler.exe), so that is the
+      loader's crash handler, not the game's. Treat "the game produced no log" as the expected state
+      rather than a broken install.