modsmith 0.6.2 → 0.7.1

package/templates/reference-bot/index.mjs

@@ -0,0 +1,59 @@
+/**
+ * 最小参考消费者：不依赖 Cortico，只证明「manifest + ids → 普通 mineflayer bot 能用」。
+ *
+ * 用法（先 npm i modsmith mineflayer）：
+ *   node index.mjs --host 127.0.0.1 --port 25565 \
+ *     --manifest ../../mods/<pack>.json --ids ../../mods/<pack>-ids.json
+ *
+ * 只读：连上、在 inject_allowed 前注入注册表、打印方块形状/实体/boss 检查，然后退出。
+ */
+import { readFileSync } from 'node:fs';
+import mineflayer from 'mineflayer';
+import { installModRegistry, installMineflayerFixes } from 'modsmith';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+const manifestPath = arg('manifest');
+const idsPath = arg('ids');
+if (!manifestPath || !idsPath) {
+  console.error('要 --manifest <manifest.json> --ids <ids.json>');
+  process.exit(2);
+}
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+const ids = JSON.parse(readFileSync(idsPath, 'utf8'));
+const bot = mineflayer.createBot({
+  host: arg('host', '127.0.0.1'),
+  port: Number(arg('port', '25565')),
+  username: arg('username', 'ModReference'),
+  version: arg('version', '1.21.1'),
+  auth: 'offline',
+  viewDistance: 2,
+});
+
+// 必须在 inject_allowed 之前；大 mod 的配方/命令/实体元数据包先丢掉，只读验证不需要。
+const counts = installModRegistry(bot, { manifest, ids });
+installMineflayerFixes(bot, { extraDrop: ['entity_metadata', 'declare_commands'], dropCommands: true });
+
+bot.once('spawn', () => {
+  const blockName = Object.keys(manifest.blocks ?? {})[0];
+  const block = blockName ? bot.registry.blocksByName[blockName] : null;
+  const entityName = Object.keys(ids.entities ?? {})[0];
+  const entity = entityName ? bot.registry.entitiesByName[entityName] : null;
+  console.log(`bot ${bot.username} @ ${bot.version} ${bot.game?.dimension ?? ''}`);
+  console.log(`注入:方块 ${counts.blocks} / 状态 ${counts.states} / 物品 ${counts.items} / 实体 ${counts.entities}`);
+  if (block) {
+    const shapes = bot.registry.blockCollisionShapes?.blocks?.[blockName];
+    console.log(`方块 ${blockName}: states ${block.stateShapes?.length ?? shapes?.length ?? 0}`);
+  }
+  if (entity) console.log(`实体 ${entityName}: ${entity.displayName ?? entity.name}${entity.boss ? ' BOSS' : ''}`);
+  bot.quit('reference done');
+});
+
+bot.on('error', (err) => {
+  console.error(`连接/消费失败：${err.message}`);
+  process.exitCode = 1;
+  try { bot.quit('reference error'); } catch { /* noop */ }
+});

package/templates/registry-dump/README.md

@@ -0,0 +1,48 @@
+# modsmith registry dump
+
+A tiny Fabric **server-side** mod that writes the server's real registry to
+`config/modsmith-dump.json` right after startup:
+
+```json
+{
+  "blocks": { "supplementaries:ash": [{ "props": { "layers": "1" }, "stateId": 63586 }] },
+  "items":  { "supplementaries:ash": 2437 },
+  "entities": {
+    "twilightforest:naga": { "id": 158, "spawnGroup": "monster", "width": 1.2, "height": 2.5 }
+  }
+}
+```
+
+Entities (0.1.2+) are what make mod bosses readable: without them the client only
+sees a number, so a Naga shows up as `unknown` in the bot's logs and tool readouts.
+
+It registers **no blocks or items**, so it does not change the registry. Install
+it once, start the server, take the dump, stop the server and **remove the jar**
+before running the host. Then:
+
+```bash
+modsmith import-dump config/modsmith-dump.json \
+  --manifest mods/<pack>.json \
+  --ids mods/<pack>-ids.json \
+  --server-mods mods
+```
+
+This replaces the hours-long `calibrate` (`setblock` per state) with a seconds-long
+registry read. The prebuilt jar is bundled with modsmith at
+`templates/registry-dump/modsmith-dump-0.1.2.jar` (run `modsmith dump-jar` to print
+its absolute path); it is also attached to the
+[registry-dump-v0.1.2 release](https://github.com/xiaoxiao150/modsmith/releases/tag/registry-dump-v0.1.2).
+`import-dump` still filters: only manifest blocks/items, every entity in that
+namespace, and nothing inside the vanilla ranges (block state ids or entity ids
+0–129).
+
+## Build
+
+```bash
+cd templates/registry-dump
+gradle build        # Java 21, Gradle 8.x
+# jar: build/libs/modsmith-dump-0.1.2.jar
+```
+
+Copy the jar into the server's `mods/`, restart, then check the log for
+`wrote registry dump to .../config/modsmith-dump.json`.

package/templates/registry-dump/build.gradle

@@ -0,0 +1,39 @@
+plugins {
+    id 'fabric-loom' version '1.9-SNAPSHOT'
+    id 'java'
+}
+
+version = '0.1.2'
+group = 'dev.modsmith'
+base {
+    archivesName = 'modsmith-dump'
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    minecraft "com.mojang:minecraft:1.21.1"
+    mappings "net.fabricmc:yarn:1.21.1+build.3:v2"
+    modImplementation "net.fabricmc:fabric-loader:0.16.9"
+    modImplementation "net.fabricmc.fabric-api:fabric-api:0.115.6+1.21.1"
+}
+
+processResources {
+    inputs.property "version", project.version
+    inputs.property "minecraft_version", '1.21.1'
+    filesMatching("fabric.mod.json") {
+        expand "version": project.version, "minecraft_version": '1.21.1'
+    }
+}
+
+tasks.withType(JavaCompile).configureEach {
+    it.options.release = 21
+    it.options.encoding = 'UTF-8'
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_21
+    targetCompatibility = JavaVersion.VERSION_21
+}

package/templates/registry-dump/gradle.properties

@@ -0,0 +1,2 @@
+org.gradle.jvmargs=-Xmx3G
+org.gradle.daemon=false

package/templates/registry-dump/settings.gradle

@@ -0,0 +1,9 @@
+pluginManagement {
+    repositories {
+        maven { url = 'https://maven.fabricmc.net/' }
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+rootProject.name = 'modsmith-dump'

package/templates/registry-dump/src/main/java/dev/modsmith/dump/RegistryDumpMod.java

@@ -0,0 +1,98 @@
+package dev.modsmith.dump;
+
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+import net.fabricmc.api.ModInitializer;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerLifecycleEvents;
+import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.SharedConstants;
+import net.minecraft.block.Block;
+import net.minecraft.block.BlockState;
+import net.minecraft.entity.EntityDimensions;
+import net.minecraft.entity.EntityType;
+import net.minecraft.item.Item;
+import net.minecraft.registry.Registries;
+import net.minecraft.state.property.Property;
+import net.minecraft.util.Identifier;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+
+/**
+ * Writes the server's real registry ids right after it starts.
+ *
+ * Why: measuring 3000+ block states over RCON takes hours. The registry is already
+ * the source of truth, so dump it in one pass. This mod registers no blocks/items,
+ * so it does not change the registry; remove the jar after the dump.
+ */
+public class RegistryDumpMod implements ModInitializer {
+    private static final Logger LOG = LoggerFactory.getLogger("modsmith-dump");
+
+    @Override
+    public void onInitialize() {
+        ServerLifecycleEvents.SERVER_STARTED.register(server -> {
+            try {
+                dump();
+            } catch (Throwable error) {
+                LOG.error("registry dump failed", error);
+            }
+        });
+    }
+
+    private static void dump() throws IOException {
+        JsonObject root = new JsonObject();
+        root.addProperty("schema", 1);
+        root.addProperty("minecraftVersion", SharedConstants.getGameVersion().getName());
+        root.addProperty("dumpMod", "modsmith-dump");
+        root.addProperty("dumpModVersion", "0.1.2");
+
+        JsonObject blocks = new JsonObject();
+        for (Block block : Registries.BLOCK) {
+            Identifier blockId = Registries.BLOCK.getId(block);
+            JsonArray states = new JsonArray();
+            for (BlockState state : block.getStateManager().getStates()) {
+                JsonObject entry = new JsonObject();
+                JsonObject props = new JsonObject();
+                for (Map.Entry<Property<?>, Comparable<?>> prop : state.getEntries().entrySet()) {
+                    props.addProperty(prop.getKey().getName(), prop.getValue().toString());
+                }
+                entry.add("props", props);
+                entry.addProperty("stateId", Block.STATE_IDS.getRawId(state));
+                states.add(entry);
+            }
+            blocks.add(blockId.toString(), states);
+        }
+        root.add("blocks", blocks);
+
+        JsonObject items = new JsonObject();
+        for (Item item : Registries.ITEM) {
+            Identifier itemId = Registries.ITEM.getId(item);
+            items.addProperty(itemId.toString(), Registries.ITEM.getRawId(item));
+        }
+        root.add("items", items);
+
+        // 实体：名字 → 数字 id + 碰撞箱 + 生成组（monster/creature/...）。
+        // 机器人按数字 id 认实体；没有这张表，模组 boss 在她眼里叫 unknown。
+        JsonObject entities = new JsonObject();
+        for (EntityType<?> type : Registries.ENTITY_TYPE) {
+            Identifier typeId = Registries.ENTITY_TYPE.getId(type);
+            EntityDimensions dims = type.getDimensions();
+            JsonObject entry = new JsonObject();
+            entry.addProperty("id", Registries.ENTITY_TYPE.getRawId(type));
+            entry.addProperty("spawnGroup", type.getSpawnGroup().getName());
+            entry.addProperty("width", dims.width());
+            entry.addProperty("height", dims.height());
+            entities.add(typeId.toString(), entry);
+        }
+        root.add("entities", entities);
+
+        Path out = FabricLoader.getInstance().getConfigDir().resolve("modsmith-dump.json");
+        Files.writeString(out, new GsonBuilder().setPrettyPrinting().create().toJson(root));
+        LOG.info("wrote registry dump to {}", out.toAbsolutePath());
+    }
+}

package/templates/registry-dump/src/main/resources/fabric.mod.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "id": "modsmith_dump",
+  "version": "${version}",
+  "name": "modsmith registry dump",
+  "description": "Dump every block state id and item id from the running server registry into config/modsmith-dump.json. Registers no content; remove it after the dump.",
+  "authors": ["modsmith"],
+  "license": "MIT",
+  "environment": "server",
+  "entrypoints": {
+    "main": ["dev.modsmith.dump.RegistryDumpMod"]
+  },
+  "depends": {
+    "fabricloader": ">=0.16.0",
+    "fabric-api": "*",
+    "minecraft": "~${minecraft_version}"
+  }
+}

package/types/index.d.ts

@@ -1,135 +1,174 @@
-/**
- * modsmith 的 TypeScript 面（手写，只声明宿主用到的窄面）。
- * modsmith 本体是 ESM JS；这仨类型按结构最小化，宿主自己的类型（ModManifest 等）
- * 在宿主侧定义，传进来时按需收窄。
- */
-
-export interface RegistryCounts {
-  blocks: number;
-  states: number;
-  items: number;
-}
-
-export interface ModPackLike {
-  manifest: object;
-  ids: object;
-}
-
-/** bot 只按形状使用（bot.registry / bot._client），不依赖 mineflayer 的完整类型。 */
-export function installModRegistry(bot: unknown, pack: ModPackLike): RegistryCounts;
-export function installMineflayerFixes(bot: unknown): void;
-
-/** 从 modsDir（setModsDir 设置，默认 cwd/mods）读 <name>.json 与 <name>-ids.json。 */
-export function loadModPack(name: string): ModPackLike | null;
-export function setModsDir(dir: string): void;
-export function listPacks(): string[];
-
-export interface ManifestIssueLike {
-  level: 'error' | 'warn';
-  path: string;
-  message: string;
-}
-
-export function validateManifest(raw: unknown): ManifestIssueLike[];
-export function hasErrors(issues: ManifestIssueLike[]): boolean;
-export function describeIssues(issues: ManifestIssueLike[]): string[];
-export function parseManifest<T = Record<string, unknown>>(raw: unknown): T | null;
-export function statsOf(manifest: Record<string, unknown>, ids?: Record<string, unknown> | null): Record<string, number>;
-
-/** 服务器 mods 目录指纹：ids.serverMods 的写入与加载侧校验（calibrate --server-mods）。 */
-export interface ServerModsFingerprint {
-  fingerprint: string;
-  files: Array<{ file: string; bytes: number; sha256: string }>;
-}
-export function fingerprintDir(dir: string): ServerModsFingerprint;
-export function checkServerMods(
-  stored: ServerModsFingerprint | undefined,
-  dir: string | undefined,
-): { ok: boolean; fatal: boolean; lines: string[] };
-
-/** 清单 → mineflayer 可消费的合成视图（pattern/key 或候选数组，已归一）。 */
-export interface CraftRecipeView {
-  id?: string;
-  type: 'crafting_shaped' | 'crafting_shapeless';
-  pattern?: string[];
-  key?: Record<string, { item?: string; id?: string; tag?: string } | Array<{ item?: string; id?: string; tag?: string }>>;
-  ingredients?: Array<Array<{ item?: string; id?: string; tag?: string }>>;
-  result: { id: string; count: number };
-}
-export function craftRecipeViews(manifest: object): CraftRecipeView[];
-
-/** 配方依赖图 + 目标规划（宿主 make 技能的输入）。 */
-export interface PlannedStep {
-  skill: 'take' | 'craft' | 'cut' | 'pot' | 'cook' | 'smelt' | 'place' | 'use' | 'pickup';
-  item?: string;
-  items?: string[];
-  recipe?: string;
-  input?: string;
-  fuel?: string;
-  block?: string;
-  times?: number;
-  count?: number;
-}
-export interface PlanResult {
-  ok: boolean;
-  steps: PlannedStep[];
-  missing: Array<{ item: string; reason: string }>;
-  notes: string[];
-}
-export function buildRecipeGraph(
-  manifest: object,
-  opts?: { stations?: Array<{ id: string; kind: string; recipeType?: string; recipeTypes?: string[] }> },
-): { byResult: Map<string, unknown[]>; views: CraftRecipeView[] };
-export function canMake(graph: { byResult: Map<string, unknown[]> }, item: string): boolean;
-export function outputOf(recipe: object): string | null;
-export function outputCountOf(recipe: object): number;
-export function planTarget(
-  graph: { byResult: Map<string, unknown[]> },
-  opts: {
-    item: string;
-    count?: number;
-    have?: Record<string, number>;
-    /** 不在背包、但在够得着的箱子里的东西（缺料时排 take） */
-    stock?: Record<string, number>;
-    stations?: Array<{ id: string; kind: string; recipeType?: string; recipeTypes?: string[] }>;
-    maxSteps?: number;
-  },
-): PlanResult;
-
-/** vanilla 物品数字 id → 全名（minecraft-data 表）。 */
-export function vanillaItemTable(mcVersion?: string): Record<string, string>;
-
-/** 文法发现：未知序列化器的候选（discoverSerializers 的产物，永不自动生效）。 */
-export interface DiscoveredSerializer {
-  typeId: number;
-  fields: Array<{ name: string; kind: string; item?: Array<{ name: string; kind: string }> }>;
-  shape: string | null;
-  occurrences: number;
-  slotIds: number[];
-  packetValidated: boolean;
-}
-export interface DiscoveryResult {
-  ok: boolean;
-  count: number;
-  segments: Array<{ index: number; typeId: number; start: number; end: number; known: boolean; occurrences: number }>;
-  discovered: DiscoveredSerializer[];
-  candidates: Record<string, DiscoveredSerializer[]>;
-  notes: string[];
-  budgetLeft: number;
-}
-export function discoverSerializers(
-  buf: Buffer,
-  opts?: {
-    serializers?: Record<string, { name?: string; fields: Array<{ name: string; kind: string; item?: unknown }> }>;
-    knownItemIds?: Set<number>;
-    maxItemId?: number;
-    maxTypeId?: number;
-    budget?: number;
-    maxCandidates?: number;
-    trace?: (phase: string, info: unknown) => void;
-  },
-): DiscoveryResult;
-export function sidesheetFromDiscovery(
-  result: DiscoveryResult,
-  meta?: { mod?: string },
-): Record<string, unknown>;
+/**
+ * modsmith 的 TypeScript 面（手写，只声明宿主用到的窄面）。
+ * modsmith 本体是 ESM JS；这仨类型按结构最小化，宿主自己的类型（ModManifest 等）
+ * 在宿主侧定义，传进来时按需收窄。
+ */
+
+export interface RegistryCounts {
+  blocks: number;
+  states: number;
+  items: number;
+  /** 模组实体（registry-dump 0.1.2+ 的 entities；老 ids 为 0） */
+  entities: number;
+}
+
+export interface ModPackLike {
+  manifest: object;
+  ids: object;
+}
+
+/** bot 只按形状使用（bot.registry / bot._client），不依赖 mineflayer 的完整类型。 */
+export function installModRegistry(bot: unknown, pack: ModPackLike): RegistryCounts;
+export function installMineflayerFixes(bot: unknown): void;
+
+/** 从 modsDir（setModsDir 设置，默认 cwd/mods）读 <name>.json 与 <name>-ids.json。 */
+export function loadModPack(name: string): ModPackLike | null;
+export function setModsDir(dir: string): void;
+export function listPacks(): string[];
+
+export interface ManifestIssueLike {
+  level: 'error' | 'warn';
+  path: string;
+  message: string;
+}
+
+export function validateManifest(raw: unknown): ManifestIssueLike[];
+export function hasErrors(issues: ManifestIssueLike[]): boolean;
+export function describeIssues(issues: ManifestIssueLike[]): string[];
+export function parseManifest<T = Record<string, unknown>>(raw: unknown): T | null;
+export function statsOf(manifest: Record<string, unknown>, ids?: Record<string, unknown> | null): Record<string, number>;
+
+/** 服务器 mods 目录指纹：ids.serverMods 的写入与加载侧校验（calibrate --server-mods）。 */
+export interface ServerModsFingerprint {
+  fingerprint: string;
+  files: Array<{ file: string; bytes: number; sha256: string }>;
+}
+export function fingerprintDir(dir: string): ServerModsFingerprint;
+export function checkServerMods(
+  stored: ServerModsFingerprint | undefined,
+  dir: string | undefined,
+): { ok: boolean; fatal: boolean; lines: string[] };
+
+/** 清单 → mineflayer 可消费的合成视图（pattern/key 或候选数组，已归一）。 */
+export interface CraftRecipeView {
+  id?: string;
+  type: 'crafting_shaped' | 'crafting_shapeless';
+  pattern?: string[];
+  key?: Record<string, { item?: string; id?: string; tag?: string } | Array<{ item?: string; id?: string; tag?: string }>>;
+  ingredients?: Array<Array<{ item?: string; id?: string; tag?: string }>>;
+  result: { id: string; count: number };
+}
+export function craftRecipeViews(manifest: object): CraftRecipeView[];
+
+/** 配方依赖图 + 目标规划（宿主 make 技能的输入）。 */
+export interface PlannedStep {
+  skill: 'take' | 'craft' | 'cut' | 'pot' | 'cook' | 'smelt' | 'place' | 'use' | 'pickup';
+  item?: string;
+  items?: string[];
+  recipe?: string;
+  input?: string;
+  fuel?: string;
+  block?: string;
+  times?: number;
+  count?: number;
+}
+export interface PlanResult {
+  ok: boolean;
+  steps: PlannedStep[];
+  missing: Array<{ item: string; reason: string }>;
+  notes: string[];
+}
+export function buildRecipeGraph(
+  manifest: object,
+  opts?: { stations?: Array<{ id: string; kind: string; recipeType?: string; recipeTypes?: string[] }> },
+): { byResult: Map<string, unknown[]>; views: CraftRecipeView[] };
+export function canMake(graph: { byResult: Map<string, unknown[]> }, item: string): boolean;
+export function outputOf(recipe: object): string | null;
+export function outputCountOf(recipe: object): number;
+export function planTarget(
+  graph: { byResult: Map<string, unknown[]> },
+  opts: {
+    item: string;
+    count?: number;
+    have?: Record<string, number>;
+    /** 不在背包、但在够得着的箱子里的东西（缺料时排 take） */
+    stock?: Record<string, number>;
+    stations?: Array<{ id: string; kind: string; recipeType?: string; recipeTypes?: string[] }>;
+    maxSteps?: number;
+  },
+): PlanResult;
+
+/** vanilla 物品数字 id → 全名（minecraft-data 表）。 */
+export function vanillaItemTable(mcVersion?: string): Record<string, string>;
+
+/** 文法发现：未知序列化器的候选（discoverSerializers 的产物，永不自动生效）。 */
+export interface DiscoveredSerializer {
+  typeId: number;
+  fields: Array<{ name: string; kind: string; item?: Array<{ name: string; kind: string }> }>;
+  shape: string | null;
+  occurrences: number;
+  slotIds: number[];
+  packetValidated: boolean;
+}
+export interface DiscoveryResult {
+  ok: boolean;
+  count: number;
+  segments: Array<{ index: number; typeId: number; start: number; end: number; known: boolean; occurrences: number }>;
+  discovered: DiscoveredSerializer[];
+  candidates: Record<string, DiscoveredSerializer[]>;
+  notes: string[];
+  budgetLeft: number;
+}
+export function discoverSerializers(
+  buf: Buffer,
+  opts?: {
+    serializers?: Record<string, { name?: string; fields: Array<{ name: string; kind: string; item?: unknown }> }>;
+    knownItemIds?: Set<number>;
+    maxItemId?: number;
+    maxTypeId?: number;
+    budget?: number;
+    maxCandidates?: number;
+    trace?: (phase: string, info: unknown) => void;
+  },
+): DiscoveryResult;
+export function sidesheetFromDiscovery(
+  result: DiscoveryResult,
+  meta?: { mod?: string },
+): Record<string, unknown>;
+
+/** 接包验收（conformance）的一条检查。 */
+export interface ConformanceCheck {
+  id: string;
+  level: 'pass' | 'warn' | 'fail';
+  subject: string;
+  message: string;
+  details?: unknown;
+}
+export interface ConformanceSummary {
+  pass: number;
+  warn: number;
+  fail: number;
+  total: number;
+}
+export interface ConformanceReport {
+  pack: string;
+  summary: ConformanceSummary;
+  checks: ConformanceCheck[];
+  live?: { username: string; version: string; dimension: string; position: unknown };
+  registry?: { blocks: number; states: number; items: number; entities: number };
+}
+export function checkManifest(manifest: object): ConformanceCheck[];
+export function checkIds(
+  manifest: object,
+  ids: object,
+  opts?: { blockStateCeiling?: number; itemCeiling?: number; entityCeiling?: number; serverMods?: string },
+): ConformanceCheck[];
+export function checkRegistry(manifest: object, ids: object, registry: object): ConformanceCheck[];
+export function summarize(checks: ConformanceCheck[]): ConformanceSummary;
+export function runConformance(opts: {
+  manifest: object;
+  ids?: object | null;
+  registry?: object | null;
+  serverMods?: string;
+  mcv?: string;
+}): ConformanceReport;