Andrew Kesterson
9151438fad
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m23s
akbasic CI Build / sanitizers (push) Failing after 4m36s
akbasic CI Build / coverage (push) Failing after 3m41s
akbasic CI Build / akgl_build (push) Failing after 4m45s
akbasic CI Build / mutation_test (push) Failing after 3m31s
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that wanted a title screen had to draw one out of CHAR and GETKEY, which is what both breakout tutorials make a reader do. The interesting part is the impedance mismatch. libakgl's UI is immediate mode -- widgets are re-declared inside a frame bracket every frame and clay borrows their text until the bracket closes -- and a BASIC program says MENU 1, "START" on line 100 and expects it up on line 900, several hundred frames later. So src/ui_akgl.c is retained on this side and immediate on that one: the record's entry points are setters that copy into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set once a frame from the host's pump. No BASIC string, which lives in the per-line value pool, is ever what clay is handed. The shapes are borrowed rather than invented. MENU retires the way SOLID does -- no entries retires one, no arguments retire them all. GETMENU holds the step loop the way GETKEY does, so parking is not blocking: the step still returns, the host keeps its frame rate, and the sprite, audio and collision services keep running underneath because they run before the blocking checks. RMENU(n,1) reads and clears the way BUMP() does. Withdrawing the device or retiring the menu releases a holding GETMENU with 0 rather than wedging the script, which is akbasic_input_service()'s rule for a withdrawn keyboard. One thing a program has to know, and docs/19-user-interface.md says it twice: a menu that is up owns the cursor keys and Return. It has to, and retiring it gives them back -- forget the MENU n before an INPUT and the INPUT never sees the Return that ends it. akbasic_runtime_set_ui() is its own function rather than a fifth argument to akbasic_runtime_set_devices(), whose signature has twenty-eight call sites in tests and documentation that are about something else. deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead centre, so HUD offers exactly those five; TODO.md records what a top-centre and bottom-centre would cost upstream, along with the three other things this deliberately leaves out. No new error code either -- DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free. tools/screenshot.c had to learn that "needs a font" and "draws the text grid" are two questions. They were one, and a UI figure came out black: the text layer owns every pixel of the rows it covers and painted over the widgets. The new ui=1 fence attribute asks for the first without the second; MAINTENANCE.md documents it. 112/112 in both configurations, 112/112 under ASan and UBSan, coverage 94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and 100% of functions, doxygen clean, and the four new figures byte-identical on a re-render. TODO.md section 8's gate table was stale on several counts besides these and is refreshed with measured numbers. Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
74 lines
3.7 KiB
Markdown
74 lines
3.7 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 |
|
|
| **[19. Menus and dialogs](19-user-interface.md)** | `MENU`, `DIALOG`, `HUD` and `UISTYLE` — the widgets, and who owns the keyboard |
|
|
|
|
## 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.
|