modwright 0.1.0

package/dist/surfaces/cyberpunk2077/validators/mesh.js

@@ -0,0 +1,338 @@
+const ID = "cp2077.history.mesh-preexport";
+const GAME = "cyberpunk2077";
+const GROUPS = ["history"];
+const MOD_TYPES = ["mesh", "garment", "weapon", "vehicle"];
+const VERTEX_CAP = 65535;
+const ICOSPHERE_VERTEX_SIGNATURE = 42;
+const UV_LAYER_NAME = "UVMap";
+const DEGENERATE_AREA_EPSILON = 1e-9;
+const EVIDENCE = [
+    "cp2077.mesh.vertex-cap-65535",
+    "cp2077.toolchain.glb-import-ignores-transforms",
+    "cp2077.toolchain.glb-contains-junk-icosphere",
+    "cp2077.mesh.glb-triangulation-required",
+    "cp2077.mesh.glb-tangent-vectors-required",
+    "cp2077.mesh.glb-uv-layers-required",
+];
+const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function approxEqual(a, b, eps = 1e-6) {
+    return Math.abs(a - b) <= eps;
+}
+function vecApproxEqual(v, expected, eps = 1e-6) {
+    if (!v)
+        return true;
+    if (v.length !== expected.length)
+        return false;
+    return v.every((n, i) => approxEqual(n, expected[i] ?? 0, eps));
+}
+function nodeIsIdentity(node) {
+    if (node.matrix)
+        return vecApproxEqual(node.matrix, IDENTITY_MATRIX);
+    return (vecApproxEqual(node.translation, [0, 0, 0]) &&
+        vecApproxEqual(node.rotation, [0, 0, 0, 1]) &&
+        vecApproxEqual(node.scale, [1, 1, 1]));
+}
+function decodeBase64DataUri(uri) {
+    if (!uri)
+        return undefined;
+    const match = /^data:[^,]*;base64,(.*)$/is.exec(uri);
+    const encoded = match?.[1];
+    if (encoded === undefined)
+        return undefined;
+    try {
+        return Buffer.from(encoded, "base64");
+    }
+    catch {
+        return undefined;
+    }
+}
+function componentByteSize(componentType) {
+    switch (componentType) {
+        case 5120:
+        case 5121:
+            return 1;
+        case 5122:
+        case 5123:
+            return 2;
+        case 5125:
+        case 5126:
+            return 4;
+        default:
+            return 4;
+    }
+}
+function numComponents(type) {
+    switch (type) {
+        case "SCALAR":
+            return 1;
+        case "VEC2":
+            return 2;
+        case "VEC3":
+            return 3;
+        case "VEC4":
+            return 4;
+        default:
+            return 1;
+    }
+}
+function readAccessorBytes(doc, accessorIndex) {
+    if (accessorIndex === undefined)
+        return undefined;
+    const accessor = doc.accessors?.[accessorIndex];
+    if (!accessor || accessor.bufferView === undefined)
+        return undefined;
+    const view = doc.bufferViews?.[accessor.bufferView];
+    if (!view)
+        return undefined;
+    const buffer = doc.buffers?.[view.buffer];
+    const bytes = decodeBase64DataUri(buffer?.uri);
+    if (!bytes)
+        return undefined;
+    const componentType = accessor.componentType ?? 5126;
+    const start = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+    const length = accessor.count * numComponents(accessor.type) * componentByteSize(componentType);
+    if (start < 0 || start + length > bytes.length)
+        return undefined;
+    return { data: bytes.subarray(start, start + length), componentType, count: accessor.count };
+}
+function readIndexArray(raw) {
+    const dv = new DataView(raw.data.buffer, raw.data.byteOffset, raw.data.byteLength);
+    const out = [];
+    for (let i = 0; i < raw.count; i++) {
+        switch (raw.componentType) {
+            case 5121:
+                out.push(dv.getUint8(i));
+                break;
+            case 5123:
+                out.push(dv.getUint16(i * 2, true));
+                break;
+            case 5125:
+                out.push(dv.getUint32(i * 4, true));
+                break;
+            default:
+                return undefined;
+        }
+    }
+    return out;
+}
+function readVec3Array(raw) {
+    if (raw.componentType !== 5126)
+        return undefined;
+    const dv = new DataView(raw.data.buffer, raw.data.byteOffset, raw.data.byteLength);
+    const out = [];
+    for (let i = 0; i < raw.count; i++) {
+        out.push([dv.getFloat32(i * 12, true), dv.getFloat32(i * 12 + 4, true), dv.getFloat32(i * 12 + 8, true)]);
+    }
+    return out;
+}
+function triangleArea(a, b, c) {
+    const ab = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+    const ac = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+    const cross = [
+        ab[1] * ac[2] - ab[2] * ac[1],
+        ab[2] * ac[0] - ab[0] * ac[2],
+        ab[0] * ac[1] - ab[1] * ac[0],
+    ];
+    return 0.5 * Math.sqrt(cross[0] * cross[0] + cross[1] * cross[1] + cross[2] * cross[2]);
+}
+function meshLabel(doc, meshIndex, primitiveIndex) {
+    const mesh = doc.meshes?.[meshIndex];
+    const name = mesh?.name ? `"${mesh.name}"` : `#${meshIndex}`;
+    return `mesh ${name} primitive ${primitiveIndex}`;
+}
+function checkGltfDoc(doc, file) {
+    const findings = [];
+    const meshes = doc.meshes ?? [];
+    for (const node of doc.nodes ?? []) {
+        if (node.mesh === undefined)
+            continue;
+        if (!nodeIsIdentity(node)) {
+            findings.push({
+                validatorId: ID,
+                severity: "block",
+                file,
+                message: `Node ${node.name ? `"${node.name}"` : `referencing mesh #${node.mesh}`} carries an un-applied transform (translation/rotation/scale/matrix is not identity). WolvenKit's GLB import ignores node transforms — run transform_apply(location=True, rotation=True, scale=True) in Blender before export, or the imported submesh lands in the wrong place relative to the donor mesh.`,
+                fix: "In Blender: select the object, Object > Apply > All Transforms (or bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)) before exporting the GLB.",
+                evidence: ["cp2077.toolchain.glb-import-ignores-transforms"],
+            });
+        }
+        if (node.name && /icosphere/i.test(node.name)) {
+            findings.push({
+                validatorId: ID,
+                severity: "block",
+                file,
+                message: `Node "${node.name}" looks like the junk 2 m icosphere every WolvenKit GLB export carries. Delete it in Blender before re-exporting — it must not reach the game mesh.`,
+                fix: 'Delete every object whose name contains "Icosphere" before export (an export script can drop them by name before writing the GLB).',
+                evidence: ["cp2077.toolchain.glb-contains-junk-icosphere"],
+            });
+        }
+    }
+    meshes.forEach((mesh, meshIndex) => {
+        mesh.primitives.forEach((primitive, primitiveIndex) => {
+            const label = meshLabel(doc, meshIndex, primitiveIndex);
+            const positionAccessorIndex = primitive.attributes.POSITION;
+            const positionAccessor = positionAccessorIndex !== undefined ? doc.accessors?.[positionAccessorIndex] : undefined;
+            if (positionAccessor) {
+                if (positionAccessor.count > VERTEX_CAP) {
+                    findings.push({
+                        validatorId: ID,
+                        severity: "block",
+                        file,
+                        message: `${label} has ${positionAccessor.count} vertices, over the engine's hard cap of ${VERTEX_CAP} per submesh. The mesh will render incompletely or fail to load silently. Split the submesh or de-duplicate double-sided geometry instead of doubling it wholesale (doubling a whole weapon mesh for a double-sided material is how this cap was first hit).`,
+                        fix: "Do not add more submeshes to dodge the cap — duplicate and normal-flip only the minimum geometry that needs a back face, and repair inward-facing normals at the source in Blender.",
+                        evidence: ["cp2077.mesh.vertex-cap-65535"],
+                    });
+                }
+                if (positionAccessor.count === ICOSPHERE_VERTEX_SIGNATURE &&
+                    !(mesh.name && /icosphere/i.test(mesh.name))) {
+                    findings.push({
+                        validatorId: ID,
+                        severity: "block",
+                        file,
+                        message: `${label} has exactly ${ICOSPHERE_VERTEX_SIGNATURE} vertices — the signature of WolvenKit's junk 2 m icosphere (unnamed or renamed so the "Icosphere" name check missed it). Delete it in Blender before re-exporting.`,
+                        fix: 'Delete the object; if it survived a rename, check by vertex count (42) rather than by name alone.',
+                        evidence: ["cp2077.toolchain.glb-contains-junk-icosphere"],
+                    });
+                }
+            }
+            const uvAttributes = Object.keys(primitive.attributes).filter((key) => key.startsWith("TEXCOORD_"));
+            if (uvAttributes.length === 0) {
+                findings.push({
+                    validatorId: ID,
+                    severity: "warn",
+                    file,
+                    message: `${label} has no UV layer. WolvenKit GLB import needs a UV set; Blender's export step smart-projects a fresh one when none exists, but exporting without one leaves it to chance.`,
+                    fix: `In Blender, add one UV layer named exactly "${UV_LAYER_NAME}" (smart UV project, angle_limit=1.15, island_margin=0.02, is the project's convention).`,
+                    evidence: ["cp2077.mesh.glb-uv-layers-required"],
+                });
+            }
+            else {
+                if (uvAttributes.length > 1) {
+                    findings.push({
+                        validatorId: ID,
+                        severity: "warn",
+                        file,
+                        message: `${label} carries ${uvAttributes.length} UV layers (${uvAttributes.sort().join(", ")}). Export exactly one, named "${UV_LAYER_NAME}" — extra layers are removed by the project's own export step.`,
+                        fix: `Remove every UV layer except the one named "${UV_LAYER_NAME}" before export.`,
+                        evidence: ["cp2077.mesh.glb-uv-layers-required"],
+                    });
+                }
+                const texcoord0Index = primitive.attributes["TEXCOORD_0"];
+                const uv0Accessor = texcoord0Index !== undefined ? doc.accessors?.[texcoord0Index] : undefined;
+                if (uv0Accessor?.name !== undefined && uv0Accessor.name !== UV_LAYER_NAME) {
+                    findings.push({
+                        validatorId: ID,
+                        severity: "warn",
+                        file,
+                        message: `${label}'s UV layer is named "${uv0Accessor.name}"; the project's convention requires exactly "${UV_LAYER_NAME}" (capital U, V, M).`,
+                        fix: `Rename the UV layer to "${UV_LAYER_NAME}" in Blender before export.`,
+                        evidence: ["cp2077.mesh.glb-uv-layers-required"],
+                    });
+                }
+            }
+            if (primitive.indices !== undefined && positionAccessorIndex !== undefined && (primitive.mode ?? 4) === 4) {
+                const indexBytes = readAccessorBytes(doc, primitive.indices);
+                const positionBytes = readAccessorBytes(doc, positionAccessorIndex);
+                const indices = indexBytes && readIndexArray(indexBytes);
+                const positions = positionBytes && readVec3Array(positionBytes);
+                if (indices && positions && indices.length % 3 === 0) {
+                    for (let t = 0; t < indices.length; t += 3) {
+                        const ia = indices[t];
+                        const ib = indices[t + 1];
+                        const ic = indices[t + 2];
+                        if (ia === undefined || ib === undefined || ic === undefined)
+                            continue;
+                        const pa = positions[ia];
+                        const pb = positions[ib];
+                        const pc = positions[ic];
+                        if (!pa || !pb || !pc)
+                            continue;
+                        if (triangleArea(pa, pb, pc) < DEGENERATE_AREA_EPSILON) {
+                            findings.push({
+                                validatorId: ID,
+                                severity: "warn",
+                                file,
+                                message: `${label} has a degenerate (zero-area) triangle at index offset ${t} (vertices ${ia}, ${ib}, ${ic}). Likely duplicate or merged geometry from the export/join step.`,
+                                fix: "Check the join-by-material step for duplicate vertices at this location; re-triangulate or remove the degenerate face in Blender.",
+                                evidence: ["cp2077.mesh.glb-triangulation-required"],
+                            });
+                        }
+                    }
+                }
+            }
+        });
+    });
+    return findings;
+}
+function extensionOf(p) {
+    const idx = p.lastIndexOf(".");
+    return idx === -1 ? "" : p.slice(idx).toLowerCase();
+}
+export const meshPreexportValidator = {
+    id: ID,
+    game: GAME,
+    groups: GROUPS,
+    modTypes: MOD_TYPES,
+    summary: "Checks a glTF mesh export for the engine's 65,535-vertex submesh cap, un-applied node transforms, the junk WolvenKit icosphere, a single correctly-named UV layer, and degenerate triangles, before it is imported over a donor mesh.",
+    appliesTo(target, _project) {
+        if (target.kind !== "file")
+            return false;
+        const ext = extensionOf(target.path);
+        return ext === ".gltf" || ext === ".glb";
+    },
+    appliesToDescription: "every .gltf or .glb mesh export file in the project",
+    needs: { project: true },
+    cost: "build",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const file = ctx.target.path;
+        const ext = extensionOf(file);
+        if (ext === ".glb") {
+            return [
+                {
+                    validatorId: ID,
+                    severity: "info",
+                    file,
+                    message: "This is a binary .glb; ModWright's validator context only reads text, so the JSON chunk cannot be parsed cheaply here and the pre-export checks (vertex cap, transforms, icosphere, UV, triangulation) are skipped for this file. Keep or add a .gltf (JSON, embedded buffers) export alongside it and validate that instead.",
+                    fix: "Export a .gltf (not .glb) intermediate for this mesh, or add a byte-level reader to ModWright's ValidationContext.",
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        let text;
+        try {
+            text = await ctx.readText(file);
+        }
+        catch (err) {
+            return [
+                {
+                    validatorId: ID,
+                    severity: "block",
+                    file,
+                    message: `Could not read this file: ${err.message}`,
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        let doc;
+        try {
+            doc = JSON.parse(text);
+        }
+        catch (err) {
+            return [
+                {
+                    validatorId: ID,
+                    severity: "block",
+                    file,
+                    message: `Cannot parse this file as glTF JSON: ${err.message}`,
+                    evidence: EVIDENCE,
+                },
+            ];
+        }
+        return checkGltfDoc(doc, file);
+    },
+};
+export const MESH_VALIDATORS = [meshPreexportValidator];

package/dist/surfaces/cyberpunk2077/validators/modsettings.js

@@ -0,0 +1,120 @@
+import * as path from "node:path";
+const ID = "cp2077.history.modsettings-annotation-keys";
+const EVIDENCE = ["ModWright research"];
+const REQUIRED_KEYS = ["mod", "category", "displayName"];
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isRedsUnderScripts(target, project) {
+    if (target.kind !== "file" || !target.path.toLowerCase().endsWith(".reds"))
+        return false;
+    return project.sources.some((s) => s.kind === "scripts" && s.exists && isWithin(s.absPath, target.path));
+}
+const ANNOTATION_RE = /^\s*@runtimeProperty\(\s*"ModSettings\.([A-Za-z][A-Za-z0-9_]*)"\s*,\s*"((?:[^"\\]|\\.)*)"\s*\)\s*$/;
+const DECL_RE = /^\s*(?:public\s+|protected\s+|private\s+)?(?:abstract\s+|final\s+)?(?:let|func|class)\s+/;
+const CLASS_DECL_RE = /^(?:public\s+|protected\s+|private\s+)?(?:abstract\s+|final\s+)?class\s+/;
+function collectAnnotationBlocks(text) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    const blocks = [];
+    let pending;
+    let pendingStart = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const m = ANNOTATION_RE.exec(line);
+        if (m) {
+            if (!pending) {
+                pending = new Map();
+                pendingStart = i + 1;
+            }
+            pending.set(m[1], m[2]);
+            continue;
+        }
+        if (pending) {
+            if (DECL_RE.test(line)) {
+                blocks.push({ keys: pending, startLine: pendingStart, declLine: i + 1, declText: line.trim() });
+            }
+            if (line.trim().length === 0 || line.trim().startsWith("//"))
+                continue;
+            pending = undefined;
+        }
+    }
+    return blocks;
+}
+const modsettingsAnnotationKeys = {
+    id: ID,
+    game: "cyberpunk2077",
+    groups: ["history"],
+    modTypes: ["gameplay-tweak"],
+    summary: "A ModSettings.* @runtimeProperty block sits on a redscript field (not a class), carries mod/category/displayName, and mod matches this project's own name.",
+    appliesTo: isRedsUnderScripts,
+    appliesToDescription: "every .reds file under a project source of kind \"scripts\"",
+    needs: { project: true },
+    cost: "edit",
+    severity: "block",
+    evidence: EVIDENCE,
+    async run(ctx) {
+        if (ctx.target.kind !== "file")
+            return [];
+        const text = await ctx.readText(ctx.target.path);
+        const blocks = collectAnnotationBlocks(text);
+        const findings = [];
+        const projectName = ctx.project.project.identity?.name ?? ctx.project.project.name;
+        for (const block of blocks) {
+            if (CLASS_DECL_RE.test(block.declText)) {
+                findings.push({
+                    validatorId: ID,
+                    severity: "block",
+                    file: ctx.target.path,
+                    line: block.declLine,
+                    message: `The ModSettings annotation block sits on "${block.declText}", a class declaration. Mod Settings binds @runtimeProperty("ModSettings.*") annotations to properties, so a block on the class exposes no control.`,
+                    fix: "Move the @runtimeProperty(\"ModSettings.*\") lines to sit directly above the `let` field they describe, inside the class body.",
+                    evidence: EVIDENCE,
+                });
+                continue;
+            }
+            const missing = REQUIRED_KEYS.filter((k) => !block.keys.has(k));
+            if (missing.length > 0) {
+                findings.push({
+                    validatorId: ID,
+                    severity: "block",
+                    file: ctx.target.path,
+                    line: block.declLine,
+                    message: `The ModSettings annotation block on "${block.declText}" is missing required key(s): ${missing.join(", ")}. The native settings UI needs mod/category/displayName to place a control at all.`,
+                    fix: `Add @runtimeProperty("ModSettings.<key>", "<value>") for: ${missing.join(", ")}.`,
+                    evidence: EVIDENCE,
+                });
+                continue;
+            }
+            const mod = block.keys.get("mod");
+            if (mod !== projectName) {
+                findings.push({
+                    validatorId: ID,
+                    severity: "block",
+                    file: ctx.target.path,
+                    line: block.declLine,
+                    message: `The ModSettings annotation block on "${block.declText}" declares mod="${mod}", which does not match this project's own name ("${projectName}"). A mismatched mod key places the control on the wrong mod's settings page.`,
+                    fix: `Set @runtimeProperty("ModSettings.mod", "${projectName}").`,
+                    evidence: EVIDENCE,
+                });
+            }
+        }
+        const bound = blocks.filter((b) => !CLASS_DECL_RE.test(b.declText));
+        if (bound.length > 0 && !/ModSettings\.RegisterListenerToClass\s*\(/.test(text)) {
+            findings.push({
+                validatorId: ID,
+                severity: "warn",
+                file: ctx.target.path,
+                line: bound[0].declLine,
+                message: "This file binds ModSettings annotations to properties but never calls ModSettings.RegisterListenerToClass. " +
+                    "Mod Settings updates the properties only of a registered listener, so the menu control renders and persists while the code keeps reading the default.",
+                fix: "Register the settings class as a listener: for a ScriptableSystem, call ModSettings.RegisterListenerToClass(this) from OnAttach() and " +
+                    "ModSettings.UnregisterListenerToClass(this) from OnDetach() (guard both with @if(ModuleExists(\"ModSettingsModule\")) to keep compiling without Mod Settings); " +
+                    "for a Codeware ScriptableService, register from OnLoad() and OnReload().",
+                evidence: [...EVIDENCE, "cp2077.ui.modsettings.listener-callbacks-require-cb-keyword"],
+            });
+        }
+        return findings;
+    },
+};
+export const MODSETTINGS_VALIDATORS = [modsettingsAnnotationKeys];