modwright 0.1.0

package/knowledge/cyberpunk2077/audio.voicesets.yaml

@@ -0,0 +1,146 @@
+game: cyberpunk2077
+topic: audio.voicesets
+title: NPC barks - context names, the voiceset scenes behind them, and which enemy voices carry
+  which contexts
+facts:
+  - id: cp2077.audio.voicesets.barks-are-context-names
+    claim: "An NPC bark is requested by a context name, not by a line: GameObject.PlayVoiceOver(self,
+      voName, debugInitialContext, optional delay, answeringEntityID, canPlayInVehicle) plays a line
+      of context voName in that NPC's own voice. The AI does the same through 242
+      AISubActionPlayVoiceOver records naming 62 contexts (flats name, delay, condition, cooldown,
+      repeat, sendEventToSquadmates, setSelfAsAnsweringEntity); for example the Reboot Optics blind
+      asks for stlh_blinded out of combat and combat_blinded in it, the Cyberpsychosis quickhack's
+      squadmate reaction asks for madness_quick_hack_reaction, and surrender and panic ask for
+      fear_beg. ReactionManagerComponent.SendVOEventToSquad(owner, voEvent) plays the context on
+      every active squadmate of the owner within AIGeneralSettings.maxDistanceBattleCry, not on the
+      owner."
+    status: verified
+    verified_on: "2.31"
+    source: tools\redmod\scripts\core\entity\gameObject.script:1003 (PlayVoiceOver);
+      core\ai\actions\tweakAISubActions.script:126-140 (SendVoiceOverEvent);
+      core\components\scriptComponents\reactionComponent.script:6055-6102 (SendVOEventToSquad); the
+      vanilla index, records of type AISubActionPlayVoiceOver and their name flats
+      (StatusEffectActions.SE_BlindDefault_inline1, SE_BlindQuickhackCombat_inline1,
+      MadnessSquadmateVoiceReaction_inline2, ReactionsActions.SurrenderFearInPlace01_inline2)
+    tags:
+      - audio
+      - voiceover
+      - bark
+      - context
+      - ai
+      - squad
+    detail: "No script API tells whether a voice has a line for a context; a voice without one plays
+      nothing (inferred from the voicesets below: nothing falls back). The scripts also call about
+      40 contexts directly (fear_beg, stlh_curious_grunt, enemy_warning, stealth_ended and others)."
+  - id: cp2077.audio.voicesets.voiceset-scene-structure
+    claim: Each generic NPC voice is a .scene under base\open_world\voicesets\<category>\
+      (gangers\<gang>, security\security_<tier>, ncpd, mercs, civilian_*), with a twin under
+      versions\gold. The scene's entryPoints are named by context, usually with _var_1.._var_3
+      variants (stlh_curious, stlh_curious_var_1, ...); each leads through a scnRandomizerNode to
+      scnSectionNodes whose scnDialogLineEvents name screenplay lines, whose locstringIds are the
+      stringIds of base\localization\en-us\subtitles\open_world\voicesets\<voice>.json. So a voice's
+      lines per context can be listed from the install without the game.
+    status: verified
+    verified_on: "2.31"
+    source: basegame_4_gamedata.archive
+      base\open_world\voicesets\gangers\tiger_claws\gang_tcl_m_01_jap_20.scene and 451 further
+      voiceset scenes; lang_en_text.archive
+      base\localization\en-us\subtitles\open_world\voicesets\*.json
+    tags:
+      - audio
+      - voiceset
+      - scene
+      - subtitle
+      - entry-point
+      - extraction
+    detail: "1,062 resources sit under base\\open_world\\voicesets (1,058 scenes, most voices twice,
+      base and versions\\gold): gangers 284, the civilian sets about 550, NCPD 80, security 68,
+      mercs 20, plus 16 shared blocks under voiceset_scene_blocks. The shared blocks
+      apuc_enemies_voiceset_scene_block and apuc_enemies_missing_scene_block list context names with
+      no lines of their own."
+  - id: cp2077.audio.voicesets.enemy-context-coverage
+    claim: Across the 226 base-game enemy voicesets (gangers, security, mercs, NCPD), stlh_curious
+      (confused "huh?" and "what was that?" lines) has lines in 215 voices and danger in 225, while
+      the 2.0-era contexts apuc_stlh_blinded, apuc_combat_blinded, apuc_madness_quick_hack_reaction,
+      apuc_call_in_confusion and apuc_combat_quick_hack have lines in the same 73 voices, spread
+      over most gangs, NCPD and security. apuc_madness_quick_hack_wearoff is listed in the shared
+      template block but no enemy voice recorded a line for it, and no enemy voiceset has fear_beg.
+      The base scenes and their versions\gold twins agree.
+    status: verified
+    verified_on: "2.31"
+    source: the extraction in cp2077.audio.voicesets.voiceset-scene-structure, over
+      base\open_world\voicesets\{gangers,security,mercs,ncpd}\ (226 voices each in the base and
+      versions\gold sets)
+    tags:
+      - audio
+      - voiceset
+      - coverage
+      - enemy
+      - quickhack
+      - possession
+    detail: "The out-of-combat blind lines often have the NPC blame their own optics or implants, which
+      suits a target coming back from a takeover; the combat ones mostly name V as the attacker.
+      Voices without the 2.0 contexts include the Aldecaldos and some whole voices in every gang.
+      Phantom Liberty's voicesets (ep1 archives) were not read. A quickhack mod (v0.12.12) plays
+      stlh_curious then stlh_blinded on a target that survives a takeover, and
+      madness_quick_hack_reaction to its squad. Observed in game (2026-09-25): both of the target's
+      contexts played on a spawned Tyger Claw; the release itself waits for a human take. Also
+      observed in game: the squad send (SendVOEventToSquad) to an alerted Valentino group was
+      inconclusive, while the same context played directly on one of them was heard."
+    related:
+      - cp2077.audio.voicesets.barks-are-context-names
+      - cp2077.audio.voicesets.apuc-contexts-requested-without-the-prefix
+  - id: cp2077.audio.voicesets.apuc-contexts-requested-without-the-prefix
+    claim: The voices name their 2.0-era contexts with an apuc_ prefix (apuc_stlh_blinded,
+      apuc_madness_quick_hack_reaction), but the AI actions that play them ask for the bare names
+      (stlh_blinded, madness_quick_hack_reaction). The engine maps the bare request to the prefixed
+      entry, and a script asking for the bare name reaches the same lines.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - audio
+      - voiceset
+      - context
+      - apuc
+    detail: "The first boot with a quickhack mod's blinded-voice arm on a voice from the 73 settles it:
+      a line means the mapping holds for a script caller."
+  - id: cp2077.audio.voicesets.voice-tag-readable-through-codeware
+    claim: An NPC entity carries its voiceset in a component named VoicesetComponent
+      (scnVoicesetComponent), whose persistent state scnVoicesetComponentPS holds voiceTag,
+      gruntSetIndex and the areVoicesetLinesEnabled / areVoicesetGruntsEnabled switches; Codeware
+      declares that state class for scripts, and GameComponent.GetPS() is public, so a script can
+      read the tag. It reads None at runtime too, on a spawned Tyger Claw that speaks, so it does
+      not name the voice.
+    status: verified
+    verified_on: "2.31"
+    source: base\characters\entities\citizen\citizen__default_ma.ent and
+      base\characters\base_entities\man_base\man_base.ent (extracted with the template tool, the
+      mod's cache); Codeware 1.20.3 Codeware.Global.reds:35180;
+      tools\redmod\scripts\core\components\scriptableComponent.script:3
+    tags:
+      - audio
+      - voiceset
+      - codeware
+      - component
+    detail: So a release can't pick contexts per voice from the tag. It plays the near-universal context
+      first and the better-fitting one after it, and voices without the second stay quiet (a
+      quickhack mod, v0.12.12).
+  - id: cp2077.audio.voicesets.replacer-body-grunts-are-the-voicesets
+    claim: On a replacer body that is the player (a PlayerPuppet record inheriting V's voice tag v and
+      her PlayerVoice combat settings v_voice), the combat grunts (hit, firing, melee, falls) are
+      the entity's voiceset's and keep V's voice whatever the record's voiceTag, an injected tag
+      (entInjectVoiceTagEvent, forceInjection) or the PlayerVoice component's combatVoSettingsName
+      says. entChangeVoicesetStateEvent with enableVoicesetGrunts false silences them.
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - audio
+      - voiceset
+      - replacer
+      - grunts
+      - player
+    detail: "What does choose the grunts is not read (candidates: the replacer node's
+      audioOverrideAppearanceName, the voiceset component's own state). A quickhack mod mutes them
+      until then."

package/knowledge/cyberpunk2077/cet.sandbox.yaml

@@ -0,0 +1,219 @@
+game: cyberpunk2077
+topic: cet.sandbox
+title: Cyber Engine Tweaks Lua sandbox, console versus mod environments
+facts:
+  - id: cp2077.cet.console-sandbox-has-no-io
+    claim: "The CET console runs in a separate, stripped sandbox: since CET 1.10 it has no `io`, `json`,
+      `dofile` or ImGui bindings. A console test of `io.open` therefore says nothing about what a
+      mod's own environment can do."
+    status: verified
+    verified_on: CET 1.10
+    source: ModWright field verification
+    tags:
+      - cet
+      - sandbox
+      - console
+      - io
+    detail: "An early in-game run read its console result as \"io does not exist at all in this CET
+      build's Lua sandbox\". That overreaches: the changelog shows the console was stripped by
+      design in 2021 while mods kept io. The decisive check for a mod is its own capability report
+      or its own log file, never a console one-liner."
+  - id: cp2077.cet.mod-sandbox-io-relative-to-mod
+    claim: Inside a mod's sandbox, `io` and `dofile` exist and every path is resolved relative to the
+      mod's own folder under `bin/x64/plugins/cyber_engine_tweaks/mods/<Mod>/`.
+    status: verified
+    verified_on: CET 1.10
+    source: 'CET changelog 1.10: "All pathing is now relative to mod (breaking change, includes all io
+      functions, dofile() and such included)"; "Introduced proper sandbox with LuaSandbox helper
+      class".'
+    tags:
+      - cet
+      - sandbox
+      - io
+      - paths
+    detail: "Not yet confirmed in-engine by ModWright on CET 1.37.1: the bridge's own capability line
+      was not captured in an early in-game run. A relative name such as \"modwright_hb.json\" is the
+      form the changelog implies; whether writes outside the mod folder are refused or silently
+      redirected is not stated."
+  - id: cp2077.cet.mod-log-files
+    claim: Each CET mod logs to its own log file, and errors raised by mod code go to the mod's log
+      rather than the console; `spdlog` is exposed so a mod can write to that log.
+    status: verified
+    verified_on: CET 1.9.1
+    source: 'CET changelog 1.9.1: "Mods will now log to their own log files, you can also use spdlog to
+      print in your log"; 1.10: "Errors that happen in Game, game class methods,... should now log
+      into proper environment (to console when executed from console, to mod log when executed from
+      mod)".'
+    tags:
+      - cet
+      - logging
+      - sandbox
+    detail: The exact file name convention is not stated in the changelog; treat "the newest .log inside
+      the mod folder" as the place to look until a real one is recorded.
+  - id: cp2077.cet-lua-is-5-1-luajit
+    claim: CET's Lua is 5.1 semantics on LuaJIT since CET 1.12.0; post-5.1 language features such as
+      bitwise operators are unavailable, and the `bit32` library is provided.
+    status: verified
+    verified_on: CET 1.12.0
+    source: "CET changelog 1.12.0: \"Lua version changed to 5.1 ... switching to LuaJIT\"; \"Added Lua's
+      bit32 library\"."
+    tags:
+      - cet
+      - lua
+      - luajit
+    detail: This is why `luac5.1 -p` is the relevant syntax check for the CET bridge (`npm run
+      bridge:lint` runs 5.1 first).
+  - id: cp2077.cet.os-rename-remove-available
+    claim: '`os.remove` and `os.rename` exist in the CET mod sandbox; CET 1.12.0 fixed them after they
+      "were not working properly".'
+    status: verified
+    verified_on: CET 1.12.0
+    source: 'CET changelog 1.12.0, "Fixes: os.remove and os.rename were not working properly."'
+    tags:
+      - cet
+      - sandbox
+      - io
+      - atomic-write
+    detail: Makes a write-temp-then-rename commit possible for the bridge's result files; unconfirmed
+      in-engine on 1.37.1.
+  - id: cp2077.cet.json-in-mod-sandbox
+    claim: A `json` library is available to CET mods (added in CET 1.9.2) but is stripped from the
+      console sandbox (CET 1.10).
+    status: verified
+    verified_on: CET 1.10
+    source: CET changelog 1.9.2 "Added json support to Lua"; 1.10 console-strip line.
+    tags:
+      - cet
+      - json
+      - sandbox
+  - id: cp2077.cet.require-uses-slashes-mod-relative
+    claim: In CET mods `require` resolves paths relative to the mod folder and uses "/" as the
+      separator, not "."; the require cache is reset on "Reload all mods"; Lua bytecode cannot be
+      loaded; `dofile` is deprecated since CET 1.9.1 but was kept working.
+    status: verified
+    verified_on: CET 1.10
+    source: "CET changelog 1.10: \"require does not support '.' instead of '/' now\"; \"require cache is
+      reset on Reload all mods now\"; \"Bytecode cannot be loaded now\"; 1.9.1: \"dofile is now
+      deprecated, use only mods please\"; 1.12.0: \"Fixed dofile, loadfile and loadstring\"."
+    tags:
+      - cet
+      - lua
+      - require
+      - modules
+  - id: cp2077.cet.getmod-only-after-oninit
+    claim: "`GetMod()` and every type or function that relies on RTTI are only available after the
+      `onInit` event; calling them earlier is unsupported."
+    status: verified
+    verified_on: CET 1.14.0
+    source: 'CET changelog 1.14.0: "The GetMod() is only available after onInit as there is no guarantee
+      that the required mod will be loaded before this event. Types and functions that rely on RTTI
+      are only available after onInit event".'
+    tags:
+      - cet
+      - lifecycle
+      - oninit
+      - getmod
+  - id: cp2077.cet.per-mod-sqlite-db
+    claim: Each CET mod is implicitly assigned a SQLite database, reachable from Lua as the `db` object.
+    status: verified
+    verified_on: CET 1.10
+    source: 'CET changelog 1.10: "Each mod is (right now) assigned sqlite3 database implicitly,
+      accessible through db lua object"; 1.9.1: SQLite3 support added.'
+    tags:
+      - cet
+      - sqlite
+      - storage
+    detail: A possible alternative transport for the verification bridge (ModWright reads SQLite through
+      sql.js), noted but not designed; concurrent writers from two processes would need care.
+  - id: cp2077.cet.current-version-and-game-support
+    claim: "CET's Nexus page shows version 1.37.1, last updated 2025-09-29, with \"Supported version:
+      2.31\" as the game build named on the page; it was run in game on build 3.0.80.51928
+      (2026-09-08)."
+    status: verified
+    verified_on: CET 1.37.1
+    source: ModWright field verification
+    tags:
+      - cet
+      - version
+      - compat
+    detail: The page's stated supported game version lags the build it was run on; check_compat's CET
+      floor should be read against the actual release notes, not this page line.
+  - id: cp2077.cet.mod-sandbox-has-no-global-table
+    claim: "Inside a CET mod's Lua environment `_G` is nil: the environment is a fresh table that falls
+      back to a whitelisted copy of the globals, and `_G` is not on the whitelist. Code that
+      discovers capabilities through `_G[name]` sees nothing; a free global name resolved through
+      the environment is the only lookup that works."
+    status: verified
+    verified_on: CET 1.37.1
+    source: ModWright field verification
+    tags:
+      - cet
+      - sandbox
+      - lua
+      - capabilities
+      - bridge
+    detail: The ModWright CET bridge's capability probe used `_G[name]` and therefore reported io absent
+      and ran log-only in an early in-game run. Fixed to reference globals by name.
+  - id: cp2077.cet.mod-sandbox-io-path-rules
+    claim: The sandboxed `io.open` resolves a path against the mod's root and refuses absolute paths and
+      any path containing `..`; a missing file is allowed when opening for write. The sandbox also
+      provides `io.lines`, `os.rename`, `os.remove`, a per-mod `db` at `db.sqlite3`, `dir()`, and a
+      curated `os` with clock, date, difftime and time.
+    status: verified
+    verified_on: CET 1.37.1
+    source: "CyberEngineTweaks/src/scripting/LuaSandbox.cpp InitializeIOForSandbox (io table:
+      open/lines/read/write/close/type/input/output), GetLuaPath (rejects absolute and `..`),
+      src/Utils.cpp GetAbsolutePath (acAllowNonExisting), LuaSandbox.cpp:53-61 (os copy)."
+    tags:
+      - cet
+      - sandbox
+      - io
+      - paths
+    detail: Every candidate prefix the bridge tries resolves under the same mod root; only the empty
+      prefix (the mod folder itself) is meaningful, and a prefix naming a missing subfolder fails
+      because io.open does not create directories.
+  - id: cp2077.cet.mod-log-file-name
+    claim: Each CET mod's own log file is `<ModFolderName>.log` inside the mod's folder, created by the
+      sandbox logger; `spdlog.info(...)` and errors from mod code land there.
+    status: verified
+    verified_on: CET 1.37.1
+    source: CyberEngineTweaks/src/scripting/LuaSandbox.cpp:638 `CreateLogger(GetAbsolutePath(acName +
+      ".log", cSBRootPath, true), acName)`.
+    tags:
+      - cet
+      - logging
+      - sandbox
+    detail: For the ModWright bridge that is bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge/
+      ModWrightBridge.log, the first file the log-polling transport reads.
+  - id: cp2077.cet.log-truncated-at-initializetweakdbmetadata-is-cosmetic
+    claim: "`cyber_engine_tweaks.log` ending mid-string at an `InitializeTweakDBMetadata(...)` call
+      signature is not by itself evidence of a TweakDB initialisation hang; the same truncated last
+      line appears on a normal launch that reaches the main menu with TweakXL fully loaded."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - cet
+      - log
+      - tweakdb
+      - hang
+      - stall
+      - diagnostics
+    detail: "A stall detector needs a positive completion signal instead: TweakXL.log's own
+      import-completed line, or a bounded wait on the main menu. An earlier intermittent stall may
+      still be real; this fact only retires the log truncation as its marker."
+  - id: cp2077.cet.sandbox.observeafter-attaches-mid-session
+    claim: "CET's ObserveAfter(class, method, fn) can be registered mid-session from a bridge eval chunk
+      (not only in onInit) and fires on the next calls: an observer on
+      NPCPuppet.DamagePipelineFinalized caught every NPC hit with its instigator, computed damage
+      and hit flags, which a redscript log could not (a null in its attack-record chain aborted
+      it)."
+    status: verified
+    verified_on: 2.31 (CET 1.x, 2026-09)
+    source: ModWright field verification
+    tags:
+      - cet
+      - observe
+      - hook
+      - debugging
+      - bridge

package/knowledge/cyberpunk2077/clothing.garments.yaml

@@ -0,0 +1,283 @@
+game: cyberpunk2077
+topic: clothing.garments
+title: ArchiveXL dynamic appearances, visual tags and substitution syntax
+facts:
+  - id: cp2077.clothing.garments.dynamic-variant-name-syntax
+    claim: In a dynamic appearance name, everything after the `!` arrives in the mesh entity under the
+      key `variant`; adding `+` splits it into parts reachable as `variant.1` and `variant.2`. A raw
+      variant of `$(base_color)+$(secondary)` resolving to `black+samurai` gives `variant` =
+      `black+samurai`, `variant.1` = `black`, `variant.2` = `samurai`; without the `+`,
+      `$(base_color)$(secondary)` yields `blacksamurai` as `variant.1` and nothing for `variant.2`.
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "Step 2: Connecting the
+      decal (and understanding variants)" (the "Examples" table)'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - variant
+      - substitution
+      - syntax
+    detail: "Used in a path as `{variant.2}` — the guide's worked step is \"In the mesh depot path,
+      replace `samurai.mesh` with `{variant.2}.mesh`\". Section names corrected 2026-09-07: the page
+      has no \"Key YAML/Manifest Syntax\" or \"Substitution Placeholders\" headings."
+  - id: cp2077.clothing.garments.substitution-path-requires-star-prefix
+    claim: ArchiveXL only substitutes `{placeholder}` inside a mesh entity component's depot path when
+      the path starts with `*`, e.g.
+      `*manavortex/equipment/torso_inner/my_custom_shirt/meshes/t1_079_p{gender}a_tshirt_casual.mesh`.
+      A path written without the leading `*` is not substituted.
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", sections "Summary" (TL;DR box,
+      "To enable substitution in mesh depot paths, make sure they start with `*`") and "Safely
+      changing mesh paths"; corroborated by "ArchiveXL: Suffixes and Substitutions", section "Which
+      substitutions exist?" ("Substitution will only become active if the property name starts with
+      an asterisk (`*`)")'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - depotpath
+      - substitution
+      - syntax
+    detail: The generator's default paths also carry the `Soft` flag alongside the `*`. WolvenKit's
+      DepotPath box has a right-click "Convert to dynamic" action that adds the `*` to a pasted
+      plain path.
+  - id: cp2077.clothing.garments.dynamic-appearance-placeholders
+    claim: ArchiveXL's substitution placeholders and what they resolve to are `{camera}` -> `fpp` or
+      `tpp`; `{gender}` -> `m` or `w`; `{body}` -> `base_body` or the body mod name in snake case;
+      `{arms}` -> `base_arms`, `mantis_blades`, `monowire`, `projectile_launcher`; `{feet}` ->
+      `flat`, `lifted`, `high_heels`, `flat_shoes` (empty for mascV); `{sleeves}` -> `full`, `part`;
+      `{skin_color}`; `{hair_color}`. They are usable inside mesh-entity component `name`,
+      `depotPath` and `appearance` fields and in an `.app` appearance's `name` field.
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Suffixes and Substitutions", section "Which substitutions
+      exist?" (placeholder table)'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - placeholder
+      - gender
+      - body-tag
+    detail: "Corrected 2026-09-07: `{gender}` resolves to `m`/`w`, NOT to `pwa`/`pma` — the vanilla path
+      shape is `p{gender}a`, which is what produces `pwa`/`pma`. Substitutions have existed since
+      ArchiveXL 1.8.0. The wiki warns its table can lag the implementation and links the
+      authoritative source, cp2077-archive-xl src/App/Extensions/GarmentOverride/Dynamic.cpp."
+  - id: cp2077.clothing.garments.root-entity-single-blank-appearance
+    claim: For a dynamic appearance, the ROOT ENTITY keeps exactly one entry in its `appearances` array,
+      named like the `entityName` in the yaml, with `appearanceName` left blank; the `.app` likewise
+      keeps one entry with that same name, has all its components deleted, and points at the mesh
+      entity. All variant logic then lives in the mesh entity file.
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "Summary" (TL;DR box) and
+      "How is this better than the old approach?" ("Dynamic variants put the logic into the `mesh
+      entity` file")'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - root-entity
+      - appearancename
+    detail: "Corrected 2026-09-07: the blank `appearanceName` belongs to the ROOT ENTITY, not to the
+      `.app` as previously recorded. \"Exactly one\" is the default shape, not a hard rule — the
+      page's \"_app: Three decals, one appearance, partsOverrides\" variant deliberately registers
+      three appearances in the root .ent and three in the .app."
+  - id: cp2077.clothing.garments.dynamicappearance-tag-required
+    claim: An appearance is declared dynamic by adding the `DynamicAppearance` tag to the visual tags in
+      its root entity — "You define an appearance as dynamic by adding the `DynamicAppearance` tag
+      to the visual tags in its root entity."
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "Prerequisites" (closing
+      paragraph) and section "Summary" (TL;DR box, root_entity step 1)'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - visual-tag
+      - required-field
+    detail: The page states the tag is how an appearance is declared dynamic; it does not separately
+      state what happens when the tag is omitted, so the previously recorded consequence
+      ("substitution logic is not applied") was removed on 2026-09-07 as unsourced.
+  - id: cp2077.clothing.garments.unvalidated-variant-crashes
+    claim: '"The game will crash if you tell it to load a mesh that does not exist" — a dynamic mesh
+      path substituted from a yaml value the user can edit is therefore a crash risk. The two
+      documented mitigations are to put all appearances in one `.mesh` and switch only
+      `meshAppearance`, or to keep separate meshes and hide the unwanted ones from the `.app` with
+      `partsOverrides` containing `componentOverrides` that set `chunkMask` to `0` and
+      `meshAppearance` to an empty string.'
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "Exercise 1: Other options"'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - crash
+      - silent-failure
+      - gotcha
+    detail: "Symptom: entering `semurai` instead of `samurai` in the yaml makes the game look for
+      `manavortex\\equipment\\torso_inner\\my_custom_shirt\\meshes\\t1_079_pwa_tshirt__casual_dec_s\
+      emurai.mesh` and crash. Corrected 2026-09-07: the crash comes from any single unresolvable
+      value, not from an invalid COMBINATION of values as previously recorded, and the page does not
+      frame it as a validation gap. `partsOverrides` can only hide components, never show them."
+  - id: cp2077.clothing.garments.dynamic-appearance-version-floors
+    claim: The dynamic-appearances guide's stated minimum tool versions are WolvenKit >= 8.11.0, TweakXL
+      >= 1.4.4, ArchiveXL >= 1.5.0 and Red4ext >= 1.17.0, plus Cyber Engine Tweaks for spawning
+      items. Dynamic variants themselves were added in ArchiveXL 1.13.
+    status: contradicted
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "Prerequisites" (bullet
+      list) and section "Summary" (opening paragraph, "via ArchiveXL (added in 1.13)") =
+      CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/README.md:12,61'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - version-floor
+      - wolvenkit
+      - tweakxl
+      - red4ext
+    detail: "Checked against the source (2026-09-08): the last sentence is wrong and the fact is retired
+      for it. The page contradicts itself — line 12 says dynamic variants were \"added in 1.13\"
+      while line 61 of the same page's Prerequisites lists \"ArchiveXL >= 1.5.0\". ArchiveXL's own
+      repository settles it: the dynamic appearance implementation
+      (src/App/Extensions/GarmentOverride/Dynamic.cpp, carrying DynamicAppearanceTag, the `!`
+      variant marker, the `&` condition marker and the gender/camera/body/feet attributes) is absent
+      at tag v1.4.1 and present at tag v1.5.0. Superseded by
+      cp2077.clothing.garments.dynamic-appearance-prerequisites, which keeps the prerequisite list
+      without the 1.13 figure; the version itself is
+      cp2077.archivexl.dynamic-appearances.introduced-in-1.5.0. These are framework versions on
+      their own numbering, not a game version, so no `verified_on` is set on either."
+  - id: cp2077.clothing.garments.dynamic-appearance-prerequisites
+    claim: The dynamic-appearances guide's stated minimum tool versions are WolvenKit >= 8.11.0, TweakXL
+      >= 1.4.4, ArchiveXL >= 1.5.0 and Red4ext >= 1.17.0, plus Cyber Engine Tweaks for spawning
+      items.
+    status: community
+    supersedes: cp2077.clothing.garments.dynamic-appearance-version-floors
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archivexl-dynamic-variants/README.md:61,
+      section "Prerequisites" (bullet list) — rendered as wiki.redmodding.org "ItemAdditions:
+      Dynamic Appearances"'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - version-floor
+      - wolvenkit
+      - tweakxl
+      - red4ext
+    detail: Framework versions on their own numbering, not a game version, so no `verified_on` is set.
+      The page spells it "Red4ext" and says to "get the most recent" rather than pinning these exact
+      builds. Replaces cp2077.clothing.garments.dynamic-appearance-version-floors, which added the
+      page's own contradictory "added in 1.13" sentence.
+    related:
+      - id: cp2077.archivexl.dynamic-appearances.introduced-in-1.5.0
+        detail: "Agrees: the prerequisite floor of 1.5.0 on this page is the version at which ArchiveXL's
+          repository actually gains the dynamic-appearance implementation."
+  - id: cp2077.clothing.garments.gendered-appearance-name-suffix
+    claim: To support only one body gender without crashing for the other, each entry in the `.app`'s
+      `appearances` array gets `&gender=w` or `&gender=m` appended to its `name` field, making it a
+      conditional appearance.
+    status: community
+    source: 'wiki.redmodding.org "ItemAdditions: Dynamic Appearances", section "1.2 Removing a body
+      gender" (steps 3-4)'
+    tags:
+      - archivexl
+      - dynamic-appearance
+      - gender
+      - appearance-name
+      - syntax
+    detail: "The reason given is that once the unsupported gender's meshes are deleted and its component
+      paths de-dynamised, \"the game will crash if the item is equipped by the unsupported body
+      gender\". Conditional appearance names outrank plainer ones: \"ArchiveXL: Suffixes and
+      Substitutions\" ranks `my_item!variant&camera=tpp` (1) above `my_item!variant` (2) above
+      `my_item&gender=w&camera=tpp` (3) above `my_item` (5)."
+  - id: cp2077.clothing.garments.visual-tags-are-case-sensitive
+    claim: Visual tags are applied by adding them to the `visualTags` property of an appearance
+      definition or to the `visualTagsSchema` of a root entity template, and "Tags are
+      case-sensitive!".
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", section "What do tags do?" (warning and danger hints)'
+    tags:
+      - archivexl
+      - visual-tags
+      - case-sensitive
+      - silent-failure
+    detail: The page states case sensitivity as a rule; it does not describe the failure mode, so the
+      previously recorded "silently does not apply" was removed on 2026-09-07.
+  - id: cp2077.clothing.garments.vanilla-hide-tags-by-slot
+    claim: "The base-game hide tags hide the ITEM in a named equipment slot, not the body part:
+      `hide_H1` (Head), `hide_F1` (Eyes), `hide_T1` (Chest), `hide_T2` (Torso), `hide_L1` (Legs),
+      `hide_S1` (Feet). Alongside them, `hide_Hair` hides hair, `hide_Genitals` hides genitals in
+      uncensored mode and underwear in censored mode, and `hide_T1part` toggles the partial suffix
+      (`&Full` -> `&Part`) when applied to a `Torso` item."
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", section "Base game tags" (tag table)'
+    tags:
+      - visual-tags
+      - hide-tag
+      - slot
+      - base-game
+    detail: 'Corrected 2026-09-07: the previous claim wrote the set as a contiguous "hide_H1 through
+      hide_S1" range over head/eyes/chest/torso/legs/feet and omitted the actual tag names
+      `hide_F1`, `hide_T1`, `hide_T2` and `hide_L1`; it also described them as hiding body parts.
+      `hide_T1part` pairs with `itemsFactoryAppearanceSuffix.Partial`, which searches the root
+      entity for `&Full` or `&Part`.'
+  - id: cp2077.clothing.garments.archivexl-fine-grained-hide-tags
+    claim: "ArchiveXL adds body-region hide tags beyond the vanilla slot set: `hide_Head`, `hide_Torso`
+      (0, 1, 2), `hide_LowerAbdomen` (3), `hide_UpperAbdomen` (2), `hide_CollarBone` (1),
+      `hide_Arms` (whole arms including hands), `hide_Thighs` (4), `hide_Calves` (5), `hide_Ankles`
+      (6), `hide_Feet` (7), `hide_Legs` (entire legs including feet, 4, 5, 6, 7). The same table
+      carries `AppearanceParts`, which goes into the .app file and enables `partsValues` for
+      non-player-equipment."
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", section "ArchiveXL tags" (tag table)'
+    tags:
+      - archivexl
+      - visual-tags
+      - hide-tag
+      - appearanceparts
+    detail: There is no tag for partially hiding default arms or cyberarms; the page points at
+      chunkmasks or custom tags for that. Section name corrected 2026-09-07 (the heading is
+      "ArchiveXL tags", not "ArchiveXL Visual Tags").
+  - id: cp2077.clothing.garments.custom-tag-declared-in-xl-not-yaml
+    claim: "A custom tag's effect on component chunk masks is declared \"in your `.xl` file (not in your
+      `.yaml`!)\" as `overrides: tags: <tag_name>: <component_name>: {show: [0, 1, 2, 3]}` (or
+      `{hide: [...]}`), and the tag is then added to the appearance's tags array. Unique component
+      names are mandatory for this, since the override matches on component name alone."
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", sections "Adding Custom tags" (danger hint) and
+      "Adding Custom tags > Registering the tag" / "Connecting the tag with the item"'
+    tags:
+      - archivexl
+      - visual-tags
+      - manifest
+      - xl
+      - custom-tag
+    detail: "The page's stated reason for custom tags over `partsOverrides` is that partsOverrides can
+      only hide components, never un-hide them. Its own example pairs `my_custom_unhiding_tag` with
+      `{show: ...}` and `my_HideSeamfix` on `t0_000_pma_base__full_seamfix` with `{hide: ...}`.
+      Advice for uniqueness: include your modder name in component names."
+  - id: cp2077.clothing.garments.heel-state-tags-need-foot-base
+    claim: "`HighHeels` turns the current (shoe) item into high heels and `FlatShoes` turns it into flat
+      shoes; `force_FlatFeet` forces female V's feet to be flat. All three require a foot item as
+      the `$base` in the item's `.yaml`."
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", section "ArchiveXL tags" (`HighHeels`, `FlatShoes`)
+      and section "Root entity tags" (`force_FlatFeet`)'
+    tags:
+      - archivexl
+      - visual-tags
+      - footwear
+      - high-heels
+      - root-entity
+    detail: 'Split out of a combined footwear+hair fact on 2026-09-07, and the previous wording
+      "suppresses the heel-posture animation regardless of equipped footwear" corrected — the tag is
+      gated on a foot `$base`. Gotcha the page flags: `force_FlatFeet` turns feet INVISIBLE for
+      mascV unless the user has switch feet installed, so apply it to a conditional appearance in
+      the .app (`&gender=m`). `HighHeels`/`FlatShoes` sit in the ArchiveXL tag table, not under
+      "Root entity tags".'
+  - id: cp2077.clothing.garments.force-hair-tag
+    claim: Head items turn hair invisible by default; adding `force_Hair` to the root entity overrides
+      that and forces hair to show up while a head item is worn.
+    status: community
+    source: 'wiki.redmodding.org "ArchiveXL: Tags", section "Root entity tags"'
+    tags:
+      - archivexl
+      - visual-tags
+      - hair
+      - root-entity
+    detail: 'Split out of a combined footwear+hair fact on 2026-09-07. The same section lists
+      footstep-sound tags for the root entity — `Boots`, `Heels`, `Sneakers`, `Stilettos`,
+      `Metal_feet` — under "Footsteps: Setting footwear sounds".'