C64_SKILLS/.ai/skills/c64-programming-practices/SKILL.md

Skill: C64 Programming Practices, Patterns, Hints, and Optimization

Use this skill when

The task asks for design advice, best practices, performance improvements, code organization, hybrid BASIC/ML strategy, or C64-specific programming patterns.

Practices

Use the right layer

• BASIC is excellent for quick control flow, menus, simple loaders, demos, and teaching.
• Assembly is best for speed, graphics effects, sound engines, raster work, custom I/O, compression, and tight loops.
• KERNAL calls are best for portability and standard I/O.
• Direct hardware access is best when KERNAL overhead or abstraction gets in the way.

Keep ML small and callable

Build small routines with clear entry and exit conditions. Document:

• Entry address.
• Input registers/memory.
• Output registers/memory.
• Clobbered registers.
• Zero-page locations used.
• Whether interrupts must be enabled/disabled.

Prefer tables

Tables are often faster and simpler than computation on a 1 MHz CPU:

• Screen row address tables.
• Sprite animation pointer tables.
• Sine/cosine movement tables.
• Frequency tables for notes.
• Bit masks.

Preserve bits

Hardware registers often pack unrelated settings into one byte. Use AND/OR masks instead of blind STA/POKE unless replacing the whole register is intended.

Respect PETSCII vs screen codes

• CHROUT expects PETSCII-style character output.
• Screen RAM expects screen codes.
• Key codes are different again.

Optimize only where needed

First make the code correct and stable. Then optimize hot paths:

• Use zero-page addressing.
• Unroll small loops when timing matters.
• Avoid BASIC inside animation loops when ML is available.
• Avoid multiplication/division in raster-critical paths.
• Use precomputed tables.

Keep recovery paths

• Use emulator snapshots.
• Keep STOP/RESTORE or reset strategy when possible.
• Include a routine to restore vectors and screen colors.
• Save original IRQ/NMI vectors before patching.

Common patterns

BASIC bootstrap + ML engine

BASIC loads/starts; ML handles fast loop.

ML service routine called by BASIC

BASIC manages user interaction; ML performs fast operation.

KERNAL I/O wrapper

ML uses KERNAL jump table for file/device operations.

Raster IRQ effect

ML installs IRQ handler; handler changes VIC registers at specific raster lines.

Double-buffered graphics data

Prepare screen/sprite/bitmap data off-screen, then switch pointers/registers.

Agent checklist

1. Choose BASIC, assembly, or hybrid explicitly.
2. Avoid magic numbers; name addresses and masks.
3. Show restore/cleanup logic.
4. Explain cycle/timing assumptions for demos/games.
5. Favor reusable routines over one-off POKEs.