Documentation

BBC MICRO · AGENT HANDBOOKALPHA · USE AT YOUR OWN RISK

ROMs, tools and verification

Prefer real ROM services on the hot path

BASIC should orchestrate game state and rules. Before writing a BASIC pixel, sprite, particle, audio or 3D-maths loop, check for an applicable implemented service in the paired ROM. Use its documented wrapper/transport and measure the result on the target: full-screen clears, repeated calls and Tube transfers still cost time.

Component Responsibility Read before use
EGFX Bitmap drawing, sprite/resources, effects and presentation. Paired docs/basic.md, docs/API.md, docs/architecture.md, actual src/gfx-basic.bas and relevant demo/test.
EAudio Music/effect playback; game chooses events and scheduling. Paired EAudio transport and workspace docs.
Game code Rules, scoring, input, collisions and game-specific state/assets. Game specification and existing game tests.

Never generate executable calls from a roadmap, editor placeholder or guessed helper name. When references conflict, check the actual binary, dispatch source, wrapper and executable test as a matched set; document the discrepancy rather than guessing which edition is “latest”. Keep ROM slots, API versions and resource formats explicit.

Discover and use the available tools

Beeb-dev reads environments from beeb-dev.ini. Prefer configured build/run scripts: they may seed ROM slots, filesystem priority and isolated emulator state. Read the relevant installed beeb-build, beeb-run-debug, beeb-memory or beeb-screen-assets skill when doing that work. Installed skills can fall behind the extension or ROMs; compare them with the matching revision.

Discover connected MCP tools first. The Beeb-dev MCP server provides:

Tool What it does
beeb_project_info Reads the environments, configured ROM slots and build/run delegates from beeb-dev.ini.
beeb_build Builds an environment and returns the exit code and output.
beeb_run Launches an environment in B-em through its run delegate.
beeb_memory_map Lists assembler labels and addresses from the build.
beeb_list_assets, beeb_list_sprites Lists the project's assets and sprite resources, with their formats.
beeb_read_screen, beeb_export_screen Reads and exports Beeb Screen Editor documents.
beeb_compile_basic Compiles a subset of BBC BASIC to 6502 assembly.
beeb_kb_list, beeb_kb_read, beeb_kb_search Lists, reads and searches the bundled BBC knowledge base.
beeb_disc_catalogue, beeb_basic_listing Read .ssd/.dsd/.zip catalogues and detokenise BASIC, including bytes after the program end.
beeb_hw_scan, beeb_disassemble Scans a binary for hardware and OS calls, with a confidence for each hit, and disassembles it.
beeb_cpu_run Runs 6502 code for a bounded number of steps with stubbed OS calls, then dumps memory: useful for decryptors and relocators.
beeb_verify_claims Checks instruction, byte, catalogue, BASIC, string and run claims against the binaries.

Analysis tools read and write only inside the project root and directories listed in BEEB_DEV_ANALYSIS_ROOTS (path-separator list) in the MCP server's environment.

If MCP is unavailable, say so and use the documented project scripts; don't spend time trying nonexistent tools or claim you used MCP. Configure a server with the actual installed extension's out/mcp/server.js and BBC project root, not the website root. Instructions and MCP are separate installations. Never grant unrestricted permissions merely to make a tool work.

Build a trustworthy debugging loop

  1. Run the unchanged known-good baseline using the exact machine, ROM/disc and harness. Verify hashes and matching labels before using label addresses.
  2. Work in an isolated B-em runtime/profile with a bounded timeout. Preserve the user's running emulator. Reuse existing capture/run scripts before constructing another shell harness.
  3. Verify input bytes: shell quoting around interpolated variables can change them. Prefer a proven typed-input path, or inspect the bytes, before changing guest code.
  4. Capture the guest error and line, or a meaningful guest checkpoint. Compare bytes when a round trip has to be byte-identical.
  5. Capture the actual main framebuffer/window, not an occluding debugger/memory viewer. With -debug, B-em opens a separate "B-Em Memory View" window beside the BBC display; both share the emulator PID, so picking a window by PID alone (e.g. xdotool search --pid ... | tail -1) can photograph the memory monitor instead of the screen. Enumerate the PID's windows with names and capture the display window, or move the memory view off-screen first. Do not guess memory banking/zero-page semantics from an all-FF dump; establish which processor, bank and address space the debugger is reading.
  6. Keep one falsifiable hypothesis per probe. If the control fails, investigate the rig before declaring a ROM regression. Do not modify ROMs without scope.
  7. Clean up only processes/session resources you own. Avoid global pkill -f patterns: they can kill the invoking shell or someone else's emulator.

Record the exact baseline/probe commands, observed errors, target profile and remaining uncertainty. Report builds, mock/CPU tests, interpreter/emulator checks, visual/input acceptance and performance separately.