andrew/akbasic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fa5623b722bb892d349bbcc4c31cf57658ae2a23
akbasic/docs/11-verb-reference.md
Andrew Kesterson 802bbcc17a
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m19s
Details
akbasic CI Build / sanitizers (push) Failing after 4m33s
Details
akbasic CI Build / coverage (push) Failing after 3m41s
Details
akbasic CI Build / akgl_build (push) Failing after 21s
Details
akbasic CI Build / mutation_test (push) Failing after 3m29s
Details
Collide sprites with rectangles that are not sprites 
`SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id`
retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and
`DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and
mean *sprite met static geometry*.

**This is the thing eight sprite slots made impossible.** A wall of bricks wants
sixty, so until now a program could only collide with one by doing the
arithmetic itself against its own array -- which is exactly what both breakout
listings do, at about two hundred lines between them. A rectangle costs no sprite
slot.

The id is the **program's own number**, 1 to 64, not a minted handle. That is the
whole trick for "which brick did I hit": the id comes back out again, so a wall
built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken
brick is `SOLID I#`.

`COLLISION 2` was refused with "sprite-to-background collision needs the screen
read back every frame", which was true of the question a C128 asks -- a sprite
against the bitmap's set pixels. `SOLID` gives this interpreter a background made
of rectangles instead, which is the same question in a form it can answer. Same
move `SPRSAV` made when it learned to take an image path.
`AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented
"COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is
separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`.

**There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's
uniform grid keeps its cell heads, cell size and origin in file-scope statics, so
it is one index per process -- and `akgl_collision_world_init()` ends in a
`reset()` that memsets those heads *and* calls
`akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its
own collision world would have destroyed every registration that game had made,
on the first `SOLID` a script ran. So the geometry is indexed by an ordinary
array here and pairs go straight to `akgl_collision_test()`, which needs no
world. At sixty-four rectangles that is the right answer anyway; libakgl's own
numbers put a naive sweep at 0.7% of a frame at sixty-four objects.

**The scan now short-circuits when nothing has moved**, and that is what makes
any of it affordable. Its inputs are the sprites' boxes, which slots are
collidable, and the static geometry; if none changed the answer cannot have. A
frame runs one full scan and 255 cached ones. Eight sprites against sixty-four
rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256
times.

The benchmark was rewritten to say which path it is timing, because with the
cache in place a loop that only calls the scan measures the short circuit and
nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached
at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0%
it cost before any of this work**, with static geometry and contacts added on
top.

`NEW` retires the rectangles, where it cannot undefine a sprite pattern: there
*is* an entry point for this one, so leaving them would be a choice, and the
wrong one -- a rectangle is invisible, so one left behind by a deleted program is
an unexplainable collision in the next. `CLR` leaves them alone.

`tests/sprite_verbs.c` gains the whole second path against the mock and its
`COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2
arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains
the end-to-end version, including a full sixty-four-rectangle wall so the proxy
budget is exercised at its ceiling and the pool has to come back intact, and the
sixty-fifth refused by name.

A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than
`akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
2026-08-02 10:25:35 -04:00

8.8 KiB
Raw Blame History

11. Verb reference

Every statement, alphabetically. This list is generated from the interpreter's own dispatch table, so it cannot drift out of step with what the program actually accepts.

A verb marked Refused parses and then reports why it cannot run — see Chapter 13 for the reasoning in each case.

Verb Form What it does
APPEND APPEND n, "name" Open a file on channel n for writing at its end.
AUTO AUTO n Number lines automatically in steps of n. AUTO 0 turns it off.
BACKUP BACKUP Refused. Duplicates one disk onto another; there are no disks.
BEGIN IF c THEN BEGIN Start a block that runs to BEND, so an IF can span lines.
BEND BEND End a BEGIN block.
BLOAD BLOAD "name", addr, len Read a file into memory. The length is required.
BOOT BOOT Refused. Loads and runs a boot sector; there is none.
BOX BOX src, x1, y1, x2, y2 [,angle] Outline a rectangle, optionally rotated.
BSAVE BSAVE "name", from, to Write a range of memory to a file.
CATALOG CATALOG Refused. The other name for DIRECTORY.
CHAR CHAR col, x, y, "text" Put text at a character cell. Needs a sink with a cursor. Terminates the row where it stops, so it erases whatever followed.
CIRCLE CIRCLE src, x, y, rx, ry [,...] Draw an ellipse, arc or polygon.
CLR CLR Drop every variable and function, keeping the program.
COLLECT COLLECT Refused. Validates a disk's block allocation map.
COLLISION COLLISION type [,target] Call a subroutine when sprites collide. No target disarms it.
COLOR COLOR src, index Bind a colour source to a palette index, 1 to 16.
CONCAT CONCAT "a", "b" Append file a to file b.
CONT CONT Resume a program stopped by STOP.
COPY COPY "a", "b" Copy file a to file b.
DATA DATA v [, ...] Declare values for READ. Collected before the program runs.
DCLEAR DCLEAR Close every open channel. The half of a drive reset that means something.
DCLOSE DCLOSE [n] Close channel n, or every channel.
DEF DEF NAME(args) = expr Define a function. Multi-line definitions end in RETURN.
DELETE DELETE [n][-n] Delete lines, with the same range forms as LIST.
DIM DIM A#(n [,...]) Make an array. Subscripts start at zero; n is the count.
DIM … AS DIM S@ AS T, DIM P@ AS PTR TO T Make a structure, or a strict pointer to one. See Chapter 16.
DIRECTORY DIRECTORY Refused. Needs a directory-reading wrapper that does not exist yet.
DLOAD DLOAD "name" Load a program from a file.
DO `DO [WHILE c UNTIL c]`
DOPEN DOPEN n, "name" [,W] Open a file on channel n. W opens it for writing.
DRAW DRAW src, x, y [TO x, y ...] Plot a point or draw a polyline.
DSAVE DSAVE "name" Save the program to a file.
DVERIFY DVERIFY "name" The other name for VERIFY.
END END Stop the program. Does not arm CONT.
ENVELOPE ENVELOPE n, a, d, s, r Define one of PLAY's ten envelope presets.
EXIT EXIT Leave the innermost FOR or DO loop.
FETCH FETCH count, from, to Copy bytes. The same as STASH; there is no expansion RAM.
FILTER FILTER ... Refused. There is no filter stage in the audio backend.
FOR FOR V = a TO b [STEP c] Start a counted loop, ended by NEXT.
GET GET V Take a keystroke if one is waiting, without stopping.
GETKEY GETKEY V Wait for a keystroke, holding the program but not the host.
GOSUB GOSUB line Call a subroutine, returning on RETURN.
GOTO GOTO line Jump to a line or a label.
GRAPHIC `GRAPHIC mode CLR`
GSHAPE GSHAPE A$, x, y Stamp a region saved by SSHAPE.
HEADER HEADER "name" Refused. Formats a disk.
HELP HELP Re-list the line the last error happened on.
IF IF c THEN s [ELSE s] Branch. Everything after THEN belongs to the condition.
INPUT INPUT ["prompt"] V Read a line from the user.
INPUT# INPUT #n, V Read a line from a channel.
KEY KEY [n, "text"] Define a function-key macro, or list them all.
LABEL LABEL NAME Mark this line with a name any branch can use.
LET LET V = expr Assign. Optional; assignment needs no verb.
LIST LIST [n][-n] List the program, or part of it.
LOAD LOAD "name" The other name for DLOAD.
LOCATE LOCATE x, y Move the pixel cursor.
LOOP `LOOP [WHILE c UNTIL c]`
MOVSPR MOVSPR n, ... Move a sprite. Four forms; see Chapter 8.
NEW NEW Erase the program and every variable.
NEXT NEXT V End a FOR loop and advance its counter.
ON `ON e GOTO GOSUB t [,...]`
PAINT PAINT src, x, y Flood-fill the region containing a point.
PLAY PLAY "notes" Queue notes. Does not block.
POINT POINT P@ AT s@ Aim a strict pointer at a structure. See Chapter 16.
POKE POKE addr, byte Write a byte to a real address.
PRINT PRINT [expr] Print a value and a newline.
PRINT# PRINT #n, expr Write a line to a channel.
PUDEF PUDEF "chars" Redefine what PRINT USING pads and punctuates with.
QUIT QUIT End the interpreter.
READ READ V [,...] Fill variables from the next DATA items.
RECORD RECORD n, r [,pos] Position a channel at record r. Records are lines.
RENAME RENAME "a", "b" Rename a file.
RENUMBER RENUMBER [start [,step [,from]]] Renumber lines, rewriting every branch to match.
RESTORE RESTORE [line] Reset the READ cursor, optionally to a line.
RESUME `RESUME [NEXT line]`
RETURN RETURN [expr] Return from a GOSUB or a multi-line DEF.
RUN RUN [line] Run the program, optionally from a line.
SAVE SAVE "name" The other name for DSAVE.
SCALE SCALE on [,xmax, ymax] Turn user coordinates on or off.
SCNCLR SCNCLR Clear the text screen.
SCRATCH SCRATCH "name" Delete a file.
SLEEP SLEEP seconds Pause. Holds the program, not the host.
SOLID SOLID [id [,x1, y1, x2, y2]] Register static collision geometry a sprite can hit. No rectangle retires it; no arguments retires them all. See Chapter 8.
SOUND SOUND v, freq, dur [,...] Play a tone on a voice. Does not block.
SPRCOLOR SPRCOLOR [c1] [,c2] Set the two shared multicolour registers.
SPRHIT SPRHIT n, kind [,x1, y1, x2, y2] Give a sprite a collision shape. Kind 0 none, 1 box, 2 circle, 3 or 4 capsule. No rectangle fits the frame. See Chapter 8.
SPRITE SPRITE n [,on] [,col] [,...] Configure a sprite. Omitted arguments are left alone.
SPRSAV SPRSAV source, n Give sprite n a picture. Three source forms; see Chapter 8.
SSHAPE SSHAPE A$, x1, y1 [,x2, y2] Save a screen region; A$ receives a handle.
STASH STASH count, from, to Copy bytes. The same as FETCH.
STOP STOP Stop the program; CONT resumes it.
SWAP SWAP A, B Exchange two variables of the same type.
SYS SYS addr Refused. There is no 6502 and no ROM to call.
TEMPO TEMPO n How fast PLAY releases its queue.
TRAP TRAP [target] Send errors to a handler. No target disarms it.
TROFF TROFF Turn line tracing off.
TRON TRON Turn line tracing on; each line prints its number in brackets.
TYPE TYPE NAME … END TYPE Declare a record, its fields one per line. See Chapter 16.
VERIFY VERIFY "name" Compare the program in memory against a file.
VOL VOL n Set the overall volume, 0 to 15.
WAIT WAIT addr, mask [,xor] Poll a byte until it matches. Holds the program.
WIDTH `WIDTH 1 2`
WINDOW WINDOW l, t, r, b [,clear] Constrain the text area. Needs a sink with a grid.

Words that are not verbs

AND, ELSE, NOT, OR, REM, STEP, THEN, TO, UNTIL, USING and WHILE are reserved, but none of them is a statement on its own — each is consumed by the verb it belongs to.

Deliberately absent

BANK, FAST, MONITOR and SPRDEF have no table entry at all. The first three are incompatible with a modern machine — there is no bank switching, no CPU speed to control, and no machine-language monitor to drop into. SPRDEF is an interactive full-screen editor rather than a programmable verb.

Reference in New Issue View Git Blame Copy Permalink