modwright 0.1.0

package/knowledge/cyberpunk2077/packaging.deploy.yaml

@@ -0,0 +1,175 @@
+game: cyberpunk2077
+topic: packaging.deploy
+title: Packaging, deployment, and version compatibility
+facts:
+  - id: cp2077.packaging.archive-cli-pack-command
+    claim: wolvenkit cli pack command packages a mod project directory into a .archive file; syntax is
+      `cli pack <source-dir> -o <output-dir> -v <verbosity>` with -v Minimal being typical for
+      distribution.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cli
+      - pack
+      - archive
+      - command
+      - deployment
+    detail: Produces <mod>.archive in the output directory. Note that -v is passed by one build script
+      but omitted from another description of the same pipeline, and no source says what it
+      controls; read it as verbosity, not compression. This is a CLI invocation, so there is no
+      in-game verification.
+  - id: cp2077.packaging.archive-xl-manifest-required
+    claim: An archivexl .archive.xl manifest file must accompany the .archive file in the deployment
+      directory; the .xl file is loaded on game init and registers resources, factories, and
+      streaming blocks from the archive.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - manifest
+      - .xl
+      - deployment
+      - registration
+    detail: <Mod>.archive is always deployed next to <Mod>.archive.xl. The .xl does not describe where
+      resources live inside the archive; it registers what ArchiveXL must wire up — localization
+      onscreens, factory csvs and streaming blocks — and the weapon's name, icon factory and world
+      case all depend on it.
+  - id: cp2077.packaging.tweakxl-yaml-deployment
+    claim: tweakxl yaml files are deployed directly to the game's r6\tweaks directory; no packing is
+      required. The yaml is loaded by tweakxl on game init or hot-reloaded via TweakXL.Reload() in
+      the CET console.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - yaml
+      - deployment
+      - hot-reload
+    detail: A mod's yaml is copied to r6\tweaks\<Mod>\. The console call is spelled TweakXL.Reload() —
+      an earlier lowercase "tweakxl.Reload()" was wrong. How fast the reload is is not recorded.
+  - id: cp2077.packaging.powershell-build-script
+    claim: powershell build scripts (build.ps1) automate the pack → deploy → verify cycle; they handle
+      file locking (wait for game exit before copying), backup of previous versions, and optional
+      nexus packaging.
+    status: inferred
+    source: ModWright research
+    tags:
+      - powershell
+      - build
+      - deploy
+      - automation
+      - packaging
+    detail: "Correction: the example build.ps1 does NOT handle file locking and does NOT back up
+      previous versions. It is param(-Export, -Dist, -Version), then optional Blender export + CLI
+      import, then `cli pack`, then three plain Copy-Item calls, then the optional dist zip. The
+      retry-on-lock behaviour described in the project notes was run ad hoc, not from this script."
+  - id: cp2077.packaging.file-lock-retry-loop
+    claim: Archive files in the game directory are locked while the game is running; deployment scripts
+      must implement a retry loop with backoff to wait for game exit before copying new versions.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - file-lock
+      - deployment
+      - game-exit
+      - retry
+      - backoff
+    detail: The lock is real and was hit during a build. The "deployment scripts must implement" half is
+      advice, and the example build.ps1 does not implement it — its Copy-Item calls simply fail
+      while the game holds the archive. yaml under r6\tweaks is not locked. This is a filesystem
+      observation, not an in-game verification.
+  - id: cp2077.packaging.nexus-zip-structure
+    claim: nexus mod packages are .zip files containing the mod directory structure with r6\tweaks\,
+      archive\, and other paths matching the game install layout; vortex unpacks these directly into
+      the game folder.
+    status: inferred
+    source: ModWright research
+    tags:
+      - nexus
+      - packaging
+      - zip
+      - vortex
+      - structure
+    detail: In the example project the zip is dist\<Author><Mod>-<Version>.zip (default version 1.0.0).
+      It contains only archive\pc\mod (the .archive and .xl) and r6\tweaks\<Mod> (the yaml) — the
+      author-only CET cleanup mod is deliberately not shipped. The mod page tells manual installers
+      to "extract the zip into the Cyberpunk 2077 root folder". Re-sourced from an uncited "nexus
+      Mods standard layout".
+  - id: cp2077.packaging.red4ext-requirement
+    claim: red4ext runtime loader 1.29.0+ is required for mods using tweakxl and archivexl; it must be
+      installed separately before any red4ext-dependent mods will load.
+    status: community
+    source: ModWright research
+    tags:
+      - red4ext
+      - loader
+      - requirement
+      - version
+      - dependency
+    detail: The 1.29.0+ floor is ArchiveXL's own stated requirement for the version compatible with game
+      2.31. The example mod lists RED4ext, ArchiveXL and TweakXL as its requirements.
+  - id: cp2077.packaging.version-matrix-breakage
+    claim: Every game patch can break mods; the version matrix (game version, red4ext, tweakxl,
+      archivexl, codeware, cet, redscript) must all align. A single version mismatch cascades into
+      silent failures or load crashes.
+    status: community
+    source: cp2077-archive-xl/README.md "Getting Started > Compatibility" (pins Cyberpunk 2077 2.31 and
+      redscript 0.5.31+, with RED4ext 1.29.0+ under Installation)
+    tags:
+      - version-matrix
+      - compatibility
+      - patch
+      - breakage
+    detail: The citable part is that a framework release pins an exact game version and exact dependency
+      floors — ArchiveXL for 2.31 requires redscript 0.5.31+ and RED4ext 1.29.0+, and the example
+      mod's CR2W assets are all stamped GameVersion 2310. A specific patch history that used to sit
+      here (RED4ext 1.26.1 breaking on 2.2, "2.31 broke core mods") came from an internal note,
+      which is not a citable source for this knowledge base, and has been removed.
+  - id: cp2077.packaging.cet-log-checks
+    claim: cet mod loading is signaled in bin/x64/plugins/cyber_engine_tweaks/cyber_engine_tweaks.log;
+      the cet console command `GetMod("name").Status()` returns the runtime state of a mod.
+    status: unverified
+    source: ModWright research
+    tags:
+      - cet
+      - log
+      - console
+      - status
+      - mod
+    detail: Two problems. The log path is not named in any of the example project's sources, so it is
+      unsupported here. And the example CET mod's init.lua registers an onUpdate handler and ends
+      with `return {}` — it exposes no Status method at all, so the console line cannot work as
+      written against that script. Method name corrected to Status() (capital S) as the project
+      notes spell it; a fabricated verified status and in-game attribution were removed.
+  - id: cp2077.packaging.game-version-compatibility
+    claim: Archive and cr2w files include a GameVersion header; a mod packed for one game version may
+      not load on another without compatibility fixes. Always verify mod dependencies match the
+      target game version.
+    status: inferred
+    source: ModWright research
+    tags:
+      - gameversion
+      - compatibility
+      - archive
+      - cr2w
+    detail: 'What is sourced: CR2W json carries a GameVersion (2310 here, i.e. game 2.31) written by
+      WolvenKit, and framework releases pin a game version. Whether a version mismatch blocks
+      loading is not recorded anywhere in these sources; the "mods built for 2.3 may not load on
+      2.1" example that used to sit in this fact was invented and has been removed, along with its
+      in-game verified attribution.'
+  - id: cp2077.packaging.mod-folder-structure
+    claim: "Game mods are installed under the game root: tweakxl yaml goes in r6\\tweaks\\, archives and
+      their .xl manifests go in archive\\pc\\mod\\, and cet mods go in
+      bin\\x64\\plugins\\cyber_engine_tweaks\\mods\\. Mods are loaded on game init and must be
+      present before launch."
+    status: inferred
+    source: ModWright research
+    tags:
+      - mod-folder
+      - directory
+      - structure
+      - layout
+    detail: The earlier version of this fact listed "r6/mods", which is not a Cyberpunk 2077 path and
+      appears in none of the sources. Redscript would live in r6\scripts; this project ships none.

package/knowledge/cyberpunk2077/packaging.variants.yaml

@@ -0,0 +1,176 @@
+game: cyberpunk2077
+topic: packaging.variants
+title: Clean-pack builds, optional CET dependency, and variant/ArchiveXL gotchas (a melee weapon mod)
+facts:
+  - id: cp2077.packaging.variants.build-sources-pack-silently-as-json
+    claim: Serialized build-source JSON files (e.g. a mesh's .mesh.json or an app's .app.json) left
+      inside the working archive-staging tree pack into the shipping archive SILENTLY, because .json
+      is a real game resource type — unlike, say, .png, which the packer skips. A clean build must
+      explicitly sweep and remove every .json in the tree except the one real localization resource
+      (en-us.json) before packing.
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - json
+      - source-leakage
+      - silent
+    detail: "Caught as a real ship blocker in a release audit: the deployed archive was carrying 1.32 MB
+      of sources (a 1044 KB body .mesh.json and a 154 KB weapon .app.json) that should never have
+      shipped, cutting the archive from 33 entries to 29 once removed. archive-staging doubles as
+      the working tree, which is why sources end up next to shipping assets in the first place."
+  - id: cp2077.packaging.variants.dead-referenced-fx-resource-must-be-pruned
+    claim: A design revert (reverting a weapon .app back to referencing a vanilla effect instead of a
+      cloned one) can leave a now-unreferenced custom effect resource still sitting in the staging
+      tree; a clean build must verify the string does not appear anywhere in the shipping app before
+      dropping such a file, rather than assuming staleness from context alone.
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - dead-asset
+      - effect
+      - cleanup
+    detail: The specific dead asset was fx\<mod>_idle_thermal.effect(.json), left over from the mod's
+      heat-haze work (see cp2077.fx.effects.heat-haze-is-a-particle-effect and
+      cp2077.fx.effects.placement-info-named-tag-required for that history). build.ps1 checks for
+      and removes this specific file by name.
+  - id: cp2077.packaging.variants.build-script-gates-source-and-dev-script-leakage
+    claim: "Also observed on a melee weapon mod, extending cp2077.packaging.powershell-build-script
+      (documented on a simpler example mod whose build.ps1 has no such gates): a release build
+      script can enforce its own cleanliness invariants by throwing a hard error if a named
+      build-source file is found in the packed archive's listing (via a CLI archiveinfo dump) or if
+      a named dev-only script survives into the final scripts package — catching packaging
+      regressions automatically rather than relying on a human to remember to check."
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - gate
+      - automated-check
+    detail: "Two separate gates: one checks the packed archive's listing for the weapon .app.json and
+      body .mesh.json build sources; the other checks the staged scripts folder for any of the named
+      dev scripts. Both throw and abort the build rather than merely warning."
+  - id: cp2077.packaging.variants.dev-scripts-that-log-every-attack-must-never-ship
+    claim: Development-only redscript files that log on every attack (<Mod>_Debug.reds,
+      <Mod>_Probe.reds, <Mod>_TrailProbe.reds) are explicitly excluded from the shipped package by
+      name; at least one of these was found still deployed in the live game install during a
+      pre-release audit, despite being headed "DELETE BEFORE SHIP" in its own file.
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - dev-script
+      - ship-blocker
+      - audit
+    detail: The audit found and removed <Mod>_Debug.reds and <Mod>_Probe.reds from the live installed
+      game folder — a real, not merely hypothetical, near-miss for shipping instrumentation to end
+      users. build.ps1's final gate (a throw if any dev script name is found in the staged package)
+      exists specifically because of this incident.
+  - id: cp2077.packaging.variants.optional-cet-dependency-flag
+    claim: A mod build script can make an entire dependency (here, Cyber Engine Tweaks, for one optional
+      cosmetic feature) opt-in via a build flag (-WithCetLight) rather than opt-out, so the default
+      build genuinely ships without that dependency listed, and a -Deploy without the flag actively
+      removes any previously-deployed instance of that dependency's files from the live game install
+      (backed up, never silently deleted).
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - cet
+      - optional-dependency
+      - flag
+    detail: 'Rationale recorded in the script: the CET-driven weapon light only added a dynamic
+      point-light cast onto nearby surfaces (the emissive glow, haze, and tip smoke are all
+      unaffected — see cp2077.fx.lights.cet-glow-light-dropped-no-functional-loss) and "did not earn
+      a whole extra dependency," per explicit user call after comparing both builds in game. The
+      removed live CET mod is backed up to rollback\cet-<ModLight>-<timestamp> rather than deleted
+      outright.'
+  - id: cp2077.packaging.variants.archive-lock-retry-loop-on-deploy
+    claim: "Also observed on a melee weapon mod, and here actually implemented: confirming
+      cp2077.packaging.file-lock-retry-loop (documented on a simpler example mod whose own build.ps1
+      does NOT implement the retry), that mod's build script copies the shipping archive into a
+      running game's mod folder with a retry loop — every 10 seconds for up to 180 attempts (30
+      minutes) — because the file is locked while the game process holds it open."
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - deploy
+      - file-lock
+      - retry
+    detail: The same retry-until-unlocked pattern is used independently in the mod's world-cache deploy
+      script (same 10 s interval, 180 attempts) and its mesh deploy script (5 s interval, 120
+      attempts) — a consistent project-wide convention for archive deploys, not a one-off.
+  - id: cp2077.packaging.variants.endless-flow-is-a-static-record-shape-not-a-runtime-toggle
+    claim: The "endless flow" no-finisher combo variant, as implemented by omitting the highest-index
+      final-attack record, is a property of which TweakDB records exist at build time — it cannot be
+      switched on or off at runtime, unlike vanilla's own CanWeaponInfinitlyCombo /
+      CanMeleeInfinitelyCombo status-effect-driven infinite-combo mechanism, which is inherently a
+      temporary, stackable, runtime-toggleable state.
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - variant
+      - endless-flow
+      - static
+      - design
+    detail: This is exactly why the variant's own notes frame vanilla's flag pair as "the right
+      foundation for anything like 'cyberware that lets you attack endlessly'" rather than reusing
+      the accidental record-shape variant for any future toggleable ability — the two approaches are
+      not interchangeable despite producing a similar-looking effect.
+  - id: cp2077.packaging.variants.unshipped-variant-kept-as-a-named-snapshot-folder
+    claim: An unshipped but design-relevant behavior can be preserved as a standalone variant folder
+      holding the EXACT pre-fix source files (the yaml and any redscript) needed to reproduce it,
+      rather than only as prose documentation — letting a future session restore the variant by
+      dropping those specific files back in, with no re-derivation needed.
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - variant
+      - snapshot
+      - documentation-pattern
+    detail: variants/endless-flow/ holds <mod>.yaml (pre-fix, with the AttacksNumber +1 but no
+      FinalAttack4 record) and <Mod>_AnimSteering.reds (the pre-refactor version) — described as
+      "the exact pre-fix state," distinct from the shipped versions of the same two files elsewhere
+      in the repo.
+  - id: cp2077.packaging.variants.nexus-name-field-charset-restriction
+    claim: The Nexus Mods mod-name field only accepts letters, numbers, spaces, and the characters ` _ '
+      ( ) . -` ; any other punctuation in an intended display name must be dropped or substituted
+      when filling in the Nexus page.
+    status: community
+    source: ModWright research
+    tags:
+      - packaging
+      - nexus
+      - name-field
+      - charset
+    detail: The project's own release-packaging notes restate the same restriction as a pre-upload
+      checklist item ("the name field allows only letters/numbers/spaces/`_ ' ( ) . -`"), so it is
+      treated as settled practice for this project rather than re-derived each release.
+  - id: cp2077.packaging.variants.shipped-package-is-three-trees-plus-optional-fourth
+    claim: "Also observed on a melee weapon mod, extending cp2077.packaging.mod-folder-structure and
+      cp2077.packaging.nexus-zip-structure (both documented on a simpler example mod, which ships no
+      redscript): a redscript-shipping mod's package contains three trees — archive\\pc\\mod\\ (the
+      archive + its .xl), r6\\tweaks\\ (the TweakXL yaml), and r6\\scripts\\<ModName>\\ (redscript,
+      minus dev-only files) — and conditionally a fourth,
+      bin\\x64\\plugins\\cyber_engine_tweaks\\mods\\<ModName>\\, present ONLY when an optional CET
+      feature is explicitly opted into at build time."
+    status: inferred
+    source: ModWright research
+    tags:
+      - packaging
+      - build
+      - package-layout
+      - trees
+    detail: This layout matches the Vortex/manual install instructions published on the Nexus page ("the
+      zip contains archive\pc\mod, r6\tweaks and r6\scripts") when the optional 4th tree is
+      excluded, i.e. the default, no-CET build.