modwright 0.1.0

package/knowledge/cyberpunk2077/fx.lights.yaml

@@ -0,0 +1,171 @@
+game: cyberpunk2077
+topic: fx.lights
+title: Weapon-mounted dynamic lights and thermal emissive glow
+facts:
+  - id: cp2077.fx.lights.app-baked-light-component-does-not-render
+    claim: "A gameLightComponent injected directly into a weapon's .app (both the appearance's
+      components array and its compiledData RedPackage chunks) assembles correctly at runtime — it
+      is findable via FindComponentByName — but its render side never initializes: setter calls
+      (SetStrength/SetRadius/SetColor) no-op and no light is cast."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - weapon
+      - app
+      - silent-failure
+    detail: This was tried as the fix for runtime AddComponent crashing (see
+      cp2077.fx.lights.runtime-addcomponent-crashes-on-draw). It failed for a different reason and
+      cost a full test cycle before the project moved to spawning a separate light entity instead
+      (which does work — see cp2077.fx.lights.vanilla-spotlight-donor-strip-pattern).
+  - id: cp2077.fx.lights.runtime-addcomponent-crashes-on-draw
+    claim: Adding a gameLightComponent to a weapon entity at runtime via Codeware's AddComponent crashes
+      the game on weapon draw; this is why the reference flashlight mod spawns a separate light
+      entity and teleport-follows it instead of attaching a component to the weapon itself.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - light
+      - weapon
+      - addcomponent
+      - crash
+    detail: "Recorded as the reason a weapon mod's own CET light helper was built around
+      entity-spawn-and-follow rather than component injection at either runtime or build time. The
+      app-baked alternative was tried next and also failed, for an unrelated reason (see
+      cp2077.fx.lights.app-baked-light-component-does-not-render). Note (2026-09-07): several
+      crash-on-load cases occurred during this work, but this specific one is not recalled, so the
+      fact stays inferred rather than verified."
+  - id: cp2077.fx.lights.bare-ent-template-missing-device-structure
+    claim: 'Spawning a gameLightComponent on a bare entEntity template (no other structure) via
+      WorldFunctionalTests.SpawnEntity fails silently: the entity spawns but the light component
+      never resolves (FindComponentByName returns nothing) because a working spawnable light needs
+      the full vanilla "device" chunk structure (an ElectricLight + ElectricLightController pairing,
+      7 Sections), not just an entity wrapping the light component.'
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - entity
+      - device-structure
+      - silent-failure
+    detail: "Diagnosed by a structural diff against the working donor: the flashlight mod's light.ent
+      turned out to BE vanilla
+      base\\gameplay\\devices\\lighting\\industrial\\spotlight\\spotlight_a.ent with
+      entMeshComponent + entColliderComponent stripped — its CRUIDs still match vanilla's, which a
+      from-scratch entity cannot replicate. See
+      cp2077.fx.lights.vanilla-spotlight-donor-strip-pattern."
+  - id: cp2077.fx.lights.wolvenkit-blank-ent-template-writes-no-entity-chunk
+    claim: A brand-new .ent file created from WolvenKit GUI's blank template writes NO entity object
+      chunk into compiledData (chunk 0 must be the entity class instance, followed by components);
+      spawning such a file crashes the game instantly, and the fix is to instantiate the root
+      `entity` handle explicitly via the GUI's add-array-item control.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - ent
+      - wolvenkit
+      - gui
+      - crash
+    detail: The GUI file had only the component (CruidIndex -1 vs. a working donor's 0; 6 Sections vs.
+      7). Instantiating the entity handle via the GUI's yellow (+) control removed WolvenKit's
+      "entity is null" warning and the instant crash, but the resulting plain-entEntity template
+      STILL failed to spawn a working light — see
+      cp2077.fx.lights.bare-ent-template-missing-device-structure — because the entity-chunk fix
+      alone does not supply the device structure a spawnable light needs.
+  - id: cp2077.fx.lights.vanilla-spotlight-donor-strip-pattern
+    claim: A working weapon-glow light entity can be built by taking vanilla
+      base\gameplay\devices\lighting\industrial\spotlight\spotlight_a.ent (a full,
+      correctly-structured light device) and stripping its entMeshComponent + entColliderComponent
+      from BOTH the compiledData chunks and the components array, remapping the CruidDict indices,
+      then retuning the retained gameLightComponent's fields.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - entity
+      - donor
+      - vanilla
+      - strip
+    detail: "This replaced an earlier version derived from a third-party flashlight mod's light.ent,
+      which had the same working structure but an open licensing question; deriving from vanilla
+      instead is covered by CDPR's fan-content policy like every other donor asset in the mod. Final
+      shipped values: LT_Point, color (255,130,30), intensity 800, radius 8, autoHideDistance 25, no
+      local shadows, turnOnByDefault flipped 0->1, isDestructible flipped 1->0 from the template
+      defaults. Confirmed working by the user after the rebuild."
+  - id: cp2077.fx.lights.spawn-entity-is-async-guard-required
+    claim: "WorldFunctionalTests.SpawnEntity is asynchronous: FindEntityByID for the new entity's ID
+      stays nil for several frames after the spawn call returns. Code that re-attempts a spawn
+      whenever the entity is not yet found (with no in-flight guard) will spawn a new entity every
+      update tick until the first one resolves, orphaning every earlier attempt."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - entity
+      - spawn
+      - async
+      - race-condition
+    detail: "Symptom before the guard: the light grew much brighter after several weapon draws, because
+      N stacked orphaned lights survived each weapon switch. The fix tracks every spawned ID in a
+      list and despawns all of them (not just the last tracked one) whenever the weapon is put away,
+      plus an awaitingSpawn flag with a 3.0 s timeout before allowing a retry."
+  - id: cp2077.fx.lights.emissive-material-alone-does-not-illuminate-surfaces
+    claim: An emissive material (e.g. the thermal blade glow) does not cast light onto nearby surfaces
+      under this engine's rasterized rendering; a separate dynamic light component/entity is
+      required to make the blade appear to light up its surroundings.
+    status: inferred
+    source: ModWright research
+    tags:
+      - fx
+      - light
+      - emissive
+      - material
+      - rendering
+    detail: This is the stated reason a weapon mod built a whole separate dynamic light (a CET helper
+      with its own glow_light.ent) on top of the already-working emissive blade material — the two
+      are additive, not the same effect.
+  - id: cp2077.fx.lights.light-component-runtime-tuning-api
+    claim: A spawned entity's gameLightComponent can be retuned live from redscript/Lua via
+      SetStrength(float), SetRadius(float), and SetColor(Color), looked up by FindComponentByName on
+      the entity; this is a real, working runtime API distinct from the app-baked injection route,
+      which does not respond to the same setters.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - component
+      - runtime
+      - api
+    detail: "Final user-tuned values for the shipped (pre-removal) light: strength 0.01 (deliberately
+      subtle), radius 0.0, color (255,130,30), weapon-local offset (0, 0.30, 0.20) rotated with the
+      weapon via a pure-Lua quaternion rotation. Contrast with
+      cp2077.fx.lights.app-baked-light-component-does-not-render, where the identical setters
+      silently do nothing on a component assembled into the .app instead of spawned as its own
+      entity."
+  - id: cp2077.fx.lights.cet-glow-light-dropped-no-functional-loss
+    claim: Removing the CET-driven weapon glow light entirely from the shipped mod has no effect on the
+      blade's emissive glow, heat haze, or tip smoke — those are independent systems living in the
+      mesh materials and the archive's effect descriptors — and doing so drops Cyber Engine Tweaks
+      from the mod's requirements entirely.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - fx
+      - light
+      - cet
+      - ship-decision
+      - dependency
+    detail: The verdict after comparing both builds in game was to make the no-light version the
+      standard. The point light only added a dynamic cast onto nearby surfaces (see
+      cp2077.fx.lights.emissive-material-alone-does-not-illuminate-surfaces) and did not justify a
+      whole extra dependency. A build switch restores it; the CET light helper stays in the repo as
+      a dev harness. Shipped requirements are therefore RED4ext + redscript + TweakXL + ArchiveXL
+      only.

package/knowledge/cyberpunk2077/hair.modding.yaml

@@ -0,0 +1,145 @@
+game: cyberpunk2077
+topic: hair.modding
+title: Hair mesh/rig/animgraph triplet and vertex-color conventions
+facts:
+  - id: cp2077.hair.modding.filename-triplet-must-match
+    claim: "Hair replacement replaces a set of three files that must share one base filename: \"you need
+      to rename your imported mesh to `fhair33_pt1.mesh`. If that's the case, you need to rename the
+      `.animgraph` and `.rig` to `fhair33_pt1.animgraph` and `fhair33_pt1.rig`.\""
+    status: community
+    source: wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "Wolvenkit"
+    tags:
+      - hair
+      - mesh
+      - rig
+      - animgraph
+      - naming
+      - file-triplet
+      - gotcha
+    detail: 'Symptom, merged in from the former cp2077.hair.modding.mismatched-triplet-morphs-weirdly on
+      2026-09-07 (it is the next sentence of the same paragraph): "Having the wrong names will cause
+      your mesh to morph weirdly." The renamed triplet is moved into the `uuh4v_framework` folder,
+      replacing the original files. Section name corrected (there is no "File Triplet Structure"
+      heading).'
+  - id: cp2077.hair.modding.uuh4v-slot-filename-convention
+    claim: '`fhair33_pt1` is a UUH4V Framework slot filename, not a vanilla one: the framework ships
+      numbered file sets and you pick the one matching the character-creator hairstyle you are
+      replacing ("I want to replace FemV hairstyle 33, so I chose file 33 for FemV"). Vanilla hair
+      meshes are instead named `hh_<index>_wa__<name>` / `hh_<index>_ma__<name>` under
+      `base\characters\common\hair\`, e.g. `hh_121_wa__t_bug_common` is FemV character-creator
+      hairstyle 33.'
+    status: community
+    source: 'wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "Wolvenkit"; vanilla
+      naming from "Cheat Sheet: Hair", section "Name of meshes by index"'
+    tags:
+      - hair
+      - naming
+      - filename
+      - convention
+      - uuh4v
+    detail: Renamed from cp2077.hair.modding.vanilla-filename-convention and corrected on 2026-09-07.
+      The previous claim, that vanilla hairstyle files follow `[gender]hair[number]_pt[partition]`,
+      is contradicted by the wiki's own hair cheat sheet; no wiki page states what `pt` stands for,
+      so "partition" was dropped as invented. To find physics-enabled vanilla hair the cheat sheet
+      suggests the WolvenKit search `base\characters\common\hair > .animgraph > _wa_`.
+  - id: cp2077.hair.modding.first-material-entry-governs-all-appearances
+    claim: "\"Unless you have multiple submeshes, only the first entry in the material matters\" — so
+      once hair submeshes are joined into one mesh, \"only the first material entry matters for
+      every appearance\", across all 35 appearances for the game's 35 hair colours. The cheap fix is
+      to copy the materials from a hairstyle that already works rather than retargeting all 35 by
+      hand."
+    status: community
+    source: wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "Wolvenkit"
+    tags:
+      - hair
+      - material
+      - join
+      - silent-failure
+      - gotcha
+    detail: "The guide's concrete case is wanting `cards` where the first entry is `cards_top`. 35 is
+      exact, not \"roughly 35\": \"Cheat Sheet: Hair\" lists 35 colour names by index, from
+      `05_brown_liquorice` (CC slot 1) to `35_silver_rose`. Corrected 2026-09-07."
+  - id: cp2077.hair.modding.version-floors
+    claim: The hair-replacement tutorial's requirements are WolvenKit >= 8.13.0, Blender >= 4.0, the
+      WolvenKit Blender IO Suite (most recent version), and the UUH4V Framework "(To avoid conflicts
+      with spawned NPCs)".
+    status: community
+    source: wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "Requirements"
+    tags:
+      - hair
+      - version-floor
+      - wolvenkit
+      - blender
+      - uuh4v
+    detail: "Corrected 2026-09-07: the stated reason for UUH4V is conflicts with SPAWNED NPCs, not
+      load-order conflicts with other hair mods. Tool versions are on their own numbering, so they
+      stay in the claim with no `verified_on`."
+  - id: cp2077.hair.modding.single-head-bone-weighting
+    claim: "\"Unlike clothes, most head meshes only have one bone: `Head`\" — the hair mesh is weighted
+      by selecting all vertices in Edit Mode, creating the `Head` entry in the Data tab of the
+      Properties panel and clicking `Assign`. A mesh rigged this way \"would stay on your
+      character's head like a helmet\", i.e. with no physics."
+    status: community
+    source: wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "The Mesh > Rigging the
+      hair"
+    tags:
+      - hair
+      - rig
+      - bone
+      - weighting
+      - head-bone
+    detail: "Corrected 2026-09-07: physics do NOT come from simply pairing an `.animgraph`/`.rig`. Per
+      \"The Physics\" and \"Finding vanilla hair to replace\", you separate the parts that should
+      move into submeshes, export a vanilla hairstyle whose shape overlaps yours together with its
+      `.rig` and `.animgraph` (\"They are the physic components for the hair\"), transfer weights
+      from the vanilla mesh to yours, and parent your meshes under the vanilla armature with an
+      armature modifier. The guide's own caveat: this is \"the easiest and fastest method, but also
+      the most unreliable\", and leaving the hair static is an acceptable outcome. It names donor
+      meshes by part: `hh_081_wa__buns_02` for front/right bangs, `hh_040_wa__pixie_bob` for left
+      bangs, `hh_118_wa__gillean` or `hh_115_wa__alanah` for hair on the shoulder,
+      `hh_083_wa__ponytail_01` for ponytails."
+  - id: cp2077.hair.modding.adapt-uv-to-shared-hair-texture
+    claim: "\"If you are porting a hairstyle from another game, it is highly recommended that you just
+      adapt the UV of your hairstyle to fit CP2077's shared hair texture instead of using the
+      original texture. This will allow your hair to use the game's hair color system, as well as
+      saving you a lot of hassle when handling the materials.\""
+    status: community
+    source: wiki.redmodding.org "Basic Hairstyle Replacement Tutorial", section "The Texture"
+    tags:
+      - hair
+      - texture
+      - uv
+      - shared-texture
+      - hair-color
+    detail: Section name corrected 2026-09-07 (this is under "The Texture", not "Mesh Preparation").
+  - id: cp2077.hair.modding.vertex-color-ao-convention
+    claim: "\"Cyberpunk hair material uses the vertex colour attribute to fake ambient occlusion. They
+      are usually red at the scalp and the innermost layer of hair cards, whereas the outer layers
+      are black.\" Doing it the other way round looks bad; the page's caption states the rule as
+      \"Red is dark and dull, black is bright and shiny\"."
+    status: community
+    source: wiki.redmodding.org "Vertex Color and Hair", section "Summary"
+    tags:
+      - hair
+      - vertex-color
+      - ambient-occlusion
+      - shader
+      - gotcha
+    detail: The page does not specify which RGB channel(s) or numeric range carry this — only the
+      relative convention — so treat exact channel/value authoring as unverified beyond "red at
+      scalp and inner layers, black on outer layers". Section name corrected 2026-09-07 (there is no
+      "Ambient Occlusion (AO) Channel" heading).
+  - id: cp2077.hair.modding.flow-map-encodes-strand-direction
+    claim: Separately from vertex-colour AO, Cyberpunk mimics anisotropy "with the flow texture, which
+      acts as a tangent map in telling the shader that the hair strands run from root to tip",
+      encoding directions as colour. "The dread flow map is inverted, as the dreadlocks have strands
+      running in the opposite direction."
+    status: community
+    source: wiki.redmodding.org "Vertex Color and Hair", section "Anisotropy"
+    tags:
+      - hair
+      - flow-map
+      - shader
+      - strand-direction
+      - dreadlocks
+    detail: 'Section name corrected 2026-09-07 (there is no "Related Concept: Flow Texture" heading).'

package/knowledge/cyberpunk2077/items.wiring.yaml

@@ -0,0 +1,246 @@
+game: cyberpunk2077
+topic: items.wiring
+title: The yaml -> csv -> root_entity.ent -> .app -> mesh_entity.ent -> .mesh chain for item additions
+facts:
+  - id: cp2077.items.wiring.four-structural-files-to-add-an-item
+    claim: "Registering a new item with TweakXL/ArchiveXL requires four structural files: the TweakXL
+      `.yaml` (the item's properties), the `.xl` manifest (tells ArchiveXL which factory csv and
+      localization json to register), the factory `.csv` (maps the yaml's `entityName` to a root
+      entity file) and the localization `.json` (translated display/description strings)."
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "Structural files: telling the game about your mod"'
+    tags:
+      - items
+      - archivexl
+      - tweakxl
+      - file-structure
+  - id: cp2077.items.wiring.yaml-four-mappings
+    claim: "A TweakXL item yaml entry performs four mappings: `entityName` points to a row in the
+      factory csv; `appearanceName` is looked up (by name, up to the first suffix) in the root
+      entity the factory resolved to; `displayName`/`localizedDescription` are keys looked up in the
+      localization json, gender-branched into `maleVariant`/`femaleVariant`; `icon` hooks up the
+      inventory preview."
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "The control file: yourModName.yaml"'
+    tags:
+      - items
+      - yaml
+      - entityname
+      - appearancename
+      - displayname
+      - icon
+    detail: "If a language's localization entry is missing, the English one is used as fallback
+      (documented under \"The .json file (custom texts, i18n)\"). Checked against the source
+      (2026-09-08): an earlier detail had the gender fallback backwards. The page says the opposite
+      — \"If you don't need a male-specific translation, you can leave it blank — by default,
+      `femaleVariant` will be used\", i.e. it is `maleVariant` that may be left blank, and
+      `femaleVariant` is the value used when it is."
+  - id: cp2077.items.wiring.factory-csv-links-entityname-to-root-entity
+    claim: The factory `.csv` file is where ArchiveXL looks up a yaml entry's `entityName` (matched
+      against the csv's first field/header) to find the corresponding root entity `.ent` path, and
+      the `appearanceName` from the yaml is then searched for inside that root entity.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "The .csv file (the factory)"
+    tags:
+      - items
+      - factory-csv
+      - entityname
+      - root-entity
+    detail: "RELATED: this generic mechanism is the same one cp2077.archivexl.factories-csv-paths and
+      cp2077.archivexl.factory-csv-appearance-mapping document concretely for one weapon mod's own
+      factory_parts.csv (columns name, path, shared) — this fact states the general csv-lookup
+      mechanism, that one the specific shipped file's schema."
+  - id: cp2077.items.wiring.root-entity-is-appearance-lookup-dictionary
+    claim: 'The root entity (`root_entity.ent`) is described as "a glorified lookup dictionary": for a
+      given `appearanceName` it specifies which `.app` file to load and which appearance name inside
+      that `.app` to use; when using dynamic appearances only one appearance entry is needed here
+      (matched up to the `!` variant separator), and it must carry the `DynamicAppearance` tag.'
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "root_entity.ent"
+    tags:
+      - items
+      - root-entity
+      - dynamic-appearances
+      - dynamicappearance-tag
+  - id: cp2077.items.wiring.mesh-entity-replaces-app-component-array
+    claim: "`mesh_entity.ent` holds the components (chiefly an `entGarmentSkinnedMeshComponent`) that
+      determine how the equipment renders and moves; using a separate mesh entity file replaces
+      having to duplicate that component array inline inside every appearance of the `.app` file.
+      The component's `name` is what the `.app`'s `materialOverride`/`partsOverrides` array
+      references back."
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "mesh_entity.ent"
+    tags:
+      - items
+      - mesh_entity
+      - entgarmentskinnedmeshcomponent
+      - .app
+  - id: cp2077.items.wiring.mesh-component-name-prefix-must-be-kept
+    claim: When renaming a garment mesh component inside `mesh_entity.ent`, the component-type name
+      prefix (e.g. `t1_`) must be left in place — the game uses that prefix to calculate collisions
+      — even though the rest of the component's name is otherwise a free label.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      warning under "mesh_entity.ent" ("you want to leave the component prefixes (t1_) in place —
+      the game needs them to calculate collisions!")
+    tags:
+      - items
+      - mesh_entity
+      - component-prefix
+      - collision
+      - gotcha
+  - id: cp2077.items.wiring.app-component-array-must-stay-empty
+    claim: An item's `appearance.app` file's own top-level `components` array must be left empty — items
+      load their components from `mesh_entity.ent` via `partsValues` instead; a non-empty
+      `components` array on an item `.app` is explicitly called out as wrong ("this is not an NPC
+      appearance!").
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md, danger
+      hint under "appearance.app" ("The .app file's component array should be **empty:** this is not
+      an NPC appearance!")
+    tags:
+      - items
+      - .app
+      - components
+      - gotcha
+      - validator
+  - id: cp2077.items.wiring.app-partsvalues-vs-partsoverrides
+    claim: Inside an item `appearance.app` entry, `partsValues` points at the `mesh_entity.ent` file(s)
+      to load as components, while `partsOverrides` tells the referenced mesh which
+      appearance/chunkmask to use; when using dynamic appearances (a single appearance entry with
+      components ignored) only `partsValues` needs to be set — `partsOverrides`-based chunkmask
+      hiding is the non-dynamic-appearance path.
+    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"
+    tags:
+      - items
+      - .app
+      - partsvalues
+      - partsoverrides
+      - dynamic-appearances
+  - id: cp2077.items.wiring.mesh-appearance-name-links-app-to-mesh
+    claim: Inside an item's `.app` appearance's `partsOverrides`, the `componentsOverride` entry's
+      `meshAppearance` field must match the `name` of a `meshMeshAppearance` entry inside the actual
+      `.mesh` resource file; the `.app` file itself does not define materials — it only selects
+      which named appearance inside the `.mesh` to use.
+    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: Making changes" (steps 8-9)'
+    tags:
+      - items
+      - .app
+      - .mesh
+      - meshappearance
+      - wiring
+  - id: cp2077.items.wiring.mesh-material-index-must-match-array-position
+    claim: Inside a `.mesh` resource, a new `materials` entry's `index` field must match that entry's
+      actual position in the `materials` array, and the corresponding new entry appended to
+      `localMaterialBuffer` must also be placed at the matching position, because the mesh's
+      materials and localMaterialBuffer entries are matched to each other by numeric array index
+      rather than by name.
+    status: community
+    source: "CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section \"Mesh: Making changes\", step 3 (\"Drag it to the last position of the array (that's
+      important, because the materials entries match by numeric index)\")"
+    tags:
+      - items
+      - .mesh
+      - materials
+      - localmaterialbuffer
+      - index
+      - gotcha
+  - id: cp2077.items.wiring.base-parameter-selects-equipment-slot
+    claim: An item yaml record's `$base` value determines which equipment slot the item occupies;
+      different equipment slots require picking a different "right" mesh entity file for the item,
+      per a separate per-slot reference the page defers to.
+    status: community
+    source: CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      section "What is it, precious? The $base parameter" ("`$base` defines which slot the item will
+      use") and section "mesh_entity.ent" ("you need to pick the right mesh entity file for each
+      equipment slot", which defers to different-equipment-slots.md)
+    tags:
+      - items
+      - $base
+      - equipment-slot
+      - mesh_entity
+  - id: cp2077.items.wiring.moving-root-entity-requires-updating-factory-csv
+    claim: Moving (renaming/relocating) the root entity `.ent` file requires manually updating the path
+      recorded for it in the factory `.csv`; moving the `.app`/appearance file requires updating the
+      path inside `root_entity.ent`; moving the mesh entity requires updating the path inside every
+      appearance in the `.app` file. Each file only knows the next file's path by an explicit string
+      reference, not a resolved relationship WolvenKit maintains automatically.
+    status: community
+    source: 'CDPR-Modding-Documentation/Cyberpunk-Modding-Docs
+      modding-guides/items-equipment/adding-new-items/archive-xl-item-structure-explained.md,
+      sections "The .csv file (the factory) > Making changes", "Root Entity: Making Changes", "Mesh
+      Entity: Making Changes" and "Appearance: Making changes"'
+    tags:
+      - items
+      - file-structure
+      - path-reference
+      - maintenance
+  - id: cp2077.items.wiring.weapon-look-is-an-app-row-not-a-root-entity
+    claim: "A vanilla weapon record has no root entity of its own to clone: it inherits `entityName:
+      weapon_root` from Items.Base_Weapon, weapons.csv
+      (base\\gameplay\\factories\\items\\weapons\\weapons.csv) maps that name to the shared
+      base\\weapons\\weapon_root.ent, and that entity's `appearances` list is empty (components
+      only: slots, audio, stats, attachment slots, projectile spawn, status effect, vision mode,
+      gameplay role, UI slots, an effect spawner). The weapon's look is the `.app` that
+      weapons_appearances.csv maps its `appearanceResourceName` to (Preset_Kenshin_Default ->
+      base\\weapons\\firearms\\handgun\\arasaka_kenshin\\w_handgun__arasaka_kenshin.app, ten named
+      appearances of 28 to 30 components each). A weapon mod therefore ships an `.app` and a factory
+      row naming it, never a root entity: one weapon mod's shipped factory_parts.csv holds exactly
+      two rows, `<mod>_body -> mod\\<mod>\\<mod>_body.app` and `<Mod>_Weapon ->
+      mod\\<mod>\\<mod>_weapon.app`, and its archive carries no `.ent` for the weapon (only the
+      cache case's)."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    related:
+      - cp2077.items.wiring.factory-csv-links-entityname-to-root-entity
+      - cp2077.items.wiring.root-entity-is-appearance-lookup-dictionary
+    tags:
+      - items
+      - weapons
+      - app
+      - factory
+      - root-entity
+      - appearance-resource-name
+      - scaffold
+  - id: cp2077.items.wiring.spawnitemdrop-drops-from-the-droppers-inventory
+    claim: "LootManager.SpawnItemDrop(obj, itemID, position, rotation) drops an item the object holds:
+      vanilla's vendor gives the item to the vendor object first and then drops it. Dropped from the
+      player with a seedless ItemID.FromTDBID she did not hold, it returned false; given first, it
+      returned true and a pickup appeared. A cyberdeck program has no world entity (its record chain
+      sets no entityName), so its pickup is invisible. HasItem and GetItemQuantity with a seedless
+      ItemID.FromTDBID do not see a program given or picked up (0 right after a GiveItem); match by
+      ItemID.GetTDBID over GetItemList."
+    status: verified
+    verified_on: "2.31"
+    source: ModWright field verification
+    tags:
+      - items
+      - loot
+      - drop
+      - pickup
+      - program
+      - itemid
+    detail: A drop placed at a surface point inside a dynamic prop's collision threw the prop (a
+      notebook on Nix's desk).

package/knowledge/cyberpunk2077/loadorder.archives.yaml

@@ -0,0 +1,71 @@
+game: cyberpunk2077
+topic: loadorder.archives
+title: Archive load order and conflict resolution
+facts:
+  - id: cp2077.loadorder.archive-conflicts-first-wins
+    claim: When two .archive files in archive\pc\mod supply the same depot path, the one that loads
+      FIRST wins. Load order is ASCII-alphabetical by filename, so the earlier-sorting archive's
+      version of the file is the one the game uses. The widely repeated "last wins" / "z-prefix
+      wins" advice is wrong.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - load-order
+      - archive
+      - conflict
+      - first-wins
+      - override
+    detail: Cost a launch. A base <Mod>.archive beat a later-sorting <Mod>Black.archive and the recolour
+      never appeared, surviving a clean restart. The fix is to make the override sort BEFORE the
+      base archive; a space right after the shared stem does it cleanly ("<Mod> - Black
+      Body.archive"), because space 0x20 sorts before the "." 0x2E of "<Mod>.archive" - no ugly
+      numeric prefix needed.
+  - id: cp2077.loadorder.archive-xl-does-not-reprioritise
+    claim: A <name>.archive.xl does NOT re-mount or re-prioritise <name>.archive. ArchiveXL only loads
+      the .xl extension; the base game still loads the .archive in its normal alphabetical position.
+      Filename is therefore the only lever over archive precedence.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - archivexl
+      - load-order
+      - archive
+      - precedence
+  - id: cp2077.loadorder.modlist-absent-means-alphabetical
+    claim: With no modlist.txt present, archives load in plain alphabetical order. An absent modlist is
+      not a fallback to install order or timestamp order.
+    status: inferred
+    source: ModWright research
+    tags:
+      - load-order
+      - modlist
+      - archive
+    detail: Recorded because it was eliminated as an explanation, not because it was independently
+      tested. Treat as the working assumption, not a measurement.
+  - id: cp2077.loadorder.rht-watches-hot-directory-only
+    claim: RedHotTools' live depot mount watches archive\pc\hot ONLY. Dropping a rebuilt archive
+      anywhere else - including archive\pc\mod - does not trigger a live remount.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - redhottools
+      - hot-reload
+      - archive
+      - depot
+  - id: cp2077.loadorder.reskin-ships-as-override-archive
+    claim: An optional reskin or recolour ships as its own .archive containing only the overridden depot
+      paths (the mesh plus any changed textures); everything else resolves from the base archive. It
+      must be NAMED to sort before the base archive or it loses the conflict.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - archive
+      - override
+      - reskin
+      - optional
+      - packaging
+    detail: Build the override mesh by editing the mesh JSON materials directly and running convert
+      deserialize, NOT by re-importing with import -k. The direct-JSON route preserves
+      boneVertexEpsilons; the import -k defect and its symptom are recorded in full at
+      cp2077.process.assetbuild.wolvenkit-import-keep-flag-wipes-bone-vertex-epsilons (which also
+      names the restore step, a restore script, and the shipped value of 3.0).