@bkm016/calcite 0.1.0 → 0.3.0

package/dist/client.js

@@ -1,579 +1,16 @@
-import { randomBytes, createHash } from 'node:crypto';
-import { EventEmitter } from 'node:events';
-import { copyFile, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { Socket } from 'node:net';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { accountsLock, listAccounts } from './accounts.js';
-import { acquireDisplay, which } from './display.js';
-import { ensureHmc, ensureHmcHome, killTree, runHmc } from './hmc.js';
-import { ensureJava } from './java.js';
-import { acquireLock, withLock } from './lock.js';
-import { logger } from './log.js';
-import { ensureClientJar, getVersionJson, requiredJavaMajor, resolveNames, resolveVersion, supportsQuickPlay } from './mojang.js';
-import { defaultOptions, writeOptions } from './options.js';
-import { resolvePaths } from './paths.js';
-import { ProbeError, ProbeServer } from './probe-server.js';
-export class CalciteError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'CalciteError';
-    }
-}
-const NAME_RE = /^[A-Za-z0-9_.-]{1,64}$/;
-const MAX_LOG = 5000;
-const MAX_CHAT = 1000;
-export function parseServer(server) {
-    if (typeof server !== 'string')
-        return { host: server.host, port: server.port || 25565 };
-    const s = server.trim();
-    const v6 = /^\[([^\]]+)\](?::(\d+))?$/.exec(s);
-    if (v6)
-        return { host: v6[1], port: v6[2] ? Number(v6[2]) : 25565 };
-    const idx = s.lastIndexOf(':');
-    if (idx > 0 && s.indexOf(':') === idx)
-        return { host: s.slice(0, idx), port: Number(s.slice(idx + 1)) };
-    return { host: s, port: 25565 };
-}
-function probeJarSource() {
-    return process.env.CALCITE_PROBE_JAR || fileURLToPath(new URL('../vendor/calcite-probe.jar', import.meta.url));
-}
-/** Copies the probe jar to the space-free probe directory (content-addressed). */
-async function installProbe(paths) {
-    const source = await readFile(probeJarSource());
-    const hash = createHash('sha256').update(source).digest('hex').slice(0, 12);
-    const target = join(paths.probe, `calcite-probe-${hash}.jar`);
-    try {
-        await stat(target);
-    }
-    catch {
-        await mkdir(paths.probe, { recursive: true });
-        const tmp = `${target}.${process.pid}.tmp`;
-        await writeFile(tmp, source);
-        await copyFile(tmp, target);
-        await rm(tmp, { force: true });
-    }
-    return target;
-}
-async function tcpReachable(host, port, timeoutMs = 3000) {
-    return new Promise((resolve) => {
-        const socket = new Socket();
-        const done = (ok) => {
-            socket.destroy();
-            resolve(ok);
-        };
-        socket.setTimeout(timeoutMs, () => done(false));
-        socket.once('error', () => done(false));
-        socket.connect(port, host, () => done(true));
-    });
-}
-/** Screens shown while joining or changing dimension; the player is not playable yet. */
-const LOADING_SCREEN = /LevelLoading|ReceivingLevel|ProgressScreen|ConnectScreen|GenericMessage|DownloadingTerrain/;
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Offline username derived from a client name (3-16 chars of [A-Za-z0-9_]). */
-export function defaultUsername(name) {
-    return name.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 16).padEnd(3, '_');
-}
-/**
- * Downloads everything a version needs (client, libraries, natives, assets, mappings, Java, HeadlessMC) without
- * starting the game, so later launches start fast and work offline.
- */
-export async function installVersion(spec, opts = {}) {
-    const paths = opts.paths ?? resolvePaths();
-    const version = await resolveVersion(paths, spec);
-    const json = await getVersionJson(paths, version);
-    const clientJar = await ensureClientJar(paths, json);
-    const names = await resolveNames(paths, json, clientJar);
-    const java = await ensureJava(paths, requiredJavaMajor(json), { javaPath: opts.javaPath, allowDownload: opts.allowJavaDownload });
-    const hmcJar = await ensureHmc(paths);
-    await ensureHmcHome(paths);
-    await installProbe(paths);
-    const run = runHmc({
-        javaPath: java.path,
-        hmcJar,
-        paths,
-        props: { 'hmc.mcdir': paths.minecraft, 'hmc.java.versions': java.path, 'hmc.offline': 'true' },
-        command: ['launch', json.id, '-prepare', '-lwjgl'],
-        onLine: opts.onLine,
-    });
-    const code = await run.exited;
-    if (code !== 0)
-        throw new CalciteError('install_failed', `HeadlessMC exited with code ${code} while downloading ${json.id}`);
-    return { id: json.id, java: java.version, probe: names.kind === 'unsupported' ? names.reason : 'supported' };
-}
+import { readFile, rm } from 'node:fs/promises';
+import { ClientCore, sleep } from './client-core.js';
+import { ProbeError } from './probe-server.js';
+import { CalciteError, } from './types.js';
+export * from './types.js';
+export { installVersion } from './install.js';
 /**
  * One Minecraft client controlled by Calcite.
  *
- * Events: 'phase' (Phase), 'log' (LogLine), 'chat' (ChatLine), 'state' (GameState), 'exit' (code).
+ * Events: 'phase' (Phase), 'log' (LogLine), 'chat' (ChatLine), 'state' (GameState), 'extension' (ExtensionEvent),
+ * 'exit' (code).
  */
-export class Client extends EventEmitter {
-    options;
-    paths;
-    gameDir;
-    render;
-    account;
-    server;
-    phaseValue = 'idle';
-    logs = [];
-    chats = [];
-    seq = 0;
-    probe = null;
-    run = null;
-    display = null;
-    releaseInstance = null;
-    probeConfig = null;
-    java = null;
-    versionJson = null;
-    names = null;
-    headlessValue = false;
-    lastState;
-    lastError;
-    /** Error code of a failure that relaunching cannot fix (reported by start() instead of "crashed"). */
-    fatalCode;
-    startedAt;
-    reconnects = 0;
-    stopping = false;
-    poller = null;
-    inGameSince = 0;
-    relaunching = false;
-    everInGame = false;
-    joinRequested = false;
-    log;
-    constructor(options) {
-        super();
-        if (!NAME_RE.test(options.name)) {
-            throw new CalciteError('bad_name', `Invalid client name "${options.name}" (allowed: letters, digits, - _ .)`);
-        }
-        this.options = options;
-        this.paths = options.paths ?? resolvePaths();
-        this.gameDir = join(this.paths.instances, options.name);
-        this.render = options.render ?? 'on-demand';
-        this.account = options.account ?? { type: 'offline', username: defaultUsername(options.name) };
-        if (this.account.type === 'offline' && !/^[A-Za-z0-9_]{3,16}$/.test(this.account.username)) {
-            throw new CalciteError('bad_username', `Offline username must be 3-16 letters, digits or underscores: "${this.account.username}"`);
-        }
-        this.server = options.server ? parseServer(options.server) : undefined;
-        this.log = logger(`client:${options.name}`);
-        this.on('error', () => undefined); // never crash the host process on an unhandled 'error' event
-    }
-    get phase() {
-        return this.phaseValue;
-    }
-    get headless() {
-        return this.headlessValue;
-    }
-    setPhase(phase) {
-        if (phase === this.phaseValue)
-            return;
-        this.phaseValue = phase;
-        this.note(`phase → ${phase}`);
-        this.emit('phase', phase);
-    }
-    note(line) {
-        this.pushLog('calcite', line);
-        this.log.debug(line);
-    }
-    pushLog(source, line) {
-        const entry = { seq: ++this.seq, time: Date.now(), source, line };
-        this.logs.push(entry);
-        if (this.logs.length > MAX_LOG)
-            this.logs.splice(0, this.logs.length - MAX_LOG);
-        this.emit('log', entry);
-        if (source === 'game') {
-            const chat = /\[CHAT\] (.*)$/.exec(line);
-            if (chat) {
-                const c = { seq: entry.seq, time: entry.time, message: chat[1] };
-                this.chats.push(c);
-                if (this.chats.length > MAX_CHAT)
-                    this.chats.splice(0, this.chats.length - MAX_CHAT);
-                this.emit('chat', c);
-            }
-        }
-    }
-    // ------------------------------------------------------------------ lifecycle
-    /**
-     * Prepares everything (Java, game files, mappings), launches the client and resolves once it is in a world
-     * (or on the title screen when no server is configured).
-     */
-    async start() {
-        if (!['idle', 'stopped', 'crashed'].includes(this.phaseValue)) {
-            throw new CalciteError('already_running', `Client "${this.options.name}" is already ${this.phaseValue}`);
-        }
-        this.stopping = false;
-        this.everInGame = false;
-        this.reconnects = 0;
-        this.lastError = undefined;
-        this.fatalCode = undefined;
-        const timeout = this.options.startTimeoutMs ?? 15 * 60_000;
-        try {
-            this.releaseInstance = await acquireLock(join(this.gameDir, '.calcite.lock'), { timeoutMs: 0 });
-        }
-        catch {
-            throw new CalciteError('instance_busy', `Client "${this.options.name}" is already running in another process`);
-        }
-        try {
-            await this.prepare();
-            await this.launch();
-            await this.waitUntilStarted(timeout);
-            return this.status();
-        }
-        catch (err) {
-            this.lastError = err.message;
-            await this.shutdown('crashed');
-            throw err;
-        }
-    }
-    /** Downloads and verifies everything needed to launch (idempotent). */
-    async prepare() {
-        this.setPhase('preparing');
-        const version = await resolveVersion(this.paths, this.options.version);
-        this.versionJson = await getVersionJson(this.paths, version);
-        const clientJar = await ensureClientJar(this.paths, this.versionJson);
-        this.names = await resolveNames(this.paths, this.versionJson, clientJar);
-        if (this.names.kind === 'unsupported')
-            this.note(`probe disabled: ${this.names.reason}`);
-        this.java = await ensureJava(this.paths, requiredJavaMajor(this.versionJson), {
-            javaPath: this.options.javaPath,
-            allowDownload: this.options.allowJavaDownload,
-        });
-        this.note(`java ${this.java.version} (${this.java.path}) for Minecraft ${this.versionJson.id}`);
-    }
-    resolveHeadless() {
-        if (this.render === 'off')
-            return true;
-        if (this.account.type === 'offline' && process.platform !== 'linux') {
-            this.note('offline accounts can only render on Linux (HeadlessMC policy); running headless — use a Microsoft account for screenshots');
-            return true;
-        }
-        return false;
-    }
-    async launch() {
-        const json = this.versionJson;
-        const java = this.java;
-        const hmcJar = await ensureHmc(this.paths);
-        await ensureHmcHome(this.paths);
-        const probeJar = await installProbe(this.paths);
-        this.headlessValue = this.resolveHeadless();
-        if (this.server) {
-            this.setPhase('waiting_for_server');
-            const deadline = Date.now() + (this.options.waitForServerMs ?? 120_000);
-            while (!(await tcpReachable(this.server.host, this.server.port))) {
-                if (this.stopping)
-                    throw new CalciteError('stopped', 'Stopped while waiting for the server');
-                if (Date.now() > deadline)
-                    throw new CalciteError('server_unreachable', `Server ${this.server.host}:${this.server.port} is not reachable`);
-                await sleep(2000);
-            }
-        }
-        // probe endpoint + config (paths inside may contain spaces; the config file itself lives in a safe dir)
-        this.probe = new ProbeServer();
-        await this.probe.listen();
-        this.probe.on('connected', () => this.onProbeConnected());
-        this.probe.on('disconnected', () => this.note('probe disconnected'));
-        this.probeConfig = join(this.paths.probe, `${this.options.name}-${randomBytes(6).toString('hex')}.properties`);
-        const cfg = [
-            `port=${this.probe.port}`,
-            `token=${this.probe.token}`,
-            `mappings=${this.names?.kind === 'mappings' ? this.names.file.replace(/\\/g, '\\\\').replace(/:/g, '\\:') : ''}`,
-            `headless=${this.headlessValue}`,
-            `render=${this.render === 'always' ? 'on' : 'off'}`,
-            'exitOnDisconnect=true',
-            '',
-        ].join('\n');
-        await mkdir(this.paths.probe, { recursive: true });
-        await writeFile(this.probeConfig, cfg, { mode: 0o600 });
-        await writeOptions(this.gameDir, defaultOptions({ renderDistance: this.options.renderDistance, maxFps: this.options.maxFps }));
-        let displayEnv = {};
-        let virtualDisplay = false;
-        if (!this.headlessValue) {
-            // offline accounts may only render on a virtual display (HeadlessMC); on-demand clients stay invisible when Xvfb exists
-            this.display = await acquireDisplay({ forceVirtual: this.account.type === 'offline' || (this.render === 'on-demand' && which('Xvfb') !== null) });
-            displayEnv = this.display.env;
-            virtualDisplay = this.display.virtual;
-        }
-        const jvmArgs = [`-Xmx${this.options.memory ?? '2G'}`, ...(this.options.jvmArgs ?? [])];
-        if (this.names?.kind !== 'unsupported')
-            jvmArgs.unshift(`-javaagent:${probeJar}=${this.probeConfig}`);
-        const gameArgs = [...(this.options.gameArgs ?? [])];
-        if (this.server) {
-            if (supportsQuickPlay(json))
-                gameArgs.unshift('--quickPlayMultiplayer', `${this.server.host}:${this.server.port}`);
-            else
-                gameArgs.unshift('--server', this.server.host, '--port', String(this.server.port));
-        }
-        for (const arg of [...jvmArgs, ...gameArgs]) {
-            if (/\s/.test(arg))
-                throw new CalciteError('bad_argument', `JVM/game arguments must not contain spaces: "${arg}"`);
-        }
-        const offline = this.account.type === 'offline';
-        const props = {
-            'hmc.gamedir': this.gameDir,
-            'hmc.mcdir': this.paths.minecraft,
-            'hmc.java.versions': java.path,
-            'hmc.offline': String(offline),
-            'hmc.always.lwjgl.flag': String(this.headlessValue),
-            'hmc.check.xvfb': String(virtualDisplay),
-            'hmc.jvmargs': jvmArgs.join(' '),
-            'hmc.gameargs': gameArgs.join(' '),
-            'hmc.exit.on.failed.command': 'true',
-        };
-        if (this.account.type === 'offline')
-            props['hmc.offline.username'] = this.account.username;
-        const command = ['launch', json.id, '-jndi', '-lookup', ...(this.headlessValue ? ['-lwjgl', '-paulscode'] : [])];
-        const env = { ...process.env, ...displayEnv };
-        this.setPhase('starting');
-        this.joinRequested = false;
-        this.startedAt = Date.now();
-        const spawnGame = async () => {
-            let launched;
-            const launchedPromise = new Promise((r) => (launched = r));
-            // 26.x+: when no graphics backend can be created the game opens a modal error box and blocks forever
-            const backendErrors = [];
-            let backendTimer;
-            const noBackend = () => {
-                if (run !== this.run || this.stopping)
-                    return;
-                const hint = process.platform === 'linux'
-                    ? ' On Linux without a GPU install Mesa EGL (apt install libegl1 libegl-mesa0) or Vulkan (apt install mesa-vulkan-drivers), or use render "off".'
-                    : ' Update the graphics drivers, or use render "off".';
-                this.fatalCode = 'renderer_unavailable';
-                this.lastError = `No graphics backend could be created: ${backendErrors.join('; ')}.${hint}`;
-                this.note(this.lastError);
-                this.setPhase('crashed');
-                void killTree(run.child);
-            };
-            this.run = runHmc({
-                javaPath: java.path,
-                hmcJar,
-                paths: this.paths,
-                props,
-                command,
-                env,
-                onLine: (line) => {
-                    this.pushLog('game', line);
-                    if (/Launching version|Minecraft exited|LWJGL Version|Backend library/i.test(line))
-                        launched();
-                    const failure = /BackendCreationException: (.*)/.exec(line);
-                    if (failure) {
-                        backendErrors.push(failure[1].trim());
-                        clearTimeout(backendTimer);
-                        backendTimer = setTimeout(noBackend, 20_000);
-                    }
-                    else if (/Using graphics backend/.test(line))
-                        clearTimeout(backendTimer);
-                },
-            });
-            const run = this.run;
-            void run.exited.then(() => clearTimeout(backendTimer));
-            void run.exited.then((code) => this.onGameExit(run, code));
-            // give HeadlessMC time to read the primary account before another launch may switch it
-            await Promise.race([launchedPromise, run.exited, sleep(60_000)]);
-        };
-        if (this.account.type === 'microsoft') {
-            const wanted = this.account.name;
-            await withLock(accountsLock(this.paths), async () => {
-                const accounts = await listAccounts(this.paths);
-                if (!accounts.length)
-                    throw new CalciteError('not_logged_in', 'No Microsoft account is stored; run `calcite login` first');
-                const match = wanted ? accounts.find((a) => a.name.toLowerCase() === wanted.toLowerCase()) : accounts[0];
-                if (!match)
-                    throw new CalciteError('unknown_account', `No stored Microsoft account named "${wanted}" (have: ${accounts.map((a) => a.name).join(', ')})`);
-                if (!match.primary) {
-                    const select = runHmc({ javaPath: java.path, hmcJar, paths: this.paths, props: {}, command: ['account', match.name] });
-                    await select.exited;
-                }
-                await spawnGame();
-            });
-        }
-        else {
-            await spawnGame();
-        }
-    }
-    async onProbeConnected() {
-        this.note('probe connected');
-        if (this.phaseValue === 'starting' || this.phaseValue === 'reconnecting')
-            this.setPhase('connecting');
-        if (!this.poller) {
-            this.poller = setInterval(() => void this.poll(), 1000);
-        }
-    }
-    async poll() {
-        if (!this.probe?.connected)
-            return;
-        let state;
-        try {
-            state = await this.probe.request('state', {}, 10_000);
-        }
-        catch (err) {
-            if (err instanceof ProbeError && err.code === 'not_ready')
-                return;
-            return;
-        }
-        const prev = this.lastState;
-        this.lastState = state;
-        if (JSON.stringify(prev) !== JSON.stringify(state))
-            this.emit('state', state);
-        if (state.inGame && !state.loading && !LOADING_SCREEN.test(state.screen ?? '')) {
-            if (this.phaseValue !== 'in_game') {
-                this.inGameSince = Date.now();
-                this.everInGame = true;
-                this.setPhase('in_game');
-            }
-            else if (this.reconnects > 0 && Date.now() - this.inGameSince > 60_000) {
-                this.reconnects = 0; // stable again
-            }
-        }
-        else if (this.server &&
-            !this.joinRequested &&
-            this.phaseValue === 'connecting' &&
-            state.screen === 'TitleScreen' &&
-            !state.loading) {
-            // Pre-1.20 versions may ignore --server (e.g. 1.16.4+ when multiplayer privileges cannot be checked)
-            this.joinRequested = true;
-            this.note(`joining ${this.server.host}:${this.server.port} from the title screen`);
-            this.probe.request('connect', { host: this.server.host, port: this.server.port }).catch((err) => this.note(`join failed: ${err.message}`));
-        }
-        else if (state.screen === 'DisconnectedScreen' && this.phaseValue !== 'disconnected' && this.phaseValue !== 'reconnecting') {
-            this.lastError = `Disconnected: ${state.disconnectReason ?? 'unknown reason'}`;
-            this.setPhase('disconnected');
-            void this.maybeReconnect();
-        }
-    }
-    reconnectLimit() {
-        const r = this.options.reconnect;
-        if (r === false)
-            return 0;
-        if (typeof r === 'object')
-            return r.maxAttempts ?? 10;
-        return 10;
-    }
-    async maybeReconnect() {
-        if (this.stopping || this.relaunching || !this.server)
-            return;
-        if (this.reconnects >= this.reconnectLimit()) {
-            this.note(`not reconnecting: ${this.reconnects} attempts used`);
-            return;
-        }
-        this.relaunching = true;
-        try {
-            this.reconnects++;
-            const delay = Math.min(5000 * 2 ** (this.reconnects - 1), 60_000);
-            this.setPhase('reconnecting');
-            this.note(`reconnecting in ${delay}ms (attempt ${this.reconnects})`);
-            if (this.run)
-                await killTree(this.run.child);
-            await sleep(delay);
-            if (this.stopping)
-                return;
-            await this.cleanupRun();
-            await this.launch();
-        }
-        catch (err) {
-            this.lastError = err.message;
-            this.setPhase('crashed');
-        }
-        finally {
-            this.relaunching = false;
-        }
-    }
-    onGameExit(run, code) {
-        if (run !== this.run)
-            return; // an older run
-        this.emit('exit', code);
-        this.note(`game process exited with code ${code}`);
-        if (this.stopping || this.relaunching || this.fatalCode)
-            return;
-        const tail = this.logs.filter((l) => l.source === 'game').slice(-15).map((l) => l.line).join('\n');
-        this.lastError = `Game exited with code ${code}${tail ? `:\n${tail}` : ''}`;
-        this.setPhase('crashed');
-        // a crash during the very first start is reported to start(); later crashes are retried
-        if (this.everInGame)
-            void this.maybeReconnect();
-    }
-    async waitUntilStarted(timeoutMs) {
-        const deadline = Date.now() + timeoutMs;
-        for (;;) {
-            const phase = this.phaseValue;
-            if (phase === 'in_game')
-                return;
-            if (!this.server && this.lastState?.ready && this.lastState.loading === false && phase === 'connecting')
-                return;
-            if (phase === 'crashed')
-                throw new CalciteError(this.fatalCode ?? 'crashed', this.lastError ?? 'The game crashed during startup');
-            if (phase === 'disconnected' && this.reconnectLimit() === 0)
-                throw new CalciteError('disconnected', this.lastError ?? 'Disconnected');
-            if (Date.now() > deadline)
-                throw new CalciteError('start_timeout', `Client did not start within ${timeoutMs}ms (phase ${phase})`);
-            await sleep(250);
-        }
-    }
-    async cleanupRun() {
-        if (this.poller) {
-            clearInterval(this.poller);
-            this.poller = null;
-        }
-        if (this.run) {
-            await killTree(this.run.child);
-            this.run = null;
-        }
-        if (this.probe) {
-            await this.probe.close();
-            this.probe = null;
-        }
-        if (this.probeConfig) {
-            await rm(this.probeConfig, { force: true });
-            this.probeConfig = null;
-        }
-        this.display?.release();
-        this.display = null;
-        this.lastState = undefined;
-    }
-    async shutdown(final) {
-        this.stopping = true;
-        await this.cleanupRun();
-        if (this.releaseInstance) {
-            await this.releaseInstance();
-            this.releaseInstance = null;
-        }
-        this.setPhase(final);
-    }
-    /** Stops the game and releases all resources. */
-    async stop() {
-        if (this.phaseValue === 'stopped' || this.phaseValue === 'idle')
-            return;
-        this.setPhase('stopping');
-        await this.shutdown('stopped');
-    }
-    status() {
-        return {
-            name: this.options.name,
-            version: this.versionJson?.id ?? this.options.version,
-            phase: this.phaseValue,
-            render: this.render,
-            headless: this.headlessValue,
-            account: this.account,
-            server: this.server,
-            gameDir: this.gameDir,
-            pid: this.run?.child.pid,
-            java: this.java?.version,
-            startedAt: this.startedAt,
-            reconnects: this.reconnects,
-            lastError: this.lastError,
-            probeConnected: !!this.probe?.connected,
-            game: this.lastState,
-        };
-    }
-    // ------------------------------------------------------------------ operations
-    requireProbe() {
-        if (this.names?.kind === 'unsupported') {
-            throw new CalciteError('unsupported_version', this.names.reason);
-        }
-        if (!this.probe?.connected)
-            throw new CalciteError('not_connected', `Client "${this.options.name}" is not running (phase ${this.phaseValue})`);
-        return this.probe;
-    }
+export class Client extends ClientCore {
     async state() {
         const state = await this.requireProbe().request('state');
         this.lastState = state;
@@ -603,14 +40,92 @@ export class Client extends EventEmitter {
     async respawn() {
         await this.requireProbe().request('respawn');
     }
+    // ------------------------------------------------------------------ actions
+    /** Turns the player to an absolute rotation (degrees; yaw 0 = south, pitch -90 = up) or towards a point. */
+    async look(to) {
+        return this.requireProbe().request('look', to);
+    }
+    /**
+     * Holds movement controls until changed (or for {@code ticks} game ticks, 20 per second). Pass false to release
+     * a control; {@link stop} releases all of them.
+     */
+    async move(controls, opts = {}) {
+        return this.requireProbe().request('move', { ...controls, ticks: opts.ticks ?? 0 });
+    }
+    /** Releases every control and cancels a running walkTo/dig/held use. */
+    async stopActions() {
+        await this.requireProbe().request('stop');
+    }
+    /**
+     * Walks in a straight line to (x, z), jumping over single blocks and swimming. Resolves when within
+     * {@code range} blocks, or with {@code arrived: false} when stuck (no progress for 3 s) or timed out.
+     * There is no path finding: route around obstacles with intermediate points.
+     */
+    async walkTo(x, z, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 60_000;
+        return this.requireProbe().request('walk_to', { x, z, range: opts.range ?? 0.5, sprint: opts.sprint ?? true, timeoutMs }, timeoutMs + 15_000);
+    }
+    /** Left click: attacks the entity (facing it first) or whatever the crosshair points at. */
+    async attack(entityId) {
+        return this.requireProbe().request('attack', entityId === undefined ? {} : { entityId });
+    }
+    /**
+     * Right click: interacts with an entity, a block (opening chests, pressing buttons, placing the held block
+     * against that face) or, with no target, whatever the crosshair points at / the held item in the air.
+     * {@code holdTicks} keeps the button pressed afterwards (eating, drinking, drawing a bow, shields).
+     */
+    async use(target = {}) {
+        const { block, ...rest } = target;
+        return this.requireProbe().request('use', { ...rest, ...(block ?? {}) });
+    }
+    /** Mines a block like a player (holding left click, taking the real break time). */
+    async dig(block, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        return this.requireProbe().request('dig', { ...block, timeoutMs }, timeoutMs + 15_000);
+    }
+    /** The block at a position as the client sees it. */
+    async block(pos) {
+        return this.requireProbe().request('block', { ...pos });
+    }
+    /** What the crosshair points at. */
+    async target() {
+        return this.requireProbe().request('target');
+    }
+    async inventory() {
+        return this.requireProbe().request('inventory');
+    }
+    /** Selects hotbar slot 0-8. */
+    async selectSlot(slot) {
+        return this.requireProbe().request('select_slot', { slot });
+    }
+    /** The open container (chest, furnace, villager trade, ...) or the inventory; {@code waitMs} waits for one to open. */
+    async container(opts = {}) {
+        const waitMs = opts.waitMs ?? 0;
+        return this.requireProbe().request('container', { waitMs }, waitMs + 15_000);
+    }
+    /**
+     * Clicks a slot of the open container (or the inventory). Modes: pickup (default; button 0 left, 1 right),
+     * quick_move (shift click), swap (button = hotbar slot 0-8 or 40 for the offhand), clone, throw (button 1 =
+     * whole stack), quick_craft, pickup_all. Slot -999 is outside the window.
+     */
+    async click(slot, opts = {}) {
+        return this.requireProbe().request('click', { slot, button: opts.button ?? 0, mode: opts.mode ?? 'pickup' });
+    }
+    async closeContainer() {
+        await this.requireProbe().request('close_container');
+    }
+    /** Drops one item (or the whole stack) from the selected hotbar slot. */
+    async drop(opts = {}) {
+        return this.requireProbe().request('drop', { all: !!opts.all });
+    }
     async setRender(enabled) {
-        if (this.headlessValue)
+        if (this.headless)
             throw new CalciteError('headless', 'This client runs without a renderer');
         await this.requireProbe().request('render', { enabled });
     }
     /** Takes a screenshot and returns the PNG. With {@code keep} the file stays in the game's screenshots folder. */
     async screenshot({ keep = false } = {}) {
-        if (this.headlessValue) {
+        if (this.headless) {
             throw new CalciteError('headless', this.render === 'off'
                 ? 'This client was started with render "off"; start it with render "on-demand" to take screenshots'
                 : 'Screenshots need a renderer: offline accounts can only render on Linux (Xvfb); use a Microsoft account on Windows/macOS');
@@ -632,13 +147,28 @@ export class Client extends EventEmitter {
         const lines = this.chats.filter((c) => c.seq > since);
         return limit ? lines.slice(-limit) : lines;
     }
+    /** Extension events received after {@code since}, optionally only those whose name matches {@code name} (regex). */
+    eventsSince(opts = {}) {
+        const re = opts.name ? new RegExp(opts.name) : undefined;
+        const list = this.events.filter((e) => e.seq > (opts.since ?? 0) && (!re || re.test(e.name)));
+        return opts.limit ? list.slice(-opts.limit) : list;
+    }
+    /** Commands registered by extensions and mods, and the extension jars the probe loaded. */
+    async extensions() {
+        return this.requireProbe().request('ext.list');
+    }
+    /** Calls an extension command, e.g. {@code call('hud.bossbars')}. */
+    async call(name, args = {}, opts = {}) {
+        return this.requireProbe().request('ext.call', { name, args }, opts.timeoutMs ?? 30_000);
+    }
     /**
-     * Waits for a condition: a chat line matching {@code chat} (regex), an entity appearing/disappearing, or a
-     * phase. Resolves with a description of what matched.
+     * Waits for a condition: a chat line matching {@code chat} (regex), an extension event whose name matches
+     * {@code event} (regex), an entity appearing/disappearing, or a phase. Resolves with a description of what matched.
      */
     async waitFor(cond, timeoutMs = 30_000) {
         const deadline = Date.now() + timeoutMs;
         const chatRe = cond.chat ? new RegExp(cond.chat, 'i') : undefined;
+        const eventRe = cond.event ? new RegExp(cond.event) : undefined;
         const startSeq = this.seq;
         for (;;) {
             if (chatRe) {
@@ -646,7 +176,12 @@ export class Client extends EventEmitter {
                 if (hit)
                     return { matched: 'chat', chat: hit };
             }
-            if (cond.phase && this.phaseValue === cond.phase)
+            if (eventRe) {
+                const hit = this.events.find((e) => e.seq > startSeq && eventRe.test(e.name));
+                if (hit)
+                    return { matched: 'event', event: hit };
+            }
+            if (cond.phase && this.phase === cond.phase)
                 return { matched: 'phase' };
             if (cond.entity && this.probe?.connected) {
                 const { present = true, ...query } = cond.entity;
@@ -662,8 +197,8 @@ export class Client extends EventEmitter {
             }
             if (Date.now() > deadline)
                 throw new CalciteError('timeout', `Condition not met within ${timeoutMs}ms`);
-            if (['stopped', 'crashed'].includes(this.phaseValue))
-                throw new CalciteError('not_running', `Client stopped (phase ${this.phaseValue})`);
+            if (['stopped', 'crashed'].includes(this.phase))
+                throw new CalciteError('not_running', `Client stopped (phase ${this.phase})`);
             await sleep(300);
         }
     }