cc65-Chess AGENTS.md

Working on cc65 Chess

A chess program in C, originally for ~1 MHz 6502 machines — c64, apple2, atmos, plus4, atari. Faster 6502s came later: cx16 and rp6502, at up to 8 MHz. Then ports that cc65 does not cover — spectrum, mac68k — plus a terminal build used for development. Each port with whichever compiler that machine needs.

doc/engine.md explains how the engine works and is the right thing to read first. This file is the short list of constraints that are easy to violate by accident.

doc/rework-log.md is the working journal, and its last section is the closed search and evaluation portfolios. Read that before proposing a search technique or an evaluation term. B3+B4 shipped (−17.2% per node on a C64). The skill budgets are 400 / 1,200 / 18,000 / 65,000. Do not reopen a rejected candidate by renaming it.

Hard constraints

plat.h and the 0–63 tile numbering are frozen. The 0x88 board representation stays inside the engine and converts at the boundary. This is what lets the platform files that cannot be built here stay untouched.

There is one addition to plat.h since the freeze, and the bar it had to clear is the point. plat_GetSeed() returns a byte of entropy for the opening randomiser. It went in because every machine has a free-running counter, cc65's own asminc names all of them, and the implementation is three lines a port that reads a register and cannot fail visibly — a wrong address gives repeating openings, which is what the engine did anyway. Anything asking to be added here should be held to that: no writes to hardware on a port that cannot be run, and a failure mode nobody has to debug. Note there are eleven platform files, not seven — c64.chr is a separate port, spectrum and mac68k use other compilers, and term is the one that must return a constant.

The frozen interface is wider than plat.h. Every port also reads four globals directly, and this was discovered the hard way:

• gChessBoard[y][x] — pieces, for drawing
• the attacker count for a tile and side — no port ever reads the attacker list
• gTile[0], gTile[1], gPiece[1], gColor[0] — the move log line, valid only inside a undo_FindUndoLine walk; see the log contract below