@kzheart_/mc-pilot 0.9.5 → 0.9.7

package/data/variants.json

@@ -1,7 +1,7 @@
 {
   "defaultVariant": "1.20.4-fabric",
   "buildSystem": "multi-module",
-  "versions": ["1.18.2", "1.20.1", "1.20.2", "1.20.4", "1.21.1", "1.21.4"],
+  "versions": ["1.18.2", "1.20.1", "1.20.2", "1.20.4", "1.21.1", "1.21.4", "1.21.11"],
   "variants": [
     {
       "id": "1.18.2-fabric",
@@ -137,6 +137,18 @@
       "modVersion": "0.9.1",
       "neoforgeVersion": "21.4.75",
       "javaVersion": 21
+    },
+    {
+      "id": "1.21.11-fabric",
+      "minecraftVersion": "1.21.11",
+      "loader": "fabric",
+      "support": "ready",
+      "validation": "verified",
+      "modVersion": "0.9.1",
+      "fabricLoaderVersion": "0.19.2",
+      "yarnMappings": "1.21.11+build.5",
+      "javaVersion": 21,
+      "gradleModule": "version-1.21.11"
     }
   ]
 }

package/dist/commands/client.js

@@ -48,7 +48,7 @@ export function createClientCommand() {
         .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("--mute", "Mute all in-game audio for this client (default)")
         .option("--no-mute", "Keep in-game audio enabled for this client")
         .option("--java <command>", "Java command to use")
         .action(wrapCommand(async (_context, { args, options }) => {
@@ -74,7 +74,9 @@ export function createClientCommand() {
             env: {
                 MCT_CLIENT_MOD_VARIANT: downloaded.variantId,
                 MCT_CLIENT_MOD_JAR: downloaded.jar
-            }
+            },
+            javaCommand: downloaded.javaCommand,
+            javaVersion: downloaded.javaVersion
         });
         return {
             created: true,
@@ -94,7 +96,7 @@ 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("--mute", "Mute all in-game audio for this launch (default)")
         .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 }) => {

package/dist/commands/craft.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 export declare function createCraftCommand(): Command;
+export declare function createRecipeCommand(): Command;
 export declare function createAnvilCommand(): Command;
 export declare function createEnchantCommand(): Command;
 export declare function createTradeCommand(): Command;

package/dist/commands/craft.js

@@ -1,15 +1,41 @@
 import { Command } from "commander";
+import { MctError } from "../util/errors.js";
 import { createRequestAction, parseJson } from "./request-helpers.js";
+function normalizeCraftRecipe(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === "object" && Array.isArray(raw.slots)) {
+        const slots = raw.slots;
+        if (slots.length !== 9) {
+            throw new MctError({ code: "INVALID_PARAMS", message: "recipe.slots must contain exactly 9 entries" }, 4);
+        }
+        return [slots.slice(0, 3), slots.slice(3, 6), slots.slice(6, 9)];
+    }
+    throw new MctError({
+        code: "INVALID_PARAMS",
+        message: "recipe must be a 3x3 row array or {\"slots\":[...9 entries...]}"
+    }, 4);
+}
 export function createCraftCommand() {
     return new Command("craft")
         .description("Crafting table recipe\n" +
         "Prerequisite: open crafting table with \"block interact <x> <y> <z>\"\n" +
         "Auto-places materials from inventory, crafts, and moves result to inventory.\n" +
         "GUI closes automatically after crafting.")
-        .requiredOption("--recipe <json>", "Recipe JSON: 9-slot array in row-major order (top-left to bottom-right).\n" +
+        .requiredOption("--recipe <json>", "Recipe JSON: 3 row arrays, or {\"slots\":[...9 entries...]} in row-major order.\n" +
         "Use item IDs without namespace (e.g. \"oak_planks\", not \"minecraft:oak_planks\").\n" +
-        "Example: '{\"slots\":[\"oak_planks\",\"oak_planks\",null,\"oak_planks\",\"oak_planks\",null,null,null,null]}'")
-        .action(createRequestAction("craft.craft", ({ options }) => ({ recipe: parseJson(String(options.recipe), "recipe") })));
+        "Example: '[[\"oak_planks\",null,null],[\"oak_planks\",null,null],[null,null,null]]'")
+        .action(createRequestAction("craft.craft", ({ options }) => ({ recipe: normalizeCraftRecipe(parseJson(String(options.recipe), "recipe")) })));
+}
+export function createRecipeCommand() {
+    const command = new Command("recipe").description("Task-level recipe helpers");
+    command
+        .command("craft-table")
+        .description("Craft with the currently open crafting table")
+        .requiredOption("--recipe <json>", "Recipe JSON: 3 row arrays or {\"slots\":[...9 entries...]}")
+        .action(createRequestAction("craft.craft", ({ options }) => ({ recipe: normalizeCraftRecipe(parseJson(String(options.recipe), "recipe")) })));
+    return command;
 }
 export function createAnvilCommand() {
     return new Command("anvil")

package/dist/commands/events.js

@@ -13,6 +13,20 @@ function resolveEventsFile(clientName) {
     }
     return path.join(resolveMctHome(), "logs", clientName, "events.jsonl");
 }
+function resolveEventClientNames(context, explicitClient, allClients) {
+    if (allClients) {
+        const clients = context.activeProfile?.clients ?? [];
+        if (clients.length === 0) {
+            throw new MctError({ code: "INVALID_PARAMS", message: "--all-clients requires an active profile with clients" }, 4);
+        }
+        return clients;
+    }
+    const clientName = explicitClient ?? context.activeProfile?.clients[0];
+    if (!clientName) {
+        throw new MctError({ code: "INVALID_PARAMS", message: "Client name is required. Use --client <name> or set an active profile." }, 4);
+    }
+    return [clientName];
+}
 function parseSince(raw, nowMs) {
     if (!raw)
         return undefined;
@@ -176,18 +190,29 @@ export function createEventsCommand() {
     command
         .command("clear")
         .description("Truncate the event log for the active client")
+        .option("--all-clients", "Clear event logs for every client in the active profile")
         .option("--file <path>", "Override the log file path")
         .action(wrapCommand(async (context, { options, globalOptions }) => {
         const { truncateSync, existsSync: exists, mkdirSync } = await import("node:fs");
-        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
-        const filePath = options.file ?? resolveEventsFile(clientName);
-        if (exists(filePath)) {
-            truncateSync(filePath, 0);
-            return { cleared: true, file: filePath };
+        if (options.file) {
+            if (exists(options.file)) {
+                truncateSync(options.file, 0);
+                return { cleared: true, file: options.file };
+            }
+            mkdirSync(path.dirname(options.file), { recursive: true });
+            return { cleared: false, reason: "file_not_found", file: options.file };
         }
-        // ensure directory exists for future writes
-        mkdirSync(path.dirname(filePath), { recursive: true });
-        return { cleared: false, reason: "file_not_found", file: filePath };
+        const clients = resolveEventClientNames(context, globalOptions.client, Boolean(options.allClients));
+        const results = clients.map((clientName) => {
+            const filePath = resolveEventsFile(clientName);
+            if (exists(filePath)) {
+                truncateSync(filePath, 0);
+                return { client: clientName, cleared: true, file: filePath };
+            }
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            return { client: clientName, cleared: false, reason: "file_not_found", file: filePath };
+        });
+        return { cleared: results.some((result) => result.cleared), clients: results };
     }));
     command
         .command("path")

package/dist/commands/gui.js

@@ -46,10 +46,27 @@ export function createGuiCommand() {
         .command("screenshot")
         .description("Take a screenshot of the current GUI")
         .option("--output <path>", "Output file path (default: project screenshot directory)")
+        .option("--timeout <seconds>", "Screenshot response timeout in seconds (default 30)", Number)
         .action(wrapCommand(async (context, { options, globalOptions }) => {
-        return sendClientRequest(context, globalOptions.client ?? context.activeProfile?.clients[0], "gui.screenshot", {
-            output: resolveScreenshotOutputPath(context, options.output, "gui")
-        });
+        return sendClientRequest(context, globalOptions.client ?? context.activeProfile?.clients[0], "gui.screenshot", { output: resolveScreenshotOutputPath(context, options.output, "gui") }, options.timeout ?? Math.max(30, context.timeout("default")));
+    }));
+    command
+        .command("click-title")
+        .description("Click a GUI slot by title text match")
+        .argument("<title>", "Regex matched against item displayName or type")
+        .option("--button <button>", "Click button: left|right|middle|shift-left|shift-right", "left")
+        .action(wrapCommand(async (context, { args, options, globalOptions }) => {
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        const snapshot = await sendClientRequest(context, clientName, "gui.snapshot", {});
+        const slots = ((snapshot.data?.data?.slots)
+            ?? (snapshot.data?.slots)
+            ?? []);
+        const pattern = new RegExp(String(args[0]));
+        const found = slots.find((slot) => slot.item && (pattern.test(String(slot.item.displayName ?? "")) || pattern.test(String(slot.item.type ?? ""))));
+        if (!found || found.slot === undefined) {
+            return { clicked: false, matched: false, title: args[0], slots: slots.length };
+        }
+        return sendClientRequest(context, clientName, "gui.click", { slot: found.slot, button: options.button ?? "left" });
     }));
     return command;
 }

package/dist/commands/project.js

@@ -53,6 +53,8 @@ export function createUpCommand() {
         .description("Deploy plugins, start server and clients, wait for ready")
         .option("--profile <name>", "Profile name")
         .option("--eula", "Auto-accept EULA")
+        .option("--server-only-ok", "Only deploy/start/wait for the server; skip launching and waiting for clients")
+        .option("--skip-client-ready", "Launch/reconnect clients but do not wait for them to join a world")
         .action(wrapCommand(async (context, { options }) => {
         const { projectFile, projectId, projectRootDir } = context;
         if (!projectFile || !projectId || !projectRootDir) {
@@ -73,7 +75,12 @@ export function createUpCommand() {
         results.server = await serverManager.start(profile.server, { eula: options.eula });
         // 3. Wait for server
         const serverMeta = await serverManager.loadMeta(profile.server);
-        await serverManager.waitReady(profile.server, context.timeout("serverReady"));
+        results.serverReady = await serverManager.waitReady(profile.server, context.timeout("serverReady"));
+        if (options.serverOnlyOk) {
+            results.ready = true;
+            results.clientsSkipped = true;
+            return results;
+        }
         // 4. Launch clients (reuse running clients via reconnect)
         const serverAddress = `localhost:${serverMeta.port}`;
         const clientResults = [];
@@ -89,8 +96,15 @@ export function createUpCommand() {
         }
         results.clients = clientResults;
         // 5. Wait for clients (WS connected + in-world)
-        for (const clientName of profile.clients) {
-            await clientManager.waitReady(clientName, context.timeout("clientReady"));
+        if (options.skipClientReady) {
+            results.clientReadySkipped = true;
+        }
+        else {
+            const readyClients = [];
+            for (const clientName of profile.clients) {
+                readyClients.push(await clientManager.waitReady(clientName, context.timeout("clientReady")));
+            }
+            results.clientReady = readyClients;
         }
         results.ready = true;
         return results;

package/dist/commands/screenshot.js

@@ -1,17 +1,53 @@
 import { Command } from "commander";
+import { ClientInstanceManager } from "../instance/ClientInstanceManager.js";
 import { wrapCommand } from "../util/command.js";
+import { MctError } from "../util/errors.js";
 import { resolveScreenshotOutputPath, sendClientRequest } from "./request-helpers.js";
+async function captureWithRetry(context, clientName, params, options) {
+    const timeout = options.timeout ?? Math.max(30, context.timeout("default"));
+    const retries = options.retries ?? 1;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await sendClientRequest(context, clientName, "capture.screenshot", params, timeout);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < retries) {
+                await new Promise((resolve) => setTimeout(resolve, 500));
+            }
+        }
+    }
+    const manager = new ClientInstanceManager(context.globalState);
+    const diagnostics = await manager.getClient(clientName).catch((error) => ({ unavailable: String(error.message) }));
+    throw new MctError({
+        code: "TIMEOUT",
+        message: `Screenshot request failed after ${retries + 1} attempt(s) with ${timeout}s timeout`,
+        details: {
+            client: clientName ?? context.activeProfile?.clients[0] ?? null,
+            timeout,
+            retries,
+            lastError: lastError instanceof Error ? lastError.message : String(lastError),
+            diagnostics
+        }
+    }, 2);
+}
 export function createScreenshotCommand() {
     return new Command("screenshot")
         .description("Take a screenshot")
         .option("--output <path>", "Output file path (default: project screenshot directory)")
         .option("--region <region>", "Capture a sub-region, format: x,y,w,h")
         .option("--gui", "Capture the current GUI screen")
+        .option("--timeout <seconds>", "Screenshot response timeout in seconds (default 30)", Number)
+        .option("--retries <count>", "Retry count after timeout/failure (default 1)", Number)
         .action(wrapCommand(async (context, { options, globalOptions }) => {
-        return sendClientRequest(context, globalOptions.client ?? context.activeProfile?.clients[0], "capture.screenshot", {
+        return captureWithRetry(context, globalOptions.client ?? context.activeProfile?.clients[0], {
             output: resolveScreenshotOutputPath(context, options.output, "screenshot"),
             region: options.region,
             gui: Boolean(options.gui)
+        }, {
+            timeout: options.timeout,
+            retries: options.retries
         });
     }));
 }

package/dist/commands/server.js

@@ -122,6 +122,16 @@ export function createServerCommand() {
         const manager = new ServerInstanceManager(context.globalState, project);
         return manager.waitReady(serverName, options.timeout ?? context.timeout("serverReady"));
     }));
+    command
+        .command("readiness")
+        .description("Report process, port and log readiness diagnostics")
+        .argument("[name]", "Server instance name (default: from active profile)")
+        .action(wrapCommand(async (context, { args }) => {
+        const project = requireProject(context);
+        const serverName = resolveServerName(context, args[0]);
+        const manager = new ServerInstanceManager(context.globalState, project);
+        return manager.readiness(serverName);
+    }));
     command
         .command("exec")
         .description("Send a console command directly to the server stdin FIFO (bypasses client chat)")
@@ -140,6 +150,8 @@ export function createServerCommand() {
         .option("--tail <n>", "Show only the last N lines", Number)
         .option("--grep <pattern>", "Filter lines by regex")
         .option("--since <lineNumber>", "Skip the first N lines (0-indexed)", Number)
+        .option("--since-start", "Only read log content written after the current server process was started")
+        .option("--after-marker <marker>", "Only read log lines after the last line containing this marker")
         .option("--follow", "Wait for new log lines (requires --timeout)")
         .option("--timeout <seconds>", "Max seconds to wait when --follow is set", Number)
         .option("--first-match", "With --follow, exit as soon as the first matching line appears")
@@ -161,8 +173,21 @@ export function createServerCommand() {
             tail: options.tail,
             grep: options.grep,
             since: options.since,
+            sinceStart: Boolean(options.sinceStart),
+            afterMarker: options.afterMarker,
             rawColors: Boolean(options.rawColors)
         });
     }));
+    command
+        .command("logs-mark")
+        .description("Append a marker line to the server log and return the marker")
+        .argument("[name]", "Server instance name (default: from active profile)")
+        .option("--label <label>", "Optional marker label")
+        .action(wrapCommand(async (context, { args, options }) => {
+        const project = requireProject(context);
+        const serverName = resolveServerName(context, args[0]);
+        const manager = new ServerInstanceManager(context.globalState, project);
+        return manager.markLogs(serverName, options.label);
+    }));
     return command;
 }

package/dist/commands/wait-log.d.ts

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

package/dist/commands/wait-log.js

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import { ServerInstanceManager } from "../instance/ServerInstanceManager.js";
+import { MctError } from "../util/errors.js";
+import { wrapCommand } from "../util/command.js";
+function requireProject(context) {
+    if (!context.projectId) {
+        throw new MctError({ code: "NO_PROJECT", message: "No project context. Run inside an mct project or use --project <id>." }, 4);
+    }
+    return context.projectId;
+}
+export function createWaitLogCommand() {
+    return new Command("wait-log")
+        .description("Wait for a server log line matching a regex")
+        .option("--server <name>", "Server instance name (default: from active profile)")
+        .requiredOption("--grep <pattern>", "Regex to match")
+        .option("--timeout <seconds>", "Timeout in seconds (default 30)", Number)
+        .option("--first-match", "Exit after the first matching line", true)
+        .action(wrapCommand(async (context, { options }) => {
+        const project = requireProject(context);
+        const serverName = options.server ?? context.activeProfile?.server;
+        if (!serverName) {
+            throw new MctError({ code: "INVALID_PARAMS", message: "Server name is required" }, 4);
+        }
+        const manager = new ServerInstanceManager(context.globalState, project);
+        return manager.followLogs(serverName, {
+            grep: options.grep,
+            timeoutSeconds: options.timeout ?? context.timeout("default"),
+            firstMatchOnly: options.firstMatch !== false
+        });
+    }));
+}

package/dist/download/VersionMatrix.js

@@ -1,5 +1,20 @@
 import { loadModVariantCatalogSync } from "./ModVariantCatalog.js";
 const VERSION_MATRIX = [
+    {
+        minecraftVersion: "1.21.11",
+        javaVersion: "21+",
+        servers: {
+            vanilla: { supported: true },
+            paper: { supported: true, latestBuild: 69 },
+            purpur: { supported: true, latestBuild: 2568 },
+            spigot: { supported: true, requiresBuildTools: true }
+        },
+        clients: {
+            fabric: { supported: true, loaderVersion: "0.19.2", modVersion: "0.9.1", validation: "verified" },
+            forge: { supported: false, notes: "不支持此版本" },
+            neoforge: { supported: false, validation: "planned", notes: "计划中" }
+        }
+    },
     {
         minecraftVersion: "1.21.4",
         javaVersion: "21+",

package/dist/download/client/FabricRuntimeDownloader.js

@@ -10,7 +10,10 @@ const DOWNLOAD_DISPATCHER = new Agent({
     connect: {
         timeout: 30_000
     },
-    connections: 2
+    headersTimeout: 30_000,
+    bodyTimeout: 30_000,
+    connections: 1,
+    pipelining: 0
 }).compose(interceptors.retry({
     maxRetries: 4,
     minTimeout: 500,
@@ -74,8 +77,8 @@ async function prepareManagedRuntime(variant, runtimeOptions, dependencies, expe
     await installDependencies(resolvedVersion, {
         side: "client",
         dispatcher: DOWNLOAD_DISPATCHER,
-        assetsDownloadConcurrency: 2,
-        librariesDownloadConcurrency: 2
+        assetsDownloadConcurrency: 1,
+        librariesDownloadConcurrency: 1
     });
     await applyArm64LwjglPatch(runtimeRootDir, installedVersionId, { fetchImpl });
     await writeFile(readyMarker, new Date().toISOString(), "utf8");

package/dist/index.js

@@ -7,7 +7,7 @@ import { createBookCommand } from "./commands/book.js";
 import { createClientCommand } from "./commands/client.js";
 import { createChatCommand } from "./commands/chat.js";
 import { createCombatCommand } from "./commands/combat.js";
-import { createAnvilCommand, createCraftCommand, createEnchantCommand, createTradeCommand } from "./commands/craft.js";
+import { createAnvilCommand, createCraftCommand, createEnchantCommand, createRecipeCommand, createTradeCommand } from "./commands/craft.js";
 import { createEntityCommand } from "./commands/entity.js";
 import { createEventsCommand } from "./commands/events.js";
 import { createGuiCommand } from "./commands/gui.js";
@@ -27,6 +27,7 @@ import { createServerCommand } from "./commands/server.js";
 import { createSignCommand } from "./commands/sign.js";
 import { createStatusCommand } from "./commands/status.js";
 import { createWaitCommand } from "./commands/wait.js";
+import { createWaitLogCommand } from "./commands/wait-log.js";
 import { createPluginCommand } from "./commands/plugin.js";
 import { createInitCommand, createDeployCommand, createUpCommand, createDownCommand, createUseCommand } from "./commands/project.js";
 import { attachGlobalOptions, wrapCommand } from "./util/command.js";
@@ -94,10 +95,12 @@ export function buildProgram() {
     program.addCommand(createResourcepackCommand());
     program.addCommand(createCombatCommand());
     program.addCommand(createCraftCommand());
+    program.addCommand(createRecipeCommand());
     program.addCommand(createAnvilCommand());
     program.addCommand(createEnchantCommand());
     program.addCommand(createTradeCommand());
     program.addCommand(createWaitCommand());
+    program.addCommand(createWaitLogCommand());
     program.addCommand(createEventsCommand());
     return program;
 }

package/dist/instance/ClientInstanceManager.d.ts

@@ -10,6 +10,8 @@ export interface CreateClientOptions {
     mute?: boolean;
     launchArgs?: string[];
     env?: Record<string, string>;
+    javaCommand?: string;
+    javaVersion?: number;
 }
 export interface LaunchClientOptions {
     server?: string;

package/dist/instance/ClientInstanceManager.js

@@ -8,6 +8,7 @@ import { MctError } from "../util/errors.js";
 import { getListeningPids, isProcessRunning, killProcessTree } from "../util/process.js";
 import { WebSocketClient } from "../client/WebSocketClient.js";
 const INSTANCE_FILE = "instance.json";
+const DEFAULT_CLIENT_MUTE = true;
 function getLaunchScriptPath() {
     const thisFile = fileURLToPath(import.meta.url);
     // dist/instance/ClientInstanceManager.js -> scripts/launch-fabric-client.mjs
@@ -30,9 +31,11 @@ export class ClientInstanceManager {
                 wsPort,
                 account: options.account,
                 headless: options.headless,
-                mute: options.mute,
+                mute: options.mute ?? DEFAULT_CLIENT_MUTE,
                 launchArgs: options.launchArgs,
                 env: options.env,
+                javaCommand: options.javaCommand,
+                javaVersion: options.javaVersion,
                 createdAt: new Date().toISOString()
             };
             await writeFile(path.join(instanceDir, INSTANCE_FILE), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
@@ -58,7 +61,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;
+            const mute = options.mute ?? meta.mute ?? DEFAULT_CLIENT_MUTE;
             if (!meta.launchArgs || meta.launchArgs.length === 0) {
                 throw new MctError({ code: "INVALID_PARAMS", message: `Client ${clientName} has no launchArgs configured` }, 4);
             }
@@ -94,6 +97,7 @@ export class ClientInstanceManager {
                     MCT_CLIENT_SERVER: options.server ?? "",
                     MCT_CLIENT_WS_PORT: String(wsPort),
                     MCT_CLIENT_HEADLESS: String(options.headless ?? meta.headless ?? false),
+                    ...(meta.javaCommand ? { MCT_CLIENT_JAVA: meta.javaCommand } : {}),
                     ...(mute === undefined ? {} : { MCT_CLIENT_MUTE: String(mute) })
                 }
             });

package/dist/instance/ServerInstanceManager.d.ts

@@ -9,6 +9,8 @@ export interface CreateServerOptions {
     version: string;
     port?: number;
     jvmArgs?: string[];
+    javaCommand?: string;
+    javaVersion?: number;
     eula?: boolean;
     cachedJarPath?: string;
 }
@@ -48,6 +50,7 @@ export declare class ServerInstanceManager {
         startedAt: string;
         logPath: string;
         instanceDir: string;
+        logStartOffset?: number;
         stdinPipe?: string;
         running: boolean;
         stale: boolean;
@@ -59,6 +62,7 @@ export declare class ServerInstanceManager {
         startedAt: string;
         logPath: string;
         instanceDir: string;
+        logStartOffset?: number;
         stdinPipe?: string;
         running: boolean;
     }>;
@@ -71,6 +75,11 @@ export declare class ServerInstanceManager {
         host: string;
         port: number;
         phase: string;
+        signals: {
+            processAlive: boolean;
+            portReachable: boolean;
+            readyLineSeen: boolean;
+        };
         logPath: string;
         lastLine: string | null;
         recentLines: string[];
@@ -84,6 +93,8 @@ export declare class ServerInstanceManager {
         tail?: number;
         grep?: string;
         since?: number;
+        sinceStart?: boolean;
+        afterMarker?: string;
         rawColors?: boolean;
     }): Promise<{
         logPath: string;
@@ -91,6 +102,10 @@ export declare class ServerInstanceManager {
         returnedLines: number;
         lines: string[];
     }>;
+    markLogs(serverName: string, label?: string): Promise<{
+        logPath: string;
+        marker: string;
+    }>;
     followLogs(serverName: string, options: {
         grep?: string;
         timeoutSeconds: number;
@@ -104,6 +119,24 @@ export declare class ServerInstanceManager {
     }>;
     private requireRuntimeEntry;
     private describeStartup;
+    readiness(serverName: string): Promise<{
+        process: {
+            alive: boolean;
+            pid: number;
+        };
+        port: {
+            reachable: boolean;
+            host: string;
+            port: number;
+        };
+        log: {
+            phase: string;
+            readyLineSeen: boolean;
+            lastLine: string | null;
+            recentLines: string[];
+            path: string;
+        };
+    }>;
     private requireRunning;
     list(): Promise<ServerInstanceMeta[]>;
     static listAll(globalState: GlobalStateStore): Promise<ServerInstanceMeta[]>;

package/dist/instance/ServerInstanceManager.js

@@ -67,6 +67,8 @@ export class ServerInstanceManager {
             mcVersion: options.version,
             port,
             jvmArgs: options.jvmArgs ?? [],
+            javaCommand: options.javaCommand,
+            javaVersion: options.javaVersion,
             createdAt: new Date().toISOString()
         };
         await writeFile(path.join(instanceDir, INSTANCE_FILE), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
@@ -95,8 +97,10 @@ export class ServerInstanceManager {
         mkdirSync(logsDir, { recursive: true });
         mkdirSync(stateDir, { recursive: true });
         const logPath = path.join(logsDir, `server-${this.project}-${serverName}.log`);
+        const logStartOffset = await stat(logPath).then((value) => value.size).catch(() => 0);
         const stdout = openSync(logPath, "a");
         const jvmArgs = options.jvmArgs ?? meta.jvmArgs;
+        const javaCommand = meta.javaCommand ?? "java";
         // Create a named pipe (FIFO) for stdin so external tools (GUI) can send commands
         const stdinPipe = path.join(stateDir, `stdin-${this.project}-${serverName}.fifo`);
         try {
@@ -109,7 +113,7 @@ export class ServerInstanceManager {
         // then exec java with stdin reading from the FIFO
         const child = spawn("bash", [
             "-c",
-            'exec 3<>"$MCT_STDIN_PIPE"; exec java "$@" 0<&3',
+            'exec 3<>"$MCT_STDIN_PIPE"; exec "$MCT_SERVER_JAVA" "$@" 0<&3',
             "mct-server",
             ...jvmArgs, "-jar", jarFile, "nogui"
         ], {
@@ -119,7 +123,8 @@ export class ServerInstanceManager {
             env: {
                 ...process.env,
                 MCT_SERVER_PORT: String(meta.port),
-                MCT_STDIN_PIPE: stdinPipe
+                MCT_STDIN_PIPE: stdinPipe,
+                MCT_SERVER_JAVA: javaCommand
             }
         });
         child.unref();
@@ -131,6 +136,7 @@ export class ServerInstanceManager {
             startedAt: new Date().toISOString(),
             logPath,
             instanceDir,
+            logStartOffset,
             stdinPipe
         };
         state.servers[stateKey] = entry;
@@ -232,6 +238,11 @@ export class ServerInstanceManager {
                     host: "127.0.0.1",
                     port: entry.port,
                     phase: snapshot.phase,
+                    signals: {
+                        processAlive: true,
+                        portReachable: true,
+                        readyLineSeen: snapshot.phase === "ready"
+                    },
                     logPath: snapshot.logPath,
                     lastLine: snapshot.lastLine,
                     recentLines: snapshot.recentLines
@@ -247,6 +258,11 @@ export class ServerInstanceManager {
                 host: "127.0.0.1",
                 port: entry.port,
                 phase: snapshot.phase,
+                signals: {
+                    processAlive: isProcessRunning(entry.pid),
+                    portReachable: false,
+                    readyLineSeen: snapshot.phase === "ready"
+                },
                 logPath: snapshot.logPath,
                 lastLine: snapshot.lastLine,
                 recentLines: snapshot.recentLines
@@ -282,11 +298,14 @@ export class ServerInstanceManager {
     async readLogs(serverName, options = {}) {
         const entry = await this.requireRuntimeEntry(serverName);
         const logPath = entry.logPath;
-        const raw = await readFile(logPath, "utf8").catch((error) => {
+        let raw = await readFile(logPath, "utf8").catch((error) => {
             if (error.code === "ENOENT")
                 return "";
             throw error;
         });
+        if (options.sinceStart && entry.logStartOffset && entry.logStartOffset > 0) {
+            raw = raw.slice(entry.logStartOffset);
+        }
         let lines = raw.split("\n");
         if (lines.length > 0 && lines[lines.length - 1] === "")
             lines = lines.slice(0, -1);
@@ -297,6 +316,18 @@ export class ServerInstanceManager {
         if (options.since !== undefined && options.since > 0) {
             lines = lines.slice(Math.max(0, options.since));
         }
+        if (options.afterMarker) {
+            let markerIndex = -1;
+            for (let index = lines.length - 1; index >= 0; index--) {
+                if (lines[index].includes(options.afterMarker)) {
+                    markerIndex = index;
+                    break;
+                }
+            }
+            if (markerIndex >= 0) {
+                lines = lines.slice(markerIndex + 1);
+            }
+        }
         if (options.grep) {
             const re = new RegExp(options.grep);
             lines = lines.filter((line) => re.test(line));
@@ -306,6 +337,12 @@ export class ServerInstanceManager {
         }
         return { logPath, totalLines: total, returnedLines: lines.length, lines };
     }
+    async markLogs(serverName, label) {
+        const entry = await this.requireRuntimeEntry(serverName);
+        const marker = `MCT_MARK ${new Date().toISOString()} ${label ?? ""}`.trim();
+        await writeFile(entry.logPath, `\n${marker}\n`, { flag: "a", encoding: "utf8" });
+        return { logPath: entry.logPath, marker };
+    }
     async followLogs(serverName, options) {
         const entry = await this.requireRuntimeEntry(serverName);
         const logPath = entry.logPath;
@@ -398,6 +435,23 @@ export class ServerInstanceManager {
             lastLine
         };
     }
+    async readiness(serverName) {
+        const entry = await this.requireRuntimeEntry(serverName);
+        const processAlive = isProcessRunning(entry.pid);
+        const portReachable = await isTcpPortReachable("127.0.0.1", entry.port);
+        const snapshot = await this.describeStartup(entry.logPath);
+        return {
+            process: { alive: processAlive, pid: entry.pid },
+            port: { reachable: portReachable, host: "127.0.0.1", port: entry.port },
+            log: {
+                phase: snapshot.phase,
+                readyLineSeen: snapshot.phase === "ready",
+                lastLine: snapshot.lastLine,
+                recentLines: snapshot.recentLines,
+                path: snapshot.logPath
+            }
+        };
+    }
     async requireRunning(serverName) {
         const entry = await this.requireRuntimeEntry(serverName);
         if (!isProcessRunning(entry.pid)) {

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

@@ -7,6 +7,8 @@ export interface ServerInstanceMeta {
     mcVersion: string;
     port: number;
     jvmArgs: string[];
+    javaCommand?: string;
+    javaVersion?: number;
     createdAt: string;
 }
 export interface ClientInstanceMeta {
@@ -19,6 +21,8 @@ export interface ClientInstanceMeta {
     mute?: boolean;
     launchArgs?: string[];
     env?: Record<string, string>;
+    javaCommand?: string;
+    javaVersion?: number;
     createdAt: string;
 }
 export interface ServerRuntimeEntry {
@@ -29,6 +33,7 @@ export interface ServerRuntimeEntry {
     startedAt: string;
     logPath: string;
     instanceDir: string;
+    logStartOffset?: number;
     stdinPipe?: string;
 }
 export interface ClientRuntimeEntry {

package/dist/util/project.js

@@ -29,16 +29,23 @@ export async function loadProjectFileById(projectId) {
     return JSON.parse(raw);
 }
 export async function loadProjectFileForCwd(cwd) {
-    const projectId = slugifyProjectId(normalizeProjectRoot(cwd));
-    const projectFile = await loadProjectFileById(projectId);
-    if (!projectFile) {
-        return null;
+    let current = normalizeProjectRoot(cwd);
+    while (true) {
+        const projectId = slugifyProjectId(current);
+        const projectFile = await loadProjectFileById(projectId);
+        if (projectFile) {
+            return {
+                projectId,
+                filePath: resolveProjectFilePath(projectId),
+                projectFile
+            };
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
     }
-    return {
-        projectId,
-        filePath: resolveProjectFilePath(projectId),
-        projectFile
-    };
 }
 export async function loadProjectFileForId(projectId) {
     const projectFile = await loadProjectFileById(projectId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kzheart_/mc-pilot",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
   "type": "module",
   "bin": {

package/scripts/launch-fabric-client.mjs

@@ -7,11 +7,12 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createQuickPlayMultiplayer, launch as launchMinecraft } from "@xmcl/core";
+import { DEFAULT_EXTRA_JVM_ARGS, createQuickPlayMultiplayer, launch as launchMinecraft } from "@xmcl/core";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const VARIANTS_PATH = path.join(__dirname, "..", "data", "variants.json");
+const DEFAULT_CLIENT_LANGUAGE = "zh_cn";
 
 function readCatalog() {
   return JSON.parse(readFileSync(VARIANTS_PATH, "utf8"));
@@ -121,6 +122,30 @@ function parseOptionalBoolean(value) {
   return undefined;
 }
 
+function getClientLanguage() {
+  return process.env.MCT_CLIENT_LANGUAGE || DEFAULT_CLIENT_LANGUAGE;
+}
+
+function localeJavaArgs(language) {
+  const [languageCode = "zh", countryCode] = String(language).replace("-", "_").split("_");
+  return [
+    `-Duser.language=${languageCode || "zh"}`,
+    ...(countryCode ? [`-Duser.country=${countryCode.toUpperCase()}`] : [])
+  ];
+}
+
+function normalizeLocaleJavaArgs(javaArgs, language) {
+  return [
+    ...javaArgs.filter((entry) => !entry.startsWith("-Duser.language=") && !entry.startsWith("-Duser.country=")),
+    ...localeJavaArgs(language)
+  ];
+}
+
+function xmclExtraJvmArgs(language, maxMemory) {
+  const defaultArgs = maxMemory ? DEFAULT_EXTRA_JVM_ARGS.filter((entry) => entry !== "-Xmx2G") : DEFAULT_EXTRA_JVM_ARGS;
+  return normalizeLocaleJavaArgs([...defaultArgs], language);
+}
+
 async function ensureFile(filePath, downloadUrl) {
   try {
     await access(filePath);
@@ -185,7 +210,7 @@ async function syncConfiguredMod(gameDir) {
   await copyFile(sourceJar, targetJar);
 }
 
-async function ensureAutomationOptions(gameDir, server, mute) {
+async function ensureAutomationOptions(gameDir, server, mute, language = DEFAULT_CLIENT_LANGUAGE) {
   const optionsPath = path.join(gameDir, "options.txt");
   const values = new Map();
 
@@ -206,6 +231,7 @@ async function ensureAutomationOptions(gameDir, server, mute) {
   values.set("joinedFirstServer", "true");
   values.set("tutorialStep", "none");
   values.set("pauseOnLostFocus", "false");
+  values.set("lang", language);
   if (mute !== undefined) {
     const volume = mute ? "0.0" : "1.0";
     for (const category of [
@@ -247,6 +273,7 @@ async function buildLaunchSpec(options) {
   const gameDir = path.join(instanceRoot, "minecraft");
   const packMeta = await readJson(path.join(instanceRoot, "mmc-pack.json"));
   const mute = parseOptionalBoolean(process.env.MCT_CLIENT_MUTE);
+  const language = getClientLanguage();
   await syncBuiltMod(instanceRoot, repoRoot, selectedVariant);
   const componentMetas = new Map();
   for (const component of packMeta.components) {
@@ -296,7 +323,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, mute);
+  await ensureAutomationOptions(gameDir, server, mute, language);
   const [serverHost, serverPort = "25565"] = server.split(":");
   const classpath = [
     path.join(librariesRoot, mainJarPath),
@@ -334,7 +361,7 @@ async function buildLaunchSpec(options) {
       "-XstartOnFirstThread",
       "-Xms512m",
       `-Xmx${options["max-mem"] || "1024m"}`,
-      "-Duser.language=en",
+      ...localeJavaArgs(language),
       `-Djava.library.path=${nativesDir}`,
       "-DFabricMcEmu=net.minecraft.client.main.Main"
     ]
@@ -350,12 +377,13 @@ async function buildManifestLaunchSpec(options) {
   const manifest = await readJson(manifestPath);
   const gameDir = manifest.gameDir;
   const mute = parseOptionalBoolean(process.env.MCT_CLIENT_MUTE);
+  const language = getClientLanguage();
   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, mute);
+  await ensureAutomationOptions(gameDir, server, mute, language);
   const [serverHost, serverPort = "25565"] = server.split(":");
   const substitutions = {
     auth_player_name: accountName,
@@ -374,9 +402,9 @@ async function buildManifestLaunchSpec(options) {
     gameArgs.push("--quickPlayMultiplayer", `${serverHost}:${serverPort}`);
   }
 
-  const javaArgs = manifest.javaArgs
+  const javaArgs = normalizeLocaleJavaArgs(manifest.javaArgs
     .map((entry) => substitute(entry, substitutions))
-    .filter((entry) => !entry.includes("${"));
+    .filter((entry) => !entry.includes("${")), language);
 
   return {
     cwd: gameDir,
@@ -418,15 +446,19 @@ async function launchXmclManagedClient(options) {
   const accountName = process.env.MCT_CLIENT_ACCOUNT || options.account || "TEST1";
   const accountUuid = offlineUuid(accountName).replaceAll("-", "");
   const server = process.env.MCT_CLIENT_SERVER || "";
-  await ensureAutomationOptions(gameDir, server);
+  const mute = parseOptionalBoolean(process.env.MCT_CLIENT_MUTE);
+  const language = getClientLanguage();
+  await ensureAutomationOptions(gameDir, server, mute, language);
   const [serverHost, serverPort = "25565"] = server.split(":");
+  const maxMemory = parseMaxMemory(options["max-mem"]);
 
   return launchMinecraft({
     gamePath: gameDir,
     resourcePath: runtimeRoot,
     javaPath: options.java || process.env.MCT_CLIENT_JAVA || "java",
     minMemory: 512,
-    maxMemory: parseMaxMemory(options["max-mem"]),
+    maxMemory,
+    extraJVMArgs: xmclExtraJvmArgs(language, maxMemory),
     version: versionId,
     gameProfile: {
       name: accountName,