Andrew Kesterson
1fb808f480
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m21s
akbasic CI Build / sanitizers (push) Failing after 4m32s
akbasic CI Build / coverage (push) Failing after 3m37s
akbasic CI Build / akgl_build (push) Failing after 22s
akbasic CI Build / mutation_test (push) Failing after 3m30s
Chapters 17 and 18 read as a code review of a finished listing: they explained why each decision had been made, walked through the project's own history, and led with what had once been broken. A reader who wanted to build the game got the reasoning and had to reconstruct the program. Both are now step-by-step. Each opens with a picture of the finished game and a bullet list of the steps, each bullet is a section, and each section states its goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and Chapter 18 is thirteen, and the last of each is the assembly: the order of the file, the full declaration block, and the routines the earlier steps referred to. Project history is gone -- it belongs in Chapter 14 and in git -- and where a listing has to do something awkward, the tutorial shows how first and names the `TODO.md` item that will make it unnecessary second. **Three defects had no entry anywhere**, which the rewrite found by trying to state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`, because `subtraction()` sits above `addition()` as its own precedence level and the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is matched, which is item 12's `if`-where-`while` on the one operator pair item 12 did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope, so a main loop written that way stops on the thirty-second lost life -- which is why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather than a preference. Chapter 3 gains the identifier rule the third trial ran into: there is no underscore in a name, and the error says `UNKNOWN TOKEN _`. **`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1` fence attribute, because Chapter 17's game is characters in the grid and a figure without that layer is two sprites on black. It opens the bundled font at the size the standalone frontend uses, so a figure's cell size is the reader's cell size, and it uses the akgl sink alone rather than a tee so the program's output lands in the picture instead of on the stdout the caller reads to decide a figure failed. Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are generated from listings in the chapters like every other one. Verified by handing each chapter, alone, to an agent on a much smaller model and telling it to build the game from the tutorial text with the `examples/` tree off limits. The first pass scored 3.5 and 3 out of 10 and named what was missing: routines referred to but never shown, the third level layout, the sprite `DATA`, the font table, edits to earlier routines that were never marked as edits. Those are now in. The second pass built a 658-line Chapter 17 game that plays itself for ninety seconds with the score at 1890 and no error line, and the third built a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found, and forty seconds clean. 9/10 and 8/10. One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already caught the ball. Both suites green in both configurations, `docs_examples` and `docs_screenshots --check` pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# 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](http://www.jbrain.com/pub/cbm/manuals/128/C128PRG.pdf):
|
|
the language first, then each hardware area, then the reference sections. If you know
|
|
BASIC 7.0 you can skip to **[Chapter 13](13-differences.md)**, which is the list of
|
|
everything that behaves differently here and why. **[Chapter 14](14-architecture.md)** 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](17-tutorial-breakout.md)** and **[18](18-tutorial-breakout-artwork.md)**
|
|
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](01-introduction.md)** | What akbasic is, what it is not, and how to build it |
|
|
| **[2. Getting started](02-getting-started.md)** | The prompt, your first program, saving and loading |
|
|
| **[3. The language](03-the-language.md)** | Variables, types, arrays, operators, expressions |
|
|
| **[4. Control flow](04-control-flow.md)** | `IF`, `FOR`, `DO`, `GOSUB`, labels, `ON`, error trapping |
|
|
| **[5. Strings and formatting](05-strings-and-formatting.md)** | String functions, `PRINT USING`, `PUDEF` |
|
|
| **[6. Graphics](06-graphics.md)** | `GRAPHIC`, `DRAW`, `BOX`, `CIRCLE`, `PAINT`, shapes |
|
|
| **[7. Sound](07-sound.md)** | `SOUND`, `PLAY`, `ENVELOPE`, `VOL`, `TEMPO` |
|
|
| **[8. Sprites](08-sprites.md)** | `SPRITE`, `SPRSAV`, `MOVSPR`, collision |
|
|
| **[9. Files and disk](09-files-and-disk.md)** | Channels, `DOPEN`, program storage |
|
|
| **[10. Embedding](10-embedding.md)** | Driving the interpreter from C |
|
|
| **[11. Verb reference](11-verb-reference.md)** | Every statement, alphabetically |
|
|
| **[12. Function reference](12-function-reference.md)** | Every function, alphabetically |
|
|
| **[13. Differences from BASIC 7.0](13-differences.md)** | What a C128 programmer needs to know |
|
|
| **[14. Architecture](14-architecture.md)** | How the interpreter is put together, how to debug it, how to change it |
|
|
| **[15. Error codes](15-error-codes.md)** | Appendix: every value `ER#` can hold and every error line the interpreter prints |
|
|
| **[16. Structures](16-structures.md)** | `TYPE`, records, strict pointers, and sharing a C struct with an embedding host |
|
|
| **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, in sixteen steps |
|
|
| **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
|
|
|
|
## The shortest possible start
|
|
|
|
```sh norun
|
|
$ cmake -S . -B build && cmake --build build
|
|
$ ./build/basic
|
|
```
|
|
|
|
```basic repl
|
|
10 FOR I# = 1 TO 5
|
|
20 PRINT "HELLO " + I#
|
|
30 NEXT I#
|
|
RUN
|
|
```
|
|
|
|
```output
|
|
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.
|