modsmith 0.6.2 → 0.7.1

package/src/block-shapes.mjs

@@ -0,0 +1,176 @@
+/**
+ * 方块碰撞/工具的唯一一份推导规则。
+ *
+ * 三个消费者必须共用：
+ *   - `inspect`：从模组 jar 的模型 parent 推 manifest 的 box/solid；
+ *   - `cortico-bridge`：把 manifest + 实测 id 注入 prismarine registry；
+ *   - `conformance`：接包验收，检查「声明的每个 state 真的有形状/能挖」。
+ *
+ * 以前 inspect 和 host 各写一份，于是 TF 的 `canopy_planks` 在清单里是实心、
+ * 注入后却是空气。规则只留这一份，测试也只钉这一份。
+ */
+
+/** 这些方块不是"挖"的对象；其余模组方块默认都能挖（作物/花没有碰撞箱，但能挖）。 */
+export const NOT_DIGGABLE = new Set([
+  'air', 'cave_air', 'void_air', 'water', 'lava', 'bedrock', 'barrier', 'light',
+  'command_block', 'chain_command_block', 'repeating_command_block', 'structure_block',
+  'structure_void', 'jigsaw', 'end_portal', 'end_portal_frame', 'nether_portal',
+  'moving_piston', 'reinforced_deepslate',
+]);
+
+export function isDiggable(name) {
+  return !NOT_DIGGABLE.has(String(name).split(':')[1] ?? name);
+}
+
+/** 从 elements 里算整体包围盒（0..1 归一化，跟 prismarine 的 box 一致）。 */
+export function boxFromElements(elements) {
+  if (!Array.isArray(elements) || elements.length === 0) return null;
+  let x0 = Infinity, y0 = Infinity, z0 = Infinity;
+  let x1 = -Infinity, y1 = -Infinity, z1 = -Infinity;
+  for (const el of elements) {
+    const [a, b] = el.from ?? [0, 0, 0];
+    const [c, d, e] = el.to ?? [16, 16, 16];
+    x0 = Math.min(x0, a); y0 = Math.min(y0, b); z0 = Math.min(z0, c);
+    x1 = Math.max(x1, c); y1 = Math.max(y1, d); z1 = Math.max(z1, e);
+  }
+  if (!Number.isFinite(x0)) return null;
+  return [x0 / 16, y0 / 16, z0 / 16, x1 / 16, y1 / 16, z1 / 16];
+}
+
+/**
+ * 原版 parent 在服务器 jar 里，模组只写 `parent: minecraft:block/cube_all`。
+ * 这些 parent 的名字就够定碰撞盒；没有它，整块木板会被当成空气（TF 实测：
+ * canopy_planks 变成 solid:false，机器人直接穿地板）。
+ */
+const VANILLA_PARENT_BOX = {
+  'block/block': [0, 0, 0, 1, 1, 1],
+  'builtin/entity': [0, 0, 0, 1, 1, 1],
+  'block/chest': [0, 0, 0, 1, 1, 1],
+  'block/bookshelf': [0, 0, 0, 1, 1, 1],
+  'block/chiseled_bookshelf': [0, 0, 0, 1, 1, 1],
+  'block/cube': [0, 0, 0, 1, 1, 1],
+  'block/cube_all': [0, 0, 0, 1, 1, 1],
+  'block/cube_bottom_top': [0, 0, 0, 1, 1, 1],
+  'block/cube_column': [0, 0, 0, 1, 1, 1],
+  'block/cube_column_horizontal': [0, 0, 0, 1, 1, 1],
+  'block/cube_directional': [0, 0, 0, 1, 1, 1],
+  'block/cube_mirrored': [0, 0, 0, 1, 1, 1],
+  'block/cube_mirrored_all': [0, 0, 0, 1, 1, 1],
+  'block/orientable': [0, 0, 0, 1, 1, 1],
+  'block/orientable_with_bottom': [0, 0, 0, 1, 1, 1],
+  'block/orientable_vertical': [0, 0, 0, 1, 1, 1],
+  'block/leaves': [0, 0, 0, 1, 1, 1],
+  'block/stairs': [0, 0, 0, 1, 0.5, 1],
+  'block/slab': [0, 0, 0, 1, 0.5, 1],
+  'block/slab_top': [0, 0.5, 0, 1, 1, 1],
+  'block/fence_post': [0.375, 0, 0.375, 0.625, 1, 0.625],
+  'block/fence_side': [0.375, 0, 0.375, 0.625, 1, 0.625],
+  'block/wall_post': [0.25, 0, 0.25, 0.75, 1, 0.75],
+  'block/wall_side': [0.25, 0, 0.25, 0.75, 1, 0.75],
+  'block/trapdoor_bottom': [0, 0, 0, 1, 0.1875, 1],
+  'block/trapdoor_top': [0, 0, 0, 1, 0.1875, 1],
+  'block/template_orientable_trapdoor_bottom': [0, 0, 0, 1, 0.1875, 1],
+  'block/template_orientable_trapdoor_top': [0, 0, 0, 1, 0.1875, 1],
+  'block/template_orientable_trapdoor_open': [0, 0, 0, 1, 1, 0.1875],
+  'block/template_fence_gate': [0, 0, 0, 1, 1, 0.375],
+  'block/template_fence_gate_open': [0, 0, 0, 1, 1, 0.375],
+  'block/template_fence_gate_wall': [0, 0, 0, 1, 1, 0.375],
+  'block/template_fence_gate_wall_open': [0, 0, 0, 1, 1, 0.375],
+  'block/door_bottom_left': [0, 0, 0, 1, 1, 0.1875],
+  'block/door_bottom_right': [0, 0, 0, 1, 1, 0.1875],
+  'block/pane_post': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/pane_side': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/template_glass_pane_post': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/template_glass_pane_side': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/template_glass_pane_side_alt': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/template_glass_pane_noside': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/template_glass_pane_noside_alt': [0.4375, 0, 0.4375, 0.5625, 1, 0.5625],
+  'block/carpet': [0, 0, 0, 1, 0.0625, 1],
+  'block/pressure_plate_up': [0, 0, 0, 1, 0.0625, 1],
+  'block/pressure_plate_down': [0, 0, 0, 1, 0.0625, 1],
+};
+
+export function vanillaParentBox(ref) {
+  const name = String(ref ?? '').replace(/^minecraft:/, '');
+  return VANILLA_PARENT_BOX[name] ?? null;
+}
+
+/** 模型链走到底：先找 elements；没有就看原版 parent 名推一个保守碰撞盒。 */
+export function boxForRef(materials, ref, depth = 0) {
+  if (!ref || depth > 8) return null;
+  const name = ref.includes(':') ? ref.split(':')[1] : ref;
+  const ns = ref.includes(':') ? ref.split(':')[0] : null;
+  const candidates = ns ? [`assets/${ns}/models/${name}.json`] : [`assets/__NS__/models/${name}.json`];
+  let json = null;
+  for (const c of candidates) {
+    json = materials.readJson(c);
+    if (json) break;
+  }
+  if (!json) return vanillaParentBox(ref);
+  const own = boxFromElements(json.elements);
+  if (own) return own;
+  if (json.parent) {
+    const inherited = boxForRef(materials, json.parent, depth + 1);
+    if (inherited) return inherited;
+  }
+  return vanillaParentBox(ref);
+}
+
+/**
+ * 非整块方块的碰撞形状不能统一用一个 box：楼梯的上/下半、台阶的朝向都不同。
+ * 原版 registry 已经带每种 state 的 shape id；按名字给模组方块找同族模板，
+ * 再用 state 属性映射到模板的具体 state。找不到模板就退回清单里的 box。
+ */
+export function shapeTemplateOf(name) {
+  const short = name.split(':')[1] ?? name;
+  if (/_trapdoor/.test(short)) return 'oak_trapdoor';
+  if (/_fence_gate/.test(short)) return 'oak_fence_gate';
+  if (/_fence/.test(short)) return 'oak_fence';
+  if (/_stairs/.test(short)) return 'oak_stairs';
+  if (/_slab/.test(short)) return 'oak_slab';
+  if (/_wall$/.test(short)) return 'cobblestone_wall';
+  if (/_door/.test(short)) return 'oak_door';
+  if (/_pane/.test(short)) return 'glass_pane';
+  if (/_carpet/.test(short)) return 'white_carpet';
+  if (/_button/.test(short)) return 'oak_button';
+  if (/_pressure_plate/.test(short)) return 'oak_pressure_plate';
+  return null;
+}
+
+/** 把模组 state 的属性映射到模板 state 的 shape id；映射不了返回 null。 */
+export function templateShapeId(reg, templateName, props) {
+  const tpl = reg.blocksByName?.[templateName];
+  const ids = reg.blockCollisionShapes?.blocks?.[templateName];
+  if (!Array.isArray(tpl?.states) || !Array.isArray(ids)) return null;
+  // 状态索引是**最后一个属性最快变化**（与 registry 的 stateId 顺序一致）：
+  // index = ((type * 2) + waterlogged)，不是 waterlogged * 3 + type。
+  // 之前按第一个属性最快算，oak_slab 的 top 拿到了下半砖形状、bottom 拿到上半砖形状
+  // （楼梯同理）——形状非空，所以只查"非空"的检查全放过了它。
+  let index = 0;
+  for (const desc of tpl.states) {
+    const raw = props?.[desc.name];
+    let value;
+    if (Array.isArray(desc.values)) {
+      value = desc.values.indexOf(String(raw));
+      if (value < 0) return null;
+    } else if (desc.type === 'bool') {
+      value = String(raw) === 'true' ? 1 : 0;
+    } else {
+      if (raw === undefined) return null;
+      value = Number(raw);
+      if (!Number.isInteger(value) || value < 0 || value >= desc.num_values) return null;
+    }
+    index = index * desc.num_values + value;
+  }
+  return ids[index] ?? null;
+}
+
+/** 从方块 tags 推 harvestTools：矿石/木头这类要工具，作物/植物用手就行。 */
+export function harvestToolsFor(reg, tags) {
+  const template = tags.includes('mineable/pickaxe') ? 'stone'
+    : tags.includes('mineable/axe') ? 'oak_log'
+      : tags.includes('mineable/shovel') ? 'dirt'
+        : tags.includes('mineable/hoe') ? 'oak_leaves'
+          : null;
+  return template ? (reg.blocksByName?.[template]?.harvestTools ?? null) : null;
+}

package/src/calibrate.mjs

@@ -126,6 +126,7 @@ export default async function cmdCalibrate(args, io) {
     try { await cmd(`setblock ${bx} ${by} ${bz} minecraft:air`); } catch { /* */ }
     try { await cmd(`forceload remove ${bx - 16} ${bz - 16} ${bx + 16} ${bz + 16}`); } catch { /* */ }
     try { bot?.quit(); } catch { /* */ }
+    cmd.close();
   };
 
   try {

package/src/conformance-live.mjs

@@ -0,0 +1,208 @@
+/**
+ * 真机参考消费：连一台测试/生产服务器，用真实 mineflayer bot 消费 manifest+ids。
+ *
+ * 只读：不 setblock、不 summon、不聊天。它验证的是「一个普通 mineflayer bot 在
+ * inject_allowed 前注入后，真的能拿到方块/形状/实体」——比离线模拟更接近宿主。
+ * 需要写世界的抽样验证（setblock/召唤）留给人工测试服，不在这里做。
+ */
+import mineflayer from 'mineflayer';
+import { Vec3 } from 'vec3';
+import { installModRegistry, installMineflayerFixes } from './cortico-bridge.mjs';
+import { checkRegistry } from './conformance.mjs';
+import { makeRcon } from './rcon.mjs';
+
+function waitSpawn(bot, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let timer = null;
+    const done = (err) => {
+      if (timer) clearTimeout(timer);
+      bot.removeListener('spawn', onSpawn);
+      bot.removeListener('error', onError);
+      bot.removeListener('end', onEnd);
+      if (err) reject(err);
+      else resolve();
+    };
+    const onSpawn = () => done(null);
+    const onError = (err) => done(err instanceof Error ? err : new Error(String(err)));
+    const onEnd = (reason) => done(new Error(`连接在 spawn 前结束：${reason}`));
+    bot.once('spawn', onSpawn);
+    bot.once('error', onError);
+    bot.once('end', onEnd);
+    timer = setTimeout(() => done(new Error(`等 spawn 超时（${timeoutMs}ms）`)), timeoutMs);
+  });
+}
+
+function sampleStates(manifest) {
+  const out = [];
+  for (const [name, spec] of Object.entries(manifest.blocks ?? {})) {
+    const states = spec?.states ?? [];
+    if (states.length === 0) continue;
+    const short = name.split(':')[1] ?? name;
+    if (/_stairs/.test(short)) {
+      for (const half of ['bottom', 'top']) {
+        const state = states.find((s) => s.half === half);
+        if (state) out.push({ name, props: state, why: `stairs ${half}` });
+      }
+    } else if (/_slab/.test(short)) {
+      for (const type of ['bottom', 'top']) {
+        const state = states.find((s) => s.type === type);
+        if (state) out.push({ name, props: state, why: `slab ${type}` });
+      }
+    } else if (spec.solid !== false && Array.isArray(spec.box)) {
+      out.push({ name, props: states[0], why: 'solid full block' });
+    }
+    if (out.length >= 8) break;
+  }
+  return out.slice(0, 8);
+}
+
+function blockSpec(name, props) {
+  const entries = Object.entries(props ?? {}).filter(([, v]) => v !== undefined);
+  if (entries.length === 0) return name;
+  return `${name}[${entries.map(([k, v]) => `${k}=${v}`).join(',')}]`;
+}
+
+/**
+ * 在固定测试格 setblock + tp，读真实 bot 的 blockAt/shapes。只应在测试服使用。
+ * 返回 L2/L3 检查；不碰生产服。
+ */
+export async function sampleWorld({ bot, manifest, ids, rcon, x = 400, y = 100, z = 400, timeoutMs = 20_000 }) {
+  const checks = [];
+  const cmd = await makeRcon(rcon.host ?? '127.0.0.1', rcon.port, rcon.password);
+  const username = bot.username;
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const at = new Vec3(x, y, z);
+  try {
+    await cmd(`forceload add ${x - 2} ${z - 2} ${x + 2} ${z + 2}`);
+    await cmd(`tp ${username} ${x + 0.5} ${y + 1} ${z + 0.5}`);
+    await sleep(600);
+    const signatures = new Map();
+    for (const sample of sampleStates(manifest)) {
+      const spec = blockSpec(sample.name, sample.props);
+      const placed = await cmd(`setblock ${x} ${y} ${z} ${spec} replace`);
+      // setblock 到客户端区块更新有延迟。只等固定 250ms 时读到的是上一态（名字还一样，
+      // 台阶/楼梯的上下两态就会看起来"形状相同"）。先按这一态的**判别属性**等。
+      // 只按 half/type 比：楼梯的 shape 会被邻居校正（inner_left→straight），
+      // 不能要求完整 props 命中，否则会把服务端正常行为误报成 id 错。
+      const key = sample.why.startsWith('stairs ') ? ['half']
+        : sample.why.startsWith('slab ') ? ['type'] : [];
+      const expected = (ids.blocks?.[sample.name] ?? [])
+        .filter((m) => key.every((k) => String(m.props?.[k]) === String(sample.props?.[k])))
+        .map((m) => m.stateId);
+      await sleep(250);
+      let block = bot.blockAt(at);
+      const deadline = Date.now() + 2000;
+      while (Date.now() < deadline && block
+        && expected.length > 0 && !expected.includes(block.stateId)) {
+        await sleep(100);
+        block = bot.blockAt(at);
+      }
+      const okName = block?.name === sample.name;
+      const okState = expected.length === 0 || expected.includes(block?.stateId);
+      const shape = block?.shapes ?? [];
+      signatures.set(`${sample.name}\u0000${sample.why}`, JSON.stringify(shape));
+      checks.push({
+        id: 'L2', level: okName && okState && shape.length > 0 ? 'pass' : 'fail',
+        subject: sample.name,
+        message: !okName
+          ? `${sample.why}：服务端/客户端名字对不上（${block?.name ?? 'null'}）`
+          : !okState
+            ? `${sample.why}：stateId ${block?.stateId} 不在 ids 的 ${expected.slice(0, 4).join('/')} 里`
+            : `${sample.why}：${placed.includes('Changed') ? '已放置' : placed}，shape ${shape.length}`,
+      });
+      await cmd(`setblock ${x} ${y} ${z} air replace`);
+    }
+    // 非空还不够：上下两态若被记成同一个 stateId，玩家看到的是半砖/楼梯永远一个朝向，
+    // 而 shape 长度照样 >0。这里把上下两态的形状逐字节比一次（实测 Supplementaries
+    // 的台阶/楼梯靠这条才能区分"读对了"和"都读成默认态"）。
+    for (const [name, kind] of Object.entries({
+      'stairs bottom': 'stairs top',
+      'slab bottom': 'slab top',
+    })) {
+      for (const [key, low] of signatures) {
+        const [subject, why] = key.split('\u0000');
+        if (why !== name) continue;
+        const high = signatures.get(`${subject}\u0000${kind}`);
+        if (high === undefined) continue;
+        checks.push({
+          id: 'L2', level: low !== high ? 'pass' : 'fail', subject,
+          message: low !== high
+            ? `${name.split(' ')[0]} 的上下两态形状不同`
+            : `${name.split(' ')[0]} 的上下两态形状相同（stateId 映射可疑）`,
+        });
+      }
+    }
+
+    const entityName = Object.entries(ids.entities ?? {}).find(([, e]) => !e?.boss)?.[0];
+    if (entityName) {
+      await cmd(`summon ${entityName} ${x + 3} ${y + 1} ${z}`);
+      await sleep(800);
+      const seen = Object.values(bot.entities ?? {}).some((e) => e?.name === entityName);
+      checks.push({
+        id: 'L3', level: seen ? 'pass' : 'fail', subject: entityName,
+        message: seen ? '召唤后 bot.entities 认得出名字' : '召唤后 bot.entities 里找不到这个名字',
+      });
+      await cmd(`kill @e[type=${entityName}]`);
+    } else {
+      checks.push({ id: 'L3', level: 'warn', subject: 'entities', message: 'ids 里没有非 boss 实体可抽样' });
+    }
+  } finally {
+    await cmd(`setblock ${x} ${y} ${z} air replace`).catch(() => undefined);
+    await cmd(`forceload remove ${x - 2} ${z - 2} ${x + 2} ${z + 2}`).catch(() => undefined);
+    cmd.close();
+  }
+  return checks;
+}
+
+/**
+ * @param {{
+ *   manifest: object, ids: object,
+ *   host?: string, port?: number, username?: string, version?: string,
+ *   timeoutMs?: number,
+ *   rcon?: { port: number, password: string, x?: number, y?: number, z?: number } | null,
+ * }} opts
+ */
+export async function liveConformance(opts) {
+  const {
+    manifest, ids,
+    host = '127.0.0.1', port = 25565, username = 'ModConform', version = '1.21.1',
+    timeoutMs = 60_000, rcon = null,
+  } = opts;
+  let bot = null;
+  try {
+    bot = mineflayer.createBot({
+      host, port, username, version, auth: 'offline', viewDistance: 2,
+    });
+    // 与宿主一样：必须在 inject_allowed 之前注入静态注册表。
+    const counts = installModRegistry(bot, { manifest, ids });
+    // prismarine-registry 会复用 minecraft-data 缓存；同进程里先跑过离线验收时，
+    // 注入器可能认为实体已经在了而返回 0。以真实 registry 里的条目为准。
+    counts.entities = Object.keys(ids.entities ?? {})
+      .filter((name) => Boolean(bot.registry?.entitiesByName?.[name])).length;
+    // 只读验证不依赖命令树/实体元数据；大 mod（TF）这两类包会让 protodef 整包错位。
+    installMineflayerFixes(bot, { extraDrop: ['entity_metadata', 'declare_commands'], dropCommands: true });
+    await waitSpawn(bot, timeoutMs);
+    const checks = checkRegistry(manifest, ids, bot.registry, { installed: true });
+    if (rcon?.password) {
+      checks.push(...await sampleWorld({ bot, manifest, ids, rcon, x: rcon.x, y: rcon.y, z: rcon.z }));
+    }
+    return {
+      counts,
+      checks,
+      bot: {
+        username: bot.username,
+        version: bot.version,
+        dimension: String(bot.game?.dimension ?? 'unknown'),
+        position: bot.entity?.position
+          ? {
+            x: Math.round(bot.entity.position.x),
+            y: Math.round(bot.entity.position.y),
+            z: Math.round(bot.entity.position.z),
+          }
+          : null,
+      },
+    };
+  } finally {
+    try { bot?.quit('conformance done'); } catch { /* 已经断开 */ }
+  }
+}