13.3 材质的数据驱动

{
  "fieldOrder": ["albedoQ8", "specularQ16", "shininessQ16", "roughnessQ16", "metalnessQ16", "normalScaleQ16"],
  "materials": [
    {"name": "hollow_stone", "albedoQ8": [150, 148, 132], "specularQ16": 6554, "shininessQ16": 1048576, "roughnessQ16": 45875, "metalnessQ16": 0, "normalScaleQ16": 65536},
    {"name": "hollow_gold", "albedoQ8": [220, 180, 90], "specularQ16": 65536, "shininessQ16": 2097152, "roughnessQ16": 13107, "metalnessQ16": 65536, "normalScaleQ16": 65536},
    {"name": "hollow_moss", "albedoQ8": [96, 132, 88], "specularQ16": 4587, "shininessQ16": 65536, "roughnessQ16": 58982, "metalnessQ16": 0, "normalScaleQ16": 32768}
  ],
  "activeMaterial": "hollow_gold"
}

# snippet: sim/cg_shade_13_3_data_driven.py 的建对象与内联读回（节选）
def build_object(entry, order):
    """把材质表的一项建成 S 层材质对象（字段按固定顺序）。"""
    return {f: entry[f] for f in order}


def write_html(path, mat):
    """W 宿主：把材质 JSON 内联进单文件 HTML 的 <script>。"""
    os.makedirs(os.path.dirname(path), exist_ok=True)
    blob = json.dumps(mat, ensure_ascii=False)
    html = (
        "<!DOCTYPE html>\n<html lang=\"zh-CN\"><head><meta charset=\"utf-8\">"
        "<title>lantern 材质（13.3）</title></head>\n<body>\n<pre id=\"dump\"></pre>\n"
        "<script>\nconst MATERIAL = " + blob + ";\n"
        "document.getElementById(\"dump\").textContent = JSON.stringify(MATERIAL);\n"
        "</script>\n</body></html>\n"
    )
    with open(path, "w", encoding="utf-8") as fh:
        fh.write(html)
    return len(html)


def read_html_material(path):
    """从 HTML 里把内联的材质 JSON 抽回来（正则抓 `const MATERIAL = {...};`）。"""
    with open(path, encoding="utf-8") as fh:
        text = fh.read()
    m = re.search(r"const MATERIAL = (\{.*?\});", text, re.S)
    if not m:
        raise ValueError("HTML 中未找到内联材质")
    return json.loads(m.group(1))

<script>
const MATERIAL = {"albedoQ8": [220, 180, 90], "specularQ16": 65536, "shininessQ16": 2097152, "roughnessQ16": 13107, "metalnessQ16": 65536, "normalScaleQ16": 65536};
document.getElementById("dump").textContent = JSON.stringify(MATERIAL);
</script>

// file: lantern/core/test/cg_shade_13_3_material_data_driven.test.ts
// tier: P
// verify: node --test 'core/test/cg_shade_13_3_material_data_driven.test.ts'
// 13.3 的 P 层：TypeScript 读同一份材质表建**同构**对象，重渲染帧，并把解析结果
// 写成 out/cg_shade_13_3_p_host.json 供三宿主对账。断言与 S 侧逐字段 / 逐字节相同。

import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { test } from "node:test";
import { fileURLToPath } from "node:url";

import {
  type MatFields,
  canonicalTable,
  renderWithMaterial,
} from "../src/lantern/cg_shade_13_material.ts";
import type { Spec } from "../src/lantern/cg_shade_02_material.ts";

const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
type Entry = { name: string } & MatFields;
const table = JSON.parse(readFileSync(join(root, "config", "cg_shade_13_3_material_table.json"), "utf8")) as {
  fieldOrder: (keyof MatFields)[]; materials: Entry[]; activeMaterial: string;
  perturbations: { field: keyof MatFields; index?: number; value: number; label: string }[];
};
const g = JSON.parse(readFileSync(join(root, "out", "cg_shade_13_3_data_driven.json"), "utf8")) as {
  table_digest: string; active_object: MatFields; w_inline_object: MatFields;
  render: { sha256: string; covered_pixels: number };
  perturbations: { field: keyof MatFields; sha256: string; w_inline_value: string; sync: boolean }[];
  all_sync: boolean;
};
const spec = JSON.parse(readFileSync(join(root, "config", "scene_spec.json"), "utf8")) as Spec;
const sha = (b: Uint8Array) => createHash("sha256").update(Buffer.from(b)).digest("hex");

/** TS 侧建对象：按 fieldOrder 抽字段，与 S 层 build_object 同构。 */
function buildObject(entry: Entry): MatFields {
  const out: Record<string, unknown> = {};
  for (const f of table.fieldOrder) out[f] = entry[f];
  return out as unknown as MatFields;
}

test("【核心】TS 建的对象规范 digest 与 S 侧逐字节相同", () => {
  const resolved: Record<string, Partial<MatFields>> = {};
  for (const m of table.materials) resolved[m.name] = buildObject(m);
  const blob = canonicalTable(resolved, table.fieldOrder);
  assert.equal(sha(new TextEncoder().encode(blob)), g.table_digest);
});

test("【核心】active 材质逐字段与 S 侧对象相同", () => {
  const active = buildObject(table.materials.find((m) => m.name === table.activeMaterial) as Entry);
  for (const f of table.fieldOrder) assert.deepEqual(active[f], g.active_object[f]);
});

test("【核心】W 宿主：HTML 内联材质读回后与 S 侧逐字段相同", () => {
  const html = readFileSync(join(root, "web", "dist", "shade13.html"), "utf8");
  const m = html.match(/const MATERIAL = (\{.*?\});/s);
  assert.ok(m, "HTML 中必须有内联材质");
  const inline = JSON.parse(m[1]) as MatFields;
  for (const f of table.fieldOrder) {
    assert.deepEqual(inline[f], g.active_object[f], `W 内联字段 ${String(f)} 与 S 不一致`);
  }
  // 把 TS 解析结果落盘，供三宿主对账表取 P 列
  writeFileSync(join(root, "out", "cg_shade_13_3_p_host.json"),
    JSON.stringify(buildObject(table.materials.find((m2) => m2.name === table.activeMaterial) as Entry), null, 2));
});

test("【核心】active 材质渲染：像素缓冲 sha256 与 S 侧逐字节相同", () => {
  const active = buildObject(table.materials.find((m) => m.name === table.activeMaterial) as Entry);
  const r = renderWithMaterial(spec, active);
  assert.equal(r.coveredCount, g.render.covered_pixels);
  assert.equal(sha(r.rgb), g.render.sha256);
});

test("改一个字段：帧 digest 与 W 内联值同步变化", () => {
  const base = buildObject(table.materials.find((m) => m.name === table.activeMaterial) as Entry);
  assert.equal(sha(renderWithMaterial(spec, base).rgb), g.render.sha256);
  for (const p of g.perturbations) {
    const mod = JSON.parse(JSON.stringify(base)) as MatFields;
    if (p.field === "albedoQ8") mod.albedoQ8[0] = Number(p.w_inline_value.split(",")[0]);
    else (mod as unknown as Record<string, number>)[p.field] = Number(p.w_inline_value);
    assert.notEqual(sha(renderWithMaterial(spec, mod).rgb), g.render.sha256, "改字段必须改帧");
    assert.equal(sha(renderWithMaterial(spec, mod).rgb), p.sha256, "P 侧帧必须与 S 侧相同");
    assert.ok(p.sync);
  }
  assert.ok(g.all_sync);
});

✔ 【核心】TS 建的对象规范 digest 与 S 侧逐字节相同
✔ 【核心】active 材质逐字段与 S 侧对象相同
✔ 【核心】W 宿主：HTML 内联材质读回后与 S 侧逐字段相同
✔ 【核心】active 材质渲染：像素缓冲 sha256 与 S 侧逐字节相同
✔ 改一个字段：帧 digest 与 W 内联值同步变化
ℹ tests 5  ℹ pass 5  ℹ fail 0