state-and-register-contracts

Documents mutable state addresses and register contracts for Z80 assembly game routines.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Z80 assembly codebases declare state inline next to routines with no variable block, so addresses shift with every build and register clobbering is invisible until it corrupts gameplay. This Skill provides the authoritative inventory of mutable state, byte-order layouts, and per-routine register contracts so changes do not silently break level state, paddle rendering, or the stack. ## Core Features & Use Cases - Mutable-state inventory: Tables every game variable with address, size, owner, writers, and readers, resolved from main.lst rather than hardcoded. - Register contract tables: Documents inputs, outputs, clobbers, and preserved registers for each routine in pelota.asm, colisiones.asm, pala.asm, and the shared print library, including the critical IX global map-pointer rule. - Stack discipline rules: Explains the CALL-to-JP conversion method with static tracing and empirical SP measurement to prevent stack leaks. - Use Case: Before adding a new collision routine, check the contract tables to confirm it must preserve IX, see which scratch bytes are free, and verify whether CalcularAtributo or CRtoATTR is safe given your BC usage. ## Quick Start Ask what registers a routine in colisiones.asm clobbers and whether it is safe to call during gameplay without saving IX.

Frequently Asked Questions about state-and-register-contracts

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

FAQPage Schema
How do I find variable addresses in a Z80 assembly project?

Resolve addresses from the main.lst listing file generated at build time, never hardcode them. Inline DB declarations shift whenever anything earlier in the include order changes size, so only the current build's listing is authoritative.

How do I know which registers an assembly routine clobbers?

Derive contracts by reading each routine body rather than trusting comments, then record inputs, outputs, clobbers, and preserved registers in a table. This Skill provides those tables for pelota.asm, colisiones.asm, pala.asm, and the shared print library.

Why does level state get corrupted after an unrelated change?

The usual cause is a routine clobbering IX, which is a global current-map pointer held across the entire game loop. Any routine called during gameplay must preserve IX, or the next Mostrar_Mapa walks garbage memory.

When should I use JP instead of CALL in assembly?

Use JP for any routine that never returns, such as end-of-game screens or frame-loop entries, since CALL leaks stack bytes per cycle. Verify statically that no RET exists on the path and empirically by measuring SP at a fixed call depth.

Why does inline DB data not reset between games?

Inline DB bytes are initialised by the loader once per LOAD, not once per game, so a second game inherits whatever the first left behind. Any state that must be fresh per round needs an explicit reset routine that writes those bytes.