akbasic/docs

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

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.