modwright 0.1.0

package/knowledge/baldursgate3/vfx.materials.yaml

@@ -0,0 +1,174 @@
+game: baldursgate3
+topic: vfx.materials
+title: VFX effects, MultiEffectInfo, materials, and custom models
+facts:
+  - id: bg3.vfx.spell-effect-fields-hold-mei
+    claim: Spell effect fields (PrepareEffect/CastEffect/TargetEffect/BeamEffect/…) hold a
+      MultiEffectInfo UUID, not an effect resource ID. Each MEI is its own tiny .lsf at
+      Public/<Mod>/MultiEffectInfos/<uuid>.lsf (filename = UUID); custom MEIs in a mod's own folder
+      are picked up.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - multieffectinfo
+      - mei
+      - spells
+    detail: Vanilla ships ~4000 MEIs in Shared.pak.
+  - id: bg3.vfx.mei-structure
+    claim: 'A MEI (region MultiEffectInfos) holds ≥1 EffectInfo child: EffectResourceGuid (the actual
+      effect), BindSourceTo/BindTargetTo (SourceEntity/TargetEntity), SourceBone/TargetBone (e.g.
+      Dummy_R_HandFX → Dummy_BodyFX), Pivot, UseDistance (drives an lsfx "Distance To Target" input
+      — this is how beams stretch caster→victim), Min/MaxDistance, DetachSource/Target.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - mei
+      - structure
+      - bones
+    detail: "UseDistance snaps a beam to the source→target distance, which is a real constraint on
+      animating beam length: a class mod's roll-out attempts animated the Model's Uniform Scale keys
+      instead, and its notes record the open possibility that outward growth cannot be keyframed
+      while UseDistance drives length."
+  - id: bg3.vfx.effectresource-in-bank
+    claim: "EffectResourceGuid matches a Resource node ID in an EffectBank _merged.lsf (vanilla:
+      Public/Shared/Content/Assets/Effects/Effects/**/[PAK]_*/_merged.lsf; mods can add their own
+      bank anywhere under Public/<Mod>/Content/**/[PAK]_*/_merged.lsf). The bank node is metadata
+      only (EffectName, bounds, Duration) plus SourceFile → the .lsfx payload path inside the pak."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - effectbank
+      - resource
+      - metadata
+    detail: The engine merges all banks from all loaded mods globally, so GUIDs resolve cross-pak.
+  - id: bg3.vfx.lsfx-recoloring
+    claim: ".lsfx files (Effects.pak, Public/Shared/Assets/Effects/Effects_Banks/**) are plain LSF:
+      divine convert-resource round-trips lsfx↔lsx. Colours are editable fvec4 keyframes under
+      Properties (Model Appearance.Color = mesh tint multiplier, Particle.Appearance.Color =
+      particle gradient). Recolor = clone lsfx + edit fvec4s + own EffectBank entry + own MEI +
+      point the spell field at the new MEI UUID."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - lsfx
+      - recoloring
+      - colors
+    detail: Scale/rotation keys are editable the same way — a class mod rewrote a garrote Model's "Scale
+      And Rotation.Uniform Scale" keys (normalized time, pivot = Source hand) to change the wire's
+      retract timing, regenerating the lsfx in place with zero GUID/stat/bank changes.
+  - id: bg3.vfx.beam-effect-field
+    claim: A beam lives ONLY in the BeamEffect field — copying Prepare/Cast/Target GUIDs from a beam
+      spell (e.g. Target_ThornWhip) misses the beam entirely. Also, AttackSpellOverride basic
+      attacks run the override's mechanics but fire NONE of its cast VFX/animation; only a real cast
+      (e.g. an UnlockSpell'ed action) plays them.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - beam
+      - attackspelloverride
+      - animation
+    detail: This is the gotcha behind "I copied a beam spell's effects and got no beam".
+  - id: bg3.vfx.lslib-meta-headers
+    claim: Keep the same lslib_meta string (e.g. "v1,bswap_guids,…") when hand-authoring lsx for divine
+      conversion. The GUID strings displayed in lsx are the logical, game-visible GUIDs — use
+      identical strings across MEI, bank and stats and everything stays consistent.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - vfx
+      - lslib
+      - meta
+      - guids
+    detail: "Practical consequence: you can copy a GUID out of one converted lsx and paste it into
+      another without worrying about byte order, as long as the meta string is preserved on the
+      round-trip."
+  - id: bg3.materials.no-custom-base-material
+    claim: "There is no standalone material registry: MaterialBank is a region inside the same
+      _merged.lsf bank files that hold VisualBank (Public/<ns>/Content/**/[PAK]_*/_merged.lsf), and
+      one merged file can hold VirtualTextureBank, PhysicsBank, MaterialBank, TextureBank and
+      VisualBank side by side. A new BASE material cannot be authored without the Toolkit, because
+      each base needs compiled per-platform shaders (.bshd/.shd) beside the .lsf — so mods recolor
+      by registering a new INSTANCE of a vanilla base."
+    status: inferred
+    source: ModWright research
+    tags:
+      - materials
+      - materialbank
+      - base
+      - instance
+    detail: "The engine merges all banks from all loaded mods globally, so GUIDs resolve
+      cross-pak/cross-mod. Worked example from the notes: MaterialID 67605e13-…
+      (WPN_HUM_Warpick_A_0) is registered in
+      Shared.pak:Public/Shared/Content/Assets/Weapons/[PAK]_Humans/_merged.lsf."
+  - id: bg3.materials.instance-recipe
+    claim: "A MaterialBank Resource node is a material INSTANCE: ID (FixedString GUID = what
+      VisualBank's MaterialID references), Name, MaterialType (uint8; copy from a vanilla instance
+      of the same base — 4 = VT weapon, 27 = Glass_Glow, 5 = GM staff), DiffusionProfileUUID,
+      SourceFile = path to a base material .lsf under Public/Shared/Assets/Materials/…, plus
+      children (ScalarParameters / Vector3Parameters / Texture2DParameters /
+      VirtualTextureParameters) that override the base's parameters (ParameterName must match the
+      base's exactly; Enabled=True to take effect)."
+    status: inferred
+    source: ModWright research
+    tags:
+      - materials
+      - instance
+      - parameters
+      - customization
+    detail: The base material .lsf contains NO GUID (region Material, no ID attribute) — the bank entry
+      is the sole GUID→file mapping. All bank IDs are FixedString, so there is no bswap_guids
+      concern.
+  - id: bg3.materials.glow-capable-bases
+    claim: "Glow-capable bases: Base_Glass_Glow (params GlowColor fvec3 + GlowIntensity, classic
+      textures) versus the *_GM_VT family (the param is Glow_Color — with an underscore — plus
+      glowmap/Gradients VT textures; this is what vanilla elemental weapons use, e.g.
+      WPN_HUM_Glaive_A_2_2G_GM_Thunder). Base_VT (the plain weapon base) has no glow params at all."
+    status: inferred
+    source: ModWright research
+    tags:
+      - materials
+      - glow
+      - bases
+      - parameters
+    detail: The parameter name differs by base family (GlowColor vs Glow_Color), and ParameterName must
+      match the base exactly for an instance override to take effect.
+  - id: bg3.materials.clone-recipe
+    claim: "Cleanest recipe for a recolour: clone a full vanilla instance node of the target base (e.g.
+      the Lathander crystal 4dd462e8-d31e-ca0d-e3db-6acf40fef4ec for Base_Glass_Glow, in
+      Assets/Puzzle/[PAK]_Lathander/_merged.lsf), keep its texture GUIDs and DiffusionProfileUUID
+      verbatim (they are globally registered), give it a fresh v4 GUID + Name, retint GlowColor,
+      then point VisualBank Objects.MaterialID (every LOD row) at the new GUID. No meta.lsx
+      dependency changes are needed — Shared.pak and Materials.pak are implicit."
+    status: unverified
+    source: ModWright research
+    tags:
+      - materials
+      - recoloring
+      - recipe
+    detail: The same clone-and-retint shape is written up in more depth for armour/gloves in a class
+      mod's research notes, also unexecuted. Treat it as the planned route, not a proven one, and
+      pair the first attempt with a diagnostic.
+  - id: bg3.materials.divine-bracket-workaround
+    claim: Divine.exe convert-resource -s chokes on literal [PAK] brackets in the source path (glob
+      expansion) — copy the file to a bracket-free path first.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - materials
+      - divine
+      - paths
+      - brackets
+    detail: "Related PowerShell trap when grepping the same paths: -Path treats [PAK]-style brackets as
+      wildcards, so use -LiteralPath or [System.IO.File]::ReadAllText."

package/knowledge/baldursgate3/visuals.characterfix.yaml

@@ -0,0 +1,73 @@
+game: baldursgate3
+topic: visuals.characterfix
+title: Fixing invisible / default-appearance Character Visuals in the Toolkit
+facts:
+  - id: bg3.visuals.characterfix.base-dropdown-must-match-animation-set
+    claim: In the Toolkit's Character Visual editor, the "_Base" selected in the first (leftmost)
+      drop-down must be set to whatever animation-set base the character actually uses, or the
+      visual's equipment slots won't resolve correctly.
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, step 1
+    tags:
+      - toolkit
+      - character-visuals
+      - invisible
+      - animation-set
+  - id: bg3.visuals.characterfix.filter-must-include-own-base-again
+    claim: 'After clicking Filter in the Character Visual editor, the "_Base" must be added a second
+      time inside the filter window itself: "search and double click to add your _Base again in the
+      first window". The outer drop-down and the filter window are separate settings, both
+      required.'
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, steps 2-3
+    tags:
+      - toolkit
+      - character-visuals
+      - filter
+      - silent-failure
+  - id: bg3.visuals.characterfix.filters-use-naming-prefix
+    claim: Additional Filters entries in the Character Visual editor should reflect the naming prefix of
+      whatever assets you want selectable for that character — only assets whose names match an
+      active filter prefix will show up as pickable options later in the fix.
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, step 4
+    tags:
+      - toolkit
+      - character-visuals
+      - filter
+      - naming-convention
+  - id: bg3.visuals.characterfix.body-gr2-goes-in-lower-right-slot
+    claim: The character's body .GR2 mesh goes into a separate field of the Filter window — "To the
+      lower right by 1, add the body gr2 by searching and double clicking" — not into the "_Base" or
+      prefix-filter entries.
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, step 5
+    tags:
+      - toolkit
+      - character-visuals
+      - body-mesh
+  - id: bg3.visuals.characterfix.save-close-required-before-picking-body
+    claim: The Filter window must be saved and closed (Save & Close) before the newly filtered body
+      option becomes selectable in the Character Visual editor's lower body drop-down.
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, steps 6-7
+    tags:
+      - toolkit
+      - character-visuals
+      - save
+      - ordering
+  - id: bg3.visuals.characterfix.missing-slots-added-with-plus
+    claim: "Any equipment slots the character is missing at the bottom of the Character Visual editor
+      must be added manually with the \"+\" button: \"At the bottom, add any slots you need and
+      don't have with the +. Anything with prefixes matching your filters and matching the slot
+      should show here now!\""
+    status: community
+    source: wiki.bg3.community/Tutorials/Toolkit/charvis-fix, step 8
+    tags:
+      - toolkit
+      - character-visuals
+      - slots
+      - filter
+    detail: "This is the fix for the symptom the page is titled after: a character showing as invisible
+      or with a default/fallback appearance because its Character Visual has no filtered, matching
+      options wired up for one or more slots."

package/knowledge/cyberpunk2077/animations.anims.yaml

@@ -0,0 +1,118 @@
+game: cyberpunk2077
+topic: animations.anims
+title: Linking a custom .anims file into a scene's cinematic animation sets
+facts:
+  - id: cp2077.animations.anims.three-part-index-linked-system
+    claim: "Playing a custom animation in a scene is \"a three-part system\": the Resource List
+      (`resourceReferences`) naming the external `.anims` files and the animations used from them;
+      the actor's \"Permissions\" (`playerActors` / `actors`) saying which animation sets it may
+      use; and the Event in the sceneGraph that plays one CName. \"The link between these three
+      parts is a simple index number (ID).\""
+    status: community
+    source: wiki.redmodding.org "Adding Animations", unheaded introduction and the "library" analogy
+      that follows it
+    tags:
+      - animation
+      - scene
+      - cinematicanimsets
+      - index-linked
+    detail: "Field-name caution for a validator: the page's introduction and \"Tying It All Together\"
+      write `resourceReferences`, while steps 1 and 2 write `resouresReferences`; the introduction's
+      spelling is the one used throughout these facts."
+  - id: cp2077.animations.anims.cinematicanimsets-depotpath-field
+    claim: A new `.anims` file is registered by adding an entry to
+      `resourceReferences.cinematicAnimSets` and setting its animation file path, "in the JSON, this
+      is `asyncAnimSet.DepotPath`". Entries are indexed from 0 upward and the index is reused in the
+      next two steps.
+    status: community
+    source: 'wiki.redmodding.org "Adding Animations", section "Step 1: Add the Animation Resource File"'
+    tags:
+      - animation
+      - scene
+      - cinematicanimsets
+      - depotpath
+      - syntax
+    detail: The page's example path is
+      `base\animations\npc\generic_characters\male_average\interactive_scene\generic_average_male_transitions.anims`.
+  - id: cp2077.animations.anims.cinematicanimnames-index-must-match
+    claim: An entry must be added to `resourceReferences.cinematicAnimNames` "at the exact same index"
+      as its `cinematicAnimSets` entry — "This is the most critical part. The index of
+      `cinematicAnimSets` and `cinematicAnimNames` must match for the same animation set." Inside
+      it, the `animationNames` array lists the CName of each animation to be called from that
+      `.anims` file.
+    status: community
+    source: 'wiki.redmodding.org "Adding Animations", section "Step 2: List the Animation Names"'
+    tags:
+      - animation
+      - scene
+      - cinematicanimnames
+      - index-match
+      - gotcha
+  - id: cp2077.animations.anims.actor-permission-is-index-only
+    claim: 'An actor is granted an animation set by adding an entry to its own animation-set array —
+      `bodyCinematicAnimSets` (full-body cinematic), `facialCinematicAnimSets` (facial expressions)
+      or `gameplayAnimSets` — where "This new entry will have a single, important field: `id`", set
+      to the shared index. The actor entry carries no resource reference of its own.'
+    status: community
+    source: "wiki.redmodding.org \"Adding Animations\", section \"Step 3: Give the Actor 'Permission' to
+      Use the Animation Set\""
+    tags:
+      - animation
+      - scene
+      - playeractors
+      - bodycinematicanimsets
+      - syntax
+  - id: cp2077.animations.anims.playeractors-vs-actors-array
+    claim: "Where to find the actor: \"if it's the player then the `playerActors`[0] or if it's a
+      specific actor, then find the entry in the `actors` array\"."
+    status: community
+    source: "wiki.redmodding.org \"Adding Animations\", section \"Step 3: Give the Actor 'Permission' to
+      Use the Animation Set\" (step 1)"
+    tags:
+      - animation
+      - scene
+      - playeractors
+      - actors
+      - syntax
+  - id: cp2077.animations.anims.rule-generalises-to-other-animset-types
+    claim: '"Although the guide specifically mentions `bodyCinematicAnimSets`, the same principle
+      applies for other animSets as well such as `lipsyncAnimSets`, `gameplayAnimSets`."'
+    status: community
+    source: wiki.redmodding.org "Adding Animations", info hint at the top of the page
+    tags:
+      - animation
+      - scene
+      - lipsyncanimsets
+      - gameplayanimsets
+      - index-match
+  - id: cp2077.animations.anims.runtime-resolution-order
+    claim: "At runtime the engine resolves a scene animation by index alone: it sees the actor is
+      playing the animation, checks the actor's `bodyCinematicAnimSets` for which animation set ids
+      it has, uses that id \"as an index to find the .anims file in
+      resourceReferences.cinematicAnimSets\", loads that file and plays the specified CName."
+    status: community
+    source: 'wiki.redmodding.org "Adding Animations", section "Tying It All Together: Playing the
+      animation"'
+    tags:
+      - animation
+      - scene
+      - runtime-resolution
+    detail: "Renamed from cp2077.animations.anims.runtime-resolution-has-no-validation on 2026-09-07:
+      the page describes the resolution order but says nothing about what a wrong index does or
+      whether WolvenKit validates it, so the previous claim's \"fails silently rather than raising a
+      WolvenKit-side validation error\" was removed as unsourced. The `scnPlaySkAnimEvent` in the
+      scene graph selects the animation by CName, e.g. `lie_ground__r_elbow_on_ground__01`."
+  - id: cp2077.animations.anims.community-anim-lookup-spreadsheet
+    claim: 'For valid animation CNames and their durations the guide points at a community Google Sheets
+      lookup: "Use this anim look up sheet to search for specific anim names, duration etc"
+      (docs.google.com/spreadsheets/d/1YxZf90FzvDfJcny94kTSed46ItH_0VyZr76rWtgEAxc).'
+    status: community
+    source: 'wiki.redmodding.org "Adding Animations", success hint under "Step 2: List the Animation
+      Names"'
+    tags:
+      - animation
+      - scene
+      - tooling
+      - community-resource
+    detail: "Corrected 2026-09-07: the previous claim's rationale, that `.anims` files are not browsable
+      by animation name from WolvenKit's scene editor, is not stated on the page."

package/knowledge/cyberpunk2077/anims.archivexl.yaml

@@ -0,0 +1,163 @@
+game: cyberpunk2077
+topic: anims.archivexl
+title: ArchiveXL animation config, resource patching, and the upstream fix for custom per-weapon FPP
+  anim sets
+facts:
+  - id: cp2077.anims.archivexl.animations-config-schema
+    claim: An ArchiveXL `animations:` .xl config entry supports `entity` (a scalar path or a list of
+      entity paths), `set` (the .anims resource path to mount), `priority` (an integer), and `vars`
+      (a list of AnimWrapper variable names gating when the set mounts).
+    status: inferred
+    source: ModWright research
+    tags:
+      - animations-config
+      - xl-schema
+      - entity
+      - set
+      - priority
+      - vars
+    detail: Described from the context of filing the two parser-bug issues below, which specifically
+      exercise the `entity`, `set`, `priority` and `vars` keys against
+      v1.27.0/v1.27.1/v1.28.0-beta.1.
+  - id: cp2077.anims.archivexl.animconfig-vars-parser-bug
+    claim: "ArchiveXL's AnimationsConfig::LoadYAML (src/App/Extensions/Animation/Config.cpp, line 82,
+      present in v1.27.0, v1.27.1 and v1.28.0-beta.1) has a parser bug: the loop over an entry's
+      `vars:` list tests `variablesNode.IsScalar()` (the SEQUENCE node) instead of
+      `variableNode.IsScalar()` (the item), so the condition is always false and entry.variables
+      stays empty — an `animations:` entry declared with `vars:` is injected with an EMPTY
+      variableNames list and mounts unconditionally instead of being variable-gated."
+    status: verified
+    verified_on: "2.3"
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - parser-bug
+      - vars
+      - animwrapper-gating
+      - config-cpp
+    detail: "Practical effect for a set that overrides shared animation names: this bug leaks the
+      override to every weapon/state using those clip names, since the intended variable gate never
+      takes effect. It went unnoticed by photo-mode pose packs because they do not use `vars:`. Fix
+      (one line): test `variableNode.IsScalar()` instead of `variablesNode.IsScalar()`."
+  - id: cp2077.anims.archivexl.animconfig-entity-list-parser-bug
+    claim: "The same Config.cpp file (line 50) has a second parser bug: its `else if` branch for the
+      `entity:` field repeats the same condition as the `if` branch above it
+      (`entityNode.IsScalar()`) instead of testing `entityNode.IsSequence()`, so a LIST form of
+      `entity:` (multiple entity paths in one `animations:` entry) never parses and the whole entry
+      is rejected as malformed."
+    status: verified
+    verified_on: "2.3"
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - parser-bug
+      - entity
+      - list-form
+      - config-cpp
+    detail: "Fix (one line): change the `else if` test from `entityNode.IsScalar()` to
+      `entityNode.IsSequence()`."
+  - id: cp2077.anims.archivexl.pr-merged-upstream
+    claim: A pull request fixing both Config.cpp parser bugs (the `vars` drop and the unreachable
+      list-form `entity:`) was submitted to psiberx/cp2077-archive-xl and was accepted and merged
+      into main on 2026-08-20.
+    status: inferred
+    source: ModWright research
+    tags:
+      - archivexl
+      - pull-request
+      - upstream
+      - merged
+      - animations-config
+    detail: "Downgraded from verified to community by review: the merge is an upstream repository event
+      reported by the project's own notes, not something observed in the engine here, and it has not
+      been re-checked against psiberx/cp2077-archive-xl. The mod does not depend on the fix landing
+      in a release — it ships via the ResourcePatch route instead (see
+      cp2077.anims.sets.resourcepatch-mounting-route) — but once an ArchiveXL release ships the fix,
+      `animations:` becomes a viable simpler alternative mounting method for a per-weapon FPP anim
+      set. Update 2026-09-07: both fixes are present in ArchiveXL v1.27.3 (source read, not tested
+      in engine, hence inferred). `animations:` with `vars:` and list-form `entity:` should work
+      from 1.27.3; the ResourcePatch route remains what the shipped mod uses and the only one
+      verified in game."
+  - id: cp2077.anims.archivexl.local-fix-dlls-used-for-testing
+    claim: "Before filing the upstream PR, the project built and locally tested three variant DLLs
+      against the stock v1.27.1 baseline: a stock reference build (ArchiveXL-1.27.1-stock.dll), a
+      build with only the two Config.cpp parser fixes applied (ArchiveXL-1.27.1-fix1.dll /
+      ArchiveXL-fix1-animconfig.dll), and a build additionally patching the
+      ResourcePatch/Extension.cpp header gate that was suspected (later retracted) to be a second
+      bug (ArchiveXL-1.27.1-fix2.dll / ArchiveXL-fix2-resourcepatch.dll)."
+    status: inferred
+    source: ModWright research
+    tags:
+      - archivexl
+      - local-build
+      - testing
+      - fix-dll
+      - resourcepatch
+    detail: Deploying a locally built test DLL requires backing up the original 1.27.1
+      red4ext\plugins\ArchiveXL\ArchiveXL.dll first and closing the game before overwriting it.
+  - id: cp2077.anims.archivexl.resourcepatch-header-issue-retracted
+    claim: An initially suspected ArchiveXL bug — that ResourcePatch component patches onto entity
+      templates silently skip base-game-cooked (base\) templates while applying fine to Phantom
+      Liberty (ep1\) templates, because of an early return when compiledDataHeader.IsEmpty() — was
+      investigated as a candidate "Fix 2" but the observed behavior was later found to be
+      MISTARGETING on the mod's own part, not an ArchiveXL bug; no issue was filed for it, and any
+      posted draft was to be retracted.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - archivexl
+      - resourcepatch
+      - retracted
+      - mistargeting
+      - dead-belief
+    detail: The candidate bug fix (relaxing the early `if (templateHeader.IsEmpty()) return;` gate and
+      enabling a commented-out ObjectPackageReader fallback) was never submitted upstream. See
+      cp2077.anims.sets.patch-the-ep1-player-ent for the real cause (the mod's own mistargeting of
+      the base\ player entity on a Phantom Liberty install), which supersedes this.
+  - id: cp2077.anims.archivexl.animwrapper-raised-lowered-from-redscript
+    claim: The AnimWrapper variable that gates a custom per-weapon FPP anim set is raised and lowered
+      from redscript on equip/holster events, wrapping PlayerPuppet.OnItemAddedToSlot /
+      OnItemRemovedFromSlot, gated on the WeaponRight slot plus a custom weapon tag; this
+      registration technique is independent of the `animations:` ArchiveXL config feature entirely.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - animwrapper
+      - redscript
+      - onitemadded
+      - equip-holster
+      - gating
+    detail: Verified in game via CET console (a mod's own debug call to disable its dev harness, then
+      holster/redraw to confirm the redscript path alone keeps the set gated correctly).
+  - id: cp2077.anims.archivexl.melee-animation-randomizer-steering-pattern
+    claim: A dissected community mod ("Melee Animation Randomizer", v4 source) demonstrated the pattern
+      of steering an animgraph's clip choice at runtime by using @wrapMethod on
+      Melee*AttackEvents.OnEnter to rewrite AnimFeature_MeleeSlotData(attackType, comboNumber) AFTER
+      the vanilla call runs, letting a mounted set play any addressable entry for any state; the
+      same mod also demonstrated a startup/active/recover speed-blend between the mechanical
+      (record) and native (visual) timing, a trailAttackSide fix, and an NPC hit-reaction fix via
+      HitReactionComponent.EvaluateHit attackDefinition swap.
+    status: community
+    source: ModWright research
+    tags:
+      - community-mod
+      - melee-animation-randomizer
+      - animsteering-pattern
+      - wrapmethod
+    detail: This dissected pattern is the direct ancestor of a melee weapon mod's own finisher redirect
+      in redscript; a mod reusing the pattern should credit the source mod.
+  - id: cp2077.anims.archivexl.archive-changes-need-restart-not-hot-reload
+    claim: "TweakXL.Reload() (the CET console hot-reload call) reloads TweakDB yaml only; ArchiveXL
+      loads and registers .xl manifest entries (animations config, resource patches, localization,
+      factories, streaming) once at game initialization and does NOT re-read them on a tweak reload
+      — any archive-side change (a repacked .anims, a changed animations: entry, a resource patch
+      edit) needs a repack, a redeploy, and a full game RESTART."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - tweakxl-reload
+      - archive-restart
+      - hot-reload-asymmetry
+      - archivexl
+    detail: This asymmetry is the main cost driver of the archive-side iteration loop, distinct from and
+      slower than the yaml-side loop.