VICE C64 Emulator MCP Server

Overview Schema Related Servers Score Discussions

readSprites

Debug C64 sprite issues by reading hardware sprite states including position, color, enable status, and expansion flags to identify visibility, color, or size problems.

Instructions

Read state of all 8 hardware sprites with interpreted values.

Returns for each sprite:

Position (X, Y) with visibility check
Color (with name)
Enable status
Multicolor mode
X/Y expansion (double size)
Priority (in front of / behind background)
Data pointer address

Use this to debug sprite issues like:

"Why is my sprite invisible?" → check enabled, position, pointer
"Wrong colors?" → check multicolor mode and color registers
"Wrong size?" → check expand flags

Options:

enabledOnly: Only return enabled sprites (default: false)

Related tools: readVicState, readMemory (for sprite data)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`enabledOnly`	No	Only return enabled sprites (default: false)

Implementation Reference

src/index.ts:1405-1523 (handler)

Main handler function for 'readSprites' tool. Reads VIC-II registers ($D000-$D02E), CIA2 bank info, sprite pointers from screen RAM + $3F8. Computes positions, colors, expansion, priority, multicolor mode for each of 8 sprites. Uses helpers for visibility check and data address validation. Returns structured sprite data with issues and hints.

    try {
      // Read VIC registers
      const vicData = await client.readMemory(0xd000, 0xd02e);

      // Read CIA2 for bank info (needed for sprite pointer calculation)
      const cia2Data = await client.readMemory(0xdd00, 0xdd00);
      const bankInfo = getVicBank(cia2Data[0]);

      // Get screen address for sprite pointers
      const d018 = vicData[0x18];
      const videoAddrs = getVideoAddresses(d018, bankInfo.baseAddress);

      // Sprite pointers are at screen + $3F8
      const spritePointerBase = videoAddrs.screenAddress + 0x3f8;
      const spritePointers = await client.readMemory(
        spritePointerBase,
        spritePointerBase + 7
      );

      const spriteEnable = vicData[0x15];
      const spriteXMsb = vicData[0x10];
      const spriteYExpand = vicData[0x17];
      const spriteXExpand = vicData[0x1d];
      const spriteMulticolor = vicData[0x1c];
      const spritePriority = vicData[0x1b];

      const sprites = [];

      for (let i = 0; i < 8; i++) {
        const enabled = !!(spriteEnable & (1 << i));

        // Skip disabled sprites if enabledOnly
        if (args.enabledOnly && !enabled) continue;

        // X position (9-bit)
        const xLow = vicData[i * 2];
        const xHigh = (spriteXMsb & (1 << i)) ? 256 : 0;
        const x = xLow + xHigh;

        // Y position (8-bit)
        const y = vicData[i * 2 + 1];

        const visibility = isSpriteVisible(x, y, enabled);

        // Sprite data address with region validation
        const pointer = spritePointers[i];
        const dataAddress = bankInfo.baseAddress + pointer * 64;
        const addressInfo = validateSpriteDataAddress(dataAddress);

        sprites.push({
          index: i,
          enabled,
          position: {
            x,
            y,
            visible: visibility.visible,
            visibilityReason: visibility.reason,
          },
          color: getColorInfo(vicData[0x27 + i]),
          multicolor: !!(spriteMulticolor & (1 << i)),
          expandX: !!(spriteXExpand & (1 << i)),
          expandY: !!(spriteYExpand & (1 << i)),
          priority: (spritePriority & (1 << i)) ? "behind" : "front",
          pointer: {
            value: pointer,
            hex: `$${pointer.toString(16).padStart(2, "0")}`,
          },
          dataAddress: {
            value: dataAddress,
            hex: `$${dataAddress.toString(16).padStart(4, "0")}`,
            region: addressInfo.region,
            severity: addressInfo.severity,
            warning: addressInfo.warning,
          },
        });
      }

      const enabledCount = sprites.filter((s) => s.enabled).length;
      const visibleCount = sprites.filter((s) => s.position.visible).length;

      // Collect visibility issues
      const visibilityIssues = sprites
        .filter((s) => s.enabled && !s.position.visible)
        .map((s) => `Sprite ${s.index}: ${s.position.visibilityReason}`);

      // Collect data address issues (warnings and errors)
      const addressIssues = sprites
        .filter((s) => s.enabled && s.dataAddress.warning)
        .map((s) => `Sprite ${s.index}: ${s.dataAddress.warning} (${s.dataAddress.hex})`);

      const allIssues = [...visibilityIssues, ...addressIssues];

      // Build hint based on most critical issue
      let hint: string;
      if (addressIssues.length > 0) {
        hint = `⚠️ ${addressIssues.length} sprite(s) with suspicious data address: ${addressIssues[0]}`;
      } else if (visibilityIssues.length > 0) {
        hint = `${visibilityIssues.length} enabled sprite(s) not visible: ${visibilityIssues[0]}`;
      } else if (enabledCount === 0) {
        hint = "No sprites enabled";
      } else {
        hint = `${enabledCount} sprite(s) enabled, ${visibleCount} visible`;
      }

      return formatResponse({
        count: sprites.length,
        enabledCount,
        visibleCount,
        sprites,
        spriteMulticolor0: getColorInfo(vicData[0x25]),
        spriteMulticolor1: getColorInfo(vicData[0x26]),
        issues: allIssues.length > 0 ? allIssues : undefined,
        hint,
      });
    } catch (error) {
      return formatError(error as ViceError);
    }
  }
);

src/index.ts:1374-1523 (registration)

Registration of the 'readSprites' tool with MCP server, including full description and Zod input schema allowing optional 'enabledOnly' boolean.

server.registerTool(
  "readSprites",
  {
    description: `Read state of all 8 hardware sprites with interpreted values.

Returns for each sprite:
- Position (X, Y) with visibility check
- Color (with name)
- Enable status
- Multicolor mode
- X/Y expansion (double size)
- Priority (in front of / behind background)
- Data pointer address

Use this to debug sprite issues like:
- "Why is my sprite invisible?" → check enabled, position, pointer
- "Wrong colors?" → check multicolor mode and color registers
- "Wrong size?" → check expand flags

Options:
- enabledOnly: Only return enabled sprites (default: false)

Related tools: readVicState, readMemory (for sprite data)`,
    inputSchema: z.object({
      enabledOnly: z
        .boolean()
        .optional()
        .describe("Only return enabled sprites (default: false)"),
    }),
  },
  async (args) => {
    try {
      // Read VIC registers
      const vicData = await client.readMemory(0xd000, 0xd02e);

      // Read CIA2 for bank info (needed for sprite pointer calculation)
      const cia2Data = await client.readMemory(0xdd00, 0xdd00);
      const bankInfo = getVicBank(cia2Data[0]);

      // Get screen address for sprite pointers
      const d018 = vicData[0x18];
      const videoAddrs = getVideoAddresses(d018, bankInfo.baseAddress);

      // Sprite pointers are at screen + $3F8
      const spritePointerBase = videoAddrs.screenAddress + 0x3f8;
      const spritePointers = await client.readMemory(
        spritePointerBase,
        spritePointerBase + 7
      );

      const spriteEnable = vicData[0x15];
      const spriteXMsb = vicData[0x10];
      const spriteYExpand = vicData[0x17];
      const spriteXExpand = vicData[0x1d];
      const spriteMulticolor = vicData[0x1c];
      const spritePriority = vicData[0x1b];

      const sprites = [];

      for (let i = 0; i < 8; i++) {
        const enabled = !!(spriteEnable & (1 << i));

        // Skip disabled sprites if enabledOnly
        if (args.enabledOnly && !enabled) continue;

        // X position (9-bit)
        const xLow = vicData[i * 2];
        const xHigh = (spriteXMsb & (1 << i)) ? 256 : 0;
        const x = xLow + xHigh;

        // Y position (8-bit)
        const y = vicData[i * 2 + 1];

        const visibility = isSpriteVisible(x, y, enabled);

        // Sprite data address with region validation
        const pointer = spritePointers[i];
        const dataAddress = bankInfo.baseAddress + pointer * 64;
        const addressInfo = validateSpriteDataAddress(dataAddress);

        sprites.push({
          index: i,
          enabled,
          position: {
            x,
            y,
            visible: visibility.visible,
            visibilityReason: visibility.reason,
          },
          color: getColorInfo(vicData[0x27 + i]),
          multicolor: !!(spriteMulticolor & (1 << i)),
          expandX: !!(spriteXExpand & (1 << i)),
          expandY: !!(spriteYExpand & (1 << i)),
          priority: (spritePriority & (1 << i)) ? "behind" : "front",
          pointer: {
            value: pointer,
            hex: `$${pointer.toString(16).padStart(2, "0")}`,
          },
          dataAddress: {
            value: dataAddress,
            hex: `$${dataAddress.toString(16).padStart(4, "0")}`,
            region: addressInfo.region,
            severity: addressInfo.severity,
            warning: addressInfo.warning,
          },
        });
      }

      const enabledCount = sprites.filter((s) => s.enabled).length;
      const visibleCount = sprites.filter((s) => s.position.visible).length;

      // Collect visibility issues
      const visibilityIssues = sprites
        .filter((s) => s.enabled && !s.position.visible)
        .map((s) => `Sprite ${s.index}: ${s.position.visibilityReason}`);

      // Collect data address issues (warnings and errors)
      const addressIssues = sprites
        .filter((s) => s.enabled && s.dataAddress.warning)
        .map((s) => `Sprite ${s.index}: ${s.dataAddress.warning} (${s.dataAddress.hex})`);

      const allIssues = [...visibilityIssues, ...addressIssues];

      // Build hint based on most critical issue
      let hint: string;
      if (addressIssues.length > 0) {
        hint = `⚠️ ${addressIssues.length} sprite(s) with suspicious data address: ${addressIssues[0]}`;
      } else if (visibilityIssues.length > 0) {
        hint = `${visibilityIssues.length} enabled sprite(s) not visible: ${visibilityIssues[0]}`;
      } else if (enabledCount === 0) {
        hint = "No sprites enabled";
      } else {
        hint = `${enabledCount} sprite(s) enabled, ${visibleCount} visible`;
      }

      return formatResponse({
        count: sprites.length,
        enabledCount,
        visibleCount,
        sprites,
        spriteMulticolor0: getColorInfo(vicData[0x25]),
        spriteMulticolor1: getColorInfo(vicData[0x26]),
        issues: allIssues.length > 0 ? allIssues : undefined,
        hint,
      });
    } catch (error) {
      return formatError(error as ViceError);
    }
  }
);

src/index.ts:1398-1403 (schema)

Zod input schema for readSprites tool: optional boolean 'enabledOnly' to filter only enabled sprites.

    enabledOnly: z
      .boolean()
      .optional()
      .describe("Only return enabled sprites (default: false)"),
  }),
},

src/utils/c64.ts:150-164 (helper)

Helper function used in readSprites to check if sprite position (x,y) is within visible screen area (24-343 x, 50-249 y) and enabled. Returns visibility status and reason if invisible.

export function isSpriteVisible(x: number, y: number, enabled: boolean): {
  visible: boolean;
  reason?: string;
} {
  if (!enabled) {
    return { visible: false, reason: "Sprite is disabled ($D015)" };
  }
  if (x < SPRITE_VISIBLE_X_MIN || x > SPRITE_VISIBLE_X_MAX) {
    return { visible: false, reason: `X position ${x} is outside visible range (${SPRITE_VISIBLE_X_MIN}-${SPRITE_VISIBLE_X_MAX})` };
  }
  if (y < SPRITE_VISIBLE_Y_MIN || y > SPRITE_VISIBLE_Y_MAX) {
    return { visible: false, reason: `Y position ${y} is outside visible range (${SPRITE_VISIBLE_Y_MIN}-${SPRITE_VISIBLE_Y_MAX})` };
  }
  return { visible: true };
}

src/utils/c64.ts:193-277 (helper)

Validates sprite data address against C64 memory map regions, categorizes as ok/warning/error with explanations (e.g., error in I/O, warning in BASIC area). Used in readSprites for dataAddress field.

export function validateSpriteDataAddress(address: number): SpriteDataAddressInfo {
  // Zero page - very wrong for sprite data
  if (address < 0x0100) {
    return {
      region: "Zero page",
      severity: "error",
      warning: "Sprite data in zero page - likely wrong pointer",
    };
  }

  // Stack - definitely wrong
  if (address < 0x0200) {
    return {
      region: "Stack",
      severity: "error",
      warning: "Sprite data in stack area - definitely wrong",
    };
  }

  // BASIC program area - might conflict with code
  if (address >= 0x0801 && address < 0x2000) {
    return {
      region: "BASIC program area",
      severity: "warning",
      warning: "Sprite data in BASIC area - may conflict with program",
    };
  }

  // Default screen RAM - usually wrong
  if (address >= 0x0400 && address < 0x0800) {
    return {
      region: "Default screen RAM",
      severity: "warning",
      warning: "Sprite data in screen RAM - probably wrong",
    };
  }

  // Common sprite data areas - OK
  if (address >= 0x2000 && address < 0x4000) {
    return {
      region: "Common sprite area",
      severity: "ok",
    };
  }

  // VIC bank 1 sprite area - OK
  if (address >= 0x4000 && address < 0x8000) {
    return {
      region: "VIC bank 1 sprite area",
      severity: "ok",
    };
  }

  // VIC bank 2 - has ROM shadow issues
  if (address >= 0x8000 && address < 0xc000) {
    return {
      region: "VIC bank 2",
      severity: "ok",
    };
  }

  // I/O area - cannot store sprite data here
  if (address >= 0xd000 && address < 0xe000) {
    return {
      region: "I/O space",
      severity: "error",
      warning: "Cannot store sprite data in I/O space",
    };
  }

  // High memory - ROM shadow area
  if (address >= 0xe000) {
    return {
      region: "KERNAL ROM area",
      severity: "warning",
      warning: "Sprite data may conflict with KERNAL ROM shadow",
    };
  }

  // Other areas
  return {
    region: describeAddress(address) || "RAM",
    severity: "ok",
  };
}

Tool Definition Quality

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by detailing the return structure (e.g., position, color, enable status) and debugging use cases. However, it lacks information on potential side effects, error handling, or performance characteristics like rate limits, leaving minor gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded, starting with the core purpose, followed by return details, usage examples, options, and related tools. Each sentence adds clear value without redundancy, making it efficient and easy to parse for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (debugging tool with detailed returns), no annotations, and no output schema, the description does a strong job by specifying the return structure and use cases. However, it could improve by mentioning error conditions or response formats more explicitly, leaving slight room for enhancement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the 'enabledOnly' parameter's purpose ('Only return enabled sprites') and default value in the 'Options' section, providing context beyond the schema. However, it doesn't elaborate on edge cases or interactions with other parameters, keeping it from a perfect score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the verb 'Read' and the resource 'state of all 8 hardware sprites with interpreted values', clearly distinguishing it from siblings like readVicState or readMemory. It specifies the exact scope (8 hardware sprites) and output format (interpreted values), making the purpose highly specific and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance with a 'Use this to debug sprite issues like:' section listing three concrete scenarios (e.g., invisible sprite, wrong colors, wrong size). It also names related tools (readVicState, readMemory) as alternatives for different contexts, clearly indicating when to use this tool versus others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/simen/vice-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server