bizhawk_read8

Instructions

Implementation Reference

• src/tools.ts:81-97 (schema)

  Tool definition and input schema for bizhawk_read8, describing the 8-bit read tool, its purpose, usage guidance, behavior (no side effects), return format, and input schema requiring 'address' (integer) with optional 'domain' (string).

  {
    name: "bizhawk_read8",
    description:
      "PURPOSE: Read an unsigned 8-bit byte from emulator memory at the given address. " +
      "USAGE: Use for single-byte status flags, counters, and 8-bit fields. For 16- or 32-bit values use bizhawk_read16/read32 (one call instead of multi-byte assembly); for spans of more than ~4 bytes use bizhawk_read_range (one round-trip instead of N frame-latency hops). " +
      "BEHAVIOR: No side effects — pure read. Reads work the same way whether emulation is paused or running. Returns an error if the named domain doesn't exist, the address is out of range for the domain, or the loaded core doesn't expose memory.read_u8. " +
      "RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)', e.g. '0x09C6: 99 (0x63)'.",
    inputSchema: {
      type: "object",
      required: ["address"],
      properties: {
        address: { type: "integer", minimum: 0, description: ADDRESS_PARAM_DESC(1) },
        domain:  { type: "string", description: DOMAIN_PARAM_DESC },
      },
      additionalProperties: false,
    },
  },

• src/tools.ts:537-537 (handler)

  Handler for bizhawk_read8: calls bh.call('read8', { address, domain }) and formats the result as 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'. This is the case in the CallToolRequestSchema switch statement that executes the tool logic.

  case "bizhawk_read8":  return ok(`${addrHex(a())}: ${fmtHex(await bh.call<number>("read8", { address: a(), ...dom() }))}`);

• src/tools.ts:486-488 (registration)

  Tool registration: TOOLS array (containing all tool definitions including bizhawk_read8) is registered via ListToolsRequestSchema handler, and the CallToolRequestSchema handler dispatches tool names (including 'bizhawk_read8') to their implementations.

  export function registerTools(server: Server, bh: BizhawkServer): void {
    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));

• src/bizhawk.ts:235-264 (helper)

  BizhawkServer.call() method: generic RPC method that enqueues commands to send to BizHawk's Lua bridge over TCP. Used by the handler to invoke 'read8' on the BizHawk side.

  async call<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
    return new Promise<T>((resolve, reject) => {
      const id = this.nextId++;
      const pending: PendingCmd = {
        id,
        method,
        params,
        resolve: (r) => resolve(r as T),
        reject,
      };
  
      const timer = setTimeout(() => {
        // Drop from queue if still waiting; from inflight if already sent.
        this.queue   = this.queue.filter((p) => p.id !== id);
        this.inflight.delete(id);
        if (this.inflight.size === 0) this.awaitingResult = false;
        reject(new Error(
          `BizHawk call "${method}" timed out (${this.timeoutMs}ms) — ` +
          `is the bridge.lua script still polling?`,
        ));
      }, this.timeoutMs);
  
      // Wrap so the timer always clears
      const origResolve = pending.resolve, origReject = pending.reject;
      pending.resolve = (r) => { clearTimeout(timer); origResolve(r); };
      pending.reject  = (e) => { clearTimeout(timer); origReject(e); };
  
      this.queue.push(pending);
    });
  }