Andrew Kesterson
f005b88980
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m20s
akbasic CI Build / sanitizers (push) Failing after 4m31s
akbasic CI Build / coverage (push) Failing after 3m40s
akbasic CI Build / akgl_build (push) Failing after 22s
akbasic CI Build / mutation_test (push) Failing after 3m28s
`SPRHIT n, kind [,x1, y1, x2, y2]` gives a sprite a collision shape: a box, a circle inscribed in it, or a capsule. `RSPHIT(n, f)` reads it back in SPRHIT's own argument order, the way RSPRITE and RSPPOS already do, and needs no device because it answers from interpreter state. The rectangle is two corners measured from the sprite's top-left, in device pixels -- the same `x1, y1, x2, y2` that `BOX` and `SSHAPE` take. A dialect with two spellings for a rectangle is one nobody can write from memory. Omit it and the shape fits whatever the picture turned out to be, which is what a sprite loaded from a file needs: `SPRSAV "ship.png", 1` takes the image's own size and the program never learns what that was. **A sprite nobody has shaped collides with its whole frame, expansion bits included, exactly as before.** That is a promise rather than a convenience, and it has its own test: the same two sprites in the same two places, once with no SPRHIT and once with a four-pixel box, reporting a collision and then not. Named SPRHIT rather than SPRSHAPE because "shape" already means "a region SSHAPE saved" in this dialect, in this very chapter -- `SPRSAV A$, 1` takes one -- and a reader who typed `SPRSHAPE A$, 1` would have had every reason to. Both names, and RSPHIT, were grepped against every label in docs/, examples/ and both corpora first: a bare word is a label here, so a verb and a label share one namespace and taking a name a checked-in listing already uses would break it silently. `SPRHIT n, 0` takes a sprite out of collision while leaving it on the screen -- the ghost, the flashing invulnerable player, the pickup already taken. Hiding it with `SPRITE n, 0` stops it colliding too, and is what you want when it should not be seen either. The circle answers the complaint chapter 8 already ships a figure of. That figure shows two discs whose *boxes* touch at a corner while the artwork is nowhere near, and `BUMP(1)` reporting a collision; two `SPRHIT n, 2` and it stops. The test asserts both halves so the figure's caption stays true. `tests/verbs_table.c` caught RSPHIT filed after RSPPOS rather than before it, which is the sorted-table test doing exactly the job it exists for. Docs: a new section in chapter 8, rows in the verb and function references in alphabetical order, and chapter 13's "collision is by bounding box" becomes "collision is by shape" with the addition named. 111 with akgl, 110 without, and the artwork breakout still runs clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
61 lines
3.6 KiB
Markdown
61 lines
3.6 KiB
Markdown
# 12. Function reference
|
|
|
|
Every function, alphabetically, generated from the interpreter's own dispatch table.
|
|
|
|
A function is called with parentheses and yields a value; it cannot stand alone as a
|
|
statement. The arity column is how many arguments it takes — the interpreter checks it,
|
|
so a call with the wrong number is a syntax error rather than a surprise.
|
|
|
|
| Function | Args | Form | What it gives |
|
|
|---|---|---|---|
|
|
| `ABS` | 1 | `ABS(n)` | The absolute value of an integer or float. |
|
|
| `ATN` | 1 | `ATN(n)` | Arctangent, in radians. |
|
|
| `BUMP` | 1 | `BUMP(1)` | Which sprites have collided, as a bitmask. **Reading clears it.** |
|
|
| `CHR` | 1 | `CHR(n)` | The character for a Unicode code point, as a string. |
|
|
| `COS` | 1 | `COS(n)` | Cosine, in radians. |
|
|
| `ERR` | 1 | `ERR(n)` | The message text for an error code. `ERR(ER#)` names the last one. |
|
|
| `HEX` | 1 | `HEX(n)` | An integer as hexadecimal text. |
|
|
| `INSTR` | 2 | `INSTR(A$, B$)` | Where `B$` appears in `A$`, counting from zero, or -1. |
|
|
| `LEFT` | 2 | `LEFT(A$, n)` | The leftmost `n` characters. Clamped to the string's length. |
|
|
| `LEN` | 1 | `LEN(x)` | The length of a string, or the element count of an array. |
|
|
| `LOG` | 1 | `LOG(n)` | Natural logarithm. |
|
|
| `MID` | 3 | `MID(A$, start, len)` | A substring, counting from zero. |
|
|
| `MOD` | 2 | `MOD(a, b)` | The remainder of `a / b`. Integers only. |
|
|
| `PEEK` | 1 | `PEEK(addr)` | The byte at a real address. |
|
|
| `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
|
|
| `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
|
|
| `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
|
|
| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
|
|
| `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
|
|
| `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
|
|
| `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
|
|
| `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |
|
|
| `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
|
|
| `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |
|
|
| `SGN` | 1 | `SGN(n)` | -1, 0 or 1 according to the sign. |
|
|
| `SHL` | 2 | `SHL(n, bits)` | Shift left. |
|
|
| `SHR` | 2 | `SHR(n, bits)` | Shift right. |
|
|
| `SIN` | 1 | `SIN(n)` | Sine, in radians. |
|
|
| `SPC` | 1 | `SPC(n)` | A string of `n` spaces. |
|
|
| `STR` | 1 | `STR(n)` | A number as a string. |
|
|
| `TAN` | 1 | `TAN(n)` | Tangent, in radians. |
|
|
| `VAL` | 1 | `VAL(A$)` | A string as a number. Refuses text that is not one. |
|
|
| `XOR` | 2 | `XOR(a, b)` | Bitwise exclusive or. |
|
|
|
|
## Reserved variables
|
|
|
|
Two things a C128 exposes as bare names are ordinary global variables here, because
|
|
this dialect has no variable name without a type suffix:
|
|
|
|
| Here | On a C128 | Holds |
|
|
|---|---|---|
|
|
| `ER#` | `ER` | the code of the last trapped error |
|
|
| `EL#` | `EL` | the line it happened on |
|
|
| `TI#` | `TI` | jiffies — sixtieths of a second — since the host's clock started |
|
|
| `TI$` | `TI$` | the same time as `HHMMSS` |
|
|
|
|
`ER#` carries this interpreter's error code, not a Commodore error number. There is no
|
|
correspondence to reproduce — the errors raised here are not the errors a 1985 ROM
|
|
raised — so print `ERR(ER#)` rather than the number. **[Chapter 15](15-error-codes.md)
|
|
lists every value it can hold.**
|