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
241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
# 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](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.
|
|
|
|
### 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.
|
|
|
|
## Block structure
|
|
|
|
**A whole loop on one line does not loop.**
|
|
|
|
```basic
|
|
10 FOR I# = 1 TO 3 : PRINT I# : NEXT I#
|
|
20 PRINT "DONE"
|
|
```
|
|
|
|
```output
|
|
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 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.
|
|
|
|
## 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.
|
|
|
|
## 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](15-error-codes.md) 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, 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.
|
|
- **`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.
|
|
- **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 `SSHAPE` at 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 watch `TI#`,
|
|
which is refreshed once per batch — so the step on which it changes is the first step
|
|
of one. [Chapter 18](18-tutorial-breakout-artwork.md#step-5-find-the-frame-boundary)
|
|
builds a pacing routine out of exactly that.
|
|
- **`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
|
|
|
|
- **Coordinates are window pixels**, not the VIC-II's raster space, and `SCALE` does
|
|
not apply to them.
|
|
- **`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.
|
|
- **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.
|
|
- **Only collision type 1 exists.** Types 2 and 3 are refused by name.
|
|
- **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 |
|
|
| 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.
|