modwright 0.1.0

package/knowledge/baldursgate3/ui.icons-atlas.yaml

@@ -0,0 +1,78 @@
+game: baldursgate3
+topic: ui.icons-atlas
+title: Icon atlas normalized-coordinate rule (BG3's inkatlas equivalent)
+facts:
+  - id: bg3.ui.icons-atlas.uv-coordinates-are-normalized-fractions-not-pixels
+    claim: "The community icon tutorial confirms bg3.icons.iconuv-region-nesting-gotcha's \"U1/U2/V1/V2
+      normalized cell bounds\" and supplies the arithmetic: the values are fractions of the whole
+      atlas, not pixels, so a 64x64 icon on a 2048x2048 atlas spans 64/2048 = 0.03125 per axis — the
+      first cell is U1/V1 0.0 with U2/V2 0.03125."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Icons/Icon-Creation ("These values are determined by the
+      size of your icon and your atlas size as a whole"; worked value 64/2048 = 0.03125)
+    tags:
+      - icons
+      - atlas
+      - uv-coordinates
+      - normalized
+      - inkatlas-equivalent
+    detail: Same normalized-coordinate convention as Cyberpunk 2077's .inkatlas, applied to BG3's
+      TextureAtlasInfo/IconUVList pair. Kept over the existing verified fact only for the
+      arithmetic; the region-nesting rule (IconUV in its own IconUVList region, NOT inside
+      TextureAtlasInfo) stays with bg3.icons.iconuv-region-nesting-gotcha.
+  - id: bg3.ui.icons-atlas.icon-size-scales-atlas-math
+    claim: TextureAtlasIconSize (icon width/height) and TextureAtlasTextureSize (the whole atlas's
+      width/height) together determine every IconUV cell's U1/V1/U2/V2 math; the tutorial's worked
+      example fixes both at 64 and 2048 respectively specifically so its example U/V values can be
+      copied without recalculating — changing either size requires recomputing every icon's UV
+      bounds.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Icons/Icon-Creation ("If you followed 64x64 and 2048x2048
+      you shouldn't have a problem copying the U1,U2,V1, and V2 that I use here")
+    tags:
+      - icons
+      - atlas
+      - texturesize
+      - iconsize
+  - id: bg3.ui.icons-atlas.atlas-path-must-match-textureatlaspath
+    claim: The icon atlas file is named Icons_<ModName>.dds with a LOWERCASE .dds extension and lives at
+      Assets/Textures/Icons/Icons_<ModName>.dds, which must be exactly the TextureAtlasPath value in
+      the atlas map .lsx that describes it. This confirms bg3.icons.spell-atlas-three-file-system's
+      atlas path.
+    status: community
+    source: 'wiki.bg3.community/en/Tutorials/Icons/Icon-Creation ("The proper name should be
+      Icons_{ModName}.dds"; atlas map "Path": "Assets/Textures/Icons/Icons_MODNAME.dds")'
+    tags:
+      - icons
+      - atlas
+      - path
+      - dds
+      - case-sensitivity
+    detail: 'Corrected from "must not be lowercase .dds", which reversed the source. Casing in BG3 is
+      per file class, not global: the ATLAS is lowercase .dds, while item/character textures and the
+      standalone tooltip and controller icons are uppercase .DDS
+      (bg3.items.visualbank.dds-extension-case-sensitive, bg3.icons.tooltip-asset-system).'
+  - id: bg3.ui.icons-atlas.extra-empty-iconuv-entries-are-harmless
+    claim: An icon atlas map can carry more IconUV entries than icons actually placed on the atlas
+      without causing errors — the tutorial leaves a second, unused IconUV entry in place "for
+      future use" alongside the one real icon with no ill effect.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Icons/Icon-Creation ("I can leave that alone for now without
+      any issues. I'd rather it be there for future use then now.")
+    tags:
+      - icons
+      - atlas
+      - iconuv
+  - id: bg3.ui.icons-atlas.hotbar-icon-size-scales-with-atlas-size
+    claim: An icon's rendered hotbar size scales with the atlas size it's placed on, not just with the
+      icon's own pixel dimensions inside that atlas — the tutorial notes this explicitly when
+      recommending sticking to a 64px icon on a 2048px atlas rather than deviating from the
+      reference proportions.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Icons/Icon-Creation ("Your hotbar icon size scales with your
+      atlas size")
+    tags:
+      - icons
+      - atlas
+      - hotbar
+      - scaling

package/knowledge/baldursgate3/ui.icons.yaml

@@ -0,0 +1,412 @@
+game: baldursgate3
+topic: ui.icons
+title: Icon systems — class icons, spell atlas, tooltip images, and metadata
+facts:
+  - id: bg3.icons.class-icon-pair
+    claim: 'Class/subclass icons are a 300×300 "main" DDS (top-right/summary icon) plus a 140×140
+      "hotbar" DDS (the class-SELECTION list icon and the round badge). Filename = the
+      ClassDescription Name (the engine auto-links subclasses by name). Copied to FOUR paths:
+      GUI/Assets/ClassIcons/<Name>.DDS, GUI/AssetsLowRes/ClassIcons/<Name>.DDS, and both again under
+      a hotbar/ subfolder (the hotbar dir holds the 140).'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - class
+      - dds
+      - resolution
+    detail: "A class mod's first attempts got this wrong twice: a _Hotbar filename suffix, and a
+      ClassIcons/LowRes/ subfolder instead of the sibling AssetsLowRes/ tree — both produced blank
+      icons in-game."
+  - id: bg3.icons.class-icon-metadata
+    claim: Hand-authored GUI textures need a GUI/metadata.lsf (per-file width/height/mipcount); the
+      Toolkit normally auto-writes it via its "Convert UI Assets" step, which an SE-compatible
+      hand-authored pipeline cannot use. Without it the game shows "Missing MetaData" and the icons
+      are blank.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - metadata
+      - lsf
+      - class
+    detail: Hand-build it by extracting vanilla's Public/Game/GUI/metadata.lsf from Game.pak, converting
+      to lsx, copying a Bard class-icon entry, editing, and converting lsx→lsf.
+  - id: bg3.icons.spell-atlas-three-file-system
+    claim: 'Spell/action icons are a texture ATLAS needing THREE files: (1) the DDS atlas
+      (Assets/Textures/Icons/<Atlas>.dds, DXT5, no mipmaps, sRGB, a grid of NxN cells); (2) the
+      descriptor GUI/<Atlas>.lsx (stays lsx) with TWO SEPARATE sibling regions — TextureAtlasInfo
+      (icon size / path+UUID / texture size) and IconUVList; (3) texture registration in
+      Content/UI/[PAK]_UI/_merged.lsf — a TextureBank Resource with the SAME UUID as the atlas path,
+      Template "Icons_Items", SRGB True. Reference it from a stat as data "Icon" "<MapKey>".'
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - atlas
+      - spell
+      - action
+    detail: "[PAK]_UI is a LITERAL bracketed folder name. Status/buff icons resolve from this same item
+      atlas — no separate status-template registration is needed; that was flagged as an UNVERIFIED
+      caveat when the first status icon was added and then confirmed in the v1.1.22.0 batch (a
+      custom status renders as a portrait buff)."
+  - id: bg3.icons.iconuv-region-nesting-gotcha
+    claim: IconUV goes in its OWN IconUVList region, NOT nested inside TextureAtlasInfo. Nesting it
+      yields the generic blue missing-icon fallback. A docs summary got this wrong; vanilla
+      Icons_Skills.lsx confirms two regions.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - atlas
+      - iconuv
+      - region
+      - nesting
+    detail: Each IconUV carries MapKey + U1/U2/V1/V2 normalized cell bounds. IconUVList is a sibling
+      region of TextureAtlasInfo, not a child.
+  - id: bg3.icons.atlas-expansion-pattern
+    claim: "To add an icon to an existing atlas: grow the DDS grid, add an IconUV, and point the stat's
+      Icon at the MapKey. Compose onto the existing atlas by decoding the DDS in PIL,
+      paste(cell,(x,y),cell), re-encode DXT5 with no mipmaps."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - atlas
+      - dds
+      - pil
+      - composition
+    detail: "Re-encode flags used: -define dds:compression=dxt5 -define dds:mipmaps=0. Adding a cell
+      needs no change to the atlas UUID or the _merged.lsf TextureBank registration."
+  - id: bg3.icons.item-tooltip-not-atlas
+    claim: The big item image in a tooltip does NOT come from the icon atlas. The atlas serves
+      inventory/hotbar cells only; an atlas-only mod icon shows in the grid but the tooltip image
+      area is BLANK. Vanilla keys look fine because vanilla ships separate tooltip textures for
+      them.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - tooltip
+      - atlas
+      - image
+    detail: "Symptom to search for: icon correct in the inventory grid, empty box in the tooltip."
+  - id: bg3.icons.tooltip-asset-system
+    claim: "Per icon KEY, ship standalone DDS files under Mods/<Mod>/GUI/:
+      Assets/Tooltips/ItemIcons/<IconKey>.DDS (380×380, the tooltip image),
+      Assets/ControllerUIIcons/items_png/<IconKey>.DDS (144×144), plus AssetsLowRes/ copies of both
+      (192 / 72), all DXT5 no-mips. Register the two Assets/ files in GUI/metadata.lsf — and the
+      MapKey uses a .png extension even though the shipped file is .DDS. AssetsLowRes files need no
+      metadata entries."
+    status: community
+    source: ModWright research
+    tags:
+      - icons
+      - tooltip
+      - dds
+      - metadata
+      - assets
+    detail: The tooltip/controller files resolve purely by GUI-path + filename = icon key; the
+      Public/<ns>/Content/UI/[PAK]_UI/_merged.lsf TextureBank registration (Template Icons_Items) is
+      only needed for the ATLAS. The same metadata.lsf carries the ClassIcons entries.
+  - id: bg3.icons.atlas-lsf-twin-blanks-passive-icons
+    claim: "Believed and later disproved: that a stray binary .lsf twin of the icon atlas .lsx in the
+      project blanked the equipment-passive icons, so deleting it was the fix."
+    status: contradicted
+    source: ModWright research
+    tags:
+      - icons
+      - passives
+      - atlas
+      - confounded
+    detail: Kept so the mistake is not remade. The real pattern was NEW GAME = the starting-kit passive
+      icons blank, save+reload = icons show, in every build — the .lsf twin was irrelevant to it.
+      Removing the twin (and the passive-only atlas keys) is still kept as project hygiene, because
+      vanilla ships atlases as .lsx only, but it was not the fix. Superseded by
+      bg3.icons.starting-kit-passive-icons.
+  - id: bg3.icons.starting-kit-passive-icons
+    claim: Starting-kit passives (granted via PassivesOnEquip on Equipment.txt CC-kit items) have icons
+      the Notable Features list only resolves on an equipment-change EVENT. On a fresh game no such
+      event fires, so the rows are blank until any gear change or a save+reload (which re-equips
+      through the normal path).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    supersedes: bg3.icons.atlas-lsf-twin-blanks-passive-icons
+    source: ModWright field verification
+    tags:
+      - icons
+      - passives
+      - equipment
+      - cc-kit
+      - script-extender
+    detail: "Vanilla never ships a Highlighted passive on a kit item, so there is no precedent. Fix
+      used: a Script Extender Lua refresh script — 2.5 s after LevelGameplayStarted, once per
+      character (PersistentVars ledger), Osi.Unequip + Osi.Equip one equipped wearable
+      (GetEquippedItem query first, entity inventory walk as fallback)."
+  - id: bg3.icons.dds-format-and-alpha
+    claim: DXT5 DDS works fine via ImageMagick or PIL (img.save(p, pixel_format="DXT5")). Main icon =
+      opaque on black; hotbar icon = transparency via HSB-brightness-as-alpha (( +clone -colorspace
+      HSB -channel B -separate +channel ) -compose CopyOpacity -composite), which beats grayscale
+      luminance for saturated colours. For transparency from a solid-black background, floodfill
+      from the four corners (-fuzz 16% -fill none -draw "alpha 0,0 floodfill" ×4) — it knocks out
+      only the border-connected background and KEEPS interior dark areas, unlike -transparent black.
+      Then -trim +repage, pad square via -extent, resize.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - dds
+      - dxt5
+      - alpha
+      - transparency
+    detail: 'HSB-brightness-as-alpha comes out DIM for bright-on-black art — floodfill is better there
+      (a class mod used -fuzz 18% for a bright-on-black source). Small-icon design: a buff badge
+      renders ~32-40px; a centered round object ringed by a symmetric radial burst reads as an EYE
+      (iris+lashes) at that size, so use a bold, diagonal/asymmetric subject and put "eye, iris,
+      radial, symmetrical" in a negative prompt. PIL needs Windows paths (C:/...), not msys /c/...;
+      ImageMagick 7 is fine either way.'
+  - id: bg3.icons.imagemagick-diagnostics
+    claim: "ImageMagick diagnostic for icon work: -alpha extract -format \"%[fx:mean*100]%%\" measures a
+      region's opacity."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - diagnostics
+      - imagemagick
+      - tools
+    detail: Useful for checking that a floodfill or alpha-from-brightness pass actually produced
+      transparency where you expect it, before spending a relaunch cycle on a blank-icon report.
+  - id: bg3.icons.public-game-gui-path-for-tooltip-and-controller-icons
+    claim: A separate community tutorial (a different mod, a class/passive icon rather than an item)
+      places tooltip and controller icon DDS files under Public\Game\GUI\Assets\Tooltips\Icons and
+      Public\Game\GUI\Assets\ControllerUIIcons\skills_png — under the mod's Public\Game\GUI tree,
+      not Mods\<Mod>\GUI — with the controller-icon subfolder named for the icon's category
+      ("skills_png" for a passive/skill icon) rather than always "items_png".
+    status: community
+    source: 'bg3-community/Tutorials/Icons/Icon-Creation.md §Mod folder setup (folder tree listing
+      "Game: GUI: Assets: Tooltips: Icons / ItemIcons", "ControllerUIIcons: skills_png /
+      items_png"), §Tooltip Icons, §Controller Icons'
+    tags:
+      - icons
+      - tooltip
+      - controller
+      - public-game-gui
+      - path
+    related:
+      - id: bg3.icons.tooltip-asset-system
+        detail: Records a second, differently-rooted path convention (Public\Game\GUI rather than
+          Mods\<Mod>\GUI) from an independent mod's tutorial; the existing fact's Mods\<Mod>\GUI
+          convention was itself only "verified against two installed item mods" — this is not a
+          contradiction so much as a second attested pattern, and both should be checked when
+          tooltip icons are blank.
+  - id: bg3.icons.blank-icon-shows-at-both-tooltip-and-cc-selection-until-fixed
+    claim: A passive/spell icon missing from tooltip/controller/hotbar locations (while still correct in
+      the inventory grid or wherever the atlas alone renders it) shows the SAME generic
+      error-fallback icon both in the tooltip and in the Character Creation selection list for that
+      passive — seeing the fallback icon in one location is a reliable signal to check the other.
+    status: community
+    source: bg3-community/Tutorials/Icons/Icon-Creation.md:189-212, §Tooltip Icons ("That is a default
+      icon the game puts if you have an error with your current one and it can't be read.")
+    tags:
+      - icons
+      - tooltip
+      - fallback-icon
+      - cc
+      - silent-failure
+    related:
+      - id: bg3.icons.item-tooltip-not-atlas
+        detail: Confirms from an independent source that the atlas and the tooltip/CC image are separately
+          resolved — a correct atlas entry does not guarantee a correct tooltip or CC-selection
+          image, and a blank/ fallback tooltip icon is the visible symptom of the missing standalone
+          file.
+  - id: bg3.icons.texturebank-resource-fields-in-merged-lsx
+    claim: "The worked Content/UI/[PAK]_UI/_merged.lsx TextureBank Resource node registering an icon
+      atlas carries: ID (FixedString, the same UUID used as the atlas map's Path attribute UUID),
+      Localized (bool, False), Name (LSString, set to the mod's name), SRGB (True), SourceFile
+      (LSString, the atlas .dds path rooted at \"Public/...\"), Streaming (True), Template
+      (FixedString \"Icons_Items\"), Type (int32 0) and _OriginalFileVersion_. The page's
+      walkthrough says only ID, Name and SourceFile need changing."
+    status: community
+    source: bg3-community/Tutorials/Icons/Icon-Creation.md:344-380, §_merged.lsx (worked TextureBank
+      Resource node and its field-by-field walkthrough)
+    tags:
+      - icons
+      - atlas
+      - texturebank
+      - merged-lsx
+      - required-fields
+    related:
+      - id: bg3.icons.spell-atlas-three-file-system
+        detail: Confirms and itemizes the exact TextureBank Resource attributes the existing fact's third
+          file (texture registration in Content/UI/[PAK]_UI/_merged.lsf) requires, including that
+          SourceFile is rooted at "Public/" while the atlas map's own Path attribute is rooted at
+          "Assets/" — a distinction worth checking directly if an atlas fails to resolve.
+  - id: bg3.icons.class-icon-vanilla-format-and-four-sizes
+    claim: "The vanilla class/subclass icon files are BC7 (DX10 header, DXGI format 98), one mip, at
+      four sizes that match the four paths of bg3.icons.class-icon-pair: Assets/ClassIcons 300x300,
+      Assets/ClassIcons/hotbar 140x140, AssetsLowRes/ClassIcons 152x152,
+      AssetsLowRes/ClassIcons/hotbar 72x72. The glyph occupies about 64% of the main canvas
+      (OpenHand: alpha bbox 53..245 of 300) over a transparent background with a soft drop shadow;
+      the art is full colour, not a tintable white glyph. The file's byte size is the same whether
+      it is BC7 or DXT5 (1 byte per pixel), so a DXT5 no-mip file written by ImageMagick is a
+      like-for-like replacement in size; whether the engine accepts DXT5 in this slot is recorded
+      separately below."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: Game.pak Public/Game/GUI/Assets/ClassIcons/OpenHand.DDS + hotbar + AssetsLowRes copies
+      (2026-09-19)
+    tags:
+      - icons
+      - class
+      - dds
+      - bc7
+      - dxt5
+      - sizes
+    detail: "Vanilla names: Monk.DDS, OpenHand.DDS, Shadow.DDS, FourElements.DDS — the subclass
+      Progression/ClassDescription Name, not the display name. A subclass mod ships its icon four
+      times under its own ClassDescription Name."
+  - id: bg3.icons.class-icon-needs-public-game-source-in-the-pak
+    claim: "Class icons live under Public/Game/GUI/..., outside the mod's own Public/<Mod>/ tree, so a
+      ModWright project whose \"public\" source is Public/<Mod> silently leaves them out of the pak:
+      the build succeeds and verify-listing passes while divine list-package shows no ClassIcons
+      entry. A second source ({\"id\": \"game-ui\", \"path\": \"Public/Game\", \"kind\":
+      \"public\"}) added to the stage step's sources puts them in at the same relative path."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - class
+      - modwright
+      - sources
+      - packaging
+  - id: bg3.icons.single-row-atlas-widening-recomputes-every-uv
+    claim: "A mod icon atlas can stay a single row of 144-px cells and simply grow wider: the DDS
+      becomes COLS*144 x 144, TextureAtlasTextureSize Width is updated to match, and EVERY IconUV's
+      U1/U2 is recomputed as idx/COLS and (idx+1)/COLS (V1 0, V2 1). The atlas UUID, the TextureBank
+      registration and the per-key tooltip/controller files do not change. A second ROW is not an
+      option: the character sheet read a two-row atlas's row 1 cells back as row 0."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - atlas
+      - uv
+      - widening
+      - single-row
+    related:
+      - id: bg3.icons.atlas-expansion-pattern
+        detail: The same operation, stated for the single-row layout and with the "every UV" recompute
+          spelled out.
+  - id: bg3.icons.status-without-icon-field-shows-a-blank-condition
+    claim: A StatusData entry with no Icon line shows a blank badge in the conditions strip and the
+      status tooltip while it is active. Statuses take the same Icon values as passives and spells
+      (an atlas MapKey of the mod's own atlas, or a vanilla icon name such as Status_Burning or
+      PassiveFeature_PatientDefence).
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - status
+      - conditions
+      - blank
+  - id: bg3.icons.icon-names-cross-stat-types
+    claim: "The Icon field is one global namespace: a passive can name a vanilla spell or action icon
+      (PassiveFeature_MartialArts_BonusUnarmedStrike, Action_Whirlwind), a spell can name a passive
+      icon, and a status can name either, so a feature can borrow any vanilla icon by name without
+      shipping a file. Whether an ITEM icon key (Item_QUEST_GLO_SoulCoin, from the vanilla item
+      atlas) also resolves on a passive is built for Soulfire but not yet seen in-game."
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - namespace
+      - vanilla-names
+      - passives
+      - spells
+      - statuses
+  - id: bg3.icons.notable-features-row-uses-the-granting-items-icon
+    claim: In the character sheet's Notable Features list, a passive granted by equipment
+      (PassivesOnEquip) is listed with the GRANTING ITEM's icon, not the passive's own Icon; the
+      passive's icon appears only in its tooltip card. This is vanilla behaviour, so making the item
+      icon legible at list size is the only fix.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - character-sheet
+      - notable-features
+      - equipment-passives
+    related:
+      - id: bg3.icons.starting-kit-passive-icons
+        detail: That fact is about WHEN the row resolves; this one is about WHICH icon it resolves to.
+  - id: bg3.icons.passive-tooltip-files-under-mods-gui-skills-folders
+    claim: For a passive or action icon (as opposed to an item icon) the per-key files go to
+      Mods/<Mod>/GUI/Assets/Tooltips/Icons/<Key>.DDS (380) and
+      Mods/<Mod>/GUI/Assets/ControllerUIIcons/skills_png/<Key>.DDS (144), with AssetsLowRes copies
+      (192 / 72) and two metadata.lsx Object entries whose MapKeys end in .png � the Mods/<Mod>/GUI
+      root works for skills, the same as bg3.icons.tooltip-asset-system records for items, so the
+      Public/Game/GUI root of the community tutorial is not required.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - passives
+      - tooltip
+      - controller
+      - skills_png
+      - metadata
+    related:
+      - id: bg3.icons.public-game-gui-path-for-tooltip-and-controller-icons
+        detail: Both roots are attested; this is the Mods/<Mod>/GUI one seen working for a skill icon.
+  - id: bg3.icons.keyed-neon-art-needs-the-same-brightness-ramp-as-recoloured-vanilla-icons
+    claim: Mixing two icon sources in one set � AI-made neon line art on black that is only alpha-keyed,
+      and vanilla icons recoloured through a luminance-to-red ramp � makes the keyed art read
+      markedly darker in the Actions panel, because keying keeps the art's own dim glow while the
+      ramp maps mid-tones to a bright core. Pushing every source through the same ramp (dark
+      110/0/0, mid 240/40/30, core 255/150/140 over luminance^0.6..0.75, plus a blurred copy
+      underneath as glow) gives a matched set.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: ModWright field verification
+    tags:
+      - icons
+      - art
+      - recolour
+      - ramp
+      - consistency
+    detail: "Keying recipe used for black-background art: alpha = clip((max(R,G,B) - 10) * 255 / 50).
+      For emblem art with dark enclosed areas a flood fill from the border keeps the interior; a
+      global key opens it."
+  - id: bg3.icons.vanilla-tooltip-icons-extract-per-file-with-divine
+    claim: A single vanilla icon's full-size art is a 380x380 BC7 DDS at
+      Public/Game/GUI/Assets/Tooltips/Icons/<name>.DDS inside Game.pak and can be pulled alone with
+      divine extract-package -x "*/GUI/Assets/Tooltips/Icons/<name>.DDS" (one call per file); PIL
+      decodes it, which is enough to recolour a vanilla icon into a mod's palette without touching
+      the game's atlases. Not every stat's Icon name has such a file � two of twelve tried
+      (Spell_Abjuration_WardingBond, PassiveFeature_DualWielder_BonusAC) had none.
+    status: verified
+    verified_on: 4.73.98.727 (Patch 8)
+    source: divine list-package Game.pak (Tooltips/Icons entries, 144548 bytes each) and the extractions
+      of 2026-09-19
+    tags:
+      - icons
+      - vanilla
+      - extract
+      - divine
+      - tooltips
+      - reference

package/knowledge/baldursgate3/ui.mcm.yaml

@@ -0,0 +1,161 @@
+game: baldursgate3
+topic: ui.mcm
+title: Mod Configuration Menu (MCM) blueprint schema and version floors
+facts:
+  - id: bg3.ui.mcm.blueprint-file-placement
+    claim: MCM integration requires an MCM_blueprint.json file placed in the same folder as the mod's
+      meta.lsx; this JSON file defines the mod's settings structure (IDs, names, types, defaults)
+      that MCM uses to generate the UI and validate values.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Quick-start guide
+    tags:
+      - mcm
+      - blueprint
+      - meta-lsx
+      - required-fields
+  - id: bg3.ui.mcm.dependency-recommended-in-meta-lsx
+    claim: "It is \"extremely recommended\" to declare MCM as a dependency in the mod's meta.lsx (rather
+      than only shipping MCM_blueprint.json with \"Optional\": true), so the game/mod managers
+      guarantee MCM loads before the dependent mod and don't require instructing users to order mods
+      manually."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Quick-start guide,
+      §Integrating MCM into your mod
+    tags:
+      - mcm
+      - dependency
+      - meta-lsx
+      - load-order
+  - id: bg3.ui.mcm.dependency-version64-should-pin-dev-version
+    claim: When declaring MCM as a meta.lsx dependency, it is recommended to always set the required
+      version (Version64) to the MCM version actually used during development; MCM 1.14+ verifies
+      dependency versions at load and warns users who have an outdated version of a dependency
+      installed.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Integrating MCM into
+      your mod ("It is also recommended to always set the required version (Version64) of MCM to the
+      version you're using"; "MCM 1.14+ also verifies dependencies' versions and warn users if they
+      have outdated versions")
+    tags:
+      - mcm
+      - dependency
+      - version-floor
+      - version64
+  - id: bg3.ui.mcm.schema-organizational-hierarchy
+    claim: 'The MCM blueprint schema is hierarchical: Tabs are the top-level units, Sections are
+      sub-divisions within tabs, and "Each tab can exclusively contain either Sections or standalone
+      Settings" — never both at the same tab level. Each Setting requires an Id ("A unique string
+      identifier"), a Name ("The readable name") and a Type ("Defines the data type"), which also
+      picks the widget rendered.'
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Schema main components
+    tags:
+      - mcm
+      - blueprint
+      - schema
+      - tabs
+      - sections
+      - settings
+  - id: bg3.ui.mcm.get-settings-value-by-id
+    claim: A mod author replaces its own settings-reading logic with MCM.Get("settingId") calls, using
+      the same Id string defined for that setting in MCM_blueprint.json, to read the current value
+      MCM manages.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Quick-start guide
+    tags:
+      - mcm
+      - api
+      - mcm-get
+  - id: bg3.ui.mcm.use-mcm-api-not-internal-table
+    claim: Mod code should call the global MCM table's documented functions (e.g. MCM.Get) rather than
+      reaching into Mods.BG3MCM's internal implementation table directly, since internals are not a
+      stable API surface.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Use the MCM API, not
+      Mods.BG3MCM internals
+    tags:
+      - mcm
+      - api
+      - stability
+  - id: bg3.ui.mcm.keybinding-support-since-1-19
+    claim: MCM's keybinding management feature (define/update/persist keybindings, register callbacks,
+      built-in conflict resolution) was added in MCM 1.19 — a mod targeting keybinding_v2 settings
+      needs a Version64 dependency floor of at least that version.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Features for mod
+      authors ("NEW IN 1.19 - Keybinding management")
+    tags:
+      - mcm
+      - keybinding
+      - version-floor
+  - id: bg3.ui.mcm.store-api-dual-storage-backend-since-1-40
+    claim: "MCM's Store API for persisting arbitrary key-value data independent of the blueprint gained
+      multiple storage backends starting with MCM 1.40+: Script Extender ModVars (save-scoped) and
+      JSON files (global). JSON storage is the default; a value is only save-scoped instead of
+      global if storage = \"modvar\" is explicitly set, and the \"modvar\" backend is still noted as
+      work-in-progress."
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Store API ("Starting
+      with MCM version 1.40+, it supports multiple storage backends"; "JSON storage is the default";
+      "modvar is still a WIP")
+    tags:
+      - mcm
+      - store-api
+      - version-floor
+      - modvar
+      - json
+  - id: bg3.ui.mcm.store-storageconfig-mirrors-native-modvar-params
+    claim: Both MCM Store backends accept a storageConfig table using the exact same parameter names as
+      BG3SE's native ModVars (Client, Server, SyncToClient, SyncToServer, Persistent,
+      WriteableOnClient, WriteableOnServer) regardless of which backend (JSON or modvar) is actually
+      selected.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Store API
+    tags:
+      - mcm
+      - store-api
+      - storageconfig
+      - modvar
+  - id: bg3.ui.mcm.ui-agnostic-works-without-imgui
+    claim: MCM is designed to function as a standalone configuration manager independent of its
+      IMGUI-based interface; a player who cannot see the IMGUI window (or if IMGUI support were
+      removed) still has a working MCM config manager underneath.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Features for mod authors
+    tags:
+      - mcm
+      - ui-agnostic
+      - imgui
+  - id: bg3.ui.mcm.blueprint-schema-source-for-validation
+    claim: MCM_blueprint.json files can be written and validated against the published JSON schema at
+      raw.githubusercontent.com/AtilioA/BG3-MCM/main/.vscode/schema.json, which is kept up to date
+      with each MCM release; setting the schema up in an editor (via a "json.schemas" entry matching
+      "MCM_blueprint*.json") catches structural mistakes before runtime.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §The MCM Schema > IDE
+      support
+    tags:
+      - mcm
+      - blueprint
+      - schema
+      - validation
+  - id: bg3.ui.mcm.settings-update-instantly-without-save-reload
+    claim: MCM-integrated settings update in real time as the player changes them in the UI, without
+      requiring a save reload — unlike a traditional settings file a mod might read only once at
+      load.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Features for mod authors
+    tags:
+      - mcm
+      - settings
+      - real-time
+  - id: bg3.ui.mcm.semantic-versioning-major-means-breaking-blueprint-change
+    claim: MCM follows semantic versioning, and "MAJOR updates would probably mean introducing breaking
+      changes to blueprints" — so a MAJOR bump is the release to re-check a blueprint against, while
+      MINOR/PATCH releases are not expected to require blueprint changes.
+    status: community
+    source: wiki.bg3.community/en/Tutorials/Mod-Frameworks/mod-configuration-menu §Concepts
+    tags:
+      - mcm
+      - versioning
+      - blueprint