Andrew Kesterson
802bbcc17a
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m19s
akbasic CI Build / sanitizers (push) Failing after 4m33s
akbasic CI Build / coverage (push) Failing after 3m41s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Failing after 3m29s
`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
127 lines
8.8 KiB
Markdown
127 lines
8.8 KiB
Markdown
# 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]` | Start a loop. The condition may be here, on the `LOOP`, or neither. |
|
|
| `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` | Choose a screen mode, or clear it. |
|
|
| `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]` | End a `DO` loop. |
|
|
| `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 [,...]` | Branch to the `e`th target, counting from one. |
|
|
| `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 from a `TRAP` handler. |
|
|
| `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` | How thick a drawn line is. |
|
|
| `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.
|