dolphin_read_range

Instructions

Implementation Reference

• src/tools.ts:517-523 (handler)

  Handler for dolphin_read_range: takes address and length, calls memory.read_bytes via the Dolphin bridge, formats the result as hex bytes.

  case "dolphin_read_range": {
    const len = p.length as number;
    const hex = await dol.call<string>("memory.read_bytes", [a(), len]);
    const bytes = hex.match(/.{2}/g) ?? [];
    const spaced = bytes.map((b) => b.toUpperCase()).join(" ");
    return ok(`${addrHex(a())} [${bytes.length} bytes]:\n${spaced}`);
  }

• src/tools.ts:155-181 (registration)

  Tool registration for dolphin_read_range including inputSchema (address, length) and description.

  {
    name: "dolphin_read_range",
    description:
      "PURPOSE: Read a contiguous range of bytes from PowerPC memory as a hex dump. " +
      "USAGE: For >4 bytes — far cheaper than looping dolphin_read8 (one bridge round-trip vs N). Max 65536 bytes/call; chunk larger reads in 64 KiB. Powers snapshot-diff RAM hunting, unknown-struct inspection, and region capture. " +
      "BEHAVIOR: No side effects. The bridge reads byte-by-byte via Felk's memory.read_u8 then returns hex over the wire. No alignment requirement.\n\n" +
      GC_WII_MEMORY_MAP + "\n\n" +
      "RETURNS: 'ADDR_HEX [N bytes]:' header + space-separated 2-digit uppercase hex bytes.",
    inputSchema: {
      type: "object",
      required: ["address", "length"],
      properties: {
        address: {
          type: "integer",
          minimum: 0,
          description: "Starting absolute PowerPC address. Bytes [address, address+length) are read. No alignment requirement.",
        },
        length: {
          type: "integer",
          minimum: 1,
          maximum: 65536,
          description: "Number of consecutive bytes to read (1-65536). Hard cap is the bridge's max; chunk larger reads yourself.",
        },
      },
      additionalProperties: false,
    },
  },

• src/tools.ts:155-181 (schema)

  Input schema for dolphin_read_range requiring address and length (1-65536).

  {
    name: "dolphin_read_range",
    description:
      "PURPOSE: Read a contiguous range of bytes from PowerPC memory as a hex dump. " +
      "USAGE: For >4 bytes — far cheaper than looping dolphin_read8 (one bridge round-trip vs N). Max 65536 bytes/call; chunk larger reads in 64 KiB. Powers snapshot-diff RAM hunting, unknown-struct inspection, and region capture. " +
      "BEHAVIOR: No side effects. The bridge reads byte-by-byte via Felk's memory.read_u8 then returns hex over the wire. No alignment requirement.\n\n" +
      GC_WII_MEMORY_MAP + "\n\n" +
      "RETURNS: 'ADDR_HEX [N bytes]:' header + space-separated 2-digit uppercase hex bytes.",
    inputSchema: {
      type: "object",
      required: ["address", "length"],
      properties: {
        address: {
          type: "integer",
          minimum: 0,
          description: "Starting absolute PowerPC address. Bytes [address, address+length) are read. No alignment requirement.",
        },
        length: {
          type: "integer",
          minimum: 1,
          maximum: 65536,
          description: "Number of consecutive bytes to read (1-65536). Hard cap is the bridge's max; chunk larger reads yourself.",
        },
      },
      additionalProperties: false,
    },
  },

• bridge/mcp_bridge.py:77-84 (helper)

  Python bridge helper that performs the actual byte-by-byte memory read via Felk's memory.read_u8 and returns hex string.

  def _read_bytes(p):
      address, length = p[0], p[1]
      if length < 1 or length > 65536:
          raise ValueError(f"length must be 1..65536, got {length}")
      out = bytearray(length)
      for i in range(length):
          out[i] = memory.read_u8(address + i)
      return out.hex()