@kzheart_/mc-pilot 0.9.1 → 0.9.3

package/dist/commands/image.js

@@ -0,0 +1,211 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { PNG } from "pngjs";
+import { wrapCommand } from "../util/command.js";
+import { MctError } from "../util/errors.js";
+import { resolveProjectRelativePath } from "./request-helpers.js";
+function parseRect(value, field) {
+    if (!value)
+        return undefined;
+    const parts = value.split(",").map((part) => Number(part.trim()));
+    if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
+        throw new MctError({ code: "INVALID_PARAMS", message: `${field} must use x,y,w,h format.` }, 4);
+    }
+    return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+function parseRgb(value) {
+    if (!value)
+        return undefined;
+    const parts = value.split(",").map((part) => Number(part.trim()));
+    if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part) || part < 0 || part > 255)) {
+        throw new MctError({ code: "INVALID_PARAMS", message: "--background must use r,g,b format." }, 4);
+    }
+    return [parts[0], parts[1], parts[2]];
+}
+function loadPng(file) {
+    return PNG.sync.read(readFileSync(file));
+}
+function pixelOffset(image, x, y) {
+    return (image.width * y + x) << 2;
+}
+function colorDistance(a, b) {
+    return Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2]);
+}
+function clampRect(rect, image) {
+    const raw = rect ?? { x: 0, y: 0, width: image.width, height: image.height };
+    const x = Math.max(0, Math.min(image.width, Math.floor(raw.x)));
+    const y = Math.max(0, Math.min(image.height, Math.floor(raw.y)));
+    const right = Math.max(x, Math.min(image.width, Math.floor(raw.x + raw.width)));
+    const bottom = Math.max(y, Math.min(image.height, Math.floor(raw.y + raw.height)));
+    return { x, y, width: right - x, height: bottom - y };
+}
+function findForegroundBounds(image, options) {
+    const region = clampRect(options.region, image);
+    const background = options.background ?? [
+        image.data[pixelOffset(image, 0, 0)],
+        image.data[pixelOffset(image, 0, 0) + 1],
+        image.data[pixelOffset(image, 0, 0) + 2]
+    ];
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = -1;
+    let maxY = -1;
+    let pixels = 0;
+    for (let y = region.y; y < region.y + region.height; y++) {
+        for (let x = region.x; x < region.x + region.width; x++) {
+            const offset = pixelOffset(image, x, y);
+            const a = image.data[offset + 3];
+            const rgb = [image.data[offset], image.data[offset + 1], image.data[offset + 2]];
+            if (a > options.alphaThreshold && colorDistance(rgb, background) > options.threshold) {
+                minX = Math.min(minX, x);
+                minY = Math.min(minY, y);
+                maxX = Math.max(maxX, x);
+                maxY = Math.max(maxY, y);
+                pixels++;
+            }
+        }
+    }
+    if (pixels === 0)
+        return null;
+    return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1, pixels };
+}
+function collectTemplatePixels(template, alphaThreshold, maxSamples) {
+    const pixels = [];
+    for (let y = 0; y < template.height; y++) {
+        for (let x = 0; x < template.width; x++) {
+            const offset = pixelOffset(template, x, y);
+            if (template.data[offset + 3] > alphaThreshold) {
+                pixels.push({ x, y, r: template.data[offset], g: template.data[offset + 1], b: template.data[offset + 2] });
+            }
+        }
+    }
+    if (pixels.length <= maxSamples)
+        return pixels;
+    const stride = pixels.length / maxSamples;
+    const sampled = [];
+    for (let i = 0; i < maxSamples; i++) {
+        sampled.push(pixels[Math.floor(i * stride)]);
+    }
+    return sampled;
+}
+function scoreTemplateAt(screenshot, samples, x, y, scale) {
+    let score = 0;
+    let compared = 0;
+    for (const sample of samples) {
+        const sx = Math.round(x + sample.x * scale);
+        const sy = Math.round(y + sample.y * scale);
+        if (sx < 0 || sy < 0 || sx >= screenshot.width || sy >= screenshot.height)
+            continue;
+        const offset = pixelOffset(screenshot, sx, sy);
+        score += Math.abs(screenshot.data[offset] - sample.r) +
+            Math.abs(screenshot.data[offset + 1] - sample.g) +
+            Math.abs(screenshot.data[offset + 2] - sample.b);
+        compared++;
+    }
+    return compared === 0 ? Number.POSITIVE_INFINITY : score / compared;
+}
+export function createImageCommand() {
+    const command = new Command("image").description("Image analysis helpers for screenshots and UI offset tuning");
+    command
+        .command("bbox")
+        .description("Find the foreground bounding box in a PNG image")
+        .argument("<image>", "PNG image path")
+        .option("--background <rgb>", "Background color to ignore, format r,g,b. Defaults to top-left pixel.")
+        .option("--threshold <value>", "RGB distance threshold", (value) => Number(value), 24)
+        .option("--alpha-threshold <value>", "Alpha threshold", (value) => Number(value), 8)
+        .option("--region <rect>", "Optional scan region x,y,w,h")
+        .action(wrapCommand(async (context, { args, options }) => {
+        const imagePath = resolveProjectRelativePath(context, args[0] ?? "");
+        const image = loadPng(imagePath);
+        const bbox = findForegroundBounds(image, {
+            background: parseRgb(options.background),
+            threshold: Number(options.threshold),
+            alphaThreshold: Number(options.alphaThreshold),
+            region: parseRect(options.region, "--region")
+        });
+        return {
+            image: path.resolve(imagePath),
+            size: { width: image.width, height: image.height },
+            bbox,
+            center: bbox ? { x: bbox.x + bbox.width / 2, y: bbox.y + bbox.height / 2 } : null
+        };
+    }));
+    command
+        .command("locate-template")
+        .description("Locate a transparent PNG template inside a screenshot, useful for tuning GUI title offsets")
+        .argument("<screenshot>", "Screenshot PNG path")
+        .argument("<template>", "Template PNG path")
+        .option("--region <rect>", "Screenshot search region x,y,w,h")
+        .option("--expected <rect>", "Expected rectangle x,y,w,h; output includes delta from it")
+        .option("--scale <value>", "Single scale to test", (value) => Number(value))
+        .option("--min-scale <value>", "Minimum scale", (value) => Number(value), 0.5)
+        .option("--max-scale <value>", "Maximum scale", (value) => Number(value), 3)
+        .option("--scale-step <value>", "Scale step", (value) => Number(value), 0.1)
+        .option("--stride <pixels>", "Search stride in screenshot pixels", (value) => Number(value), 2)
+        .option("--alpha-threshold <value>", "Template alpha threshold", (value) => Number(value), 16)
+        .option("--max-samples <count>", "Maximum template pixels to sample", (value) => Number(value), 4000)
+        .action(wrapCommand(async (context, { args, options }) => {
+        const screenshotPath = resolveProjectRelativePath(context, args[0] ?? "");
+        const templatePath = resolveProjectRelativePath(context, args[1] ?? "");
+        const screenshot = loadPng(screenshotPath);
+        const template = loadPng(templatePath);
+        const region = clampRect(parseRect(options.region, "--region"), screenshot);
+        const expected = parseRect(options.expected, "--expected");
+        const samples = collectTemplatePixels(template, Number(options.alphaThreshold), Number(options.maxSamples));
+        if (samples.length === 0) {
+            throw new MctError({ code: "INVALID_PARAMS", message: "Template has no visible pixels after alpha filtering." }, 4);
+        }
+        const scales = options.scale
+            ? [Number(options.scale)]
+            : Array.from({ length: Math.max(1, Math.floor((Number(options.maxScale) - Number(options.minScale)) / Number(options.scaleStep)) + 1) }, (_, index) => Number((Number(options.minScale) + index * Number(options.scaleStep)).toFixed(4)));
+        let best;
+        for (const scale of scales) {
+            const width = Math.round(template.width * scale);
+            const height = Math.round(template.height * scale);
+            for (let y = region.y - height; y <= region.y + region.height; y += Number(options.stride)) {
+                for (let x = region.x - width; x <= region.x + region.width; x += Number(options.stride)) {
+                    const score = scoreTemplateAt(screenshot, samples, x, y, scale);
+                    if (!best || score < best.score) {
+                        best = { x, y, scale, score, compared: samples.length };
+                    }
+                }
+            }
+        }
+        if (!best) {
+            throw new MctError({ code: "INVALID_STATE", message: "No template match candidate found." }, 3);
+        }
+        const bbox = {
+            x: best.x,
+            y: best.y,
+            width: Math.round(template.width * best.scale),
+            height: Math.round(template.height * best.scale)
+        };
+        const center = { x: bbox.x + bbox.width / 2, y: bbox.y + bbox.height / 2 };
+        const expectedCenter = expected ? { x: expected.x + expected.width / 2, y: expected.y + expected.height / 2 } : undefined;
+        return {
+            screenshot: path.resolve(screenshotPath),
+            template: path.resolve(templatePath),
+            screenshotSize: { width: screenshot.width, height: screenshot.height },
+            templateSize: { width: template.width, height: template.height },
+            samples: samples.length,
+            match: {
+                bbox,
+                center,
+                scale: best.scale,
+                score: Number(best.score.toFixed(3))
+            },
+            expected: expected
+                ? {
+                    bbox: expected,
+                    center: expectedCenter,
+                    delta: {
+                        x: Number((center.x - expectedCenter.x).toFixed(3)),
+                        y: Number((center.y - expectedCenter.y).toFixed(3))
+                    }
+                }
+                : undefined
+        };
+    }));
+    return command;
+}

package/dist/download/VersionMatrix.d.ts

@@ -40,21 +40,7 @@ export interface ClientSearchResult {
     notes?: string;
     javaVersion: string;
 }
-export declare function getVersionMatrix(): {
-    minecraftVersion: string;
-    javaVersion: string;
-    servers: {
-        paper: ServerSupportInfo;
-        purpur: ServerSupportInfo;
-        vanilla: ServerSupportInfo;
-        spigot: ServerSupportInfo;
-    };
-    clients: {
-        fabric: ClientLoaderSupportInfo;
-        forge: ClientLoaderSupportInfo;
-        neoforge: ClientLoaderSupportInfo;
-    };
-}[];
+export declare function getVersionMatrix(): MinecraftSupportEntry[];
 export declare function getSupportedMinecraftVersions(): string[];
 export declare function getMinecraftSupport(version: string): MinecraftSupportEntry | undefined;
 export declare function searchServerVersions(filter?: {

package/dist/download/VersionMatrix.js

@@ -41,7 +41,7 @@ const VERSION_MATRIX = [
         },
         clients: {
             fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1" },
-            forge: { supported: true, loaderVersion: "49.0.49", modVersion: "0.9.1" },
+            forge: { supported: true, loaderVersion: "49.0.49", modVersion: "0.9.1", validation: "limited" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -56,7 +56,7 @@ const VERSION_MATRIX = [
         },
         clients: {
             fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1", validation: "verified" },
-            forge: { supported: false, notes: "当前未接入此 loader" },
+            forge: { supported: true, loaderVersion: "48.1.0", modVersion: "0.9.1", validation: "limited" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -86,7 +86,7 @@ const VERSION_MATRIX = [
         },
         clients: {
             fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1" },
-            forge: { supported: true, loaderVersion: "47.x", modVersion: "0.9.1" },
+            forge: { supported: true, loaderVersion: "47.3.0", modVersion: "0.9.1", validation: "limited" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -150,8 +150,8 @@ function overlayClientSupport(entry, loader) {
         notes: variant.notes
     };
 }
-export function getVersionMatrix() {
-    return VERSION_MATRIX.map((entry) => ({
+function overlayMinecraftSupport(entry) {
+    return {
         minecraftVersion: entry.minecraftVersion,
         javaVersion: entry.javaVersion,
         servers: { ...entry.servers },
@@ -160,13 +160,17 @@ export function getVersionMatrix() {
             forge: overlayClientSupport(entry, "forge"),
             neoforge: overlayClientSupport(entry, "neoforge")
         }
-    }));
+    };
+}
+export function getVersionMatrix() {
+    return VERSION_MATRIX.map((entry) => overlayMinecraftSupport(entry));
 }
 export function getSupportedMinecraftVersions() {
     return VERSION_MATRIX.map((entry) => entry.minecraftVersion);
 }
 export function getMinecraftSupport(version) {
-    return VERSION_MATRIX.find((entry) => entry.minecraftVersion === version);
+    const entry = VERSION_MATRIX.find((candidate) => candidate.minecraftVersion === version);
+    return entry ? overlayMinecraftSupport(entry) : undefined;
 }
 export function searchServerVersions(filter) {
     const types = filter?.type ? [filter.type] : getServerTypes();

package/dist/download/client/ClientDownloader.d.ts

@@ -1,7 +1,7 @@
 import { CacheManager } from "../CacheManager.js";
 import { detectJava } from "../JavaDetector.js";
 import type { LoaderType, ModVariant } from "../types.js";
-import { prepareManagedFabricRuntime } from "./FabricRuntimeDownloader.js";
+import { prepareManagedClientRuntime } from "./FabricRuntimeDownloader.js";
 export interface DownloadClientOptions {
     loader?: LoaderType;
     version?: string;
@@ -20,7 +20,7 @@ export interface DownloadClientDependencies {
     cacheManager?: CacheManager;
     detectJavaImpl?: typeof detectJava;
     fetchImpl?: typeof fetch;
-    prepareManagedRuntimeImpl?: typeof prepareManagedFabricRuntime;
+    prepareManagedRuntimeImpl?: typeof prepareManagedClientRuntime;
 }
 export declare function resolveArtifact(cwd: string, variant: ModVariant, cacheManager: CacheManager, fetchImpl?: typeof fetch): Promise<{
     sourcePath: string;

package/dist/download/client/ClientDownloader.js

@@ -7,7 +7,7 @@ import { CacheManager } from "../CacheManager.js";
 import { copyFileIfMissing, downloadFile } from "../DownloadUtils.js";
 import { detectJava } from "../JavaDetector.js";
 import { findVariantByVersionAndLoader, getDefaultVariant, getModArtifactFileName, loadModVariantCatalog } from "../ModVariantCatalog.js";
-import { prepareManagedFabricRuntime } from "./FabricRuntimeDownloader.js";
+import { prepareManagedClientRuntime } from "./FabricRuntimeDownloader.js";
 function getLaunchScriptPath() {
     const thisFile = fileURLToPath(import.meta.url);
     // dist/download/client/ClientDownloader.js -> scripts/launch-fabric-client.mjs
@@ -15,13 +15,27 @@ function getLaunchScriptPath() {
 }
 const GITHUB_RELEASE_BASE_URL = process.env.MCT_MOD_DOWNLOAD_BASE_URL || "https://github.com/kzheart/mc-pilot/releases/download";
 function ensureSupportedVariant(variant) {
-    if (variant.loader !== "fabric") {
+    if (variant.support !== "ready" && variant.support !== "configured") {
         throw new MctError({
-            code: "UNSUPPORTED_LOADER",
-            message: `Loader ${variant.loader} is not implemented yet`
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} is not buildable yet`,
+            details: {
+                support: variant.support,
+                validation: variant.validation
+            }
+        }, 4);
+    }
+    if (variant.loader === "fabric" && (!variant.fabricLoaderVersion || !variant.yarnMappings)) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} is not buildable yet`,
+            details: {
+                support: variant.support,
+                validation: variant.validation
+            }
         }, 4);
     }
-    if (!variant.fabricLoaderVersion || !variant.yarnMappings) {
+    if (variant.loader === "forge" && !variant.forgeVersion) {
         throw new MctError({
             code: "VARIANT_NOT_BUILDABLE",
             message: `Variant ${variant.id} is not buildable yet`,
@@ -31,6 +45,12 @@ function ensureSupportedVariant(variant) {
             }
         }, 4);
     }
+    if (variant.loader !== "fabric" && variant.loader !== "forge") {
+        throw new MctError({
+            code: "UNSUPPORTED_LOADER",
+            message: `Loader ${variant.loader} is not implemented yet`
+        }, 4);
+    }
 }
 export async function resolveArtifact(cwd, variant, cacheManager, fetchImpl = fetch) {
     const artifactFileName = getModArtifactFileName(variant);
@@ -114,6 +134,12 @@ function resolveLaunchRuntimePaths(cwd, options) {
     };
 }
 function buildLaunchArgs(runtimePaths, variant) {
+    if (variant.loader !== "fabric") {
+        throw new MctError({
+            code: "INVALID_PARAMS",
+            message: `Custom runtime directories are not supported for ${variant.loader} clients yet`
+        }, 4);
+    }
     return [
         "--instance-dir",
         runtimePaths.instanceDir,
@@ -169,11 +195,13 @@ export async function downloadClientModToDir(cwd, targetDir, options, dependenci
     const cacheManager = dependencies.cacheManager ?? new CacheManager();
     const detectJavaImpl = dependencies.detectJavaImpl ?? detectJava;
     const fetchImpl = dependencies.fetchImpl ?? fetch;
-    const prepareManagedRuntimeImpl = dependencies.prepareManagedRuntimeImpl ?? prepareManagedFabricRuntime;
+    const prepareManagedRuntimeImpl = dependencies.prepareManagedRuntimeImpl ?? prepareManagedClientRuntime;
     const catalog = await loadModVariantCatalog();
     const variant = options.version
         ? findVariantByVersionAndLoader(catalog, options.version, loader)
-        : getDefaultVariant(catalog);
+        : loader === "fabric"
+            ? getDefaultVariant(catalog)
+            : undefined;
     if (!variant) {
         throw new MctError({
             code: "VARIANT_NOT_FOUND",

package/dist/download/client/FabricRuntimeDownloader.d.ts

@@ -12,3 +12,5 @@ export interface PrepareFabricRuntimeOptions {
     gameDir: string;
 }
 export declare function prepareManagedFabricRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;
+export declare function prepareManagedForgeRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;
+export declare function prepareManagedClientRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;

package/dist/download/client/FabricRuntimeDownloader.js

@@ -2,7 +2,7 @@ import { access, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { MinecraftFolder, Version } from "@xmcl/core";
-import { getVersionList, installDependencies, installFabric, installVersion } from "@xmcl/installer";
+import { getVersionList, installDependencies, installFabric, installForge, installVersion } from "@xmcl/installer";
 import { Agent, interceptors } from "undici";
 import { MctError } from "../../util/errors.js";
 import { applyArm64LwjglPatch } from "./Arm64LwjglPatcher.js";
@@ -42,19 +42,11 @@ async function fetchWithRetry(input, init, attempts = 4) {
     }
     throw lastError;
 }
-export async function prepareManagedFabricRuntime(variant, runtimeOptions, dependencies = {}) {
+async function prepareManagedRuntime(variant, runtimeOptions, dependencies, expectedVersionId, installLoader) {
     const fetchImpl = dependencies.fetchImpl ?? fetchWithRetry;
-    const loaderVersion = variant.fabricLoaderVersion;
-    if (!loaderVersion) {
-        throw new MctError({
-            code: "VARIANT_NOT_BUILDABLE",
-            message: `Variant ${variant.id} does not define a Fabric loader version`
-        }, 4);
-    }
     const { runtimeRootDir, gameDir } = runtimeOptions;
     await mkdir(runtimeRootDir, { recursive: true });
     await mkdir(gameDir, { recursive: true });
-    const expectedVersionId = `${variant.minecraftVersion}-fabric${loaderVersion}`;
     const readyMarker = path.join(runtimeRootDir, `.ready-${expectedVersionId}`);
     try {
         await access(readyMarker);
@@ -77,13 +69,7 @@ export async function prepareManagedFabricRuntime(variant, runtimeOptions, depen
         side: "client",
         dispatcher: DOWNLOAD_DISPATCHER
     });
-    const installedVersionId = await installFabric({
-        minecraftVersion: variant.minecraftVersion,
-        version: loaderVersion,
-        minecraft,
-        side: "client",
-        fetch: fetchImpl
-    });
+    const installedVersionId = await installLoader(minecraft, fetchImpl);
     const resolvedVersion = await Version.parse(minecraft, installedVersionId);
     await installDependencies(resolvedVersion, {
         side: "client",
@@ -99,3 +85,47 @@ export async function prepareManagedFabricRuntime(variant, runtimeOptions, depen
         versionId: installedVersionId
     };
 }
+export async function prepareManagedFabricRuntime(variant, runtimeOptions, dependencies = {}) {
+    const loaderVersion = variant.fabricLoaderVersion;
+    if (!loaderVersion) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} does not define a Fabric loader version`
+        }, 4);
+    }
+    return prepareManagedRuntime(variant, runtimeOptions, dependencies, `${variant.minecraftVersion}-fabric${loaderVersion}`, (minecraft, fetchImpl) => installFabric({
+        minecraftVersion: variant.minecraftVersion,
+        version: loaderVersion,
+        minecraft,
+        side: "client",
+        fetch: fetchImpl
+    }));
+}
+export async function prepareManagedForgeRuntime(variant, runtimeOptions, dependencies = {}) {
+    const forgeVersion = variant.forgeVersion;
+    if (!forgeVersion) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} does not define a Forge version`
+        }, 4);
+    }
+    return prepareManagedRuntime(variant, runtimeOptions, dependencies, `${variant.minecraftVersion}-forge-${forgeVersion}`, (minecraft) => installForge({
+        mcversion: variant.minecraftVersion,
+        version: forgeVersion
+    }, minecraft, {
+        side: "client",
+        dispatcher: DOWNLOAD_DISPATCHER
+    }));
+}
+export async function prepareManagedClientRuntime(variant, runtimeOptions, dependencies = {}) {
+    if (variant.loader === "fabric") {
+        return prepareManagedFabricRuntime(variant, runtimeOptions, dependencies);
+    }
+    if (variant.loader === "forge") {
+        return prepareManagedForgeRuntime(variant, runtimeOptions, dependencies);
+    }
+    throw new MctError({
+        code: "UNSUPPORTED_LOADER",
+        message: `Loader ${variant.loader} is not implemented yet`
+    }, 4);
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { createEntityCommand } from "./commands/entity.js";
 import { createEventsCommand } from "./commands/events.js";
 import { createGuiCommand } from "./commands/gui.js";
 import { createHudCommand } from "./commands/hud.js";
+import { createImageCommand } from "./commands/image.js";
 import { createInputCommand } from "./commands/input.js";
 import { createInventoryCommand } from "./commands/inventory.js";
 import { createLookCommand } from "./commands/look.js";
@@ -83,6 +84,7 @@ export function buildProgram() {
     program.addCommand(createEntityCommand());
     program.addCommand(createInventoryCommand());
     program.addCommand(createGuiCommand());
+    program.addCommand(createImageCommand());
     program.addCommand(createScreenshotCommand());
     program.addCommand(createScreenCommand());
     program.addCommand(createHudCommand());

package/dist/instance/ClientInstanceManager.d.ts

@@ -7,6 +7,7 @@ export interface CreateClientOptions {
     wsPort?: number;
     account?: string;
     headless?: boolean;
+    mute?: boolean;
     launchArgs?: string[];
     env?: Record<string, string>;
 }
@@ -15,6 +16,7 @@ export interface LaunchClientOptions {
     account?: string;
     wsPort?: number;
     headless?: boolean;
+    mute?: boolean;
     force?: boolean;
 }
 export interface WaitReadyOptions {

package/dist/instance/ClientInstanceManager.js

@@ -30,6 +30,7 @@ export class ClientInstanceManager {
                 wsPort,
                 account: options.account,
                 headless: options.headless,
+                mute: options.mute,
                 launchArgs: options.launchArgs,
                 env: options.env,
                 createdAt: new Date().toISOString()
@@ -57,6 +58,7 @@ export class ClientInstanceManager {
             const meta = await this.loadMeta(clientName);
             const instanceDir = resolveClientInstanceDir(clientName);
             const wsPort = options.wsPort ?? meta.wsPort;
+            const mute = options.mute ?? meta.mute;
             if (!meta.launchArgs || meta.launchArgs.length === 0) {
                 throw new MctError({ code: "INVALID_PARAMS", message: `Client ${clientName} has no launchArgs configured` }, 4);
             }
@@ -91,7 +93,8 @@ export class ClientInstanceManager {
                     MCT_CLIENT_ACCOUNT: options.account ?? meta.account ?? "",
                     MCT_CLIENT_SERVER: options.server ?? "",
                     MCT_CLIENT_WS_PORT: String(wsPort),
-                    MCT_CLIENT_HEADLESS: String(options.headless ?? meta.headless ?? false)
+                    MCT_CLIENT_HEADLESS: String(options.headless ?? meta.headless ?? false),
+                    ...(mute === undefined ? {} : { MCT_CLIENT_MUTE: String(mute) })
                 }
             });
             child.unref();

package/dist/schema.js

@@ -1,11 +1,11 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-function resolveRepoRoot() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+function resolvePackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 }
 function loadJsonFile(relativePath) {
-    const filePath = path.join(resolveRepoRoot(), relativePath);
+    const filePath = path.join(resolvePackageRoot(), relativePath);
     return JSON.parse(readFileSync(filePath, "utf8"));
 }
 function serializeOption(option) {
@@ -55,9 +55,9 @@ function collectLeafCommands(commands) {
     return leaves;
 }
 export function buildSchemaDocument(program) {
-    const actions = loadJsonFile("protocol/actions.json");
-    const queries = loadJsonFile("protocol/queries.json");
-    const errors = loadJsonFile("protocol/errors.json");
+    const actions = loadJsonFile("data/protocol/actions.json");
+    const queries = loadJsonFile("data/protocol/queries.json");
+    const errors = loadJsonFile("data/protocol/errors.json");
     const commands = program.commands.map((command) => serializeCommand(command));
     return {
         schemaVersion: 1,

package/dist/util/instance-types.d.ts

@@ -16,6 +16,7 @@ export interface ClientInstanceMeta {
     wsPort: number;
     account?: string;
     headless?: boolean;
+    mute?: boolean;
     launchArgs?: string[];
     env?: Record<string, string>;
     createdAt: string;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@kzheart_/mc-pilot",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
   "type": "module",
   "bin": {
-    "mct": "./bin/mct"
+    "mct": "bin/mct"
   },
   "files": [
     "bin/",
@@ -27,7 +27,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/kzheart/mc-pilot.git",
+    "url": "git+https://github.com/kzheart/mc-pilot.git",
     "directory": "cli"
   },
   "license": "MIT",
@@ -44,10 +44,12 @@
     "@xmcl/file-transfer": "^2.0.3",
     "@xmcl/installer": "^6.1.2",
     "commander": "^14.0.1",
+    "pngjs": "^7.0.0",
     "ws": "^8.19.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2"