4 Commits

Author	SHA1	Message	Date
Andrew Kesterson	9151438fad	Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers ... 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	2026-08-02 18:37:10 -04:00
Andrew Kesterson	1fb808f480	Rewrite the two game tutorials as instructions rather than commentary ... Chapters 17 and 18 read as a code review of a finished listing: they explained why each decision had been made, walked through the project's own history, and led with what had once been broken. A reader who wanted to build the game got the reasoning and had to reconstruct the program. Both are now step-by-step. Each opens with a picture of the finished game and a bullet list of the steps, each bullet is a section, and each section states its goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and Chapter 18 is thirteen, and the last of each is the assembly: the order of the file, the full declaration block, and the routines the earlier steps referred to. Project history is gone -- it belongs in Chapter 14 and in git -- and where a listing has to do something awkward, the tutorial shows how first and names the `TODO.md` item that will make it unnecessary second. **Three defects had no entry anywhere**, which the rewrite found by trying to state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`, because `subtraction()` sits above `addition()` as its own precedence level and the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is matched, which is item 12's `if`-where-`while` on the one operator pair item 12 did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope, so a main loop written that way stops on the thirty-second lost life -- which is why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather than a preference. Chapter 3 gains the identifier rule the third trial ran into: there is no underscore in a name, and the error says `UNKNOWN TOKEN _`. **`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1` fence attribute, because Chapter 17's game is characters in the grid and a figure without that layer is two sprites on black. It opens the bundled font at the size the standalone frontend uses, so a figure's cell size is the reader's cell size, and it uses the akgl sink alone rather than a tee so the program's output lands in the picture instead of on the stdout the caller reads to decide a figure failed. Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are generated from listings in the chapters like every other one. Verified by handing each chapter, alone, to an agent on a much smaller model and telling it to build the game from the tutorial text with the `examples/` tree off limits. The first pass scored 3.5 and 3 out of 10 and named what was missing: routines referred to but never shown, the third level layout, the sprite `DATA`, the font table, edits to earlier routines that were never marked as edits. Those are now in. The second pass built a 658-line Chapter 17 game that plays itself for ninety seconds with the score at 1890 and no error line, and the third built a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found, and forty seconds clean. 9/10 and 8/10. One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already caught the ball. Both suites green in both configurations, `docs_examples` and `docs_screenshots --check` pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL	2026-08-02 08:08:23 -04:00
Andrew Kesterson	3415c9aec6	Take libakgl 0.5.0 and rename every symbol it namespaced ... 0.5.0 gives every exported symbol the akgl_ prefix, which is the first libakgl release to break this project's source rather than only its ABI. The soname goes to libakgl.so.0.5 and include/akbasic/akgl.h asserts the floor. What moved here: akgl_render_bind2d is akgl_render_2d_bind, akgl_sprite_sheet_coords_for_frame is akgl_spritesheet_coords_for_frame, the renderer, camera and window globals carry the prefix, and _akgl_renderer and _akgl_camera are akgl_default_renderer and akgl_default_camera. The renames were applied by site rather than by pattern, because renderer is also a parameter name in src/sprite_akgl.c and a struct member throughout src/frontend_akgl.c -- a substitution would have rewritten both without a word. That is the same trap upstream describes hitting, and it is worth knowing that the defect behind the rename was not cosmetic: an exported global called renderer collided with a test's own variable, the executable's definition preempted the library's, and every texture load in that suite failed while the suite passed. 0.5.0 also fixes libakgl defect 26, which was one of the two reasons src/sprite_akgl.c installs its own renderfunc: akgl_actor_render took its destination height from the sprite's width, drawing a 24x21 Commodore sprite as a 24x24 square. The renderfunc stays, because the other reason has not moved -- an actor carries one scalar scale and SPRITE has separate x- and y-expand bits -- but the comments and TODO.md deviation 40 no longer claim a defect that is fixed. Every documentation figure re-renders byte-identical under the new library, which is what says the sprite and drawing paths did not move underneath them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 08:01:43 -04:00
Andrew Kesterson	16b38c1138	Generate the documentation's figures from the listings they illustrate ... Chapters 6 and 8 described what a verb draws in prose. Eight figures now show it, and each one is produced by running the BASIC listing printed immediately above it -- so a picture cannot drift away from the code beside it, which is the way a screenshot goes wrong and the way nothing notices. tools/screenshot.c is a second SDL host, much smaller than the frontend: dummy video driver, software renderer, run to completion, read the target back, write a PNG. It draws no text layer on purpose, so a READY in the corner is not noise in a figure about BOX and no font has to be resolved. tools/docs_screenshots.sh reads the new screenshot=NAME fence tag straight out of the markdown. size=WxH is the second tag, and SCALE's figure uses it: the point being made is a 320x200 listing filling a larger window, which cannot be made on a 320x200 surface. Two gates, answering different questions. docs_examples fails a tagged block with no image, in both configurations, so a figure cannot be added and forgotten. docs_screenshots -- a CTest, AKGL build only -- re-renders every figure and compares byte for byte, so a listing edited without regenerating fails. Only the second catches a stale picture. The PNGs are checked in because a reader on the forge has no build tree, and docs/images/README.md says loudly that they are generated. Regenerating is never part of a build: the target is run deliberately, so a make cannot put eight binary diffs in front of whoever ran it. Drawing the BOX figure caught a defect in TODO.md itself. Deviation 16 claimed in bold that BOX fills on a negative angle while its own paragraph said the fill was filed rather than implemented. BOX cannot fill, and filled_rect is reached by no verb as a result. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-01 07:37:04 -04:00