2026-07-31 21:50:50 -04:00
|
|
|
# 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.
|
|
|
|
|
|
Write down that the left operand decides integer or float arithmetic
No behaviour change, by decision. `A# * 0.45` is 0 and `0.45 * A#` is 1.35,
because every operator branches on `self->valuetype` and converts the right
operand to match. It is inherited from the Go reference, a C128 promotes to
float instead, and this interpreter is at least consistent about it -- so a
dialect saying the left operand wins is a defensible position, and changing it
to promotion would alter the result of every mixed expression in every existing
program.
**The defect was that nobody said so.** Chapter 3's "Numbers" did not mention
it, Chapter 13 did not list it among the differences, and nothing fails when a
program gets it wrong -- it computes something else and carries on. The game in
examples/ lost its per-level speed increase to `5.6 + LEVEL# * 0.45` evaluating
to a flat 5.6, and bled velocity out of every bounce through `0 - BLVX%(B#)`
quantising to whole pixels. Both read correctly. Neither produced a diagnostic.
Now said in three places: a section in Chapter 3 with the demonstration and the
two rules that keep a program out of it (put the float on the left, put the
answer somewhere with a `%` on it), a row in Chapter 13 naming it as the
difference from 7.0 most likely to turn a working listing into a quietly wrong
one, and the reasoning on value.h where the operators are declared.
tests/value_arithmetic.c pins it in both directions across multiply and
subtract, with a comment saying it is the documented contract rather than an
accident -- so promotion becomes a decision somebody takes deliberately rather
than a change that could slip in under a passing suite.
TODO.md section 9 item 4, struck as a documentation outcome.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-02 00:23:20 -04:00
|
|
|
### 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](03-the-language.md#the-left-operand-decides-whether-the-arithmetic-is-integer-or-float)
|
|
|
|
|
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.
|
|
|
|
|
|
Document structures: a chapter, the architecture, and the differences
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict
pointers, lists, what is checked and what is not, and how a host shares its own
C structs. Every example in it is executed by docs_examples and byte-compared,
including the refusals -- so a message that changes fails the suite rather than
quietly making the chapter wrong.
The chapter makes one contrast explicitly, because it is the question a reader
will actually have: a misspelled *field* is refused and a misspelled *variable*
still prints zero. The rule underneath is that what the program declared gets
checked and what it did not gets shrugged at -- a variable's name is never
declared, a TYPE's field list is. Structures end up the strictest thing in the
language, not from a higher standard but because they are the only named thing
whose valid spellings are written down.
Chapter 14 gains the layout: an instance is a contiguous run of value slots with
a diagram of where the fields sit, the three-pass prescan and why each pass
exists, why the copy cannot live in akbasic_value_clone(), and why the render
depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13
records that all of this is an addition BASIC 7.0 has nothing like, and the verb
reference gains TYPE, POINT and DIM ... AS.
MAINTENANCE.md gains the two rules that are on a maintainer rather than on a
test: a structure copy must not go through clone, and a field chain gets its own
leaf field. TODO.md section 5 records what was invented and the three limits
that are ours, and section 8 records the two defects the work exposed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 12:03:02 -04:00
|
|
|
### 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](16-structures.md)**
|
|
|
|
|
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.
|
|
|
|
|
|
2026-07-31 21:50:50 -04:00
|
|
|
## Block structure
|
|
|
|
|
|
|
|
|
|
**A whole loop on one line does not loop.**
|
|
|
|
|
|
Execute every documented example as a test
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand
exactly once, when it was written, which is not a standard that survives a
changing interpreter -- and four were already wrong: two transcripts showing a
leading space PRINT does not emit, akbasic_TextSink in README.md missing the
two members it had grown hours earlier, and FILTER's refusal quoted with
wording the code does not use.
tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds.
BASIC programs and transcripts run and are byte-compared against an `output`
block; C snippets compile with -fsyntax-only against the real include path,
which CMake writes out because it is transitive through akerror, akstdlib and
akgl; shell blocks run in a sandbox. Anything that would reconfigure the build
tree, hit the network or re-enter the suite is tagged norun with the reason in
MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision.
An untagged block is a failure rather than a default, and the pass line
reports what it executed by kind. Both exist because the way a harness like
this dies is by quietly matching nothing and passing -- which it duly did on
the first CTest run, where a generator expression evaluating to nothing still
contributed an empty argument that the script read as a filename. The count is
what caught it.
The excerpt check earns its own mention: a block tagged
`c excerpt=include/akbasic/sink.h` must still appear in that header, comments
and whitespace ignored. Compiling it would only redefine the type, so a
compile check could not have found the stale struct, and did not.
Registered as the CTest case docs_examples in both configurations. Fixing the
four wrong examples turned up two interpreter defects, fixed in the previous
commit and recorded in TODO.md section 8.
MAINTENANCE.md is new: the fence-tag reference, what to do when the case
fails, and the conventions that until now only existed inside source comments
-- the three test lists and how two of them invert "passed", the sorted verb
table, that a golden file is never edited to suit this interpreter, and that a
fix gets mutation-checked with a file copy rather than git checkout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 22:41:36 -04:00
|
|
|
```basic
|
2026-07-31 21:50:50 -04:00
|
|
|
10 FOR I# = 1 TO 3 : PRINT I# : NEXT I#
|
Execute every documented example as a test
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand
exactly once, when it was written, which is not a standard that survives a
changing interpreter -- and four were already wrong: two transcripts showing a
leading space PRINT does not emit, akbasic_TextSink in README.md missing the
two members it had grown hours earlier, and FILTER's refusal quoted with
wording the code does not use.
tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds.
BASIC programs and transcripts run and are byte-compared against an `output`
block; C snippets compile with -fsyntax-only against the real include path,
which CMake writes out because it is transitive through akerror, akstdlib and
akgl; shell blocks run in a sandbox. Anything that would reconfigure the build
tree, hit the network or re-enter the suite is tagged norun with the reason in
MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision.
An untagged block is a failure rather than a default, and the pass line
reports what it executed by kind. Both exist because the way a harness like
this dies is by quietly matching nothing and passing -- which it duly did on
the first CTest run, where a generator expression evaluating to nothing still
contributed an empty argument that the script read as a filename. The count is
what caught it.
The excerpt check earns its own mention: a block tagged
`c excerpt=include/akbasic/sink.h` must still appear in that header, comments
and whitespace ignored. Compiling it would only redefine the type, so a
compile check could not have found the stale struct, and did not.
Registered as the CTest case docs_examples in both configurations. Fixing the
four wrong examples turned up two interpreter defects, fixed in the previous
commit and recorded in TODO.md section 8.
MAINTENANCE.md is new: the fence-tag reference, what to do when the case
fails, and the conventions that until now only existed inside source comments
-- the three test lists and how two of them invert "passed", the sorted verb
table, that a golden file is never edited to suit this interpreter, and that a
fix gets mutation-checked with a file copy rather than git checkout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 22:41:36 -04:00
|
|
|
20 PRINT "DONE"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```output
|
|
|
|
|
DONE
|
2026-07-31 21:50:50 -04:00
|
|
|
```
|
|
|
|
|
|
Execute every documented example as a test
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand
exactly once, when it was written, which is not a standard that survives a
changing interpreter -- and four were already wrong: two transcripts showing a
leading space PRINT does not emit, akbasic_TextSink in README.md missing the
two members it had grown hours earlier, and FILTER's refusal quoted with
wording the code does not use.
tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds.
BASIC programs and transcripts run and are byte-compared against an `output`
block; C snippets compile with -fsyntax-only against the real include path,
which CMake writes out because it is transitive through akerror, akstdlib and
akgl; shell blocks run in a sandbox. Anything that would reconfigure the build
tree, hit the network or re-enter the suite is tagged norun with the reason in
MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision.
An untagged block is a failure rather than a default, and the pass line
reports what it executed by kind. Both exist because the way a harness like
this dies is by quietly matching nothing and passing -- which it duly did on
the first CTest run, where a generator expression evaluating to nothing still
contributed an empty argument that the script read as a filename. The count is
what caught it.
The excerpt check earns its own mention: a block tagged
`c excerpt=include/akbasic/sink.h` must still appear in that header, comments
and whitespace ignored. Compiling it would only redefine the type, so a
compile check could not have found the stale struct, and did not.
Registered as the CTest case docs_examples in both configurations. Fixing the
four wrong examples turned up two interpreter defects, fixed in the previous
commit and recorded in TODO.md section 8.
MAINTENANCE.md is new: the fence-tag reference, what to do when the case
fails, and the conventions that until now only existed inside source comments
-- the three test lists and how two of them invert "passed", the sorted verb
table, that a golden file is never edited to suit this interpreter, and that a
fix gets mutation-checked with a file copy rather than git checkout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 22:41:36 -04:00
|
|
|
The loop prints nothing. Block skipping walks source *lines*, so a `NEXT` on the same line as
|
2026-07-31 21:50:50 -04:00
|
|
|
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 3` runs
|
|
|
|
|
with 1, 4, 7 *and 10*.
|
|
|
|
|
- **`FOR I = 1 TO 1` does 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.
|
|
|
|
|
|
Document optional line numbers
Chapter 2 gets the rule and the refusal, chapter 4 gets the payoff for
LABEL, chapter 9 says DSAVE writes the numbers it handed out and to
RENUMBER first if you want gaps, chapter 10 shows a host loading numberless
source, chapter 13 gets the QuickBASIC-shaped divergence, and chapter 14's
source[] passage gets its second half.
Chapter 14 said "two prescans" and listed two; there were three before this
and there are four now, so it lists all four and says which of them reports
against the right line.
TODO.md section 6 records four things found on the way and deliberately not
fixed: set_label() filing into the active scope rather than the root, three
prescans reporting the wrong line number, duplicate written line numbers
still replacing silently, and renumber.c's file-scope scratch arrays.
examples/embed.c runs the same program twice, numbered and not, so the
example compiles the feature rather than describing it. Its header pointed
at ./build/examples/embed, which is not where the binary lands.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 16:43:14 -04:00
|
|
|
## 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
|
|
|
|
|
numbers `GOTO 100` would otherwise find the hundredth line and branch there. It is
|
|
|
|
|
refused before the program runs. `GOTO <label>` is unaffected.
|
|
|
|
|
- **`LIST` and `DSAVE` show the numbers that were handed out**, one apart. `RENUMBER`
|
|
|
|
|
before `DSAVE` if you want gaps to insert into.
|
|
|
|
|
|
|
|
|
|
An unnumbered program is capped at 9998 lines, which is the cap that already applied.
|
|
|
|
|
|
2026-07-31 21:50:50 -04:00
|
|
|
## 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
|
Document every error code a script can see, as chapter 15
ER# held numbers nothing explained. The appendix lists the four error classes
the interpreter prints, the eight codes it owns and what raises each, and the
codes that reach ER# from errno, libakerror and libakgl underneath it.
The table is not asserted. A program in the chapter trips seven of the eight and
prints what it got, and docs_examples byte-compares the result -- so the numbers
are checked rather than claimed. The eighth, 516, is not usefully trappable and
the chapter says why: entering a handler takes a scope, and the pool being empty
is what raised it.
Two things worth a reader's attention came out of writing it. Two codes register
the same ERR() text, so a program must compare the number and print the text.
And VAL reports libakerror's Value Error rather than the interpreter's 517,
which makes that number the platform's rather than ours -- filed as section 6
item 21, not fixed here, because deciding which libakstdlib failures to
translate is a boundary question and ENOENT out of DOPEN is the counter-case.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 07:36:36 -04:00
|
|
|
`ERR(ER#)` for the text, and see [Chapter 15](15-error-codes.md) for the whole list.
|
2026-07-31 21:50:50 -04:00
|
|
|
|
|
|
|
|
## Graphics
|
|
|
|
|
|
Draw into the whole window, not its top-left 320x200
The graphics verbs documented a coordinate transform that did not exist. With
SCALE off a coordinate went straight to akgl_draw_* as a pixel address, so an
800x600 window drew a C128 listing into its corner and left the rest unused --
while the chapter said coordinates were 320x200 and stretching to fit was the
host's business.
akbasic_GraphicsBackend gains a size entry point, require_graphics() asks it
before every verb that draws so a resized window is honoured between two
statements, and 320x200 becomes the fallback for a backend that leaves it NULL.
It is the record's one optional member, so a host written against the old header
keeps the behaviour it had.
SCALE now maps onto the device, and RGR(1)/RGR(2) report the drawing surface so
a program can use a window whose size it did not choose. RGR(0) is BASIC 7.0's
own field, the GRAPHIC mode.
SCALE also mapped xmax onto the width rather than onto the last pixel, so
SCALE 1, 319, 199 followed by DRAW 1, 319, 199 drew nothing at all -- one pixel
past the surface. Fixed in the same line, because it is what makes "SCALE gives
a C128 listing the whole window" true rather than nearly true.
The akgl test renders against a 128x128 target, deliberately smaller than the
old constants: a SCALE still dividing by them misses it entirely rather than
landing somewhere plausible.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 07:35:20 -04:00
|
|
|
- **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, 199` gives it the
|
|
|
|
|
whole window back. `RGR(1)` and `RGR(2)` report the size, and are ours rather than
|
|
|
|
|
7.0's — where 7.0's `RGR` takes only field 0, the `GRAPHIC` mode.
|
2026-07-31 21:50:50 -04:00
|
|
|
- **`SSHAPE` puts a handle in the string, not the pixels.** You can pass it to `GSHAPE`
|
|
|
|
|
and `SPRSAV`; you cannot save it or take its `LEN`.
|
|
|
|
|
- **`WIDTH` is emulated** by drawing parallel passes.
|
Keep what a program draws, instead of making it a sprite
A drawing lasted exactly one frame. The verbs are immediate, they went to the
back buffer, SDL double-buffers and the frontend never clears -- so the only way
to keep a picture was to capture it with `SSHAPE` and install it as a sprite,
which is what `examples/breakout/sprites/breakout.bas` spends two of its eight
sprites doing. That was TODO.md section 9 item 9.
The drawing verbs now render into a layer texture the frame composites under the
text and the sprites. Draw once; it is there on every frame after.
**Bracketed around the step phase, not around each verb.** One pair of
`SDL_SetRenderTarget` calls a frame instead of one per `DRAW`, and it is also
what makes `SSHAPE` read back what the program has just drawn rather than
whatever the last frame left.
**The layer is transparent where nothing was drawn.** It covers the whole window
and composites underneath, so an opaque one would black out the frame the moment
a program issued a single `DRAW`. And a fresh SDL target texture's contents are
undefined, so it is cleared on creation -- skipping that puts uninitialised
memory under the first frame's text and looks like a driver bug rather than a
missing memset.
**The line editor forced a wrinkle worth naming.** `akbasic_frontend_akgl_pump()`
is called from two places with different answers to "is a render target current":
the frame loop calls it between steps, and the sink's editor calls it from
*inside* a step, borrowing a frame while it waits for a typed line. SDL refuses
to present while a target is current, so the pump ends the layer, presents, and
puts it back only if it was the one that ended it. `akgl_frontend` caught this --
it drives a REPL session, and it failed with "You can't present on a render
target" the first time the brackets went in.
This does not make a drawing *visible* on its own. The text layer still repaints
every row it owns, opaque, every frame, and by default it owns the whole window;
`WINDOW` shrinks it and that half was already fixed. The two together are what a
picture needed, and the tests assert both -- a pixel still there a frame later
with nothing redrawn, and a pixel below a shrunk text area surviving the text
repaint. The second assertion wipes to a non-black colour first, because against
black it could not tell a transparent layer from an opaque one.
The tests found two of their own bugs on the way: `stop_runtime()` was not
tearing the graphics backend down, so re-initialising it dropped a live texture
on the floor; and a first draft called `begin()` before `start_runtime()`, which
re-inits the backend, so the assertion read back off an orphaned render target
and passed while proving nothing.
Chapters 6 and 13 stop saying a drawing has to be redrawn every frame, because it
does not. The batch-boundary tear stays documented -- it bites an `SSHAPE`
capture, which matters much less now that capturing is not the only way to keep a
picture.
Both games still run clean. 111 with akgl, 110 without.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
2026-08-02 10:46:10 -04:00
|
|
|
- **Drawing persists, and the text layer covers it.** A drawing goes into a layer that
|
|
|
|
|
survives the frame, so a program draws its picture once and it stays — no redrawing, no
|
|
|
|
|
capturing it into a sprite. What is still true is that the text layer repaints every row
|
|
|
|
|
it owns, opaque, every frame, and by default it owns the whole window. `WINDOW` shrinks
|
|
|
|
|
it and hands the rest over. The two together are what makes a picture usable:
|
|
|
|
|
`WINDOW 0, 0, 39, 1` keeps a one-row status line and gives the drawing verbs everything
|
|
|
|
|
below it.
|
|
|
|
|
- **A drawing still has to fit in one batch.** The host runs a fixed number of source lines
|
|
|
|
|
and then presents, and an `SSHAPE` capture spanning that boundary comes back **half
|
|
|
|
|
drawn** — the part issued since the present, over whatever was there before. 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. This bites a *capture*, not the
|
|
|
|
|
drawing itself, so it matters far less than it did when capturing was the only way to
|
|
|
|
|
keep a picture. The only way a program can see the boundary is to watch `TI#`, which is
|
|
|
|
|
refreshed once per batch.
|
2026-07-31 21:50:50 -04:00
|
|
|
- **`CHAR` ignores its colour argument** and needs a text device with a cursor.
|
|
|
|
|
|
|
|
|
|
## Sound
|
|
|
|
|
|
|
|
|
|
- **`PLAY` and `SOUND` do not block.** The statement after them runs immediately.
|
|
|
|
|
- **`FILTER` is refused.** There is no filter stage to configure.
|
|
|
|
|
- **`PLAY`'s `M` is accepted and does nothing.**
|
|
|
|
|
- **`TEMPO`'s calibration is a choice**, not a transcription.
|
|
|
|
|
|
|
|
|
|
## Sprites
|
|
|
|
|
|
Draw into the whole window, not its top-left 320x200
The graphics verbs documented a coordinate transform that did not exist. With
SCALE off a coordinate went straight to akgl_draw_* as a pixel address, so an
800x600 window drew a C128 listing into its corner and left the rest unused --
while the chapter said coordinates were 320x200 and stretching to fit was the
host's business.
akbasic_GraphicsBackend gains a size entry point, require_graphics() asks it
before every verb that draws so a resized window is honoured between two
statements, and 320x200 becomes the fallback for a backend that leaves it NULL.
It is the record's one optional member, so a host written against the old header
keeps the behaviour it had.
SCALE now maps onto the device, and RGR(1)/RGR(2) report the drawing surface so
a program can use a window whose size it did not choose. RGR(0) is BASIC 7.0's
own field, the GRAPHIC mode.
SCALE also mapped xmax onto the width rather than onto the last pixel, so
SCALE 1, 319, 199 followed by DRAW 1, 319, 199 drew nothing at all -- one pixel
past the surface. Fixed in the same line, because it is what makes "SCALE gives
a C128 listing the whole window" true rather than nearly true.
The akgl test renders against a 128x128 target, deliberately smaller than the
old constants: a SCALE still dividing by them misses it entirely rather than
landing somewhere plausible.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 07:35:20 -04:00
|
|
|
- **Coordinates are window pixels**, not the VIC-II's raster space, and `SCALE` does
|
|
|
|
|
not apply to them.
|
2026-07-31 21:50:50 -04:00
|
|
|
- **`SPRSAV` takes 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.
|
Let a program say what part of a sprite collides
`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
2026-08-02 10:01:33 -04:00
|
|
|
- **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; `SPRHIT`
|
|
|
|
|
narrows that to a box, a circle or a capsule. None of them is pixel-exact.
|
|
|
|
|
- **`SPRHIT` and `RSPHIT` are an addition.** BASIC 7.0 has `COLLISION` and `BUMP` and
|
|
|
|
|
nothing else, and nothing about them changes an existing program.
|
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
|
|
|
- **Collision types 1 and 2 exist.** Type 2 means the rectangles `SOLID` registered, 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.
|
|
|
|
|
- **`SOLID` is 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.
|
2026-07-31 21:50:50 -04:00
|
|
|
- **Priority and multicolour are recorded but not drawn.**
|
|
|
|
|
- **`SPRDEF` is out of scope.**
|
|
|
|
|
|
|
|
|
|
## Files
|
|
|
|
|
|
|
|
|
|
- **`PRINT #` and `INPUT #` need a space before the `#`.** `PRINT#1` scans as a
|
|
|
|
|
variable name.
|
|
|
|
|
- **`RECORD` counts lines**, not fixed-length records.
|
|
|
|
|
- **`BLOAD` requires a length.**
|
|
|
|
|
- **`HEADER`, `COLLECT`, `BACKUP` and `BOOT` are refused.** They operate on a physical
|
|
|
|
|
disk.
|
|
|
|
|
- **`DIRECTORY` is refused** pending a wrapper in the standard library.
|
|
|
|
|
|
|
|
|
|
## Machine
|
|
|
|
|
|
|
|
|
|
- **`SYS` is refused.** There is no 6502 and no ROM.
|
|
|
|
|
- **`FETCH` and `STASH` are the same byte copy.** There is no expansion RAM to tell
|
|
|
|
|
them apart.
|
|
|
|
|
- **`POKE`, `PEEK` and `POINTER` use real process addresses.** A wrong one is a
|
|
|
|
|
segmentation fault, not an error message.
|
|
|
|
|
- **`BANK`, `FAST` and `MONITOR` do not exist.**
|
|
|
|
|
|
|
|
|
|
## Formatting
|
|
|
|
|
|
|
|
|
|
- **`PRINT USING` renders one field per statement.** `PRINT USING "### ###"; A, B` is
|
|
|
|
|
not supported.
|
|
|
|
|
- **Exponential fields (`^^^^`) are not implemented.**
|
|
|
|
|
|
|
|
|
|
## Console
|
|
|
|
|
|
|
|
|
|
- **`SLEEP` and `WAIT` hold the program without blocking the host.** `SLEEP` with no
|
|
|
|
|
host clock does nothing at all rather than waiting forever.
|
|
|
|
|
- **`TI` and `TI$` are `TI#` and `TI$`**, refreshed once per step.
|
|
|
|
|
- **`WAIT` polls ordinary process memory.** Nothing changes it but the host.
|
|
|
|
|
- **`KEY` stores macros and nothing expands them.**
|
|
|
|
|
|
|
|
|
|
## Limits
|
|
|
|
|
|
|
|
|
|
| | |
|
|
|
|
|
|---|---|
|
|
|
|
|
| Source lines | 9999 |
|
|
|
|
|
| Line length | 255 |
|
|
|
|
|
| String length | 255 |
|
|
|
|
|
| Variables | 128 |
|
2026-08-02 00:32:20 -04:00
|
|
|
| Array elements | 1024 per array, 4096 across every array and structure |
|
2026-07-31 21:50:50 -04:00
|
|
|
| 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.
|
2026-08-02 00:32:20 -04:00
|
|
|
|
|
|
|
|
**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.
|