modwright 0.1.0

package/knowledge/cyberpunk2077/anims.sets.yaml

@@ -0,0 +1,176 @@
+game: cyberpunk2077
+topic: anims.sets
+title: Player FPP animation sets, mounting and gating
+facts:
+  - id: cp2077.anims.sets.vars-are-animwrapper-weights
+    claim: The variableNames that gate an animAnimSetupEntry on the player entity are AnimWrapper
+      weights, not booleans or TweakDB flags. Raise one from script with
+      AnimationControllerComponent.SetAnimWrapperWeight(ent, n"<name>", 1.0) or by sending an
+      AnimWrapperWeightSetter event. Custom variable names can be invented; they do not have to
+      exist in vanilla.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - animation
+      - animwrapper
+      - anim-set
+      - gating
+      - player
+      - fpp
+  - id: cp2077.anims.sets.lower-priority-number-wins
+    claim: Between two mounted animation sets, the LOWER priority number wins (pwa_katana at 128 beats
+      default_melee_weapon at 200). Sets override each other by shared animation NAMES, not by slot
+      or by file.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - animation
+      - anim-set
+      - priority
+      - override
+    detail: pwa_katana shares 83 of 97 animation names with default_melee_weapon, which is why mounting
+      it replaces most of the melee moveset.
+  - id: cp2077.anims.sets.patch-the-ep1-player-ent
+    claim: With Phantom Liberty installed the game loads
+      ep1\characters\entities\player\player_ma/wa_fpp_ep1.ent. The base\ entity is only the no-EP1
+      fallback. A patch aimed only at base\ registers successfully and then silently does nothing,
+      with NO log line. List BOTH paths so the mod works with and without PL.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - ep1
+      - phantom-liberty
+      - player-entity
+      - silent-failure
+      - archivexl
+      - patch
+    supersedes: cp2077.anims.archivexl.resourcepatch-header-issue-retracted
+    detail: "Cost a long debug session and two nearly-filed ArchiveXL bug reports - the no-op looks
+      exactly like a broken tool. The ep1 template is a standalone 124-component copy, not an
+      include. GENERALISES: before blaming a tool for a silent no-op on a vanilla asset, grep
+      tools\\redmod\\tweaks for an [ EP1 ] override of that asset. MERGED from two equivalent facts
+      (one in the ArchiveXL topic, one in the packaging topic). What they add: the wrong diagnosis
+      this replaced was an ArchiveXL bug report claiming ResourcePatch component patches silently
+      skip base-game-cooked templates because of an early return when compiledDataHeader.IsEmpty() —
+      that draft issue was RETRACTED once the ep1 mistargeting was found
+      (cp2077.anims.archivexl.resourcepatch-header-issue-retracted), and no such issue was filed
+      upstream. The rule for a manifest is therefore to list BOTH the base\\ and ep1\\ template
+      paths for BOTH genders in the same `resource: patch:` block, which is what the shipped .xl
+      does, so the mod works with and without Phantom Liberty."
+  - id: cp2077.anims.sets.do-not-hot-reload
+    claim: .anims content does NOT hot-reload, and swapping an archive underneath a mounted animation
+      set CRASHES the game. Animation sets are cached when the set mounts, so a depot swap never
+      reaches them. Budget a full relaunch per animation iteration.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - animation
+      - hot-reload
+      - crash
+      - redhottools
+      - iteration
+    detail: A same-name repack with a different donor set was dropped into archive\pc\hot. RedHotTools
+      ingested it, the idle stayed on the OLD clips, and forcing a re-resolve by switching weapons
+      killed the process. Meshes and textures hot-reload fine; this is specific to anims.
+  - id: cp2077.anims.sets.resourcepatch-mounting-route
+    claim: An animation set can be mounted by appending a small entAnimationSetupExtensionComponent
+      (controlBinding to root) to the player fpp entities via ArchiveXL ResourcePatch.
+      MergeComponents matches on name plus id, and no match means append. The .ent carries its own
+      variableNames, so gating works with no ArchiveXL fix required.
+    status: verified
+    verified_on: 1.27.1
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - resourcepatch
+      - animation
+      - anim-set
+      - player-entity
+    detail: "MERGED from an equivalent fact, which records this as the SHIPPING route on stock ArchiveXL
+      1.27.1 with no upstream fix required: the set at mod\\<mod>\\anims\\p[mw]a_<mod>.anims,
+      priority 127, gated on w_melee_<mod>, mounted when its wrapper variable was raised, and the
+      machete's own anim set was confirmed unchanged in the same session — i.e. per-weapon gating
+      worked as intended with zero effect on other weapons. The patch targets are the ep1 player fpp
+      .ent files plus the base\\ paths as a no-Phantom-Liberty fallback (see
+      cp2077.anims.sets.patch-the-ep1-player-ent)."
+  - id: cp2077.anims.sets.archivexl-animations-feature-broken
+    claim: 'The ArchiveXL "animations:" .xl feature is broken in versions up to and including 1.27.1:
+      vars: are dropped, and the list form of entity: never parses. Until a fix ships, do not use
+      "animations:" to mount a weapon-specific set - the dropped vars mount it on every melee
+      weapon.'
+    status: verified
+    verified_on: 1.27.1
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - animation
+      - anim-set
+      - bug
+      - upstream
+    detail: "The two typos are recorded at mechanism level, one fact each, at
+      cp2077.anims.archivexl.animconfig-vars-parser-bug (line 82 tests the SEQUENCE node instead of
+      the item, so entry.variables stays empty) and
+      cp2077.anims.archivexl.animconfig-entity-list-parser-bug (line 50's `else if` repeats the
+      `if`'s IsScalar() test instead of IsSequence(), so the list form of `entity:` never parses and
+      the entry is rejected as malformed). Both are present in v1.27.0, v1.27.1 and v1.28.0-beta.1,
+      and each fix is one line. MERGED from a third, packaging-side restatement, which adds the
+      standing manifest rule this produced: the shipped mod's .archive.xl carries a comment telling
+      future editors NOT to switch the mount to the `animations:` feature and to keep the `resource:
+      patch:` route, because the .ent's own variableNames field is not subject to the parser bug
+      (see cp2077.anims.sets.resourcepatch-mounting-route). Update 2026-09-07: fixed upstream in
+      ArchiveXL v1.27.3 (see cp2077.anims.archivexl.pr-merged-upstream); the claim holds for 1.27.1
+      and earlier and for 1.28.0-beta.1, which predates the fix."
+  - id: cp2077.anims.sets.melee-motion-database-csv
+    claim: Melee clip names are NOT composed by an index switch in the animgraph. They come from a
+      motion database CSV, base\animations\anim_motion_database\player_melee_attacks.csv (plus _hits
+      and _deflects), keyed by (MeleeSlotData.attackType, MeleeSlotData.comboNumber). Row (0,N)
+      resolves to combo_attack_0(N+1), (1,N) to heavy_attack_0(N+1), (2,N) to final_attack_0(N+1),
+      nine slots per class.
+    status: inferred
+    source: ModWright research
+    tags:
+      - animation
+      - melee
+      - motion-database
+      - csv
+      - attack
+    detail: "The attackType table has 13 rows: 0 __COMBO__, 1 __STRONG__, 2 __FINAL__, 3 __BLOCK__, 4
+      __SAFE__, 5 __SLIDE__, 6 __CROUCH__, 7 __JUMP__, 8 __SPRINT__, 9 __FALL__, 10 __THROW__, 11
+      __DODGE__, 12 __EQUIP__ (rows 3-12 take comboNumber \"*\"). A custom set that omits a row
+      plays ANOTHER WEAPON'S clip rather than failing. Note parried_*, block_deflect_* and
+      melee_slide_* are NOT in this table at all - they are animgraph-driven, so grepping the CSV
+      does not prove a clip is dead. MERGED from an equivalent fact, which adds: each of the three
+      CSVs (player_melee_attacks.csv and its _hits / _deflects siblings) carries 50 rows; the
+      __STRONG__ row also maps melee_hack_attack, mantisblade_special_heavy and
+      one_punch_heavy_attack; and the \"clip names come from the CSV, not from an index switch in
+      the animgraph\" finding was established by TWO independent reachability walks of the
+      serialized live Attack pose graph, which refuted an earlier reading of a dead legacy subtree
+      (see cp2077.anims.graph.real-swing-ceiling-is-nine-slot-csv)."
+  - id: cp2077.anims.sets.weapon-family-set-is-the-fallback
+    claim: A clip name that a custom animation set omits falls through to the WEAPON-FAMILY set first,
+      not straight to the ungated default. The machete plays pwa_one_handed_blunt.anims at priority
+      128, gated on the AnimWrapper variable w_melee_one_hand_blunt, which is the weapon record's
+      friendlyName. default_melee_weapon.anims is only the ungated priority-200 fallback.
+    status: inferred
+    source: ModWright research
+    tags:
+      - animation
+      - anim-set
+      - fallback
+      - priority
+      - melee
+      - friendlyname
+    supersedes: cp2077.anims.graph.anim-set-gating-variable-is-native-old-belief
+    detail: "There is no pwa_machete.anims. Established by reading scripts and records offline rather
+      than by an in-engine experiment. MERGED from an equivalent fact, which adds the MECHANISM and
+      its moddability: the gating AnimWrapper variable IS the weapon record's own friendlyName
+      string field, raised natively via SetAnimWrapperWeight(puppet,
+      StringToName(itemRecord.FriendlyName()), value) at inGameMenuGameController.script:637 — so it
+      is fully moddable by setting friendlyName on a custom item record in yaml, with no native
+      change needed. Confirmed on base_katana.tweak:15, base_knife.tweak:7, base_baton.tweak:9,
+      base_two_hand_hammer.tweak:13 and five one-hand-blunt-family bases (all at
+      w_melee_one_hand_blunt). This supersedes an earlier project hypothesis that the variable was
+      native C++ behaviour with no data lever. See
+      cp2077.anims.graph.machete-plays-one-handed-blunt-set for the depot survey ruling out a
+      per-weapon machete file, and cp2077.anims.graph.custom-set-mount-priority-competitor for what
+      inheriting a base preset's friendlyName costs a custom weapon."

package/knowledge/cyberpunk2077/archivexl.bodytypes.yaml

@@ -0,0 +1,149 @@
+game: cyberpunk2077
+topic: archivexl.bodytypes
+title: ArchiveXL body-type tag registration for body mods and refits
+facts:
+  - id: cp2077.archivexl.bodytypes.player-bodytypes-key
+    claim: "A body mod registers itself with ArchiveXL by putting a `player` top-level key in a `.xl`
+      manifest with a `bodyTypes` list of one or more tag names, e.g. `player: { bodyTypes: [
+      MyBodyName ] }`; this registration method requires ArchiveXL >= 1.14 (an older, more tedious
+      per-appearance method also still works and is documented separately)."
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits/README.md,
+      sections "Body modders: Adding support" and "1. Registering the body mod"'
+    tags:
+      - archivexl
+      - manifest
+      - player
+      - bodytypes
+      - body-mod
+    detail: The page's minimum-required-ArchiveXL-version banner for the page as a whole is 1.5, but the
+      `player.bodyTypes` shortcut specifically is called out as "the new method (for version >=
+      1.14)"; a scaffold targeting the shortcut key should gate on 1.14, not the page's overall 1.5
+      floor.
+    related:
+      - id: cp2077.clothing.refits.body-mod-version-floor
+        detail: 'Agrees, and is the same page read for its version banner alone: that fact records the 1.5
+          floor and the ">= 1.14" new-method note; this one records what the new method actually is
+          (the `player.bodyTypes` manifest key). Neither number is a game version.'
+  - id: cp2077.archivexl.bodytypes.tag-name-becomes-snake-case-substitution
+    claim: A body tag registered via `player.bodyTypes` (e.g. `BoobsForBackProblems`) is converted to
+      snake_case (`boobs_for_back_problems`) to become the `{body}` substitution value usable in
+      dynamic-appearance conditions and path substitutions; if no body mod is installed, `{body}`
+      resolves to the literal string `base_body`.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits/README.md,
+      section "1. Registering the body mod" (yaml comment) and "Clothing mods: Making use of the
+      tags" (`base_body` fallback warning)'
+    tags:
+      - archivexl
+      - body-tag
+      - snake_case
+      - substitution
+      - base_body
+    detail: "`base_body` is also the value clothing mods should target for body mods that keep the
+      vanilla body shape (the page names EVB and VTK Vanilla HD FemV as examples of vanilla-shaped
+      bodies that use `base_body` rather than registering their own tag)."
+  - id: cp2077.archivexl.bodytypes.registration-needs-patched-mesh-component-name
+    claim: "Registering a body tag also requires patching the player entity: a patch `.ent` containing
+      an `entMeshComponent` whose `name` is changed to `Body:<BodyModName>` (e.g. `Body:NewBody`)
+      must be registered against the vanilla player entity files via ArchiveXL resource patching
+      (`resource.patch`), separately per body gender (`player_wa.ent` / `player_ma.ent` — only the
+      relevant gender needs including)."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits/README.md,
+      sections "2. Patch the player entity files" and "Register the patch .ent"
+    tags:
+      - archivexl
+      - body-tag
+      - resource-patch
+      - entmeshcomponent
+    detail: "RELATED: this is a concrete worked use of cp2077.archivexl.manifest.resource-patch-key
+      against the base game's player entity specifically, not an arbitrary mod-owned resource."
+  - id: cp2077.archivexl.bodytypes.check-current-body-via-cet
+    claim: The currently active body-tag suffix for the local player can be read from CET with
+      `Game.GetScriptableSystemsContainer():Get("PuppetStateSystem"):GetBodyTypeSuffix(ItemID.new(),
+      GetPlayer(), nil)`; the same `PuppetStateSystem` also exposes `GetArmsStateSuffix` and
+      `GetFeetStateSuffix` for the arm-cyberware and foot-state substitutions.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits/README.md,
+      section "Checking the current body"; and archivexl-suffixes-and-substitutions.md, sections
+      "Arm states" and "Foot states"
+    tags:
+      - archivexl
+      - cet
+      - puppetstatesystem
+      - debugging
+      - body
+      - arms
+      - feet
+  - id: cp2077.archivexl.bodytypes.arm-state-table-is-source-checked
+    claim: The documented arm-cyberware substitution values (`base_arms`, `mantis_blades`, `monowire`,
+      `projectile_launcher`) and foot-state values (`flat`, `lifted`, `high_heels`, `flat_shoes`)
+      both carry an explicit note to re-check them against
+      `src/App/Extensions/PuppetState/System.cpp` in psiberx/cp2077-archive-xl if they stop working,
+      because the wiki table is not guaranteed to track the source.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      sections "Arm states" (link to src/App/Extensions/PuppetState/System.cpp#L72) and "Foot
+      states" (same file #L89), both pinned at psiberx/cp2077-archive-xl commit
+      027aab7139689ee8d14163682ab6d506fbccea2a'
+    tags:
+      - archivexl
+      - arms
+      - feet
+      - source-of-truth
+      - staleness
+  - id: cp2077.archivexl.bodytypes.male-feet-states-need-a-mod
+    claim: Foot-state substitution (flat/lifted/high-heels) is only implemented for the female-rigged
+      body by default; male-rigged V has no vanilla foot-state support and needs a body mod or the
+      "Toggleable Feet" mod to get one — for male V the foot-state suffix/substitution is documented
+      as simply empty.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Foot states" (warning hint and table row "Male / Any / (empty)")
+    tags:
+      - archivexl
+      - feet
+      - male
+      - gender
+      - gap
+  - id: cp2077.archivexl.bodytypes.body-support-tag-only-needed-for-nonstandard-shape
+    claim: A body mod only needs to register its own ArchiveXL body tag if its mesh shape differs from
+      the base game body; a body mod that keeps the vanilla proportions does not need to register a
+      tag and clothing should target it as `base_body`.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-body-mods-and-refits/README.md,
+      hint under "Body modders: Adding support" ("If your body mod has the same shape as the
+      basegame body, you do not need to do this.")'
+    tags:
+      - archivexl
+      - body-tag
+      - base_body
+      - when-not-needed
+  - id: cp2077.archivexl.bodytypes.resource-patch-entry-needs-at-least-one-target
+    claim: 'An ArchiveXL manifest resource.patch entry whose target list is empty is rejected at
+      extension load: ArchiveXL logs "[error] Line #N: Patch definition must have at least one
+      target." for each such entry and then "[warning] Archive extensions are loaded with issues.",
+      and the patch .ent attaches to nothing. The rest of the manifest (player bodyTypes,
+      localization, factories) still loads.'
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - resource-patch
+      - manifest
+      - body-tag
+      - scaffold
+      - lint
+    detail: The new-garment-refit scaffold emitted the empty lists until this run; it now names the base
+      + ep1 player FPP entity per gender, and cp2077.history.xl-manifest-lint warns on an empty
+      target list. Which player entities a body-mesh patch must target for third-person visibility
+      (player_XX_tpp.ent exists in the vanilla index) is not yet observed.

package/knowledge/cyberpunk2077/archivexl.dynamic-appearances.yaml

@@ -0,0 +1,218 @@
+game: cyberpunk2077
+topic: archivexl.dynamic-appearances
+title: ArchiveXL dynamic appearances — conditions, substitutions and their placeholders
+facts:
+  - id: cp2077.archivexl.dynamic-appearances.introduced-in-1.5.0
+    claim: ArchiveXL's dynamic appearances feature (rule-based selection of components and appearances,
+      replacing hand-multiplied suffix combinations) was introduced in ArchiveXL version 1.5.0.
+    status: verified
+    source: psiberx/cp2077-archive-xl@7988eb5, `git ls-tree v1.4.1` vs `v1.5.0`
+      (src/App/Extensions/GarmentOverride/Dynamic.{cpp,hpp} first appear at v1.5.0, defining
+      DynamicAppearanceTag, VariantMarker '!', ConditionMarker '&', DynamicValueMarker '*' and the
+      gender/camera/body/feet attributes); CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/README.md, section "Dynamic appearances"
+      ("Version 1.5.0 of ArchiveXL solves this problem by introducing dynamic variants")
+    tags:
+      - archivexl
+      - dynamic-appearances
+      - version-floor
+    detail: "Checked against the source (2026-09-08): this contradicted the existing
+      cp2077.clothing.garments.dynamic-appearance-version-floors, which said dynamic variants were
+      \"added in 1.13\" on the strength of one sentence in the dynamic-variants guide. The guide's
+      own Prerequisites section says ArchiveXL >= 1.5.0, and the repository's tags confirm 1.5.0, so
+      that fact is now contradicted and this one supersedes it. No `verified_on`: the source names
+      an ArchiveXL version, not a game build."
+  - id: cp2077.archivexl.dynamic-appearances.substitutions-since-1.8.0
+    claim: Path/name substitutions for dynamic appearances (the `{placeholder}` interpolation syntax)
+      were added in ArchiveXL 1.8.0, three minor versions after dynamic appearances themselves
+      (1.5.0); conditions and substitutions are documented as two related but separately-versioned
+      capabilities.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Which substitutions exist?" ("Since 1.8.0, ArchiveXL supports substitutions for
+      dynamic-appearances")
+    tags:
+      - archivexl
+      - dynamic-appearances
+      - substitution
+      - version-floor
+    detail: "RELATED: sharpens cp2077.archivexl.dynamic-appearances.introduced-in-1.5.0 — a project
+      whose ArchiveXL floor is 1.5.x-1.7.x can use conditions but not substitutions."
+  - id: cp2077.archivexl.dynamic-appearances.substitution-requires-leading-asterisk
+    claim: A field value that should be interpolated as a dynamic-appearance substitution (in a mesh
+      entity component's `name`, `depotPath` or `appearance`, or an `.app` appearance's `name`) only
+      activates interpolation if the string starts with an asterisk (`*`); without the leading `*`,
+      `{placeholder}` text is treated as a literal string.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Which substitutions exist?"
+    tags:
+      - archivexl
+      - substitution
+      - syntax
+      - gotcha
+    detail: A validator that greps for `{gender}`/`{body}`/etc. in a resource field should also check
+      the field starts with `*`, since a substitution-looking string without the prefix silently
+      does not substitute.
+  - id: cp2077.archivexl.dynamic-appearances.placeholder-table
+    claim: "The page's placeholder table lists eight substitutions: `{camera}` (`fpp`/`tpp`), `{gender}`
+      (`m`/`w`), `{body}` (`base_body` or the registered body-mod tag in snake_case), `{arms}`
+      (`base_arms`, `mantis_blades`, `monowire`, `projectile_launcher`), `{feet}` (`flat`, `lifted`,
+      `high_heels`, `flat_shoes`, empty for male-rigged V), `{sleeves}` (`full`, `part`),
+      `{skin_color}` (the skin-tone appearance name from customization, e.g. `03_senna`) and
+      `{hair_color}` (the hair-colour name, e.g. `black_liquorice`)."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Which substitutions exist?" (placeholder table)
+    tags:
+      - archivexl
+      - substitution
+      - placeholder
+      - gender
+      - body
+      - arms
+      - feet
+    detail: "The page warns this table can go stale and points to the source of truth:
+      `src/App/Extensions/GarmentOverride/Dynamic.cpp#L29` in psiberx/cp2077-archive-xl (not re-read
+      line-by-line for this fact — only the wiki table was transcribed). Checked against the source
+      (2026-09-08): an earlier wording listed only the first five placeholders as though the table
+      were complete; `{sleeves}`, `{skin_color}` and `{hair_color}` are in the same table and have
+      been added."
+  - id: cp2077.archivexl.dynamic-appearances.unresolvable-placeholder-falls-back
+    claim: If a `@context`-defined substitution placeholder cannot be resolved for a given mesh (e.g. a
+      custom `GlobalNormal` parameter defined on one patched mesh but not on another), ArchiveXL
+      ignores the unresolved placeholder and falls back to the base material's own value for that
+      parameter, rather than failing to load.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-resource-patching/README.md,
+      section "Partial templates: @Context"'
+    tags:
+      - archivexl
+      - substitution
+      - fallback
+      - failure-mode
+  - id: cp2077.archivexl.dynamic-appearances.appearance-conditions-two-locations
+    claim: "Dynamic-appearance conditions (e.g. `&camera=fpp`, `&gender=w`) can be written in exactly
+      two places: the `name` field of an `appearanceAppearanceDefinition` inside a `.app` file, and
+      the `name` field of a component inside a `mesh_entity.ent` file; using gendered per-component
+      conditions in the mesh entity is called out as generally worse practice than gendered whole
+      appearances, because components for the inactive gender are still added to the entity."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Conditions"
+    tags:
+      - archivexl
+      - condition
+      - .app
+      - mesh_entity
+      - performance
+  - id: cp2077.archivexl.dynamic-appearances.appearance-name-truncated-at-variant-separator
+    claim: When using dynamic appearances, the `appearanceName` a mod's `.yaml` entry gives is matched
+      against the root entity's appearance `name` only up to the first `!` (the "variant
+      separator"); everything after `!` is the dynamic-appearance condition/substitution suffix that
+      ArchiveXL resolves itself, not part of the name TweakXL's yaml needs to match.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md, hint
+      under "root_entity.ent" ("must match the field `appearanceName` in the `.yaml` up to the
+      variant separator `!`")
+    tags:
+      - archivexl
+      - dynamic-appearances
+      - root-entity
+      - appearancename
+    detail: "RELATED: the `!` variant separator is a different delimiter from the `&` used for legacy
+      suffixes and for dynamic conditions; the suffixes-and-substitutions page's
+      substitution-load-order table shows both in one name (`my_item!variant&camera=tpp`), so `!`
+      and `&` are not interchangeable spellings of one mechanism. See
+      cp2077.archivexl.dynamic-appearances.legacy-suffix-still-first-match for the legacy suffix
+      system itself."
+  - id: cp2077.archivexl.dynamic-appearances.legacy-suffix-still-first-match
+    claim: "Before ArchiveXL 1.5, conditional appearance selection used only suffixes: for N independent
+      suffix axes (gender, camera, ...) the root entity needed 2^N appearance entries (one per
+      combination); the page's own worked example describes going from 96 suffix-based entries in
+      one root entity down to 9 after moving to dynamic appearances."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Why are suffixes?"
+    tags:
+      - archivexl
+      - suffix
+      - legacy
+      - root-entity
+  - id: cp2077.archivexl.dynamic-appearances.suffix-load-order-most-specific-wins
+    claim: "The documented suffix load order for a legacy (pre-1.5, non-dynamic) suffixed appearance
+      name is two steps: the base appearance name (with no suffix) first, then \"the most specific
+      suffix collection it can find\" — a less specific match that exists is ignored when a more
+      specific one also exists (the page's worked example marks the bare name and
+      `appearance_&Female` as \"ignored: a better match exists\")."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Suffix load order" (worked example table)
+    tags:
+      - archivexl
+      - suffix
+      - load-order
+      - appearance-resolution
+    detail: 'Checked against the source (2026-09-08): an earlier wording said the game "searches suffix
+      combinations from least to most specific". The page states only which entry wins, not the
+      order in which candidates are tried; that search-order detail is removed.'
+  - id: cp2077.archivexl.dynamic-appearances.disable-suffixes-empty-array
+    claim: "Setting `appearanceSuffixes: []` in a TweakXL yaml item entry is the documented way to
+      disable suffixes for that item."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      for-mod-creators-theory/core-mods-explained/archivexl/archivexl-suffixes-and-substitutions.md,
+      section "Disabling Suffixes"
+    tags:
+      - archivexl
+      - suffix
+      - appearancesuffixes
+      - yaml
+  - id: cp2077.archivexl.dynamic-appearances.app-condition-variables-since-1.4.0
+    claim: For ArchiveXL >= 1.4.0, an `.app` file's appearance overrides can use the interpolation
+      variables `{gender}` (m/w), `{skin_color}` (skin tone appearance name) and `{hair_color}`
+      (hair color appearance name) inside the `meshAppearance` field.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "appearance.app" (variable table, citing ArchiveXL release tag v1.4.0-rc2)
+    tags:
+      - archivexl
+      - dynamic-appearances
+      - .app
+      - meshappearance
+      - version-floor
+    detail: "RELATED: this predates dynamic appearances proper
+      (cp2077.archivexl.dynamic-appearances.introduced-in-1.5.0 puts that at 1.5.0), so
+      `meshAppearance` interpolation was available slightly earlier than full condition/substitution
+      support."
+  - id: cp2077.archivexl.dynamic-appearances.camera-perspective-helpers
+    claim: "ArchiveXL 1.27.1 ships two redscript helpers in module ArchiveXL.DynamicAppearance:
+      ConvertAppearanceNameToTPP(app) and ConvertAppearanceNameToFPP(app). A plain appearance name
+      gets the substring &FPP swapped for &TPP, or back. A dynamic appearance (one with '!') gets
+      its 'camera' condition set to tpp or fpp through OverrideDynamicAppearanceCondition. The
+      static natives ArchiveXL.DisableGarmentOffsets() and EnableGarmentOffsets() switch the garment
+      offsets. A third-person mod (Immersive Third Person 1.3.0) shows V's clothes whole in third
+      person this way: it converts each equipped area's current appearance and applies it with
+      TransactionSystem.ChangeItemAppearanceByName, with the garment offsets off while in third
+      person."
+    status: verified
+    source: <install>\red4ext\plugins\ArchiveXL\Scripts\ArchiveXL.DynamicAppearance.reds (lines 4-60)
+      and ArchiveXL.Global.reds (DisableGarmentOffsets); Immersive Third Person 1.3.0
+      r6\scripts\immersive_third_person\tpp_camera_bridge.reds (ApplyArea,
+      ApplyGarmentOffsetsForPerspective, ApplyVisibleRenderPerspective)
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - camera
+      - tpp
+      - fpp
+      - garment