memory-map-and-playfield

Documents ZX Spectrum attribute-file playfield addressing, drawing, and collision rules for assembly game code.

Updated Nov 29, 2024
One-click install
npx skills add https://github.com/SpeedRD/Arkanoid_Z80 --skill memory-map-and-playfield-speedrd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: memory-map-and-playfield
Source: https://github.com/SpeedRD/Arkanoid_Z80/tree/main/.claude/skills/memory-map-and-playfield
Command: npx skills add https://github.com/SpeedRD/Arkanoid_Z80 --skill memory-map-and-playfield-speedrd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When writing or debugging ZX Spectrum assembly game code, developers corrupt the screen because the playfield is the attribute file itself — erasing an entity overwrites whatever was underneath, and attribute values like $38 and $10 are ambiguous between ball, paddle, and bricks. This Skill provides the memory map, cell-to-address arithmetic, and drawing rules needed to avoid those bugs. ## Core Features & Use Cases - Memory map reference: Documents the full address layout from ROM through the attribute file ($5800-$5AFF), program image, free RAM, and stack, with warnings that symbol addresses shift on every build. - Attribute byte semantics: Explains FLASH/BRIGHT/PAPER/INK bit layout and why attribute values are ambiguous ($38 is both the ball and a colour-7 brick), requiring position-based entity discrimination. - Cell-to-address routines: Compares the three implementations (PosXY, CalcularAtributo, CRtoATTR) including register clobbering contracts like CalcularAtributo destroying BC. - Use Case: While adding a collision routine, you need to read the cell the ball is about to occupy. This Skill tells you to compute the address as $5800 + row x 32 + column, identify entities by position rather than attribute value, and preserve BC across the conversion call. ## Quick Start Explain how to safely draw and erase an entity on the Spectrum attribute playfield without destroying bricks or the border.

Frequently Asked Questions about memory-map-and-playfield

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a row and column to a Spectrum attribute address?

Compute the address as $5800 + row x 32 + column. Three routines exist in the codebase: PosXY (H=row, L=column, preserves AF), CalcularAtributo (B=row, C=column, clobbers BC), and CRtoATTR (preserves BC and stores the result in SCR_ATTR_PTR).

Why do bricks disappear when the ball passes through them?

The playfield is the attribute file, so erasing the ball by writing 0 paints the cell black and destroys whatever was underneath. The fix is erase-restore: the ball saves the cell's byte in BallSaved before drawing and writes it back afterward, plus it is confined to rows 1-22 and columns 1-30.

How do I tell the ball apart from a brick on screen?

You cannot distinguish them by attribute value: $38 is both the ball and a colour-7 brick, and $10 is both the paddle and a colour-2 brick. Discriminate by position instead — the paddle is only on row 23, the border on column 0, column 31 and row 0, and bricks in between.

Where can I put new game state in ZX Spectrum RAM?

Free RAM exists at $5B00-$7FFF (9472 bytes) and from $A0CF upward, but neither is initialised by loading the binary. Inline DB declarations are initialised only once per load, not per game, so reset code must write every such byte explicitly.

Why does CalcularAtributo break my map rendering loop?

CalcularAtributo clobbers BC by executing ld bc,$5800, so any caller loop using B or C loses its counters. Use CRtoATTR instead when BC must survive, since it performs the same conversion while preserving BC.