modwright 0.1.0

package/dist/surfaces/baldursgate3/validators/items.js

@@ -0,0 +1,1001 @@
+import * as path from "node:path";
+import { walk } from "../../../core/fsutil.js";
+import { parseLsx, walkLsxNodes } from "../index/parsers/lsx.js";
+import { parseStats } from "../index/parsers/stats.js";
+export const GAME = "baldursgate3";
+export async function collectProjectFiles(project, pattern) {
+    const out = [];
+    for (const source of project.sources) {
+        if (!source.exists)
+            continue;
+        const walked = await walk(source.absPath, { limit: 50_000 });
+        for (const rel of walked.files) {
+            if (pattern.test(rel))
+                out.push({ abs: path.join(source.absPath, rel), rel, sourceId: source.id });
+        }
+    }
+    return out;
+}
+async function parseLsxFile(ctx, file) {
+    try {
+        return parseLsx(await ctx.readText(file.abs), file.rel);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function parseStatsFile(ctx, file) {
+    try {
+        return parseStats(await ctx.readText(file.abs), file.rel);
+    }
+    catch {
+        return [];
+    }
+}
+export async function collectProjectLsx(ctx) {
+    const files = await collectProjectFiles(ctx.project, /\.lsx$/i);
+    const byId = new Map();
+    for (const file of files) {
+        const doc = await parseLsxFile(ctx, file);
+        if (!doc)
+            continue;
+        for (const region of doc.regions) {
+            walkLsxNodes(region.root, (node) => {
+                const list = byId.get(node.id);
+                const ref = { node, file: file.rel, region: region.id };
+                if (list)
+                    list.push(ref);
+                else
+                    byId.set(node.id, [ref]);
+            });
+        }
+    }
+    return { byId };
+}
+export function nodesOf(idx, id) {
+    return idx.byId.get(id) ?? [];
+}
+export function attr(node, id) {
+    const v = node.attributes[id]?.value;
+    return v === undefined || v === "" ? undefined : v;
+}
+export function child(node, id) {
+    return node.children.find((c) => c.id === id);
+}
+export function children(node, id) {
+    return node.children.filter((c) => c.id === id);
+}
+export async function collectAllStatEntries(ctx) {
+    const files = await collectProjectFiles(ctx.project, /(^|\/)Stats\/Generated\/Data\/[^/]+\.txt$/i);
+    const byName = new Map();
+    for (const file of files) {
+        for (const entry of await parseStatsFile(ctx, file))
+            byName.set(entry.name, entry);
+    }
+    return byName;
+}
+export const ARMOR_WEAPON_STATS = /(^|\/)Stats\/Generated\/Data\/(Armor|Weapon)\.txt$/i;
+export async function collectArmorWeaponEntries(ctx) {
+    const files = await collectProjectFiles(ctx.project, ARMOR_WEAPON_STATS);
+    const out = [];
+    for (const file of files) {
+        const statKind = /Weapon\.txt$/i.test(file.rel) ? "Weapon" : "Armor";
+        for (const entry of await parseStatsFile(ctx, file))
+            out.push({ ...entry, statKind });
+    }
+    return out;
+}
+export async function collectRootTemplates(idx) {
+    const out = [];
+    for (const ref of nodesOf(idx, "GameObjects")) {
+        const mapKey = attr(ref.node, "MapKey");
+        if (!mapKey)
+            continue;
+        const equipment = child(ref.node, "Equipment");
+        out.push({
+            mapKey,
+            name: attr(ref.node, "Name"),
+            visualTemplate: attr(ref.node, "VisualTemplate"),
+            equipmentVisualSet: equipment ? attr(equipment, "VisualSet") : undefined,
+            parentTemplateId: attr(ref.node, "ParentTemplateId"),
+            race: attr(ref.node, "Race"),
+            icon: attr(ref.node, "Icon"),
+            file: ref.file,
+            node: ref.node,
+        });
+    }
+    return out;
+}
+export function collectBankResources(idx) {
+    const out = [];
+    for (const ref of nodesOf(idx, "Resource")) {
+        if (ref.region !== "VisualBank" && ref.region !== "MaterialBank" && ref.region !== "TextureBank")
+            continue;
+        out.push({ region: ref.region, id: attr(ref.node, "ID"), name: attr(ref.node, "Name"), file: ref.file, node: ref.node });
+    }
+    return out;
+}
+export async function detectPartialTree(ctx) {
+    const missing = ctx.project.sources.filter((s) => !s.exists);
+    if (missing.length > 0) {
+        return (`modwright.json declares source(s) ${missing.map((s) => `"${s.id}" (${s.path})`).join(", ")} ` +
+            `not present on disk here; this checkout is a partial tree, so a name that looks undefined may ` +
+            `only be missing because its source isn't checked out in this environment.`);
+    }
+    const checkedMods = new Set();
+    for (const source of ctx.project.sources) {
+        if (!source.exists)
+            continue;
+        const rel = path.relative(ctx.project.root, source.absPath).split(path.sep);
+        if (rel[0] !== "Public" || !rel[1])
+            continue;
+        const modName = rel[1];
+        if (checkedMods.has(modName))
+            continue;
+        checkedMods.add(modName);
+        const metaPath = path.join(ctx.project.root, "Mods", modName, "meta.lsx");
+        if (!(await ctx.exists(metaPath))) {
+            return (`source "${source.id}" is a Public/${modName} tree with no matching Mods/${modName}/meta.lsx ` +
+                `in this project; the module tree looks partial (missing the Mods/ half of the mod).`);
+        }
+    }
+    return undefined;
+}
+export function skipFinding(validatorId, project, reason, evidence) {
+    return [{ validatorId, severity: "info", file: project.file, message: `Skipped: ${reason}`, evidence }];
+}
+export function isProjectTarget(target) {
+    return target.kind === "project";
+}
+async function resolveStatName(ctx, name, byName) {
+    if (byName.has(name))
+        return true;
+    if (!ctx.store)
+        return false;
+    const res = await ctx.lookup("stat", { name });
+    return res.count > 0;
+}
+async function resolveVanillaBank(ctx, id, expectedRegion) {
+    if (!ctx.store)
+        return false;
+    const res = await ctx.lookup("guid", { uuid: id });
+    return res.rows.some((r) => r.kind === "Resource" && r.region === expectedRegion);
+}
+async function resolveBankId(ctx, id, banks, expectedRegion) {
+    if (banks.some((b) => b.id === id))
+        return true;
+    return resolveVanillaBank(ctx, id, expectedRegion);
+}
+function hasModDependency(project) {
+    return (project.project.dependencies ?? []).some((d) => d.kind === "mod");
+}
+const statsRootTemplateLink = {
+    id: "bg3.items.stats-roottemplate-link",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "Armor.txt/Weapon.txt data \"RootTemplate\" must link two ways to a RootTemplate GameObjects node.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every Armor.txt/Weapon.txt entry",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.visualbank.roottemplate-mapkey-links-stats-entry",
+        "bg3.weapons.summoned-custom-recipe",
+    ],
+    async run(ctx) {
+        const entries = await collectArmorWeaponEntries(ctx);
+        const idx = await collectProjectLsx(ctx);
+        const templates = await collectRootTemplates(idx);
+        const findings = [];
+        const withRootTemplateField = entries.filter((e) => e.fields.RootTemplate);
+        if (withRootTemplateField.length > 0 && templates.length === 0) {
+            return skipFinding(this.id, ctx.project, "no RootTemplates .lsx found in this project (they may ship only as a compiled _merged.lsf, which this rule cannot read without divine)", this.evidence);
+        }
+        const compiledLsf = await collectProjectFiles(ctx.project, /RootTemplates[\\/][^\\/]*\.lsf$/i);
+        const unverifiable = [];
+        for (const entry of withRootTemplateField) {
+            const rootTemplate = entry.fields.RootTemplate;
+            const template = templates.find((t) => t.mapKey === rootTemplate);
+            if (!template) {
+                if (compiledLsf.length > 0) {
+                    unverifiable.push({ name: entry.name, rootTemplate });
+                    continue;
+                }
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: entry.file,
+                    line: entry.line,
+                    message: `${entry.statKind} entry "${entry.name}"'s data "RootTemplate" "${rootTemplate}" does not match ` +
+                        `any RootTemplate GameObjects node's MapKey in this project.`,
+                    fix: `Add a GameObjects node with MapKey="${rootTemplate}" under RootTemplates, or fix the stats entry's RootTemplate value.`,
+                    evidence: this.evidence,
+                });
+                continue;
+            }
+            if (template.name !== entry.name) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: entry.file,
+                    line: entry.line,
+                    message: `RootTemplate "${rootTemplate}" (Name="${template.name ?? ""}") does not equal the stats entry name ` +
+                        `"${entry.name}" that references it via data "RootTemplate" — the two-way link is broken.`,
+                    fix: `Set the RootTemplate GameObjects node's Name to "${entry.name}", or point the stats entry at the correct RootTemplate.`,
+                    related: [template.file],
+                    evidence: this.evidence,
+                });
+            }
+        }
+        if (unverifiable.length > 0) {
+            const shown = unverifiable.slice(0, 10).map((u) => `${u.name} (${u.rootTemplate})`).join(", ");
+            findings.push({
+                validatorId: this.id,
+                severity: "info",
+                file: ctx.project.file,
+                message: `${unverifiable.length} Armor/Weapon entr${unverifiable.length === 1 ? "y" : "ies"} reference a RootTemplate that no project .lsx defines, ` +
+                    `but this project also ships compiled ${compiledLsf.map((f) => f.rel).join(", ")}, which this rule cannot read; ` +
+                    `they may well be defined there. Not verified: ${shown}${unverifiable.length > 10 ? ", ..." : ""}.`,
+                fix: `To verify, convert the compiled file to .lsx (the convert tool's bg3.lsf-to-lsx) and check each MapKey, or keep the project's RootTemplates as .lsx sources.`,
+                related: compiledLsf.map((f) => f.rel),
+                evidence: this.evidence,
+            });
+        }
+        return findings;
+    },
+};
+const roottemplateVisualLink = {
+    id: "bg3.items.roottemplate-visual-link",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "A RootTemplate's VisualTemplate/Equipment visual UUIDs must resolve to a VisualBank Resource.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every RootTemplate GameObjects node",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.visualbank.visualbank-id-links-roottemplate",
+        "bg3.items.visualbank.weapon-loot-model-equals-item-model",
+        "bg3.loadorder.external-guid-dependencies",
+    ],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const templates = await collectRootTemplates(idx);
+        const banks = collectBankResources(idx);
+        const armorWeapon = await collectArmorWeaponEntries(ctx);
+        const findings = [];
+        const visualBanks = banks.filter((b) => b.region === "VisualBank");
+        const dependencyDeclared = hasModDependency(ctx.project);
+        for (const template of templates) {
+            const isWeapon = armorWeapon.some((e) => e.statKind === "Weapon" && e.fields.RootTemplate === template.mapKey);
+            for (const [label, uuid] of [
+                ["VisualTemplate", template.visualTemplate],
+                ["Equipment/VisualSet", template.equipmentVisualSet],
+            ]) {
+                if (!uuid)
+                    continue;
+                if (await resolveBankId(ctx, uuid, visualBanks, "VisualBank"))
+                    continue;
+                const message = dependencyDeclared
+                    ? `RootTemplate "${template.mapKey}" (${template.name ?? "?"})'s ${label} "${uuid}" does not resolve to any ` +
+                        `VisualBank Resource in this project or the vanilla index — it may be defined by a declared mod ` +
+                        `dependency (bg3.loadorder.external-guid-dependencies): verify load order, or fix the UUID if it's a typo.`
+                    : `RootTemplate "${template.mapKey}" (${template.name ?? "?"})'s ${label} "${uuid}" does not resolve to any ` +
+                        `VisualBank Resource in this project or the vanilla index.`;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: template.file,
+                    message,
+                    fix: `Add a VisualBank Resource with ID="${uuid}", declare the owning mod as a "mod" dependency in modwright.json, or fix the UUID.`,
+                    evidence: this.evidence,
+                });
+            }
+            if (isWeapon && template.visualTemplate && template.equipmentVisualSet && template.visualTemplate !== template.equipmentVisualSet) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: template.file,
+                    message: `Weapon RootTemplate "${template.mapKey}" (${template.name ?? "?"})'s VisualTemplate ` +
+                        `("${template.visualTemplate}") and equipped visual ("${template.equipmentVisualSet}") differ — for a ` +
+                        `weapon the loot model and the item model must be the same UUID.`,
+                    fix: `Set Equipment/VisualSet to the same UUID as VisualTemplate ("${template.visualTemplate}").`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const visualMaterialTextureChain = {
+    id: "bg3.items.visual-material-texture-chain",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "VisualBank Objects/MaterialID and MaterialBank Texture2DParameters/ID must chain to a real bank entry, in this project or the vanilla index.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over the merged VisualBank/MaterialBank/TextureBank tree",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.items.visualbank.three-region-chain"],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const banks = collectBankResources(idx);
+        const materialBanks = banks.filter((b) => b.region === "MaterialBank");
+        const textureBanks = banks.filter((b) => b.region === "TextureBank");
+        const findings = [];
+        for (const visual of banks.filter((b) => b.region === "VisualBank")) {
+            for (const objects of children(visual.node, "Objects")) {
+                const materialId = attr(objects, "MaterialID");
+                if (!materialId)
+                    continue;
+                const material = materialBanks.find((m) => m.id === materialId);
+                if (!material) {
+                    if (await resolveVanillaBank(ctx, materialId, "MaterialBank"))
+                        continue;
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: visual.file,
+                        message: `VisualBank Resource "${visual.name ?? visual.id ?? "?"}" (ID=${visual.id ?? "?"})'s Objects/MaterialID ` +
+                            `"${materialId}" does not match any MaterialBank Resource ID in this project or the vanilla index.`,
+                        fix: `Add a MaterialBank Resource with ID="${materialId}", or fix the MaterialID.`,
+                        evidence: this.evidence,
+                    });
+                    continue;
+                }
+                for (const texParam of children(material.node, "Texture2DParameters")) {
+                    const textureId = attr(texParam, "ID");
+                    if (!textureId)
+                        continue;
+                    if (textureBanks.some((t) => t.id === textureId))
+                        continue;
+                    if (await resolveVanillaBank(ctx, textureId, "TextureBank"))
+                        continue;
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: material.file,
+                        message: `MaterialBank Resource "${material.name ?? material.id ?? "?"}" (ID=${material.id ?? "?"})'s ` +
+                            `Texture2DParameters ID "${textureId}" does not match any TextureBank Resource ID in this project or ` +
+                            `the vanilla index.`,
+                        fix: `Add a TextureBank Resource with ID="${textureId}", or fix the Texture2DParameters ID.`,
+                        related: [visual.file],
+                        evidence: this.evidence,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+const ddsExtensionCase = {
+    id: "bg3.items.dds-extension-case",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "TextureBank SourceFile must end in uppercase .DDS (lowercase .dds for an Icons_Items icon atlas) and exist at that exact path.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every TextureBank Resource",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.visualbank.dds-extension-case-sensitive",
+        "bg3.ui.icons-atlas.atlas-path-must-match-textureatlaspath",
+        "bg3.se.config-required",
+    ],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const banks = collectBankResources(idx);
+        const findings = [];
+        for (const texture of banks.filter((b) => b.region === "TextureBank")) {
+            const sourceFile = attr(texture.node, "SourceFile");
+            if (!sourceFile)
+                continue;
+            const isAtlas = attr(texture.node, "Template") === "Icons_Items";
+            const wantExt = isAtlas ? ".dds" : ".DDS";
+            if (!sourceFile.endsWith(wantExt)) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: texture.file,
+                    message: isAtlas
+                        ? `TextureBank Resource "${texture.name ?? texture.id ?? "?"}" is an icon atlas (Template "Icons_Items") ` +
+                            `but its SourceFile "${sourceFile}" does not end in lowercase ".dds" — atlases are the one texture ` +
+                            `class shipped lowercase (bg3.items.visualbank.dds-extension-case-sensitive, detail).`
+                        : `TextureBank Resource "${texture.name ?? texture.id ?? "?"}"'s SourceFile "${sourceFile}" does not end ` +
+                            `in uppercase ".DDS" — capitalisation is checked on the recorded string, since a lowercase ".dds" ` +
+                            `file at the same path will not load in the packed pak.`,
+                    fix: isAtlas
+                        ? `Rename the atlas file, the SourceFile value and GUI/<Atlas>.lsx's TextureAtlasPath to end in ".dds" (lowercase).`
+                        : `Rename the file and the SourceFile value to end in ".DDS" (uppercase).`,
+                    evidence: this.evidence,
+                });
+                continue;
+            }
+            const abs = path.isAbsolute(sourceFile) ? sourceFile : path.join(ctx.project.root, sourceFile);
+            if (!(await ctx.exists(abs))) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: texture.file,
+                    message: `TextureBank Resource "${texture.name ?? texture.id ?? "?"}"'s SourceFile "${sourceFile}" does not exist at that exact path.`,
+                    fix: `Add the texture file at "${sourceFile}" (relative to the project root), or fix the SourceFile value.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const MAP_ROLE_SUFFIXES = { BM: true, NM: false, PM: false, MSK: false };
+const texturebankSrgb = {
+    id: "bg3.items.texturebank-srgb",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "SRGB is True only on the basecolor (_BM) TextureBank entry; normal/physical/mask maps are False.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over TextureBank entries whose filename ends _BM/_NM/_PM/_MSK",
+    needs: { project: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.items.visualbank.texturebank-srgb-basecolor-only"],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const banks = collectBankResources(idx);
+        const findings = [];
+        for (const texture of banks.filter((b) => b.region === "TextureBank")) {
+            const sourceFile = attr(texture.node, "SourceFile");
+            const srgb = attr(texture.node, "SRGB");
+            if (!sourceFile || srgb === undefined)
+                continue;
+            const stem = path.basename(sourceFile).replace(/\.[^.]+$/, "");
+            const suffix = Object.keys(MAP_ROLE_SUFFIXES).find((s) => stem.endsWith(`_${s}`));
+            if (!suffix)
+                continue;
+            const expected = MAP_ROLE_SUFFIXES[suffix];
+            const actual = srgb.toLowerCase() === "true";
+            if (actual !== expected) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: texture.file,
+                    message: `TextureBank Resource "${sourceFile}" is a ${suffix} map but SRGB="${srgb}" ` +
+                        `(expected ${expected ? "True (basecolor)" : "False (no color data)"}).`,
+                    fix: `Set SRGB="${expected ? "True" : "False"}" on this Resource.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const OBJECT_CATEGORY = /object category\s+"([^"]+)"/g;
+const treasuretableIPrefix = {
+    id: "bg3.items.treasuretable-i-prefix",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "Every TreasureTable.txt `object category` line uses the I_ prefix and resolves to a stat entry or a known vanilla treasure category.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every TreasureTable.txt `object category` line",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: ["bg3.items.visualbank.treasuretable-i-prefix"],
+    async run(ctx) {
+        const files = await collectProjectFiles(ctx.project, /TreasureTable\.txt$/i);
+        const byName = await collectAllStatEntries(ctx);
+        const findings = [];
+        for (const file of files) {
+            const text = await ctx.readText(file.abs);
+            for (const m of text.matchAll(OBJECT_CATEGORY)) {
+                const value = m[1];
+                if (!value.startsWith("I_")) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: file.abs,
+                        message: `TreasureTable.txt object category "${value}" is missing the required "I_" item prefix.`,
+                        fix: `Rename the reference to "I_${value}" and the item's stats entry to match.`,
+                        evidence: this.evidence,
+                    });
+                    continue;
+                }
+                const statName = value.slice(2);
+                if (await resolveStatName(ctx, statName, byName))
+                    continue;
+                if (ctx.store) {
+                    const treasureRes = await ctx.lookup("list", { kind: "TreasureCategory", name: value, limit: 1 });
+                    if (treasureRes.count > 0)
+                        continue;
+                }
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: file.abs,
+                    message: `TreasureTable.txt object category "${value}" names item "${statName}", which is not a defined stats ` +
+                        `entry or a known vanilla treasure category in this mod or vanilla.`,
+                    fix: `Define a stats entry named "${statName}", or fix the TreasureTable reference.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const iconMapkeyResolves = {
+    id: "bg3.items.icon-mapkey-resolves",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "An item's Icon (a stats entry's data \"Icon\", or a RootTemplate's Icon attribute) must resolve to an IconUV MapKey in a mod atlas or the vanilla index.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every Armor.txt/Weapon.txt entry's data \"Icon\" and every project RootTemplate's Icon attribute",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: [
+        "bg3.icons.spell-atlas-three-file-system",
+        "bg3.ui.icons-atlas.atlas-path-must-match-textureatlaspath",
+        "bg3.icons.item-tooltip-not-atlas",
+    ],
+    async run(ctx) {
+        const entries = await collectArmorWeaponEntries(ctx);
+        const idx = await collectProjectLsx(ctx);
+        const iconKeys = new Set(nodesOf(idx, "IconUV").map((ref) => attr(ref.node, "MapKey")).filter((v) => !!v));
+        const findings = [];
+        const owners = [
+            ...entries.map((entry) => ({ owner: `${entry.statKind} entry "${entry.name}"`, icon: entry.fields.Icon, file: entry.file, line: entry.line, where: 'data "Icon"' })),
+            ...(await collectRootTemplates(idx)).map((t) => ({ owner: `RootTemplate "${t.name ?? t.mapKey}"`, icon: t.icon, file: t.file, where: "Icon attribute" })),
+        ];
+        for (const entry of owners) {
+            const icon = entry.icon;
+            if (!icon)
+                continue;
+            if (iconKeys.has(icon))
+                continue;
+            let resolved = false;
+            if (ctx.store) {
+                const res = await ctx.lookup("guid", { name: icon });
+                resolved = res.rows.some((r) => r.kind === "IconUV");
+            }
+            if (!resolved) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: entry.file,
+                    ...(entry.line !== undefined ? { line: entry.line } : {}),
+                    message: `${entry.owner}'s ${entry.where} "${icon}" does not resolve to an IconUV MapKey ` +
+                        `in this mod's atlases or the vanilla index — it will show the blue fallback icon. Note: even a ` +
+                        `resolved atlas hit does not give the item a tooltip image (bg3.icons.item-tooltip-not-atlas).`,
+                    fix: `Add an IconUV MapKey="${icon}" to an atlas descriptor .lsx, or fix the Icon.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const parenttemplateidTypeMatch = {
+    id: "bg3.items.parenttemplateid-type-match",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory"],
+    summary: "A RootTemplate's ParentTemplateId must resolve, and the parent's item type (Slot) should match.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over RootTemplates that declare a ParentTemplateId",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "warn",
+    evidence: ["bg3.items.visualbank.parenttemplateid-inheritance-fallback"],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const templates = await collectRootTemplates(idx);
+        const stats = await collectArmorWeaponEntries(ctx);
+        const statByRootTemplate = new Map(stats.filter((s) => s.fields.RootTemplate).map((s) => [s.fields.RootTemplate, s]));
+        const findings = [];
+        for (const template of templates) {
+            if (!template.parentTemplateId)
+                continue;
+            const ownStat = statByRootTemplate.get(template.mapKey);
+            const ownSlot = ownStat?.fields.Slot;
+            if (!ownSlot)
+                continue;
+            let parentSlot;
+            const parentTemplate = templates.find((t) => t.mapKey === template.parentTemplateId);
+            if (parentTemplate?.name) {
+                parentSlot = statByRootTemplate.get(parentTemplate.mapKey)?.fields.Slot;
+            }
+            else if (ctx.store) {
+                const guidRes = await ctx.lookup("guid", { uuid: template.parentTemplateId });
+                const parentName = guidRes.rows[0]?.name;
+                if (parentName) {
+                    const statRes = await ctx.lookup("stat", { name: parentName });
+                    parentSlot = statRes.rows[0]?.fields?.Slot;
+                }
+            }
+            if (!parentSlot)
+                continue;
+            if (parentSlot !== ownSlot) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: template.file,
+                    message: `RootTemplate "${template.mapKey}" (Slot="${ownSlot}") has ParentTemplateId "${template.parentTemplateId}" ` +
+                        `whose resolved item type is Slot="${parentSlot}" — an item silently inherits unset properties from its ` +
+                        `ParentTemplateId, so a mismatched type here means it "will not know it is a ${ownSlot}".`,
+                    fix: `Point ParentTemplateId at a RootTemplate of the same Slot type ("${ownSlot}").`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const armorWeaponFields = {
+    id: "bg3.items.armor-weapon-fields",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon"],
+    summary: "Armor/Weapon entries carry the fields their type requires, and `using` resolves.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every Armor.txt/Weapon.txt entry",
+    needs: { project: true, index: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.weapons.reach-is-weapon-property",
+        "bg3.weapons.no-new-base-weapon-type",
+        "bg3.practice.reference-checker-invaluable",
+    ],
+    async run(ctx) {
+        const entries = await collectArmorWeaponEntries(ctx);
+        const byName = await collectAllStatEntries(ctx);
+        const findings = [];
+        for (const entry of entries) {
+            if (!entry.fields.RootTemplate) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: entry.file,
+                    line: entry.line,
+                    message: `${entry.statKind} entry "${entry.name}" has no data "RootTemplate" — it cannot spawn or equip.`,
+                    fix: `Add data "RootTemplate" "<GameObjects MapKey>".`,
+                    evidence: this.evidence,
+                });
+            }
+            if (entry.statKind === "Weapon") {
+                if (!entry.fields["Proficiency Group"]) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "warn",
+                        file: entry.file,
+                        line: entry.line,
+                        message: `Weapon entry "${entry.name}" has no data "Proficiency Group".`,
+                        fix: `Add data "Proficiency Group" "<Group>" — there is no new base weapon type (bg3.weapons.no-new-base-weapon-type); fake one by combining an existing group with Weapon Properties.`,
+                        evidence: this.evidence,
+                    });
+                }
+                if (!entry.fields["Weapon Properties"]) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "warn",
+                        file: entry.file,
+                        line: entry.line,
+                        message: `Weapon entry "${entry.name}" has no data "Weapon Properties".`,
+                        fix: `Add data "Weapon Properties" "<Properties>" (e.g. Reach is a Weapon Property, not a boost — bg3.weapons.reach-is-weapon-property).`,
+                        evidence: this.evidence,
+                    });
+                }
+            }
+            if (entry.using) {
+                const resolved = await resolveStatName(ctx, entry.using, byName);
+                if (!resolved) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: entry.file,
+                        line: entry.line,
+                        message: `${entry.statKind} entry "${entry.name}" uses parent "${entry.using}", which is not defined in this mod or vanilla.`,
+                        fix: `Define "${entry.using}", or fix the using value.`,
+                        evidence: this.evidence,
+                    });
+                }
+                else {
+                    let current = entry.using;
+                    const seen = new Set([entry.name]);
+                    let depth = 0;
+                    while (current && depth < 10) {
+                        if (seen.has(current)) {
+                            findings.push({
+                                validatorId: this.id,
+                                severity: "block",
+                                file: entry.file,
+                                line: entry.line,
+                                message: `${entry.statKind} entry "${entry.name}"'s using-chain cycles back to "${current}".`,
+                                fix: `Break the using-chain cycle.`,
+                                evidence: this.evidence,
+                            });
+                            break;
+                        }
+                        seen.add(current);
+                        current = byName.get(current)?.using;
+                        depth++;
+                    }
+                }
+            }
+        }
+        return findings;
+    },
+};
+export const BODY_TYPE_KEYS = [
+    { key: "7d73f501-f65e-46af-a13b-2cacf3985d05", label: "M (HUM_M)" },
+    { key: "71180b76-5752-4a97-b71f-911a69197f58", label: "F (HUM_F)" },
+    { key: "e39505f7-f576-4e70-a99e-8e29cd381a11", label: "M" },
+    { key: "47c0315c-7dc6-4862-b39b-8bf3a10f8b54", label: "F" },
+    { key: "f07faafa-0c6f-4f79-a049-70e96b23d51b", label: "M" },
+    { key: "06aaae02-bb9e-4fa3-ac00-b08e13a5b0fa", label: "F" },
+    { key: "abf674d2-2ea4-4a74-ade0-125429f69f83", label: "M" },
+    { key: "b4a34ce7-41be-44d9-8486-938fe1472149", label: "F" },
+    { key: "a933e2a8-aee1-4ecb-80d2-8f47b706f024", label: "M" },
+    { key: "8f00cf38-4588-433a-8175-8acdbbf33f33", label: "F" },
+    { key: "5640e766-aa53-428d-815b-6a0b4ef95aca", label: "M" },
+    { key: "c491d027-4332-4fda-948f-4a3df6772baa", label: "F" },
+    { key: "9a8bbeba-850c-402f-bac5-ff15696e6497", label: "M" },
+    { key: "6d38f246-15cb-48b5-9b85-378016a7a78e", label: "F" },
+];
+const equipmentVisualsStructure = {
+    id: "bg3.items.equipment-visuals-structure",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "accessory"],
+    summary: "A worn item's Equipment/Visuals body-type map is a direct child of Equipment (not inside VisualSet) and maps all 14 body-type keys.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every RootTemplate GameObjects node with an Equipment child",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.visualbank.equipment-visuals-is-direct-child-not-in-visualset",
+        "bg3.items.visualbank.equipment-visuals-fourteen-body-type-keys",
+        "bg3.items.visualbank.parentrace-zero-uuid-opts-out",
+    ],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const templates = await collectRootTemplates(idx);
+        const findings = [];
+        for (const template of templates) {
+            const equipment = child(template.node, "Equipment");
+            if (!equipment)
+                continue;
+            const who = `RootTemplate "${template.name ?? template.mapKey}"`;
+            const visualSet = child(equipment, "VisualSet");
+            const visuals = child(equipment, "Visuals");
+            if (visualSet && child(visualSet, "Visuals")) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: template.file,
+                    message: `${who}'s Equipment/VisualSet contains a Visuals node — Visuals must be a direct child of Equipment, ` +
+                        `a sibling of VisualSet (and of Slot and ParentRace), not nested inside it. Nested there the engine ` +
+                        `finds no worn body map: the item is invisible when equipped on every body type, and examining it ` +
+                        `falls back to the loot VisualTemplate.`,
+                    fix: `Move the Visuals node out of VisualSet so it sits directly under Equipment > children, beside Slot and VisualSet.`,
+                    evidence: this.evidence,
+                });
+                continue;
+            }
+            const slotNode = child(equipment, "Slot");
+            const slot = slotNode ? attr(slotNode, "Object") : undefined;
+            if (!visuals) {
+                if (slot) {
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "block",
+                        file: template.file,
+                        message: `${who}'s Equipment declares Slot "${slot}" but has no Visuals child — with no body-type map the ` +
+                            `worn mesh is invisible on every body type.`,
+                        fix: `Add a Visuals node directly under Equipment > children with one Object child per body-type MapKey (14 keys) whose MapValue/Object is the VisualBank Resource ID.`,
+                        evidence: this.evidence,
+                    });
+                }
+                continue;
+            }
+            const mapped = new Set();
+            for (const object of children(visuals, "Object")) {
+                const key = attr(object, "MapKey");
+                if (!key)
+                    continue;
+                mapped.add(key.toLowerCase());
+                const mapValue = child(object, "MapValue");
+                if (!mapValue || !attr(mapValue, "Object")) {
+                    const label = BODY_TYPE_KEYS.find((b) => b.key === key.toLowerCase())?.label;
+                    findings.push({
+                        validatorId: this.id,
+                        severity: "warn",
+                        file: template.file,
+                        message: `${who}'s Equipment/Visuals maps body type ${key}${label ? ` (${label})` : ""} to an empty MapValue/Object — ` +
+                            `that body will render the item invisible.`,
+                        fix: `Set that MapValue's Object attribute to the VisualBank Resource ID of the mesh for this body type.`,
+                        evidence: this.evidence,
+                    });
+                }
+            }
+            const missing = BODY_TYPE_KEYS.filter((b) => !mapped.has(b.key));
+            if (missing.length > 0) {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "warn",
+                    file: template.file,
+                    message: `${who}'s Equipment/Visuals maps ${BODY_TYPE_KEYS.length - missing.length} of the 14 body-type keys; ` +
+                        `missing ${missing.map((m) => `${m.key} (${m.label})`).join(", ")}. There is no fallback — those bodies ` +
+                        `will render the item invisible.`,
+                    fix: `Add an Object child under Visuals for each missing MapKey, pointing MapValue/Object at the matching body's VisualBank Resource ID.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const SCENERY_BASE_MATERIAL = /\/Materials\/Base\//i;
+const wornVisualMaterialDomain = {
+    id: "bg3.items.worn-visual-material-domain",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "accessory"],
+    summary: "A VisualBank Resource with Slot=\"Body\" uses MaterialType 0 and a Materials/Characters/CHAR_BASE* base material, not the weapon/scenery values.",
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: "once per project, over every VisualBank Resource whose Slot is \"Body\"",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.visualbank.worn-body-resource-needs-character-material-domain",
+        "bg3.items.visualbank.material-shader-selection-by-filename",
+    ],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const banks = collectBankResources(idx);
+        const materialBanks = banks.filter((b) => b.region === "MaterialBank");
+        const findings = [];
+        for (const visual of banks.filter((b) => b.region === "VisualBank")) {
+            if (attr(visual.node, "Slot") !== "Body")
+                continue;
+            const who = `VisualBank Resource "${visual.name ?? visual.id ?? "?"}" (ID=${visual.id ?? "?"}, Slot="Body")`;
+            const materialType = attr(visual.node, "MaterialType");
+            if (materialType === "4") {
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: visual.file,
+                    message: `${who} has MaterialType="4", the weapon/rigid value — a worn body mesh needs MaterialType 0 (character ` +
+                        `domain); at 4 it gets no skinned shader permutation and is invisible when equipped.`,
+                    fix: `Set MaterialType="0" on this Resource (and instance a Materials/Characters/CHAR_BASE*.lsf base material).`,
+                    evidence: this.evidence,
+                });
+            }
+            for (const objects of children(visual.node, "Objects")) {
+                const materialId = attr(objects, "MaterialID");
+                if (!materialId)
+                    continue;
+                const material = materialBanks.find((m) => m.id === materialId);
+                if (!material)
+                    continue;
+                const sourceFile = attr(material.node, "SourceFile");
+                if (!sourceFile || !SCENERY_BASE_MATERIAL.test(sourceFile))
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: material.file,
+                    message: `${who}'s Objects/MaterialID "${materialId}" is MaterialBank Resource "${material.name ?? materialId}" whose ` +
+                        `SourceFile "${sourceFile}" is a generic/scenery base (Materials/Base/) — a worn body mesh on that base ` +
+                        `has no skinned shader permutation and is invisible when equipped.`,
+                    fix: `Instance a character-domain base instead: SourceFile Public/Shared/Assets/Materials/Characters/CHAR_BASE.lsf, CHAR_BASE_AlphaTest.lsf or CHAR_BASE_VertCut.lsf (same basecolor/normalmap/physicalmap params).`,
+                    related: [visual.file],
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+const GUID_TYPED_ROOTTEMPLATE_ATTRS = {
+    EquipmentTypeID: {
+        requirement: 'the engine reads EquipmentTypeID as a GUID (the custom EquipmentType\'s UUID) and vanilla always declares it type="guid"',
+        consequence: "the item silently falls back to default one-handed equipment handling (held in one hand, no back-sheath, wrong attack animation)",
+    },
+    Race: {
+        requirement: 'on a character template the engine reads Race as a GUID reference and vanilla declares it type="guid" (on an item template Race is instead a plain int8 flag, which this rule leaves alone)',
+        consequence: "the character's race reference is silently dropped and the engine falls back to a default race",
+        onlyType: "character",
+    },
+    Faction: {
+        requirement: 'the engine reads Faction as a GUID and vanilla always declares it type="guid"',
+        consequence: "the template's faction reference is silently dropped and the engine falls back to a default faction",
+    },
+    EquipmentRace: {
+        requirement: 'the engine reads EquipmentRace as a GUID and vanilla always declares it type="guid"',
+        consequence: "the template's equipment-race reference is silently dropped (its race-specific equipment visuals fall back to a default)",
+    },
+    AiHint: {
+        requirement: 'the engine reads AiHint as a GUID and vanilla always declares it type="guid"',
+        consequence: "the template's AI hint reference is silently dropped and the engine falls back to default AI behaviour",
+    },
+    DeathEffect: {
+        requirement: 'the engine reads DeathEffect as a GUID and vanilla always declares it type="guid"',
+        consequence: "the template's death-effect reference is silently dropped",
+    },
+    ColorPreset: {
+        requirement: 'the engine reads ColorPreset as a GUID and vanilla always declares it type="guid"',
+        consequence: "the template's colour-preset reference is silently dropped and the engine falls back to a default",
+    },
+};
+const REQUIRED_GUID_TYPE = "guid";
+const roottemplateGuidAttributeType = {
+    id: "bg3.items.roottemplate-guid-attribute-type",
+    game: GAME,
+    groups: ["items"],
+    modTypes: ["armor", "weapon", "accessory", "origin", "race"],
+    summary: 'A RootTemplate GameObjects attribute the engine reads as a GUID (EquipmentTypeID; Faction/EquipmentRace/AiHint/DeathEffect/ColorPreset; Race on a character) must be declared type="guid"; type="FixedString" is silently ignored.',
+    appliesTo: (target) => isProjectTarget(target),
+    appliesToDescription: 'once per project, over every GameObjects node\'s known-guid attributes (EquipmentTypeID, Faction, EquipmentRace, AiHint, DeathEffect, ColorPreset, and Race on a character-Type node)',
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: [
+        "bg3.items.roottemplates.equipmenttypeid-must-be-guid-typed",
+        "bg3.weapons.custom-equipment-type",
+    ],
+    async run(ctx) {
+        const idx = await collectProjectLsx(ctx);
+        const findings = [];
+        for (const ref of nodesOf(idx, "GameObjects")) {
+            const identity = attr(ref.node, "Name") ?? attr(ref.node, "MapKey") ?? "?";
+            const nodeType = attr(ref.node, "Type");
+            for (const [attrId, spec] of Object.entries(GUID_TYPED_ROOTTEMPLATE_ATTRS)) {
+                const declared = ref.node.attributes[attrId];
+                if (!declared)
+                    continue;
+                if (declared.type === REQUIRED_GUID_TYPE)
+                    continue;
+                if (spec.onlyType && nodeType !== spec.onlyType)
+                    continue;
+                findings.push({
+                    validatorId: this.id,
+                    severity: "block",
+                    file: ref.file,
+                    message: `RootTemplate GameObjects node "${identity}" declares ${attrId} as type="${declared.type}", but ` +
+                        `${spec.requirement}. A wrong type here is not an error — the attribute is silently ignored and ` +
+                        `${spec.consequence}.`,
+                    fix: `Change ${attrId}'s type="${declared.type}" to type="guid" on this GameObjects node.`,
+                    evidence: this.evidence,
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const ITEM_VALIDATORS = [
+    statsRootTemplateLink,
+    roottemplateVisualLink,
+    visualMaterialTextureChain,
+    ddsExtensionCase,
+    texturebankSrgb,
+    treasuretableIPrefix,
+    iconMapkeyResolves,
+    parenttemplateidTypeMatch,
+    armorWeaponFields,
+    equipmentVisualsStructure,
+    wornVisualMaterialDomain,
+    roottemplateGuidAttributeType,
+];