modwright 0.1.0

package/knowledge/skyrimse/toolchain.xedit-spriggit.yaml

@@ -0,0 +1,336 @@
+game: skyrimse
+topic: toolchain.xedit-spriggit
+title: The unattended toolchain — xEdit switches and exit codes, Spriggit round-trip fidelity, the
+  Papyrus compiler, and what cannot be automated
+facts:
+  - id: sse.toolchain.xedit-spriggit.one-binary-renamed-or-switched
+    claim: xEdit is one executable selected by rename or by switch. Renaming it to SSEEdit makes it work
+      with Skyrim SE, and the -sse switch does the same; mode detection checks the command line
+      first and then substring-matches the executable's own filename.
+    status: community
+    source: github.com/TES5Edit/TES5Edit README.md, "xEdit versions" ("Rename to SSEEdit to work with
+      Skyrim SE"); xEdit/xeInit.pas, DetectAppMode
+    tags:
+      - xedit
+      - sseedit
+      - toolchain
+      - invocation
+    detail: The filename fallback is why SSEEditQAC.exe works. Game modes accepted by the -<gamemode>
+      switch are tes5vr, fo4vr, tes4, tes5, enderal, sse, fo3, fnv, fo4, fo76.
+  - id: sse.toolchain.xedit-spriggit.unattended-modes
+    claim: "xEdit runs without user interaction only in its wbAutoModes set. The self-closing ones take
+      a positional plugin name - -checkforerrors, -checkforitm, -checkfordr, -sortandcleanmasters,
+      -setesm, -clearesm, -masterupdate, -masterrestore, -onamupdate. -script: and -qac need
+      -autoload and -autoexit as well."
+    status: community
+    source: github.com/TES5Edit/TES5Edit Core/wbInterface.pas, wbAutoModes and wbPluginModes (commented
+      "Tool modes that run without user interaction until final status" and "Auto modes that require
+      a specific plugin to be provided"); whatsnew.md sections "Auto Exit", "Auto Load for Quick
+      [Auto] Clean"
+    tags:
+      - xedit
+      - cli
+      - unattended
+      - automation
+      - toolchain
+    detail: The documented recipe is `SSEEdit.exe -quickautoclean -autoload update.esm`. -autoexit "can
+      be used together with a number of different modes ... to have xEdit automatically close after
+      the operation is finished"; -autoload "will not show the Module Selection dialog and just load
+      all modules that are active according to plugins.txt". Neither switch appears on the docs site
+      - only in whatsnew.md.
+  - id: sse.toolchain.xedit-spriggit.exit-code-is-the-issue-count
+    claim: In the three check modes, xEdit's process exit code is the count of errors, ITMs or UDRs
+      found, capped at 127. 255 means an unexpected mode and 0 means clean or any non-check mode.
+    status: community
+    source: github.com/TES5Edit/TES5Edit xEdit/xeMainForm.pas (`if ErrorsCount>126 then CheckResult :=
+      127 else CheckResult := ErrorsCount;`, identically for ITMcount and DRcount, with `CheckResult
+      := 255;` as the fallthrough and `ExitCode := CheckResult;`)
+    tags:
+      - xedit
+      - cli
+      - exit-code
+      - automation
+      - toolchain
+      - validator
+    detail: This is the only genuinely scriptable status signal in the Skyrim toolchain and makes
+      -checkforitm usable as a build gate.
+  - id: sse.toolchain.xedit-spriggit.modals-can-still-block-a-fresh-run
+    claim: Three dialogs can still appear in an otherwise unattended xEdit run - the developer/donation
+      message (re-shown every 14 days for non-patrons), a 64-bit first-start confirmation gated on
+      the settings key Init\First64Start, and the game selection dialog when neither the exe name
+      nor a -<gamemode> switch resolves.
+    status: community
+    source: github.com/TES5Edit/TES5Edit xEdit/xeMainForm.pas (`if (not wbPatron or not xeAutoLoad) and
+      not xeTestConflicts then ShowDeveloperMessage;` and the MessageDlg gated on Init\First64Start)
+      and xEdit/xeInit.pas (TfrmGameSelect)
+    tags:
+      - xedit
+      - cli
+      - unattended
+      - gotcha
+      - first-run
+      - toolchain
+    detail: 'A first unattended run on a clean machine can therefore hang. A separate trap - if the
+      script named by -script: does not exist, xEdit opens a file-open dialog titled "Select a
+      script to execute" rather than failing.'
+  - id: sse.toolchain.xedit-spriggit.quick-auto-clean-is-not-byte-stable
+    claim: Quick Auto Clean applies the filter, undeletes and disables references, and removes
+      identical-to-master records, three times with a silent save between each pass. It marks all
+      groups and records modified before saving, so it produces a different CRC than the old manual
+      method.
+    status: community
+    source: tes5edit.github.io/docs 7.4.7.2 "Quick Auto Clean Method" ("This procedure cleans 3 times
+      and saves in between each step", "For quick auto clean you will not be given an option to
+      save"); whatsnew.md "Quick [Auto] Clean" ("using Quick Clean will now produce a different CRC
+      than using the old manual method")
+    tags:
+      - xedit
+      - cleaning
+      - itm
+      - udr
+      - byte-stability
+      - build-step
+      - gotcha
+    detail: Byte comparison cannot be used to verify a cleaning step. Cleaning must also be done one
+      file at a time - with other mods loaded, ITMs become "identical to master, but conflict
+      winner" and are not cleaned (docs 7.4.2). Undeleting a reference moves it, with xEdit setting
+      the Z axis position to -30,000 units (docs 7.5.3).
+  - id: sse.toolchain.xedit-spriggit.conflict-model-is-two-dimensional
+    claim: xEdit computes two independent statuses per row - a per-record TConflictAll shown as the
+      background colour, and a per-file TConflictThis shown as the text colour.
+    status: community
+    source: github.com/TES5Edit/TES5Edit Core/wbInterface.pas, wbNameConflictAll and wbNameConflictThis;
+      tes5edit.github.io/docs 5.5 "Color Schemes and Display Order"
+    tags:
+      - xedit
+      - conflict
+      - record
+      - model
+    detail: TConflictAll values are Single Record, Multiple but no conflict, Benign Conflict, Override
+      without conflict, Conflict, Critical Conflict. TConflictThis values are Ignored, Not Defined,
+      Identical to Master, Single Record, Hidden by Mod Group, Master, Benign conflict, Override
+      without conflict, Identical to Master but conflict winner, Conflict winner, Conflict loser.
+      The docs' example - green background with grey text for a lone module - makes the two axes
+      concrete.
+  - id: sse.toolchain.xedit-spriggit.spriggit-cli-syntax
+    claim: Spriggit converts a plugin to and from a folder of one-file-per-record YAML or JSON. Its
+      verbs are convert-from-plugin and convert-to-plugin, with serialize and deserialize accepted
+      as aliases, taking --InputPath, --OutputPath, --GameRelease SkyrimSE and --PackageName
+      Spriggit.Yaml.
+    status: community
+    source: github.com/Mutagen-Modding/Spriggit README.md and docs/cli.md, including the example
+      `Spriggit.CLI.exe convert-from-plugin --InputPath "...\Data\SomeMod.esp" --OutputPath
+      "C:\MyGitRepository\SomeMod.esp" --GameRelease SkyrimSE --PackageName Spriggit.Yaml`
+    tags:
+      - spriggit
+      - cli
+      - toolchain
+      - text-converter
+      - yaml
+      - git
+    detail: Other arguments - -v/--PackageVersion, -t/--Threads, -m/--ModKey, -c/--Check,
+      -d/--DataFolder, -u/--ErrorOnUnknown, plus -l/--Localized and -b/--BackupDays on deserialize.
+      The translation logic lives in NuGet packages fetched at run time and stamped into
+      spriggit-meta.json, so deserialization can pull the exact version that wrote the text.
+  - id: sse.toolchain.xedit-spriggit.spriggit-is-not-lossless
+    claim: Spriggit does not round-trip a plugin byte-identically. It deliberately omits unused and
+      unknown fields (including group header data, timestamps and last-modified data), reorders
+      list-type fields on purpose, and refuses to proceed rather than skip a record it does not
+      recognise.
+    status: community
+    source: 'github.com/Mutagen-Modding/Spriggit docs/omissions.md ("Omitted fields are: Not written
+      during serialization ... Set to default values during deserialization"), docs/sorting.md,
+      docs/unexpected-records.md ("If Spriggit encounters a record that it is unsure of, it refuses
+      to proceed, rather than skip the record")'
+    tags:
+      - spriggit
+      - fidelity
+      - round-trip
+      - text-converter
+      - gotcha
+      - verification
+    detail: Its own --Check is weak by design - PostSerializeChecker.cs compares only the record count
+      and a set of record identifiers, with no field-level or byte-level comparison. A separate
+      `standardize` verb exists precisely because binary comparison needs normalising first. So a
+      converter built on Spriggit cannot use a byte-compare round-trip verification.
+  - id: sse.toolchain.xedit-spriggit.spriggit-is-the-only-ci-ready-piece
+    claim: Spriggit publishes a self-contained linux-x64 single-file CLI alongside the Windows one and
+      tests on ubuntu and macos runners, making it the only part of the Skyrim toolchain built for
+      headless use.
+    status: community
+    source: github.com/Mutagen-Modding/Spriggit .github/workflows/ci-publish.yml (dotnet publish -r
+      win-x64 and -r linux-x64 with PublishSingleFile and --self-contained) and the 0.41.0 release
+      assets SpriggitCLI.zip and SpriggitLinuxCLI.zip
+    tags:
+      - spriggit
+      - ci
+      - linux
+      - headless
+      - toolchain
+      - packaging
+    detail: The README's claim that the CLI "is not self contained" is out of date relative to the
+      pipeline. It also installs as a dotnet tool named spriggit. The author maintains a reference
+      workflow at github.com/Noggog/SpriggitWorkflowTests that runs the Linux CLI on ubuntu-latest.
+  - id: sse.toolchain.xedit-spriggit.mutagen-has-no-node-path
+    claim: Mutagen is a C# library with no executable, CLI, server or stdio interface of its own. The
+      only shipped CLI surfaces built on it are Spriggit.CLI and Synthesis.CLI, so a Node process
+      must shell out to Spriggit and read its YAML or JSON.
+    status: inferred
+    source: mutagen-modding.github.io/Mutagen docs index ("Mutagen is a C# library for analyzing,
+      modifying, and creating Bethesda mods"); every project in the Mutagen repository is a library,
+      code generator, test project or WPF app
+    tags:
+      - mutagen
+      - node
+      - integration
+      - toolchain
+      - constraint
+    detail: Marked inferred because it is a conclusion from the absence of an Exe project rather than a
+      documented statement. Mutagen's GameRelease enum, which is what Spriggit's --GameRelease
+      accepts, includes SkyrimSE, SkyrimSEGog, SkyrimLE, SkyrimVR, EnderalSE, Fallout4 and
+      Starfield.
+  - id: sse.toolchain.xedit-spriggit.synthesis-cli-is-not-released
+    claim: Synthesis bundles patchers into a single output plugin named Synthesis.esp and documents a
+      run-pipeline CLI, but no CLI binary is published in its releases and it requires the .NET SDK
+      rather than just a runtime, because it compiles patchers from source at run time.
+    status: community
+    source: mutagen-modding.github.io/Synthesis docs index and docs/Synthesis-CLI.md;
+      docs/Installation.md ("Be sure to install the SDK; The Runtime alone is not enough for
+      Synthesis to compile patchers"); the 0.36.6 release ships only Synthesis.zip
+    tags:
+      - synthesis
+      - patcher
+      - cli
+      - toolchain
+      - constraint
+  - id: sse.toolchain.xedit-spriggit.papyrus-source-directory-is-inverted-on-sse
+    claim: Skyrim SE's Papyrus source folder is Data\Source\Scripts, not Data\Scripts\Source, which is
+      Skyrim LE's. Compiled output goes to Data\Scripts for both.
+    status: community
+    source: github.com/joelday/papyrus-lang src/papyrus-lang-vscode/src/CreationKitInfoProvider.ts,
+      getDefaultPapyrusConfigForGame (skyrim -> '.\\Data\\Scripts\\Source\\', skyrimSpecialEdition
+      -> '.\\Data\\Source\\Scripts\\')
+    tags:
+      - papyrus
+      - paths
+      - sse-vs-le
+      - gotcha
+      - scaffold
+      - build-step
+    detail: Both directories exist on a real SE install because SKSE's readme instructs users to put its
+      own .psc files in Data\Scripts\Source. An import path should include both. These are not
+      hardcoded - they come from CreationKit.ini's [Papyrus] sScriptSourceFolder, sAdditionalImports
+      (which supports a $(source) token), sScriptCompiledFolder and sCompilerFolder.
+  - id: sse.toolchain.xedit-spriggit.papyrus-compiler-invocation
+    claim: The compiler is <game root>\Papyrus Compiler\PapyrusCompiler.exe and is invoked per script as
+      `PapyrusCompiler.exe "<script.psc>" -f="<flags file>" -i="<imports joined by ;>" -o="<output
+      dir>" [-op]`, with TESV_Papyrus_Flags.flg as the flags file for both Skyrim LE and SE.
+    status: community
+    source: github.com/fireundubh/pyro pyro/ProjectBase.py get_compiler_path, pyro/Constants.py class
+      FlagsName, and pyro/PapyrusProject.py's argument assembly; corroborated for the flags file by
+      papyrus-lang src/papyrus-lang-vscode/src/common/PathResolver.ts
+    tags:
+      - papyrus
+      - compiler
+      - cli
+      - build-step
+      - toolchain
+    detail: -release and -final are emitted only for Fallout 4 and Starfield, never for SSE. The
+      spellings -all, -q and -optimize are widely repeated but unconfirmed - Pyro emits -op and
+      compiles per script, and PapyrusCompiler.exe -h could not be reached because the Creation Kit
+      wiki is unavailable.
+  - id: sse.toolchain.xedit-spriggit.creationkit-reads-two-ini-files-on-sse
+    claim: The Skyrim SE Creation Kit reads CreationKit.ini and CreationKitCustom.ini, where the Skyrim
+      LE editor reads SkyrimEditor.ini.
+    status: community
+    source: github.com/joelday/papyrus-lang src/papyrus-lang-vscode/package.json, the
+      papyrus.skyrimSpecialEdition.creationKitIniFiles and papyrus.skyrim.creationKitIniFiles
+      defaults
+    tags:
+      - creation-kit
+      - ini
+      - sse-vs-le
+      - paths
+  - id: sse.toolchain.xedit-spriggit.creationkit-version-line-is-1-6-x
+    claim: The Skyrim SE Creation Kit's version line is 1.5.x to 1.6.x, with 1.5.73.0, 1.6.1130.0 and
+      1.6.1378.1 currently active. The 2.x "Creation Kit" numbering belongs to Starfield's editor,
+      not Skyrim's.
+    status: community
+    source: github.com/Perchik71/Creation-Kit-Platform-Extended wiki, the supported editor versions
+      table, corroborated by the repository's Stuffs/__CreateDatabase_sse_*.bat scripts
+    tags:
+      - creation-kit
+      - version
+      - compat-matrix
+    detail: CKPE's own SSE patch for the 1.71 plugin format defines the editor's ESL-capacity strings "
+      <NOT ESL Capable - no more IDs remaining>" and " <ESL Capable - %d IDs remaining>" alongside
+      constexpr float fPluginVersion = 1.71f.
+  - id: sse.toolchain.xedit-spriggit.wrye-bash-has-no-headless-mode
+    claim: Wrye Bash has no command-line way to build a Bashed Patch. Its entire CLI is path overrides,
+      settings backup and restore, UAC flags and a language switch; everything else launches the
+      GUI.
+    status: community
+    source: github.com/wrye-bash/wrye-bash Mopy/bash/barg.py, which parses -o/--oblivionPath,
+      -m/--oblivionMods, -p, -u, -l, -b/--backup, -r/--restore, -f/--filename, -q/--quiet-quit,
+      --no-uac/--uac, -L/--Language, -n/--unsupported and a deprecated -d/--debug
+    tags:
+      - wrye-bash
+      - cli
+      - automation
+      - constraint
+      - toolchain
+    detail: ModWright can detect a Bashed Patch's presence but cannot build or refresh one. The Leveled
+      Lists patcher is the one that matters most - it merges changes multiple mods make to the same
+      leveled list, which last-loaded-wins would otherwise discard.
+  - id: sse.toolchain.xedit-spriggit.bash-tags-come-from-loot
+    claim: Wrye Bash's Bash Tags are read, in increasing priority, from the plugin's own header
+      description, a bundled taglist.yaml, LOOT's masterlist.yaml, LOOT's userlist.yaml,
+      <Game>\Data\BashTags\<plugin>.txt, and finally tags set manually in Wrye Bash.
+    status: community
+    source: wrye-bash.github.io "Wrye Bash Advanced Readme", section "Bash Tags"
+    tags:
+      - wrye-bash
+      - bash-tags
+      - loot
+      - masterlist
+      - metadata
+    detail: This is why a TES4 header parser should surface SNAM - a plugin's description is a real
+      metadata channel, not just documentation. Wrye Bash looks for LOOT's files in
+      %LOCALAPPDATA%\LOOT\<Game>\ and falls back to its own bundled taglist.
+  - id: sse.toolchain.xedit-spriggit.behaviour-and-lod-tools-cannot-be-automated
+    claim: Nemesis, Pandora, DynDOLOD and xLODGen cannot be driven unattended. Nemesis must live inside
+      <Data>\Nemesis_Engine and is a Qt GUI whose command-line paths end in a blocking getch();
+      Pandora always creates a window; DynDOLOD documents no switch that starts or finishes
+      generation; xLODGen is xEdit's LODGen mode behind an unconditional modal.
+    status: community
+    source: github.com/ShikyoKira/Project-New-Reign---Nemesis-Main src/nemesisinfo.cpp, src/main.cpp and
+      src/ui/CmdLaunch.cpp; github.com/Monitor221hz/Pandora-Behaviour-Engine-Plus Program.cs and
+      App.axaml.cs; dyndolod.info/Help/Command-Line-Argument and /Generation-Instructions;
+      github.com/TES5Edit/TES5Edit xEdit/xeMainForm.pas (`if ShowModal <> mrOk then Exit;` on the
+      LODGen form)
+    tags:
+      - nemesis
+      - pandora
+      - dyndolod
+      - xlodgen
+      - automation
+      - constraint
+      - toolchain
+    detail: The reason to avoid DynDOLOD is not runtime - its own site says vanilla LOD generation
+      "should not take more than 15 minutes or so" - but that there is no way to start or finish it
+      from a command line, and "Manually closing DynDOLOD or LODGen while they are still running
+      results in incomplete output that can not be used in the game."
+  - id: sse.toolchain.xedit-spriggit.xedit-does-not-support-linux
+    claim: xEdit's maintainers state on the record that Wine is not a supported environment and that a
+      native Linux build is impossible because there is no VCL for Linux. The repository has no CI.
+    status: community
+    source: github.com/TES5Edit/TES5Edit issues 1069 (closed not_planned, wontfix), 774 ("Wine is not an
+      officially supported environment for xEdit", "No, because there is no VCL for Linux") and 1486
+      ("We do not and really we cant support Linux in any way shape or form")
+    tags:
+      - xedit
+      - linux
+      - wine
+      - ci
+      - constraint
+      - toolchain