map-data-format

Documents the binary map data format and editing rules for a Z80 assembly Breakout game.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Editing levels in Mapas.asm is error-prone because the format is partially undocumented, the level-completion counter lives in an undocumented byte 0, and level progression silently depends on maps being physically adjacent in memory — mistakes produce no assembler errors, only broken gameplay at runtime. ## Core Features & Use Cases - Verified format reference: Documents the true per-map layout (destructible-brick count byte, then Y/count/colour rows terminated by $FF), verified by counting every cell in all four maps. - Rendering and collision constraints: Explains the colour-to-attribute mapping (colour << 3), the special-cased $78 attribute for indestructible colour-8 bricks, and why classify_cell's comparison must stay in sync. - Safe editing checklist: Provides a step-by-step checklist for adding or editing levels, covering byte-0 counting, the 15-entries-per-row limit, the adjacency dependency, and CantidadNiveles synchronization. - Use Case: You want to add a fifth level to the game. The Skill tells you to append it after map3 with no padding, count only destructible bricks (colours 1-7) into byte 0, terminate with DEFB 255, and bump CantidadNiveles — avoiding the silent failure where the level renders garbage or can never be completed. ## Quick Start Ask the assistant to walk you through adding a new level to Mapas.asm using the map data format rules, including the correct byte-0 brick count and placement after map3.

Frequently Asked Questions about map-data-format

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

FAQPage Schema
How do I add a new level to Mapas.asm in this Z80 Breakout game?

Append the new map immediately after map3 with no padding, put the destructible-brick count (colours 1-7 only) in byte 0, encode each row as Y, count, then colour bytes, terminate with DEFB 255, and bump CantidadNiveles in Partida.asm to match.

What is the byte 0 at the start of each map in Mapas.asm?

Byte 0 is the count of destructible bricks in the map, verified by counting every cell in all four maps. Mostrar_Mapa loads it into bricks_left, destroy_brick decrements it, and the level completes when it reaches zero, so an incorrect value breaks completion detection.

Why does level progression break if I reorder maps in Mapas.asm?

Fin_Juego advances levels by incrementing IX past the $FF terminator directly onto the next map's first byte, relying on maps being physically contiguous in memory. Reordering, inserting padding, or splitting maps across files causes silent runtime failures with no assembler error.

How are brick colours converted to screen attributes in PintarMapa.asm?

Colours 1-7 are shifted left three times to place them in the PAPER bits. Colour 8 is special-cased to attribute $78 (bright white paper) because 8 << 3 would overflow into the BRIGHT bit and render invisible black-on-black.

What is the maximum number of bricks per row in a map?

A row can hold at most 15 entries. Bricks are 2 attribute cells wide starting at column 1, and the right border sits at column 31, so entry i occupies columns 1+2i and 2+2i with i ≤ 14.

Why does changing the colour-8 attribute break collision detection?

classify_cell in colisiones.asm reads the painted attribute byte back from the screen and compares it against $78 to identify indestructible bricks. If the rendered attribute changes without updating that comparison, colour-8 bricks misclassify as destructible and corrupt the bricks_left count.