@minecraft/creator-tools/lib/app/toolcommands/commands/ScriptCommand.d.ts

Minecraft Creator Tools command line and libraries.

/**
 * ScriptCommand - Run JavaScript or send messages via Bedrock Dedicated Server
 *
 * ARCHITECTURE DOCUMENTATION
 * ==========================
 *
 * Executes code or commands on an active Bedrock server connection.
 * This is useful for testing and debugging script behavior.
 *
 * EXECUTION PATHWAYS:
 *
 * 1. **Action Set pathway (default, reliable)**:
 *    Uses the `mct:runactions` protocol which has a complete round-trip:
 *    - Sends an action set to the in-game creator_tools_ingame addon
 *    - The addon parses the action set, executes it, and returns results
 *    - Actions include: world_send_message, test_simulated_player_spawn, etc.
 *    - This is the same pathway used by the MCP server's runActionSetInMinecraft
 *
 * 2. **Direct command pathway (--raw flag)**:
 *    Sends a raw Bedrock server command (e.g., `/say Hello`, `/tp @s 0 64 0`)
 *    via DedicatedServer.writeToServer(). No response parsing.
 *
 * 3. **Eval pathway (--eval flag)**:
 *    Evaluates arbitrary JavaScript code in the in-game scripting context.
 *    Uses the `mct:eval` scriptevent protocol with token-based response:
 *    - Encodes code: replaces `"` with `|` for transport
 *    - Sends: `/scriptevent mct:eval "token|encodedCode"`
 *    - Addon receives via scriptEventReceive, reverses encoding
 *    - Addon evaluates code with `new Function("world", "system", "dimension", code)`
 *    - Addon responds: `console.log("evl|" + token + "|" + result)`
 *    - ScriptCommand parses the `evl|token|result` response line
 *    The eval function receives `world`, `system`, and `dimension` (overworld)
 *    as available variables. Example: `/script --eval return world.getAllPlayers().length`
 *
 * TRANSPORT ENCODING:
 * The scriptevent transport cannot carry JSON double-quotes directly, so all
 * quotes in the payload are replaced with `|` before sending and reversed on
 * receipt. Response prefixes: `ras|` for actionset, `evl|` for eval, `gs|` for getState.
 *
 * RELATED FILES:
 * - src/local/DedicatedServer.ts — writeToServer(), runCommandImmediate()
 * - src/local/MinecraftMcpServer.ts — _runActionSet() with token-based responses
 * - src/actions/IActionSetData.ts — Action set data structures
 * - mc/scripts/creator_tools/CreatorTools.ts — In-game handler (outside workspace)
 *   Handles mct:actionset, mct:eval, and mct:state scriptevents + CustomCommands.
 *
 * In MCP context, requires a session to be created first via createMinecraftSessionWithContent.
 */
import type { IToolCommandMetadata, IToolCommandResult } from "../IToolCommand";
import { ToolCommandBase } from "../IToolCommand";
import type { IToolCommandContext } from "../IToolCommandContext";
export declare class ScriptCommand extends ToolCommandBase {
    readonly metadata: IToolCommandMetadata;
    execute(context: IToolCommandContext, args: string[], flags: Record<string, string | boolean | string[]>): Promise<IToolCommandResult>;
    /**
     * Evaluates JavaScript code in the in-game scripting context via the mct:eval
     * scriptevent protocol with token-based response parsing.
     *
     * Protocol:
     * 1. Encode: replace all `"` with `|` in the code
     * 2. Send: `/scriptevent mct:eval "token|encodedCode"`
     * 3. Wait for stdout line containing the token
     * 4. Parse `evl|token|result` from the response
     */
    private _executeEval;
}
export declare const scriptCommand: ScriptCommand;