modwright 0.1.0

package/knowledge/baldursgate3/items.visualbank.yaml

@@ -0,0 +1,628 @@
+game: baldursgate3
+topic: items.visualbank
+title: Item VisualBank / MaterialBank / TextureBank UUID chain
+facts:
+  - id: bg3.items.visualbank.three-region-chain
+    claim: "An item's visual data is a three-region chain that must cross-link by UUID: a VisualBank
+      Resource's Objects/MaterialID must equal a MaterialBank Resource's ID, and that MaterialBank
+      Resource's Texture2DParameters ID must equal a TextureBank Resource's ID. All three regions
+      typically live in the same pair of .lsf.lsx files under
+      Public/<Mod>/Content/Assets/Characters/[PAK]_Armor."
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Meshes.lsx, §Materials and Texture .lsx
+    tags:
+      - items
+      - visualbank
+      - materialbank
+      - texturebank
+      - uuid
+    detail: '"[PAK]_Armor" is a literal bracketed folder name. The wiki: "If there is anything wrong
+      with the material, your item may simply refuse to show up, so it is worth double-checking
+      everything here." — the chain fails silently. Community confirmation of
+      bg3.materials.no-custom-base-material, which read the same side-by-side bank layout
+      (VisualBank / MaterialBank / TextureBank as regions of one merged bank file) straight out of
+      the Patch 8 paks.'
+  - id: bg3.items.visualbank.visualbank-id-links-roottemplate
+    claim: The VisualBank Resource's ID attribute is the UUID a RootTemplate's VisualTemplate (loot
+      appearance) or Equipment/VisualSet (equipped appearance) references to attach the mesh to an
+      item.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Meshes.lsx ("(This UUID links up to the Roottemplate)")
+    tags:
+      - items
+      - visualbank
+      - roottemplate
+      - uuid
+  - id: bg3.items.visualbank.objectid-mesh-order-vs-lod
+    claim: "A VisualBank Objects node's ObjectID suffix (e.g. \"..._Mesh.0\") denotes mesh order (\"The
+      .0 denotes mesh order\"), which is a different number from the LOD attribute on the same node:
+      \"What level of LOD it is. This is a LOD0, so it is the highest quality mesh and the one we
+      see in cutscenes.\""
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Meshes.lsx
+    tags:
+      - items
+      - visualbank
+      - lod
+      - mesh-order
+    detail: The exporter-side number that produces the suffix is the per-mesh Export Order field — see
+      bg3.character-creation.heads-hair.export-order-must-be-sequential.
+  - id: bg3.items.visualbank.name-fields-unreferenced-but-unique
+    claim: The Name attribute on a VisualBank mesh Resource and on a MaterialBank material Resource is
+      never referenced anywhere else in the data, but should still be kept unique per mod to avoid
+      clashing with another mod's identically-named entries.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Meshes.lsx, §Materials and Texture .lsx
+    tags:
+      - items
+      - visualbank
+      - materialbank
+      - naming
+  - id: bg3.items.visualbank.vertexcolormaskslots-hides-body-part
+    claim: Setting SupportsVertexColorMask to True on a VisualBank Resource and adding a child
+      VertexColorMaskSlots/Object node with a slot name (e.g. value="feet") makes the underlying
+      body part disappear when that item is equipped — the standard fix for boots clipping through
+      feet.
+    status: community
+    source: "bg3.wiki/wiki/Modding:Items §Meshes.lsx (\"You need this set to True if you want, say,
+      pants to vanish when boots are equipped\"; the feet example: \"This code would stop the body's
+      feet from loading in and clipping, ideal for boot items\")"
+    tags:
+      - items
+      - visualbank
+      - vertexcolormask
+      - clipping
+  - id: bg3.items.visualbank.material-shader-selection-by-filename
+    claim: "The MaterialBank Resource's SourceFile picks the shader by filename convention:
+      \"CHAR_BASE.lsf\" is a standard opaque shader; a name containing \"Alpha\" (e.g.
+      \"CHAR_BASE_AlphaTest_2S.lsf\") enables transparency and disables backface culling;
+      \"..._AlphaTest_2S_Dither\" is required for underwear to hide correctly; \"..._VertCut\" is
+      required (with SupportsVertexColorMask/VertexColorMaskSlots) to make a body part disappear; a
+      \"_VT\" suffix only works with virtual textures and is not generally useful for modding."
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Materials and Texture .lsx
+    tags:
+      - items
+      - materialbank
+      - shader
+      - transparency
+      - underwear
+    detail: "Exact wiki wording for the two load-bearing ones: \"Underwear needs to have a Dither shader
+      or it won't hide correctly\" and \"Materials with _VT at the end are less useful, as they only
+      work with virtual texture.\" Names the shader files behind bg3.materials.instance-recipe's
+      \"SourceFile = path to a base material .lsf\", which was inferred from vanilla data rather
+      than from a tutorial."
+  - id: bg3.items.visualbank.texturebank-srgb-basecolor-only
+    claim: A TextureBank Resource's SRGB attribute must be True only for the basecolor (BM) texture; the
+      normal (NM), physical (PM), and mask (MSK) maps must have SRGB set to False because they don't
+      carry color information.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Materials and Texture .lsx
+    tags:
+      - items
+      - texturebank
+      - srgb
+      - basecolor
+  - id: bg3.items.visualbank.dds-extension-case-sensitive
+    claim: "A TextureBank Resource's SourceFile path is case-sensitive on the .DDS extension itself: a
+      texture file is expected as uppercase \".DDS\" and a lowercase \".dds\" file at the same path
+      will not load."
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Materials and Texture .lsx ("Capitalisation is IMPORTANT. Make
+      sure your texture is not named MSW_CoolCirclet_NM.dds or it won't load.")
+    tags:
+      - items
+      - texturebank
+      - dds
+      - case-sensitivity
+      - silent-failure
+    detail: "The casing rule is per file class, not global: item/character textures and .GR2 meshes are
+      uppercase (.DDS / .GR2), while an ICON ATLAS .dds is lowercase — see
+      bg3.ui.icons-atlas.atlas-path-must-match-textureatlaspath."
+  - id: bg3.items.visualbank.undersized-texture-tiles
+    claim: A TextureBank Resource's Width/Height attributes don't have to exactly match the source .DDS
+      file's real dimensions, but if the listed size is larger than the actual texture, the texture
+      tiles instead of scaling.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §Materials and Texture .lsx
+    tags:
+      - items
+      - texturebank
+      - texture-size
+    detail: "The wiki hedges it: \"These dimensions don't need to be exact. I believe if it is smaller
+      than listed, the texture will tile.\""
+  - id: bg3.items.visualbank.roottemplate-mapkey-links-stats-entry
+    claim: "A RootTemplate GameObjects node's Name and MapKey attributes both link it to the matching
+      stats entry (Armor.txt or Weapon.txt): the stats file's data \"RootTemplate\" value must equal
+      the RootTemplate's MapKey, and the stats entry name must equal the RootTemplate's Name."
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §RootTemplate
+    tags:
+      - items
+      - roottemplate
+      - armor-txt
+      - weapon-txt
+      - uuid-linkage
+  - id: bg3.items.visualbank.parenttemplateid-inheritance-fallback
+    claim: Any RootTemplate attribute left unspecified (Description, Icon, EquipSound, etc.) silently
+      falls back to the value on the item's ParentTemplateId template. Using the wrong
+      ParentTemplateId for the item's real type (e.g. not a shield's parent template for a shield)
+      causes inherited-property mismatches — "a shield will not know it is a shield without this
+      ParentTemplate."
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §RootTemplate
+    tags:
+      - items
+      - roottemplate
+      - parenttemplateid
+      - inheritance
+      - silent-failure
+  - id: bg3.items.visualbank.parentrace-zero-uuid-opts-out
+    claim: Githyanki, Dragonborn, Tiefling, and Half-Orc automatically fall back to HUM/HUM_STRONG body
+      meshes for an item unless a race is explicitly opted out; opting out is done with an
+      Equipment/ParentRace/Object node whose MapKey is the race's UUID and whose MapValue is the
+      all-zero UUID (00000000-0000-0000-0000-000000000000), which "zeroes the race out" of using
+      that item's race-specific mesh.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §RootTemplate
+    tags:
+      - items
+      - roottemplate
+      - parentrace
+      - race-uuid
+  - id: bg3.items.visualbank.treasuretable-i-prefix
+    claim: "TreasureTable.txt entries reference item root templates with an \"I_\" prefix on the item
+      name, in the form: object category \"I_ITEM_NAME\",1,0,0,0,0,0,0,0 — \"Make sure you don't
+      forget the I_ prefix for the item!\""
+    status: community
+    source: 'bg3.wiki/wiki/Modding:Items §TreasureTable (worked example: object category
+      "I_MY_COOL_NEW_CIRCLET",1,0,0,0,0,0,0,0)'
+    tags:
+      - items
+      - treasuretable
+      - naming-convention
+  - id: bg3.items.visualbank.weapon-loot-model-equals-item-model
+    claim: A RootTemplate's VisualTemplate is normally the dropped/examined "LOOT model," distinct from
+      the equipped VisualSet mesh — except for a weapon, where "the LOOT model and the item model
+      are the same," so a weapon RootTemplate's VisualTemplate should point at the same visual as
+      its equipped mesh.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §RootTemplate
+    tags:
+      - items
+      - weapon
+      - visualtemplate
+      - roottemplate
+  - id: bg3.items.visualbank.weapon-shares-visualbank-chain
+    claim: Weapons use the identical VisualBank/MaterialBank/TextureBank chain, folder ([PAK]_Armor),
+      and file pairing (.lsf.lsx meshes + materials/textures) as armor — the wiki's
+      Stats/Generated/Data folder listing names "Armor.txt, Object.txt, Passive.txt, Weapon.txt"
+      side by side as the stats files that reference the same RootTemplates/[PAK]_Armor content
+      tree, and the Sample Equipment Mod template is explicitly described as "for Armor and Weapon
+      modding" using one shared workflow.
+    status: community
+    source: bg3.wiki/wiki/Modding:Items §File Overview, §Sample Templates
+    tags:
+      - items
+      - weapon
+      - visualbank
+      - shared-pattern
+    detail: "Extends the armor-focused walkthrough: no separate weapon-only visual pipeline is
+      documented on the page. What the page does state weapon-specifically is the loot-model rule —
+      see bg3.items.visualbank.weapon-loot-model-equals-item-model."
+  - id: bg3.items.visualbank.texture-map-suffix-taxonomy
+    claim: "BG3's texture filenames encode their map type by suffix: BM (Basecolor), NM (Normal), PM
+      (Physical: Metallic+Roughness+AO), and MSK (Mask, material-region/dye definition) are the
+      Hardsurface set; CLEA (Cavity/Hair/Makeup/AO) and HMVY (Hemoglobin/Melanin/Vein/Yellowing) are
+      Skin-only; CTLO (Cavity/Thickness/Lips/AO, replaces CLEA) and DMSK (Decorative/Accent Mask)
+      are Dragonborn-Skin-only. NM and MSK suffixes are shared between Hardsurface and Skin but mean
+      different channel layouts in each (see
+      bg3.items.visualbank.msk-channel-meaning-differs-hardsurface-vs-skin)."
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md §Texture formats > Maps (the eight-row
+      Map Type table)
+    tags:
+      - items
+      - texture
+      - suffix
+      - naming-convention
+      - msk
+      - bm
+      - nm
+      - pm
+    related:
+      - id: bg3.items.visualbank.material-shader-selection-by-filename
+        detail: Complements the existing fact's shader-selection-by-filename convention (CHAR_BASE, _Alpha,
+          _Dither, _VertCut, _VT) with the separate, orthogonal suffix system that names which
+          TEXTURE MAP TYPE a given .dds is, independent of which shader a material chooses.
+  - id: bg3.items.visualbank.hardsurface-channel-layout-and-compression
+    claim: "Hardsurface texture maps' channel layout and DDS compression: BM stores RGB color intensity
+      plus an alpha channel, compressed BC1/DXT1 Linear (and \"can be either full color or
+      grayscale\"); NM stores Y Axis Normals in Green, Z Axis Normals in Blue, and X Axis Normals in
+      Alpha with Red unused, BC3/DXT5 Linear; PM stores Metallic Intensity (Red), Roughness (Green),
+      and Ambient Occlusion (Blue) with Alpha unused, BC1/DXT1 Linear; MSK's channel makeup is
+      \"largely irrelevant\" (a colored mask for material regions) with Alpha unused, BC1/DXT1
+      Linear."
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md §Objects (Hardsurface) texture map
+      breakdown
+    tags:
+      - items
+      - texture
+      - hardsurface
+      - channel-layout
+      - compression
+      - bm
+      - nm
+      - pm
+      - msk
+  - id: bg3.items.visualbank.normal-map-red-channel-relocated-to-alpha
+    claim: Converting a standard tangent-space DX normal map to BG3's NM format requires moving the Red
+      channel's data into the Alpha channel and then setting Red itself to black — BG3's NM format
+      does not use Red for X-axis normal data the way a conventional DX normal map does; X-axis data
+      instead lives in Alpha.
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md §DGB texture map breakdown, NM entry
+      ("To convert a 'regular' tangent DX normal map to BG3, put the Red channel into Alpha channel
+      and set Red channel to black")
+    tags:
+      - items
+      - texture
+      - normal-map
+      - dragonborn
+      - conversion
+      - gotcha
+  - id: bg3.items.visualbank.msk-channel-meaning-differs-hardsurface-vs-skin
+    claim: "The same MSK suffix means a different channel layout depending on context: a Hardsurface
+      MSK's channel makeup is stated as irrelevant (any colored region works as a material mask),
+      while a Skin MSK has a fixed meaning — Red: Non-Skin, Green: Melanin Removal, Blue: Mucous
+      Map, Alpha: Not Used — both compressed BC1/DXT1 Linear despite the different channel
+      semantics."
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md §Objects (Hardsurface) texture map
+      breakdown (MSK row) and §Skin texture map breakdown (MSK row)
+    tags:
+      - items
+      - texture
+      - msk
+      - hardsurface
+      - skin
+      - channel-layout
+  - id: bg3.items.visualbank.dragonborn-ctlo-thickness-and-ao-need-adjustment-from-bakes
+    claim: Dragonborn's CTLO map's Thickness channel (Green) "is inverted compared to one from Marmoset
+      and much lighter," and its Ambient Occlusion channel (Alpha) "is much whiter then one you will
+      bake in Marmoset or Substance" — a Thickness/AO map baked in either of those tools needs
+      adjustment before it will look correct packed into BG3's CTLO layout.
+    status: community
+    source: "bg3-community/Information/Textures/texture-types.md §DGB texture map breakdown, CTLO entry
+      (Note: \"Thickness - it's inverted compared to one from Marmoset and much lighter\"; \"AO -
+      it's much whiter then one you will bake in Marmoset or Substance, so adjust them if you want
+      to mix with yours\")"
+    tags:
+      - items
+      - texture
+      - dragonborn
+      - ctlo
+      - thickness
+      - ambient-occlusion
+      - gotcha
+  - id: bg3.items.visualbank.draconic-bloodline-dmsk-replaces-dmsk-at-runtime
+    claim: A Dragonborn's DMSK (decorative/accent mask) texture is dynamically replaced by a separate
+      "Draconic Bloodline DMSK" texture at runtime if the player chose the Draconic Bloodline
+      sorcerer subclass — a mod that only authors the base DMSK will not see its accent details on a
+      Draconic Bloodline character.
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md §DGB texture map breakdown, "Draconic
+      Bloodline DMSK" entry ("they will replace DMSK if gamer choose the DB subclass, keep it in
+      mind")
+    tags:
+      - items
+      - texture
+      - dragonborn
+      - dmsk
+      - draconic-bloodline
+      - subclass
+  - id: bg3.items.visualbank.illithid-msk-body-uses-stacked-uv-halves
+    claim: The Illithid MSK texture uses a 1x1 UV ratio for the head but a 1x2 (vertically stacked)
+      ratio for the body; any body UV island placed outside the top 1x1 square draws its data from
+      the second (bottom) half of the texture instead.
+    status: community
+    source: bg3-community/Information/Textures/texture-types.md:247-252, §DGB texture map breakdown,
+      "Illithid MSK" entry ("For head it is 1x1 ratio image, for body it is 1x2."; the note then
+      says UV parts outside that 1x1 take their data from the second part of the texture)
+    tags:
+      - items
+      - texture
+      - illithid
+      - msk
+      - uv-layout
+  - id: bg3.items.visualbank.mesh-needs-msk-map-to-be-dyeable
+    claim: A mesh only supports in-game dyeing if it has an MSK map; the MSK map is what "allows you to
+      set which dye parameters different areas in your mesh use." A mesh with no MSK map cannot be
+      dyed regardless of what dye/colour preset is applied to it.
+    status: community
+    source: bg3-community/Information/Textures/mskColours.md §MSK Colours (opening paragraph)
+    tags:
+      - items
+      - texture
+      - msk
+      - dye
+      - requirement
+  - id: bg3.items.visualbank.msk-twelve-parameter-armor-scheme
+    claim: "The primary armor shader's MSK map uses exactly 12 dye parameters, three each for Cloth,
+      Leather, and Metal (Primary/Secondary/Tertiary), plus Accent_Color, Custom_1, and Custom_2 —
+      each with a fixed reference sRGB/hex swatch value used to paint that region in the MSK texture
+      (e.g. Cloth_Primary = #FF8000, Leather_Primary = #8000FF, Metal_Primary = #00FF80)."
+    status: community
+    source: bg3-community/Information/Textures/mskColours.md §MSK Colours (12-parameter table)
+    tags:
+      - items
+      - texture
+      - msk
+      - dye
+      - parameters
+  - id: bg3.items.visualbank.msk-simple-three-parameter-scheme-aliases-the-twelve-parameter-one
+    claim: "Simpler meshes can use a 3-parameter MSK scheme instead (Color_01/Color_02/Color_03), but
+      the two schemes cannot be combined on the same MSK map: Color_01/02/03 use the exact same
+      reference RGB values as Cloth_Secondary, Metal_Secondary, and Leather_Secondary respectively,
+      so a value written for one scheme is indistinguishable in the raw texture from the
+      corresponding value in the other — which set of 12-or-3 meanings actually applies depends on
+      the material shader assigned to the mesh, not on the MSK texture itself."
+    status: community
+    source: bg3-community/Information/Textures/mskColours.md:36, §MSK Colours ("You cannot combine these
+      on the same MSK map as the parameters above, as you may notice they use the same values as
+      Cloth_Secondary, Metal_Secondary, and Leather_Secondary respectively."; the next sentence adds
+      that which value is used depends on the material shader)
+    tags:
+      - items
+      - texture
+      - msk
+      - dye
+      - shader-dependent
+      - gotcha
+  - id: bg3.items.visualbank.solid-colour-msk-uses-engine-msk-uuids
+    claim: For a solid-colour MSK region, a material can reference the built-in Engine_MSK colour map's
+      UUID for the desired parameter instead of authoring a new solid-color MSK texture — e.g.
+      Cloth_Primary = 01e0ce88-b357-fd26-323a-5a3577fcc35a, Metal_Primary =
+      40daac11-00dc-de43-7dcc-7cb7206fd298. The community reference itself records
+      Leather_Tertiary's UUID as "unknown" — not yet documented anywhere.
+    status: community
+    source: bg3-community/Information/Textures/mskColours.md §Solid Colour MSK (UUID table)
+    tags:
+      - items
+      - texture
+      - msk
+      - engine-msk
+      - uuid
+      - solid-color
+    detail: The community page's own gap (Leather_Tertiary = "unknown") is preserved here rather than
+      guessed at — a mod needing that specific solid parameter should extract Engine_MSK from the
+      vanilla paks directly rather than trust an invented UUID.
+  - id: bg3.items.visualbank.msk-compression-matches-basecolor-map
+    claim: "MSK maps for clothing and armor use the same compression settings as the base color (BM)
+      map: BC1/DXT1 with mipmaps enabled — not a different compression profile from the diffuse
+      texture it accompanies."
+    status: community
+    source: bg3-community/Information/Textures/mskColours.md §Compression
+    tags:
+      - items
+      - texture
+      - msk
+      - compression
+      - bc1
+      - dxt1
+  - id: bg3.items.visualbank.equipment-visuals-is-direct-child-not-in-visualset
+    claim: 'In an item RootTemplate (GameObjects, Type="item") the worn mesh comes ONLY from the
+      Equipment child node, and the body-type map node Visuals must be a DIRECT child of Equipment —
+      a sibling of Slot, VisualSet and ParentRace — never nested inside VisualSet. With Visuals
+      nested under VisualSet the engine finds no worn body map: the armor is invisible when equipped
+      on every body type, and examining it falls back to the loot VisualTemplate.'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - roottemplate
+      - equipment
+      - visuals
+      - visualset
+      - silent-failure
+      - invisible-armor
+    related:
+      - id: bg3.items.visualbank.equipment-visuals-fourteen-body-type-keys
+        detail: The keys that Visuals node must carry once it is in the right place.
+      - id: bg3.items.visualbank.parentrace-zero-uuid-opts-out
+        detail: ParentRace is the other direct child of Equipment; it is a race-remap opt-out, not a mesh
+          map.
+    detail: 'The correct shape under Equipment > children is: ParentRace (4 Object children, MapKey guid
+      -> MapValue guid, zero uuid = opt-out); Slot (attribute Object FixedString "Body"); VisualSet
+      (attributes BodySetVisual FixedString "", ShowEquipmentVisuals bool False; children
+      MaterialOverrides and RealMaterialOverrides); and Visuals, whose children are Object nodes
+      with a MapKey guid attribute (the body-type uuid) and a MapValue child whose Object
+      FixedString attribute is the VisualBank Resource ID. VisualSet is an easy trap because the
+      name sounds like where visuals go — it only carries the material-override banks. Validator
+      bg3.items.equipment-visuals-structure blocks the nested shape.'
+  - id: bg3.items.visualbank.equipment-visuals-fourteen-body-type-keys
+    claim: "There is no automatic body-type fallback in Equipment/Visuals: each race+gender body type
+      looks up its OWN MapKey, so any body type left unmapped renders the armor invisible on that
+      body. The vanilla robe maps exactly 14 keys, all with real VisualBank IDs, strictly
+      alternating male/female — MALE: 7d73f501-f65e-46af-a13b-2cacf3985d05 (HUM_M),
+      e39505f7-f576-4e70-a99e-8e29cd381a11, f07faafa-0c6f-4f79-a049-70e96b23d51b,
+      abf674d2-2ea4-4a74-ade0-125429f69f83, a933e2a8-aee1-4ecb-80d2-8f47b706f024,
+      5640e766-aa53-428d-815b-6a0b4ef95aca, 9a8bbeba-850c-402f-bac5-ff15696e6497; FEMALE:
+      71180b76-5752-4a97-b71f-911a69197f58 (HUM_F), 47c0315c-7dc6-4862-b39b-8bf3a10f8b54,
+      06aaae02-bb9e-4fa3-ac00-b08e13a5b0fa, b4a34ce7-41be-44d9-8486-938fe1472149,
+      8f00cf38-4588-433a-8175-8acdbbf33f33, c491d027-4332-4fda-948f-4a3df6772baa,
+      6d38f246-15cb-48b5-9b85-378016a7a78e."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - roottemplate
+      - equipment
+      - visuals
+      - body-type
+      - race
+      - gender
+      - invisible-armor
+    related:
+      - id: bg3.items.visualbank.parentrace-zero-uuid-opts-out
+        detail: ParentRace maps 4 of these same keys (f07faafa, 06aaae02, 9a8bbeba, 6d38f246) to the
+          all-zero UUID — a race-remap opt-out that is SEPARATE from Visuals; those 4 keys still
+          carry real meshes in Visuals.
+    detail: A mod that only maps HUM_M/HUM_F (the two keys most tutorials show) ships armor that is
+      invisible on the other 12 bodies. Validator bg3.items.equipment-visuals-structure warns on any
+      of the 14 keys missing from a Visuals map and on a MapValue with an empty Object.
+  - id: bg3.items.visualbank.worn-body-resource-needs-character-material-domain
+    claim: "A VisualBank Resource with Slot=\"Body\" (a body-skinned worn mesh) must be MaterialType 0
+      and its Objects/MaterialID material must instance a CHARACTER-domain base material
+      (Materials.pak Public/Shared/Assets/Materials/Characters/CHAR_BASE.lsf,
+      CHAR_BASE_AlphaTest.lsf or CHAR_BASE_VertCut.lsf — all declare the same Texture2D params
+      basecolor/normalmap/physicalmap). MaterialType 4 is a weapon/rigid value: a Body resource at
+      MaterialType 4 whose material's SourceFile is the generic scenery base
+      Public/Shared/Assets/Materials/Base/Base_AlphaTest.lsf gets no skinned shader permutation and
+      the mesh is invisible when worn."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - visualbank
+      - materialbank
+      - materialtype
+      - char-base
+      - base-alphatest
+      - worn-mesh
+      - invisible-armor
+    related:
+      - id: bg3.items.visualbank.material-shader-selection-by-filename
+        detail: That fact picks a shader by CHAR_BASE filename suffix; this one adds the prerequisite that
+          the base must be in the Characters/ domain at all for a worn mesh.
+    detail: Base_AlphaTest + MaterialType 4 remains correct for a rigid WEAPON (Slot="Unassigned"),
+      which is exactly why a weapon recipe copied onto an armor piece fails silently. The vanilla
+      worn robe uses MaterialType 13 + CHAR_BASE_VertCut_VT, a VirtualTexture base that lslib/divine
+      cannot bake — clone the shader FAMILY (non-VT CHAR_BASE) rather than the exact vanilla
+      material. Validator bg3.items.worn-visual-material-domain blocks a Body resource at
+      MaterialType 4 or on a Materials/Base/ material.
+  - id: bg3.items.visualbank.gr2-mesh-name-must-match-objectid
+    claim: A worn VisualBank Resource's Objects/ObjectID is "<GR2 basename>.<meshname>.<n>" and its
+      Template is "<GR2 basename>.<model root>.0"; the mesh name inside the GR2 must match the
+      ObjectID's middle segment exactly. The pipeline exports mesh "model" under root "Dummy_Root";
+      a stray Blender "model.001" datablock exported in its place silently breaks the link and the
+      mesh is invisible.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - visualbank
+      - gr2
+      - objectid
+      - mesh-name
+      - blender
+      - silent-failure
+    related:
+      - id: bg3.items.visualbank.objectid-mesh-order-vs-lod
+        detail: The trailing ".<n>" is the export-order suffix that fact describes; the middle segment is
+          the mesh name.
+    detail: Check with divine -g bg3 -a convert-model gr2->dae and read the mesh/geometry ids, or in
+      Blender confirm the object and mesh datablock are both named "model" before export. No
+      ModWright validator reads GR2 binaries, so this stays a checklist item.
+  - id: bg3.items.visualbank.worn-gr2-orientation-numeric-check
+    claim: "A Blender-exported worn GR2 whose vertices are rotated 90 degrees about X out of its own
+      skeleton frame renders in-game as a collapsed pile at the character's feet. Cause: exporting
+      after bpy.ops.object.parent_set(type='ARMATURE_NAME') leaves a non-identity
+      matrix_parent_inverse; fix: set an identity parent-inverse and identity local transform before
+      the COLLADA export. Offline numeric check: divine -g bg3 -a convert-model gr2->dae, then the
+      mesh POSITION bounding box must be tall on Y within the skeleton's height (e.g. y=[0.26,1.63]
+      with Root_M at y~1.045), as vanilla HUM_F_ARM_Robe_A_Body reads; a mesh spanning
+      z=[-1.63,-0.26] is the broken one."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - gr2
+      - blender
+      - orientation
+      - parent-inverse
+      - collada
+      - divine
+      - worn-mesh
+    detail: "This needs no engine: the dae is plain XML, so the POSITION source's min/max per axis is
+      readable with any script. Deliberately not a ModWright validator (it needs divine on the path
+      and a GR2 conversion per mesh); it belongs in the mesh-export checklist next to the mesh-name
+      check."
+  - id: bg3.items.visualbank.worn-open-garment-needs-two-sided-base
+    claim: A single-layer collar or lapel wound away from the body shows only its outer face, because
+      the engine culls backfaces on CHAR_BASE. Materials.pak ships
+      Public/Shared/Assets/Materials/Characters/CHAR_BASE_AlphaTest_2S.lsf — non-VT, two-sided, with
+      the same basecolor/normalmap/physicalmap Texture2D parameters as CHAR_BASE — and an open
+      garment should instance that base instead, keeping the basecolor alpha opaque.
+    status: unverified
+    source: ModWright research
+    tags:
+      - items
+      - visualbank
+      - materialbank
+      - char-base
+      - two-sided
+      - backface-culling
+      - worn-mesh
+    related:
+      - id: bg3.items.visualbank.worn-body-resource-needs-character-material-domain
+        detail: CHAR_BASE_AlphaTest_2S is in the Characters/ material domain that fact requires, so it stays
+          valid for a worn mesh.
+      - id: bg3.items.visualbank.material-shader-selection-by-filename
+    detail: Same parameter set means the existing MaterialBank Texture2DParameters carry over unchanged;
+      only SourceFile changes. Because it is non-VT it survives the lslib/divine bake, unlike
+      CHAR_BASE_VertCut_VT.
+  - id: bg3.items.visualbank.atlas-gutter-bleed
+    claim: "An AI-sculpt texture atlas with thousands of tiny UV islands and ~47% pixel coverage shows
+      hard-edged colour patches along triangle edges in-game, because the mipmaps average each
+      island's colour with the black gutters around it. Fix: rasterise the UV layout and dilate
+      island colour ~32 px into the gutters before making the DDS."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - textures
+      - atlas
+      - uv
+      - mipmaps
+      - gutter
+      - dds
+      - physicalmap
+    related:
+      - bg3.items.visualbank.msk-compression-matches-basecolor-map
+    detail: "A second symptom from the same atlas: a per-island metal/roughness map produces
+      per-triangle specular (each island averages to a different value). Cloth should ship a
+      near-constant physical map rather than one derived per island."
+  - id: bg3.items.visualbank.vertexcolormaskslots-underwear-fix
+    claim: "Copying the vanilla robe's seven VertexColorMaskSlots (Torso, upperarm, decolletage_02,
+      lowerarm, Shoulders, Underwear_Bra, Nipple Covers) plus SupportsVertexColorMask=True onto a
+      custom worn body VisualBank Resource stopped the underwear showing through the robe. The
+      robe's own material stayed CHAR_BASE: the mask is declared by the hiding item, and the
+      VertCut/dither shaders belong to the mesh being hidden."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - items
+      - visualbank
+      - vertexcolormask
+      - underwear
+      - clipping
+      - worn-mesh
+    related:
+      - id: bg3.items.visualbank.vertexcolormaskslots-hides-body-part
+        detail: The community "feet" example generalised to a worn body — the same node hides the body and
+          underwear regions a robe covers.
+      - id: bg3.items.visualbank.material-shader-selection-by-filename
+        detail: That fact's Dither/VertCut wording applies to the HIDDEN mesh's material (vanilla underwear
+          and body), not to the garment doing the hiding.
+    detail: "Side effect to plan for: the same mask hides the arms whenever the robe is drawn, which is
+      what made a kit with two Breast-slot armors lose the arms in character creation
+      (bg3.equipment.cc-kit-one-body-item)."