Andrew Kesterson
8da8d717c8
The previous commit converted `examples/breakout/characters/breakout.bas` and left the chapter teaching three routines the listing no longer has. This closes that. Step 5 gains the `SOLID` registration beside the `BR#()` array, and says why there are two records of the same thing: one is the program's, one is the interpreter's, and the id is the array index plus one so neither has to be looked up from the other. It is also now the only place cells and pixels meet, which Step 2 used to promise about Step 10. Step 10 is rewritten. It was `HITTEST` -- fourteen lines dividing pixels by cell sizes to recover a grid index -- plus `XBRICK` and `YBRICK` testing the ball's leading edge, with a paragraph explaining that the cost of testing an edge rather than a box is missing a brick clipped at the corner by up to seven pixels. All of that is gone. What replaces it asks four questions: which rectangle, is it still there, which way out and how far, and which axis to reverse. Three things in it are worth the reader's attention and get it: `BUMP(2)` is a separate accumulator from `BUMP(1)` so the handler never sees the paddle; the guard against being told about an already-broken brick, because a handler runs a line or two after the overlap; and `SOLID BI# + 1` in `KILLBR`, without which the ball goes on bouncing off a brick that is no longer drawn. That last one is now a row in the rules table. The float note is kept and sharpened rather than dropped. `D%` must be a float because field 4 is one, and the products land in integer `BX#`/`BY#` -- which is safe here because a box against a box gives a normal that is exactly -1, 0 or 1, and would *not* be safe against a circle. Stated as a reason rather than left as something that happens to work. Step 9 loses its two brick calls and its `OX#`/`OY#` backup, with a sentence saying why there is nothing to restore to. Step 16's declaration block and name count follow, and the skeleton arms the handler. Every fenced example still runs; both suites green; the game runs clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
The akbasic guide
akbasic is a BASIC interpreter in the style of Commodore BASIC 7.0 — the dialect the C128 shipped with — and Dartmouth BASIC. It runs programs from a file or from an interactive prompt, and it is also a C library you can link into a game so that players can script it.
These chapters follow the shape of the C128 Programmer's Reference Guide: the language first, then each hardware area, then the reference sections. If you know BASIC 7.0 you can skip to Chapter 13, which is the list of everything that behaves differently here and why. Chapter 14 is the odd one out: it is about the interpreter rather than the language, for anyone embedding it, debugging it or changing it.
Chapters 17 and 18 are tutorials rather than reference: they build one complete game twice, two different ways, in numbered steps you can type in one at a time. Start with 17 — it needs nothing but the earlier chapters, and 18 assumes it.
Chapters
| 1. Introduction | What akbasic is, what it is not, and how to build it |
| 2. Getting started | The prompt, your first program, saving and loading |
| 3. The language | Variables, types, arrays, operators, expressions |
| 4. Control flow | IF, FOR, DO, GOSUB, labels, ON, error trapping |
| 5. Strings and formatting | String functions, PRINT USING, PUDEF |
| 6. Graphics | GRAPHIC, DRAW, BOX, CIRCLE, PAINT, shapes |
| 7. Sound | SOUND, PLAY, ENVELOPE, VOL, TEMPO |
| 8. Sprites | SPRITE, SPRSAV, MOVSPR, collision |
| 9. Files and disk | Channels, DOPEN, program storage |
| 10. Embedding | Driving the interpreter from C |
| 11. Verb reference | Every statement, alphabetically |
| 12. Function reference | Every function, alphabetically |
| 13. Differences from BASIC 7.0 | What a C128 programmer needs to know |
| 14. Architecture | How the interpreter is put together, how to debug it, how to change it |
| 15. Error codes | Appendix: every value ER# can hold and every error line the interpreter prints |
| 16. Structures | TYPE, records, strict pointers, and sharing a C struct with an embedding host |
| 17. Tutorial: Breakout | Build a whole game out of the text grid and two DATA sprites, in sixteen steps |
| 18. Tutorial: Breakout with artwork | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
The shortest possible start
$ cmake -S . -B build && cmake --build build
$ ./build/basic
10 FOR I# = 1 TO 5
20 PRINT "HELLO " + I#
30 NEXT I#
RUN
HELLO 1
HELLO 2
HELLO 3
HELLO 4
HELLO 5
READY
Two things in that program are not Commodore BASIC and will catch you out
immediately: variables carry a type suffix (I# is an integer) and +
concatenates a string with a number. Chapter 3 explains both.
Every example in these chapters is executed by the test suite and its output
compared byte for byte — see MAINTENANCE.md if you are editing them.