Andrew Kesterson
a1dcfcacf3
A grid row is a NUL-terminated string, and `putchar_at()` wrote the character, advanced and terminated -- so `CHAR 1, 40, 1, "#"` on an otherwise empty row stored the `#` at column 40 with `text[1][0]` still `'\0'`, and the render loop, which stops at the terminator, drew nothing at all. The silent nothing is the trap. The write succeeded, the cursor moved, the stdout mirror showed the character, and only the window stayed blank -- so the program looked right everywhere except where it mattered. The documented truncation on the way *back* is fine and is unaffected. `putchar_at()` now fills the gap with spaces before storing. **Padded there rather than in `sink_moveto()`**, which TODO.md proposed: this way `moveto` stays read-only -- the objection that entry raised against its own suggestion -- and a row is only ever padded when a character actually arrives. The pad fills from the terminator rather than replacing it. The buffer is not cleared between rows, so replacing only the terminator would expose the tail of whatever longer row used to be there: writing "ABCDEFGHIJ", truncating it to "ABCX", then writing at column 7 must give "ABCX Z" and not "ABCX FGZ". tests/akgl_backends.c asserts all three cases, and the middle one keeps the truncation pinned. TODO.md section 6 item 32, struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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, and are where the rules that a real program runs into are collected.
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, a step at a time |
| 18. Tutorial: Breakout with artwork | Build it again out of loaded artwork, powerups and a drawn HUD |
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.