# 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 20](20-tutorial-galaga.md)** and
**[21](21-tutorial-galaga-enemies.md)** are the third tutorial, from the other side of
the boundary: a C game on libakgl that embeds the interpreter as its enemy-behavior
engine, for anyone whose question is "how do I put this in *my* game".

## 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 |
| **[19. Menus and dialogs](19-user-interface.md)** | `MENU`, `DIALOG`, `HUD` and `UISTYLE` — the widgets, and who owns the keyboard |
| **[20. Tutorial: GALAGA](20-tutorial-galaga.md)** | Build a C engine on libakgl that embeds the interpreter, boots a script and hands it an actor |
| **[21. Tutorial: GALAGA enemies](21-tutorial-galaga-enemies.md)** | Share three C structs with the script, then write the wave's whole brain in BASIC |

## 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.
