Andrew Kesterson
5709dc160c
A drawing lasted exactly one frame. The verbs are immediate, they went to the back buffer, SDL double-buffers and the frontend never clears -- so the only way to keep a picture was to capture it with `SSHAPE` and install it as a sprite, which is what `examples/breakout/sprites/breakout.bas` spends two of its eight sprites doing. That was TODO.md section 9 item 9. The drawing verbs now render into a layer texture the frame composites under the text and the sprites. Draw once; it is there on every frame after. **Bracketed around the step phase, not around each verb.** One pair of `SDL_SetRenderTarget` calls a frame instead of one per `DRAW`, and it is also what makes `SSHAPE` read back what the program has just drawn rather than whatever the last frame left. **The layer is transparent where nothing was drawn.** It covers the whole window and composites underneath, so an opaque one would black out the frame the moment a program issued a single `DRAW`. And a fresh SDL target texture's contents are undefined, so it is cleared on creation -- skipping that puts uninitialised memory under the first frame's text and looks like a driver bug rather than a missing memset. **The line editor forced a wrinkle worth naming.** `akbasic_frontend_akgl_pump()` is called from two places with different answers to "is a render target current": the frame loop calls it between steps, and the sink's editor calls it from *inside* a step, borrowing a frame while it waits for a typed line. SDL refuses to present while a target is current, so the pump ends the layer, presents, and puts it back only if it was the one that ended it. `akgl_frontend` caught this -- it drives a REPL session, and it failed with "You can't present on a render target" the first time the brackets went in. This does not make a drawing *visible* on its own. The text layer still repaints every row it owns, opaque, every frame, and by default it owns the whole window; `WINDOW` shrinks it and that half was already fixed. The two together are what a picture needed, and the tests assert both -- a pixel still there a frame later with nothing redrawn, and a pixel below a shrunk text area surviving the text repaint. The second assertion wipes to a non-black colour first, because against black it could not tell a transparent layer from an opaque one. The tests found two of their own bugs on the way: `stop_runtime()` was not tearing the graphics backend down, so re-initialising it dropped a live texture on the floor; and a first draft called `begin()` before `start_runtime()`, which re-inits the backend, so the assertion read back off an orphaned render target and passed while proving nothing. Chapters 6 and 13 stop saying a drawing has to be redrawn every frame, because it does not. The batch-boundary tear stays documented -- it bites an `SSHAPE` capture, which matters much less now that capturing is not the only way to keep a picture. Both games still run clean. 111 with akgl, 110 without. 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.