Andrew Kesterson
802bbcc17a
`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
11 KiB
13. Differences from BASIC 7.0
If you already write Commodore BASIC, this is the chapter to read first. Everything
here is deliberate, and everything is recorded in the repository's TODO.md with the
reasoning — this is the short version.
The language
Variables carry a type suffix, and the suffixes differ
| Integer | Float | String | |
|---|---|---|---|
| C128 | A% |
A |
A$ |
| akbasic | A# |
A% |
A$ |
There is no such thing as an unsuffixed variable. A bare name is a label.
= works in a condition, and == works everywhere
IF A = 5 THEN does what you expect. == also means equality and is what the older
programs in this repository use. Outside a condition = is assignment, as always.
AND, OR and NOT in conditions
These work, and a condition is a whole expression rather than a single comparison, so
IF A = 1 AND B = 2 THEN parses. Truth is nonzero, so IF A THEN works too.
MID and INSTR count from zero
A C128 counts from one. A failed INSTR gives -1 rather than 0.
THEN needs a verb
IF X THEN 100 is not a jump. Write IF X THEN GOTO 100.
Strings are 255 characters and cannot contain a quote
There is no escape character.
Numbers
Integers are 64-bit and floats are IEEE doubles, so PRINT 1.5 gives 1.500000. A
leading zero is not octal; 0x is hexadecimal.
Mixed arithmetic follows the left operand, not the wider type
A C128 promotes to float. This does not. An integer on the left converts the right
operand to an integer and throws its fraction away, so A# * 0.45 is 0 where
0.45 * A# is 1.35. It is consistent, it is inherited from the Go interpreter this was
ported from, and nothing fails when you get it wrong — the program computes something
else and carries on.
Chapter 3 has the two rules that keep you out of it. This is the difference from 7.0 most likely to turn a working listing into a quietly wrong one.
Structures are an addition
BASIC 7.0 has no records at all. TYPE/END TYPE, DIM X@ AS T, the @ suffix, . and
->, PTR TO and POINT ... AT are all new here, and Chapter 16
is the whole of it. Nothing about it changes an existing program.
Two consequences a C128 programmer should know. A structure assignment copies, like
every other assignment; sharing is spelled POINT. And a type name is a bare word, so it
shares a namespace with verbs and labels — TYPE POINT is refused because POINT is now a
verb.
Block structure
A whole loop on one line does not loop.
10 FOR I# = 1 TO 3 : PRINT I# : NEXT I#
20 PRINT "DONE"
DONE
The loop prints nothing. Block skipping walks source lines, so a NEXT on the same line as
its FOR is never reached. The same applies to DO/LOOP. Write loops across lines.
Two known defects in FOR
Both are recorded, both have tests asserting the correct behaviour, and both are waiting on a decision rather than on work:
- A step that overshoots runs the body one extra time.
FOR I = 1 TO 9 STEP 3runs with 1, 4, 7 and 10. FOR I = 1 TO 1does not run its body at all, where every other BASIC runs it once.
The two errors cancel out for a step of 1, which is why they went unnoticed. Fixing them would change the output of a checked-in acceptance file, which is not something this project does silently.
A loop counter does not survive its loop. It lives in the loop's own scope, so reading it afterwards gives zero.
Direct mode
A statement typed with no line number runs immediately, as it should. This was not true until recently — the interpreter used to file everything but a handful of verbs as program text.
Line numbers
A program in a file does not need them. Every BASIC this dialect descends from required a number on every line; here that requirement belongs to the prompt alone, where the number is the only thing separating program text from a statement to run now. A program loaded from a file, or handed to the library as a string, may leave them out, and a line without one is given the next number going. The two mix: a numbered line sets where the next unnumbered one goes.
This is QuickBASIC's idea rather than the C128's, and it is here for the same reason
QuickBASIC had it — a program that branches by LABEL never names a line number, so the
numbers are maintenance with nothing on the other end of it.
Two consequences worth knowing:
GOTO <number>must name a number the program wrote. In a file with no line numbersGOTO 100would otherwise find the hundredth line and branch there. It is refused before the program runs.GOTO <label>is unaffected.LISTandDSAVEshow the numbers that were handed out, one apart.RENUMBERbeforeDSAVEif you want gaps to insert into.
An unnumbered program is capped at 9998 lines, which is the cap that already applied.
Errors
ER and EL are ER# and EL#, ordinary global variables. ER# holds this
interpreter's error code, which bears no relation to a Commodore error number. Print
ERR(ER#) for the text, and see Chapter 15 for the whole list.
Graphics
- A coordinate is a window pixel, not one of 320 by 200. A C128 listing therefore
draws in the top-left corner of a larger window;
SCALE 1, 319, 199gives it the whole window back.RGR(1)andRGR(2)report the size, and are ours rather than 7.0's — where 7.0'sRGRtakes only field 0, theGRAPHICmode. SSHAPEputs a handle in the string, not the pixels. You can pass it toGSHAPEandSPRSAV; you cannot save it or take itsLEN.WIDTHis emulated by drawing parallel passes.- Drawing does not persist across frames. The verbs draw straight to the renderer, so anything drawn is overwritten on the next frame unless the program redraws it. This is a defect, not a design.
- And a redraw has to fit. The host runs a fixed number of source lines and then
presents the frame, and presenting discards the drawing buffer — so a sequence of
drawing verbs longer than one batch comes back half drawn, with an
SSHAPEat the end capturing only what was issued since the present. "Redraw it every frame" is therefore not sufficient advice on its own. Measured against the standalone frontend's 256 lines a batch: after synchronising to a jiffy edge, 220 lines of drawing survive a capture and 250 do not. The only way a program can see the boundary is to watchTI#, which is refreshed once per batch — so the step on which it changes is the first step of one. Chapter 18 builds a pacing routine out of exactly that. CHARignores its colour argument and needs a text device with a cursor.
Sound
PLAYandSOUNDdo not block. The statement after them runs immediately.FILTERis refused. There is no filter stage to configure.PLAY'sMis accepted and does nothing.TEMPO's calibration is a choice, not a transcription.
Sprites
- Coordinates are window pixels, not the VIC-II's raster space, and
SCALEdoes not apply to them. SPRSAVtakes an integer array, not a string, for the data form — a string here cannot hold a zero byte. It also takes an image file path, which a C128 cannot.- A sprite loaded from a file keeps the image's own size, not 24 by 21.
MOVSPR's speed unit is a choice. The manual does not say what a unit is worth.- Collision is by shape, not by pixel. A sprite nobody has shaped collides with its
whole frame, expansion bits included, which is what a bounding box means here;
SPRHITnarrows that to a box, a circle or a capsule. None of them is pixel-exact. SPRHITandRSPHITare an addition. BASIC 7.0 hasCOLLISIONandBUMPand nothing else, and nothing about them changes an existing program.- Collision types 1 and 2 exist. Type 2 means the rectangles
SOLIDregistered, not a screen read back — a C128 collides a sprite against the bitmap's set pixels and this cannot, so the question is asked against geometry instead. Type 3 is still refused; there is no light pen. SOLIDis an addition. BASIC 7.0 has no static collision geometry at all, and it is what lets a program collide with something that is not one of the eight sprites.- Priority and multicolour are recorded but not drawn.
SPRDEFis out of scope.
Files
PRINT #andINPUT #need a space before the#.PRINT#1scans as a variable name.RECORDcounts lines, not fixed-length records.BLOADrequires a length.HEADER,COLLECT,BACKUPandBOOTare refused. They operate on a physical disk.DIRECTORYis refused pending a wrapper in the standard library.
Machine
SYSis refused. There is no 6502 and no ROM.FETCHandSTASHare the same byte copy. There is no expansion RAM to tell them apart.POKE,PEEKandPOINTERuse real process addresses. A wrong one is a segmentation fault, not an error message.BANK,FASTandMONITORdo not exist.
Formatting
PRINT USINGrenders one field per statement.PRINT USING "### ###"; A, Bis not supported.- Exponential fields (
^^^^) are not implemented.
Console
SLEEPandWAIThold the program without blocking the host.SLEEPwith no host clock does nothing at all rather than waiting forever.TIandTI$areTI#andTI$, refreshed once per step.WAITpolls ordinary process memory. Nothing changes it but the host.KEYstores macros and nothing expands them.
Limits
| Source lines | 9999 |
| Line length | 255 |
| String length | 255 |
| Variables | 128 |
| Array elements | 1024 per array, 4096 across every array and structure |
| Scopes | 32 |
| Labels | 64 |
DATA items |
512 |
| File channels | 10 |
| Operations per line | roughly 16 |
Every one is a fixed pool. Nothing in the interpreter calls malloc, which is what
makes it safe to embed in a game that cannot afford a surprise allocation.
A scalar does not come out of the 4096. It lives in the variable itself, so creating
one inside a GOSUB or a FOR — including the loop counter — costs nothing and can be
done for as long as the program runs. An array declared inside a scope does come out of
it and is not given back: the pool never frees, which is what lets a pointer into a
record outlive the scope that declared it. In practice that means DIM at the top rather
than in a loop, which is where you would have put it anyway.