modwright 0.1.0

package/knowledge/cyberpunk2077/process.assetbuild.yaml

@@ -0,0 +1,154 @@
+game: cyberpunk2077
+topic: process.assetbuild
+title: Process lessons from a melee weapon mod build (non-animation)
+facts:
+  - id: cp2077.process.assetbuild.reasoning-chain-broke-at-flag-vs-resolved-value
+    claim: A plausible-sounding multi-step inference chain ("the idle_thermal desc renders, and the
+      function that requests it only fires for Thermal-type weapons, therefore this weapon's
+      resolved damage type is Thermal, therefore the engine wants the trail_thermal effect name")
+      can be wrong at its final step even when every earlier step is individually true, because a
+      gameplay FLAG (DealsThermalDamage) and the engine's actually RESOLVED value
+      (GetCurrentDamageType(), from comparing stat values) are not the same thing and can disagree.
+    status: inferred
+    source: ModWright research
+    tags:
+      - process
+      - reasoning
+      - flag-vs-resolved-value
+      - debugging
+    detail: Cost three relaunch cycles before a logging probe (49/49 requests for "trail_physical")
+      settled it. Shipping both possible effect names looked like it made the question moot; it did
+      not, because both names had been pointed at the same wrong effect. See
+      cp2077.fx.effects.trail-name-resolved-from-damage-comparison for the underlying game fact this
+      reasoning failure was about.
+  - id: cp2077.process.assetbuild.probe-must-read-a-discriminating-public-getter
+    claim: A debug probe that only logs that a shared method fired proves nothing about a SPECIFIC
+      object's behavior, because other objects (e.g. every NPC) run the same shared code path; a
+      probe must instead read a public getter or property that is specific to the object under test
+      (e.g. HasTag(n"<ModWeapon>") plus the public GetCurrentMeleeTrailEffectName() getter) to
+      actually discriminate between "this object's path is dead" and "this object's path works but
+      is invisible."
+    status: inferred
+    source: ModWright research
+    tags:
+      - process
+      - debugging
+      - probe
+      - methodology
+    detail: The probe's first revision (<Mod>_TrailProbe.reds v1) logged that
+      StartCurrentMeleeTrailEffect fired and was over-read as proof the trigger worked for this
+      specific weapon; it proved nothing, since NPCs run the identical code. v2's two discriminating
+      facts, both via public API, are what actually broke the deadlock.
+  - id: cp2077.process.assetbuild.control-must-be-conspicuous-under-test-conditions
+    claim: A control case chosen to validate a debugging setup must be proven conspicuous UNDER THE
+      SPECIFIC CONDITIONS the test exercises, not merely proven to render or work in general; an
+      effect that is obviously visible while idle can still be a useless control for a fast, narrow
+      event window, because it may emit almost nothing inside that window.
+    status: inferred
+    source: ModWright research
+    tags:
+      - process
+      - debugging
+      - control
+      - bisect
+      - methodology
+    detail: Two bisects were wasted picking the mantis idle haze/smoke as "known good because it renders
+      on this weapon" — an ambient effect that, when pulsed into a fast swing's 0.3 s trail window,
+      emits almost nothing, so "I can't see it" could never distinguish a dead trigger path from a
+      merely-invisible one. This sharpens the general isolation lesson already recorded as
+      cp2077.process.control-experiment-testing and cp2077.process.bisect-silent-failures with a
+      concrete new failure mode. A duplicate of this rule previously also sat in the fx.effects
+      topic and was merged here.
+  - id: cp2077.process.assetbuild.rht-hot-folder-banned-for-whole-mesh-archives
+    claim: RedHotTools' archive\pc\hot hot-reload folder is safe for many kinds of resource-level
+      hot-reload, but whole-archive hot ingest of an archive containing a MOUNTED WEAPON MESH
+      re-reads geometry buffers with mismatched offsets, exploding vertices across the screen until
+      the game is restarted; for a mesh-carrying archive, deploy cold (game closed) only.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - toolchain
+      - redhottools
+      - hot-reload
+      - mesh
+      - crash
+    detail: "The mesh deploy script's own conclusion: \"meshes 'hot-reload fine' applied to the
+      resource-level reloads of the past, not whole-archive swaps.\" The script also actively
+      removes any stale copy left in archive\\pc\\hot after a successful cold deploy, since that
+      folder is a watcher that auto-ingests on its own schedule and running a parallel copy to `mod`
+      as well risks a crash from double writers (noted separately in the project's own RHT-flow
+      notes)."
+  - id: cp2077.process.assetbuild.stale-serialized-sidecar-can-resurrect-old-geometry
+    claim: A stale serialized .mesh.json sidecar left next to a freshly rebuilt .mesh binary can
+      resurrect old geometry if a later step re-reads the sidecar instead of the fresh binary;
+      deploy scripts should delete any such sidecar and re-serialize fresh from the current binary
+      at deploy time, every time, rather than trusting an existing sidecar.
+    status: inferred
+    source: ModWright research
+    tags:
+      - process
+      - toolchain
+      - mesh
+      - sidecar
+      - stale-data
+    detail: 'Recorded as having "already resurrected old geometry once in this project." The fix in the
+      deploy script: `Remove-Item "$Stage.json"` then `convert serialize` fresh, every deploy,
+      before packing.'
+  - id: cp2077.process.assetbuild.mesh-and-textures-are-a-matched-pair-requiring-joint-rebuild
+    claim: An export pipeline step that discards ALL UV layers and re-runs automatic unwrapping on every
+      export (rather than preserving a stable UV layout across edits) means ANY geometry edit
+      re-lays the UV islands; textures already baked against the previous layout then sample the
+      wrong part of the atlas — observed as visible black patches on an emissive surface. The mesh
+      and its baked textures must therefore always be treated as a matched pair and rebuilt
+      together, never independently.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - mesh
+      - uv
+      - texture
+      - matched-pair
+    detail: "Measured extent of the relay after the v5 detail pass: all 4932 of one submesh's UV loops
+      moved, up to 0.986 UV units. The deploy script enforces this with an explicit staleness gate
+      comparing file modification times of the blend, the exported glb, and all baked textures,
+      throwing before packing if any texture predates the blend."
+  - id: cp2077.process.assetbuild.wolvenkit-import-keep-flag-wipes-bone-vertex-epsilons
+    claim: WolvenKit.CLI `import -k` (import keeping materials/appearances) preserves the material and
+      appearance chunks of a target .mesh but WIPES the boneVertexEpsilons field to an empty list /
+      zero; that field is what stops the mesh being frustum-culled away from its attachment bone, so
+      a zeroed value makes the mesh blink out at off-angles in game — a failure mode invisible in
+      every offline preview, because the geometry itself is unchanged and perfect.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - toolchain
+      - wolvenkit
+      - mesh
+      - bone-vertex-epsilon
+      - silent-failure
+    detail: Shipped value is 3.0; the verify gate treats anything below 0.1 as the import bug. A restore
+      script exists purely to put the value back (serialize -> set field -> deserialize) after every
+      `import -k`, and is idempotent when run on a mesh that already has the right value.
+  - id: cp2077.process.assetbuild.asset-attribution-pattern-donor-and-vanilla-strip
+    claim: A weapon-adjacent asset (here, a spawnable weapon-light entity) can be rebuilt from a vanilla
+      donor by the same structural-strip technique originally learned from a third-party mod's
+      asset, closing a license question without losing the working structure — the third-party mod's
+      author is still credited for the PATTERN even after the shipped asset no longer derives from
+      their file.
+    status: inferred
+    source: ModWright research
+    tags:
+      - process
+      - attribution
+      - license
+      - donor
+      - vanilla
+    detail: "Extends the general asset-attribution practice already recorded as
+      cp2077.process.asset-attribution with a concrete pattern: keanuWheeze is credited for the
+      flashlight light-entity PATTERN even though the shipped light entity was rebuilt from vanilla
+      spotlight_a.ent specifically to remove the third-party-derivation question — CDPR's
+      fan-content policy is treated as covering the vanilla-derived version without needing separate
+      credit, per the project's stated interpretation."

package/knowledge/cyberpunk2077/process.lessons.yaml

@@ -0,0 +1,276 @@
+game: cyberpunk2077
+topic: process.lessons
+title: Standing rules, debugging patterns, and development process lessons
+facts:
+  - id: cp2077.process.manual-first-principle
+    claim: If a manual/gui path is >99% likely to work and the headless path is unproven, offer the
+      manual path first. A world-sector authoring effort violated this rule; the lesson is applied
+      going forward.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - process
+      - manual
+      - gui
+      - headless
+      - principle
+      - sector
+    detail: "The concrete shape of the rule for world placement: the user runs WolvenKit GUI + Script
+      Manager's Object Spawner import on their own entSpawner export, packs and installs from the
+      GUI and tests a vanilla control case; only then is the custom case and loot table injected
+      into the GENERATED (proven) sector. That is what finally worked — \"resolved — Option B
+      injection worked\". Hand-authoring a sector from guessed field values is the anti-pattern the
+      rule was written against. The in-game verified_on/verified_by this fact carried were
+      fabricated; it is a user instruction, not an engine observation."
+  - id: cp2077.process.control-experiment-testing
+    claim: When debugging world placement or entity issues, place a vanilla control entity alongside the
+      custom one at a known offset; test render, loot, and interaction separately to isolate whether
+      the bug is in the entity, appearance, or sector.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - testing
+      - control
+      - diagnosis
+      - isolation
+    detail: "Run as node 0 (custom case) and node 1 (untouched vanilla common_suitcase_small.ent, +1.5m
+      in x, identical loot instanceData). Its real payoff was negative: the \"still
+      invisible/unlootable\" branch fired, which is what stopped the hand-authoring and sent the
+      placement through the official entSpawner import. The claim's three-way isolation is the
+      intent, not a demonstrated outcome — see cp2077.sectors.custom-ent-vs-vanilla-control, which
+      is unverified."
+  - id: cp2077.process.entspawner-as-reference
+    claim: Use entspawner to place a vanilla entity in-game and export the project as a reference; the
+      export reveals correct sector structure, appearance names, streaming values, and
+      category/level settings for hand-authored sectors.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - entspawner
+      - reference
+      - export
+      - sector
+      - authoring
+    detail: entSpawner is worldBuilder v1.0.81, installed from GitHub after the previous install turned
+      out to be a hollow Vortex skeleton. The export revealed category "Exterior" level 1, the full
+      appearance name suitcase_small_neomilitary_a, the placement (-835.758, 328.628, 7.884) and
+      streaming values MaxStreamingDistance 120 / UkFloat1 100 / Uk10 1056 / Uk11 512. The sector
+      builder script was rebuilt from those values, but the sector that shipped was the one
+      WolvenKit's official entSpawner import script generated, with loot injected by a separate
+      script.
+  - id: cp2077.process.cet-mods-sandboxed
+    claim: cet mods run in a sandboxed lua environment; console access is via `GetMod("ModName")`, and
+      each mod's init.lua must return a table with methods that the console can call.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - mod
+      - sandbox
+      - lua
+      - console
+    detail: The lesson requires init.lua to return a table; it does not require the table to have
+      methods. An example CET mod's init.lua registers an onUpdate handler and returns an empty
+      table `{}`, so a `GetMod("<Mod>").Status()` console line would not resolve against it.
+  - id: cp2077.process.tweakxl-hot-reload
+    claim: tweakxl yaml tweaks can be hot-reloaded in-game via `TweakXL.Reload()` in the cet console
+      without restarting the game; this is the fastest iteration path for tweaks and records.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - tweakxl
+      - hot-reload
+      - cet
+      - console
+      - yaml
+    detail: 'The iteration loop this enabled: edit yaml, copy to r6\tweaks, TweakXL.Reload(), spawn with
+      Game.AddToInventory("Items.<Preset>", 1), read the in-game panel. Archive changes get no such
+      path — they need a restart. Call spelled TweakXL.Reload() (the lowercase form previously in
+      this file was wrong).'
+  - id: cp2077.process.tweakdb-ground-truth
+    claim: tweakdb ground truth is the vanilla `tools\redmod\tweaks\` folder (2,684 files); when
+      documentation and wiki disagree, check the actual vanilla record definitions in the source.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakdb
+      - ground-truth
+      - vanilla
+      - source
+      - documentation
+    detail: The vanilla patterns a weapon mod copies (Quality.Random +
+      CraftableIconicQualityRandomisation, the SilencerBase stat pair, the
+      ma_wbr_jpn_20_Igla_Sovereign_recipe_loot_table level-band structure) all come from that
+      corpus. In-game verified_on/verified_by removed — this is about files on disk.
+  - id: cp2077.process.never-regex-version-strings
+    claim: Never derive script or record versions using regex substitution; version strings have
+      internal encoding (dot bugs, underscore rules) that silently fail to match after regex. Copy
+      files and use the Edit tool instead.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - automation
+      - regex
+      - version
+      - pitfall
+      - encoding
+    detail: The recorded instance is the v20/v21 dot bug while iterating a series of kitbash scripts (v1
+      through v22). In-game verified_on/verified_by removed — this is an authoring-tool trap.
+  - id: cp2077.process.bisect-silent-failures
+    claim: "When debugging silent failures (invisible entities, unlootable containers, unresolved
+      resources), bisect the changes: create a minimal control case, remove one change at a time,
+      and re-test. Isolate the exact field causing failure."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - debugging
+      - bisect
+      - silent-failure
+      - isolation
+    detail: "Honest outcome: bisecting the ent-derived loot chunk did NOT isolate the field the
+      RedPackage json reader rejected — the project's notes say it \"was never identified\" — and
+      the work moved to a transplanted reference chunk instead. Bisecting is worth doing; the
+      claim's final sentence (\"isolate the exact field\") is not always achievable. See
+      cp2077.toolchain.redpackage-reader-rejects-unidentified-field. In-game verified_on/verified_by
+      removed."
+  - id: cp2077.process.template-transplant-vs-blind-authoring
+    claim: When a silent-failure field remains unidentified after bisecting, transplant the entire
+      structure from a known-working template rather than continue blind authoring. This is faster
+      and more reliable than trying to guess the field semantics.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - template
+      - transplant
+      - authoring
+      - blind
+      - reliability
+    detail: The working chunk came from a modded ShardCaseContainer node in AldecaldosHighStakes, saved
+      as a reference sector json. Both builder scripts deep-copy that node's instanceData, set $type
+      to LootContainerObjectAnimatedByTransform, pop itemTDBID and shardMesh, and overwrite
+      lootTables / lootQuality / containerType. The case that ships loots, so the transplant is
+      confirmed in game.
+  - id: cp2077.process.case-pose-vs-state-lesson
+    claim: "A mesh's authored pose (how it's modeled in blender/3D) is distinct from entity animation
+      state; confusion between these causes misdirected debugging. Lesson: \"was the mesh pose, not
+      state.\""
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - mesh
+      - pose
+      - state
+      - animation
+      - debugging
+    supersedes: cp2077.entities.case-open-is-entity-state
+    detail: 'The vanilla gun-case meshes are authored open, exterior-up. The fix was geometric — the
+      lid-building script spins the lid 180° about Z and seats it on the bottom by bbox math — not a
+      state fix. Note the tail of the earlier version of this fact ("then remove the animator") is
+      itself superseded: the shipped case keeps its gameTransformAnimatorComponent and animates open
+      (cp2077.entities.transform-animator-open-anim).'
+  - id: cp2077.process.asset-attribution
+    claim: When reusing chunks, materials, or other assets from another mod, document the source and
+      author attribution; nexus ToS requires consent and proper attribution for reused work.
+    status: community
+    source: ModWright research
+    tags:
+      - attribution
+      - reuse
+      - asset
+      - permission
+      - nexus
+    detail: "What these sources support is the practice: the example project names its base-asset and
+      tool authors on its Nexus page and in its README, and its notes name the mod the loot chunk
+      was adapted from. The claim's second half — what Nexus's terms of service require — came from
+      an internal note and has no citable source here, so do not treat it as established. A
+      fabricated in-game verified attribution was removed."
+  - id: cp2077.process.headless-render-for-qa
+    claim: Headless blender renders (via --background --python scripts) can be used for visual QA of
+      icons and models without launching the game; this speeds iteration on visual assets.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - headless
+      - render
+      - blender
+      - qa
+      - visual
+    detail: Four headless render scripts exist for exactly this reason, and the rendered pngs are kept
+      alongside them. In-game verified_on/verified_by removed — nothing here is observed in the
+      engine.
+  - id: cp2077.process.cet-cleanup-continuous
+    claim: A cet cleanup mod can run continuously (every 3s) to remove debug/legacy entities spawned
+      during development; this allows rapid iteration without manual cleanup between test runs.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - cleanup
+      - debug
+      - automation
+      - iteration
+    detail: "init.lua accumulates dt in an onUpdate handler, and every 3 seconds deletes every dynamic
+      entity carrying either of the mod's two cleanup tags via
+      GetDynamicEntitySystem():GetTaggedIDs. The one-shot version of this failed: it missed
+      late-streaming persistent entities and left two overlapping, unlootable cases. The mod is
+      author-only and is not shipped to users."
+  - id: cp2077.process.world-placement-via-blender-script
+    claim: Python scripts (a sector builder, a lid builder) can programmatically generate sector json,
+      mesh edits, and placement coordinates from blender math; this allows reproducible world
+      placement without manual json authoring.
+    status: inferred
+    source: ModWright research
+    tags:
+      - scripting
+      - python
+      - sector
+      - placement
+      - reproducible
+    detail: "True as far as it goes, with the sector saga's caveat attached: the sector builder's fully
+      hand-generated sector never shipped. What shipped is the minimal-diff approach of a
+      loot-injection script — \"Inject loot instanceData into the OFFICIAL entSpawner-generated
+      sector. Minimal change: everything else in the file stays byte-identical.\" The lid builder's
+      geometry (180° Z spin, bbox seating, raycast plaque placement) did ship. Fabricated in-game
+      verified attribution removed."
+  - id: cp2077.process.incremental-test-cycles
+    claim: "Develop in short cycles: change one thing, test in-game (yaml via hot-reload or entity spawn
+      via cet), read results (panels, logs, visual feedback), iterate. Avoid long chains of untested
+      changes."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - testing
+      - cycle
+      - iteration
+      - rapid-feedback
+    detail: "The worked example is the damage tuning: DamagePerHit -0.25 read 278 at T5, -0.104 read 333
+      (the yaml's own arithmetic predicted 332), each pass via TweakXL.Reload() and a fresh spawn.
+      Contrast the sector work, where long chains of untested json changes cost the most time in the
+      project."
+  - id: cp2077.process.scripted-spacebar-at-main-menu-unreliable
+    claim: 'Sending a spacebar to the Cyberpunk 2077 window from a script (`AppActivate` +
+      `SendKeys::SendWait(" ")`) to pass the press-any-key screen is unreliable: it can fail with
+      the window title present, so a non-empty MainWindowTitle is not proof of real input focus for
+      a DirectX game.'
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - process
+      - launch
+      - automation
+      - sendkeys
+      - focus
+      - unattended
+    detail: Scripted launches with no one at the keyboard that need the key should treat it as a step a
+      person may have to do, or use a mechanism that does not depend on foreground focus. The same
+      session also could not decode the CET overlay key from bindings.json's packed integer, so
+      console input was pasted by hand.

package/knowledge/cyberpunk2077/quests.minor.yaml

@@ -0,0 +1,46 @@
+game: cyberpunk2077
+topic: quests.minor
+title: Vanilla minor quests - their folders, phases, facts and items, as read for mod gating
+facts:
+  - id: cp2077.quests.minor.spellbound-is-mq015-wizardbook
+    claim: "Spellbound (Nix's book quest) is the minor quest mq015_wizardbook (journal path
+      quests/minor_quest/mq015_wizardbook), in base\\quest\\minor_quests\\mq015\\. Its phases:
+      mq015_01_hook, mq015_02_restaurant (and _combat), mq015_03_stash, mq015_04_afterlife. The
+      stash phase grants QuestRewards.mq015_found_wizardbook, and the book is the item
+      Items.mq015_wizardbook_encrypted. Its ItemAction.Crack makes Items.mq015_wizardbook_decrypted.
+      The Afterlife phase opens with the objective 04_afterlife/01_get_back_nix, checks the fact
+      mq015_decrypted_wizardbook, and at the end sets mq015_done to 1 and mq015_active to 0. Nix's
+      reward includes the recipes Items.Recipe_DisableCyberwareProgram and
+      Items.Recipe_WeaponMalfunctionProgram."
+    status: verified
+    verified_on: "2.31"
+    source: base\quest\minor_quests\mq015\mq015_wizardbook.quest and phases\mq015_0*.questphase; TweakDB
+      Items.mq015_wizardbook_encrypted, Items.mq015_wizardbook_decrypted,
+      QuestRewards.mq015_found_wizardbook
+    tags:
+      - quest
+      - minor-quest
+      - mq015
+      - spellbound
+      - nix
+      - facts
+      - journal
+    detail: 'For a gate on "V has progressed to the point of having the book, or further": V holds
+      either book item, or mq015_done >= 1. Where mq015_decrypted_wizardbook is set was not found in
+      these phases.'
+  - id: cp2077.quests.minor.kold-mirage-is-mq016-bartmoss
+    claim: Kold Mirage (Nix's Bartmoss quest) is the minor quest mq016_bartmoss, in
+      base\quest\minor_quests\mq016\. Its phases are mq016_00_shard, mq016_01_freezer and
+      mq016_02_afterlife. Its entities are mq016_bartmoss_cyberdeck, mq016_coffin and mq016_fusebox.
+    status: verified
+    verified_on: "2.31"
+    source: .modwright-cache/cyberpunk2077/vanilla.sqlite resource rows under
+      base\quest\minor_quests\mq016\
+    tags:
+      - quest
+      - minor-quest
+      - mq016
+      - kold-mirage
+      - nix
+    detail: The side_quests folders sq017 and sq012 are Kerry Eurodyne's questline and the Peralez "law"
+      quest, not these two.