@kzheart_/mc-pilot 0.9.1 → 0.9.2

package/data/variants.json

@@ -31,11 +31,12 @@
       "id": "1.20.1-forge",
       "minecraftVersion": "1.20.1",
       "loader": "forge",
-      "support": "planned",
-      "validation": "planned",
+      "support": "configured",
+      "validation": "limited",
       "modVersion": "0.9.1",
       "forgeVersion": "47.3.0",
-      "javaVersion": 17
+      "javaVersion": 17,
+      "gradleModule": "version-1.20.1-forge"
     },
     {
       "id": "1.20.2-fabric",
@@ -53,11 +54,12 @@
       "id": "1.20.2-forge",
       "minecraftVersion": "1.20.2",
       "loader": "forge",
-      "support": "planned",
-      "validation": "planned",
+      "support": "configured",
+      "validation": "limited",
       "modVersion": "0.9.1",
       "forgeVersion": "48.1.0",
-      "javaVersion": 17
+      "javaVersion": 17,
+      "gradleModule": "version-1.20.2-forge"
     },
     {
       "id": "1.20.4-fabric",
@@ -75,11 +77,12 @@
       "id": "1.20.4-forge",
       "minecraftVersion": "1.20.4",
       "loader": "forge",
-      "support": "planned",
-      "validation": "planned",
+      "support": "configured",
+      "validation": "limited",
       "modVersion": "0.9.1",
       "forgeVersion": "49.0.49",
-      "javaVersion": 17
+      "javaVersion": 17,
+      "gradleModule": "version-1.20.4-forge"
     },
     {
       "id": "1.20.4-neoforge",

package/dist/commands/client.js

@@ -5,14 +5,8 @@ import { ServerInstanceManager } from "../instance/ServerInstanceManager.js";
 import { MctError } from "../util/errors.js";
 import { createRequestAction } from "./request-helpers.js";
 import { wrapCommand } from "../util/command.js";
-import { CacheManager } from "../download/CacheManager.js";
-import { findVariantByVersionAndLoader, getModArtifactFileName, loadModVariantCatalog } from "../download/ModVariantCatalog.js";
-import { detectJava } from "../download/JavaDetector.js";
-import { prepareManagedFabricRuntime } from "../download/client/FabricRuntimeDownloader.js";
-import { copyFileIfMissing, downloadFile } from "../download/DownloadUtils.js";
+import { downloadClientModToDir } from "../download/client/ClientDownloader.js";
 import { resolveClientInstanceDir } from "../util/paths.js";
-import { access, mkdir } from "node:fs/promises";
-import path from "node:path";
 export async function resolveProfileServerAddress(context, explicitServer, loadPort) {
     if (explicitServer) {
         return explicitServer;
@@ -50,93 +44,46 @@ export function createClientCommand() {
         .description("Create a new client instance")
         .argument("<name>", "Client instance name (e.g. fabric-1.20.4)")
         .option("--version <version>", "Minecraft version (default: 1.21.4)")
-        .option("--loader <loader>", "Client loader: fabric (default: fabric)")
+        .option("--loader <loader>", "Client loader: fabric|forge (default: fabric)")
         .option("--ws-port <port>", "WebSocket port (auto-assigned if omitted)", Number)
         .option("--account <account>", "Offline username or account identifier")
         .option("--headless", "Launch in headless mode")
+        .option("--mute", "Mute all in-game audio for this client")
+        .option("--no-mute", "Keep in-game audio enabled for this client")
         .option("--java <command>", "Java command to use")
         .action(wrapCommand(async (_context, { args, options }) => {
         const clientName = args[0];
         const loader = options.loader ?? "fabric";
         const version = options.version ?? "1.21.4";
-        const cacheManager = new CacheManager();
-        const catalog = await loadModVariantCatalog();
-        const variant = findVariantByVersionAndLoader(catalog, version, loader);
-        if (!variant) {
-            throw new MctError({ code: "VARIANT_NOT_FOUND", message: `No mod variant found for ${version} / ${loader}` }, 4);
-        }
-        if (variant.loader !== "fabric") {
-            throw new MctError({ code: "UNSUPPORTED_LOADER", message: `Loader ${variant.loader} is not implemented yet` }, 4);
-        }
-        // Check Java
-        const java = await detectJava(options.java ?? "java");
-        const requiredJava = variant.javaVersion ?? 17;
-        if (!java.available || (java.majorVersion ?? 0) < requiredJava) {
-            throw new MctError({ code: "JAVA_NOT_FOUND", message: `Java ${requiredJava}+ is required for ${variant.id}` }, 4);
-        }
-        // Resolve mod artifact
-        const artifactFileName = getModArtifactFileName(variant);
-        const cacheArtifactPath = cacheManager.getModFile(artifactFileName);
-        const gradleModule = variant.gradleModule ?? `version-${variant.minecraftVersion}`;
-        const localBuildPath = path.join(process.cwd(), "client-mod", gradleModule, "build", "libs", artifactFileName);
-        let sourcePath;
-        try {
-            await access(localBuildPath);
-            sourcePath = localBuildPath;
-            await copyFileIfMissing(localBuildPath, cacheArtifactPath);
-        }
-        catch {
-            try {
-                await access(cacheArtifactPath);
-                sourcePath = cacheArtifactPath;
-            }
-            catch {
-                const modVersion = variant.modVersion ?? "0.9.1";
-                const baseUrl = process.env.MCT_MOD_DOWNLOAD_BASE_URL || "https://github.com/kzheart/mc-pilot/releases/download";
-                const downloadUrl = `${baseUrl}/v${modVersion}/${artifactFileName}`;
-                await downloadFile(downloadUrl, cacheArtifactPath, fetch);
-                sourcePath = cacheArtifactPath;
-            }
-        }
-        // Set up client instance directory
         const instanceDir = resolveClientInstanceDir(clientName);
-        const minecraftDir = path.join(instanceDir, "minecraft");
-        const modsDir = path.join(minecraftDir, "mods");
-        await mkdir(modsDir, { recursive: true });
-        await copyFileIfMissing(sourcePath, path.join(modsDir, artifactFileName));
-        // Prepare Fabric runtime
-        const runtimeRootDir = path.join(cacheManager.getRootDir(), "client", "runtime", variant.minecraftVersion);
-        const managedRuntime = await prepareManagedFabricRuntime(variant, {
-            runtimeRootDir,
-            gameDir: minecraftDir
-        }, { fetchImpl: fetch });
-        const launchArgs = [
-            "--runtime-root", managedRuntime.runtimeRootDir,
-            "--version-id", managedRuntime.versionId,
-            "--game-dir", managedRuntime.gameDir
-        ];
+        const downloaded = await downloadClientModToDir(process.cwd(), instanceDir, {
+            version,
+            loader,
+            java: options.java
+        });
         const manager = new ClientInstanceManager(_context.globalState);
         const meta = await manager.create({
             name: clientName,
-            loader,
-            version: variant.minecraftVersion,
+            loader: downloaded.loader,
+            version: downloaded.minecraftVersion,
             wsPort: options.wsPort,
             account: options.account,
             headless: options.headless,
-            launchArgs,
+            mute: options.mute,
+            launchArgs: downloaded.launchArgs,
             env: {
-                MCT_CLIENT_MOD_VARIANT: variant.id,
-                MCT_CLIENT_MOD_JAR: path.join(modsDir, artifactFileName)
+                MCT_CLIENT_MOD_VARIANT: downloaded.variantId,
+                MCT_CLIENT_MOD_JAR: downloaded.jar
             }
         });
         return {
             created: true,
             ...meta,
-            javaCommand: java.command,
-            javaVersion: java.majorVersion,
-            modsDir,
-            runtimeRootDir: managedRuntime.runtimeRootDir,
-            runtimeVersionId: managedRuntime.versionId
+            javaCommand: downloaded.javaCommand,
+            javaVersion: downloaded.javaVersion,
+            modsDir: downloaded.modsDir,
+            runtimeRootDir: downloaded.runtimeRootDir,
+            runtimeVersionId: downloaded.runtimeVersionId
         };
     }));
     command
@@ -147,6 +94,8 @@ export function createClientCommand() {
         .option("--account <account>", "Offline username or account identifier")
         .option("--ws-port <port>", "WebSocket port override", Number)
         .option("--headless", "Launch in headless mode")
+        .option("--mute", "Mute all in-game audio for this launch")
+        .option("--no-mute", "Keep in-game audio enabled for this launch")
         .option("--force", "Kill any existing client with the same name before launching")
         .action(wrapCommand(async (context, { args, options }) => {
         const clientName = args[0] ?? context.activeProfile?.clients[0];

package/dist/commands/image.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createImageCommand(): Command;

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/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,6 +1,6 @@
 {
   "name": "@kzheart_/mc-pilot",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
   "type": "module",
   "bin": {
@@ -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"

package/scripts/launch-fabric-client.mjs

@@ -106,6 +106,21 @@ function substitute(template, variables) {
   return template.replace(/\$\{([^}]+)\}/g, (_, key) => variables[key] ?? "");
 }
 
+function parseOptionalBoolean(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (["true", "1", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["false", "0", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return undefined;
+}
+
 async function ensureFile(filePath, downloadUrl) {
   try {
     await access(filePath);
@@ -170,7 +185,7 @@ async function syncConfiguredMod(gameDir) {
   await copyFile(sourceJar, targetJar);
 }
 
-async function ensureAutomationOptions(gameDir, server) {
+async function ensureAutomationOptions(gameDir, server, mute) {
   const optionsPath = path.join(gameDir, "options.txt");
   const values = new Map();
 
@@ -191,6 +206,23 @@ async function ensureAutomationOptions(gameDir, server) {
   values.set("joinedFirstServer", "true");
   values.set("tutorialStep", "none");
   values.set("pauseOnLostFocus", "false");
+  if (mute !== undefined) {
+    const volume = mute ? "0.0" : "1.0";
+    for (const category of [
+      "master",
+      "music",
+      "record",
+      "weather",
+      "block",
+      "hostile",
+      "neutral",
+      "player",
+      "ambient",
+      "voice"
+    ]) {
+      values.set(`soundCategory_${category}`, volume);
+    }
+  }
   if (server) {
     values.set("lastServer", server);
   }
@@ -214,6 +246,7 @@ async function buildLaunchSpec(options) {
   const nativesDir = options["natives-dir"] || path.join(instanceRoot, "natives");
   const gameDir = path.join(instanceRoot, "minecraft");
   const packMeta = await readJson(path.join(instanceRoot, "mmc-pack.json"));
+  const mute = parseOptionalBoolean(process.env.MCT_CLIENT_MUTE);
   await syncBuiltMod(instanceRoot, repoRoot, selectedVariant);
   const componentMetas = new Map();
   for (const component of packMeta.components) {
@@ -263,7 +296,7 @@ async function buildLaunchSpec(options) {
   const accountName = process.env.MCT_CLIENT_ACCOUNT || options.account || "TEST1";
   const accountUuid = offlineUuid(accountName);
   const server = process.env.MCT_CLIENT_SERVER || "";
-  await ensureAutomationOptions(gameDir, server);
+  await ensureAutomationOptions(gameDir, server, mute);
   const [serverHost, serverPort = "25565"] = server.split(":");
   const classpath = [
     path.join(librariesRoot, mainJarPath),
@@ -316,12 +349,13 @@ async function buildManifestLaunchSpec(options) {
 
   const manifest = await readJson(manifestPath);
   const gameDir = manifest.gameDir;
+  const mute = parseOptionalBoolean(process.env.MCT_CLIENT_MUTE);
   await syncConfiguredMod(gameDir);
 
   const accountName = process.env.MCT_CLIENT_ACCOUNT || options.account || "TEST1";
   const accountUuid = offlineUuid(accountName);
   const server = process.env.MCT_CLIENT_SERVER || "";
-  await ensureAutomationOptions(gameDir, server);
+  await ensureAutomationOptions(gameDir, server, mute);
   const [serverHost, serverPort = "25565"] = server.split(":");
   const substitutions = {
     auth_player_name: accountName,