BBC MICRO · AGENT HANDBOOKALPHA · USE AT YOUR OWN RISK

BBC development: start here

Handbook revision 1 · BBC Micro / Master · Beeb-dev

Read this before generating, building or debugging BBC game code. Project-specific target configuration remains authoritative.

Establish the target before coding

Inspect beeb-dev.ini, the selected environment, project instructions and the existing working example. Record these facts once; update them when they change:

Question	Required evidence
Machine and processor?	Model B / Master; host CPU; Tube type or none.
Language?	Actual interpreter and version (BASIC II / IV), or assembler CPU.
MOS and filing system?	Selected ROMs/configuration; DFS/ADFS affects available RAM and loading.
ROM services?	Configured slots, actual binary versions/hashes and matching API/helpers. Distinguish implemented, experimental and planned.
Memory available?	Program, variables/strings/arrays, software stack, buffers, ROM workspace and screen ownership. Separate host from parasite.
Build/run path?	Configured build/run delegates, input sources, disc output and one known-good baseline command.
Agent tools?	Discover the tools actually connected.

Do not fill unknowns with plausible defaults. Resolve unknowns that affect the next operation by inspecting configuration, references or a small probe. Ask the user only when evidence cannot settle an important choice.

Read only the relevant detail

BBC BASIC and memory: dialect, loading, HIMEM, budget and workspace.
ROMs, tools and verification: ROM-first game design, build/run and debugging discipline.
Agent setup: Kilo, Claude and other hosts; manual installation and updates.
BBC knowledge base (bundled with the extension, served by the Beeb-dev MCP server): beeb_kb_list, then beeb_kb_read / beeb_kb_search. It covers the memory map, CRTC, Video ULA, VIAs, sound/keyboard, OS calls, loader idioms and game techniques. Use it instead of recalled BBC details. Start at its README. Analysing existing game discs follows analysis/assessing-games.

Before the first game change

Read the applicable language/memory and ROM/tool guidance above.
Run the existing known-good baseline in an isolated environment. Record its exact command, profile and outcome. If it fails, resolve the baseline/rig before blaming new game code or changing a ROM.
Check the working tree and preserve unrelated changes. Identify the smallest observable test for the requested change, then implement it using real APIs.

Report separately: build/tokenization; load; interpreter execution; ROM ACK; frame correctness; input/gameplay; sustained timing; tested machine profiles. HTML/link tests do not validate a guest program. An emulator launch or a green mock CPU test does not prove a playable game.