# VIXEN-32 BASIC tutorials Fifteen short programs, one hardware idea each, written to be read as much as run. They need **kernel build 103 or newer** — every one of them prints what it needs, and several use commands (`READF`, `WRITEF`, the screen and font registers) that simply do not exist in older kernels. | File | Shows | Key registers | |------|-------|---------------| | `BAS1` | Poking characters and colors into screen cells | `$B0A7-$B0AC` | | `BAS2` | Defining your own characters from `DATA` | `$B0C0`, `$B0CF`, `$B0CE` | | `BAS3` | 480 unique 8x16 characters = a 320x192 picture | `READF 2`, `$B0CE` | | `BAS4` | Drawing on the hidden map, then flipping to it | `$B0AB` bit 3, `$B046` | | `BAS5` | A hardware sprite, image loaded straight to a slot | `$B030-$B036`, `$B015` | | `BAS6` | The 384x224 bitmap layer, and scrolling it | `$B050-$B055` | | `BAS7` | Copper raster bars — the hardware does it, not you | `$B071-$B079` | | `BAS8` | The beeper (takes Hz) and the SID | `$B0AD/E`, `$B400+` | | `BAS9` | Saving and loading your own data, and the status byte | `READF`, `WRITEF`, `$B0BC-$B0BF` | | `BAS10` | Keyboard, both joystick ports and the jiffy clock | `$B0E0`, `$B060/1`, `$B090` | | `BAS11` | A real 256-color picture, palette and all | `READF 5`, `$B0AF`, `$B0B9-B` | | `BAS12` | `RECT` and `IMAGE` — shapes and a scaled image | `CANVAS`, `RECT`, `IMAGE` | | `BAS13` | Sampled sound, one sample at four pitches | `$B0E2-$B0E8` | | `BAS14` | `LINE` — string art, thickness, clipping, a spinning spoke | `LINE`, `CANVAS` | | `BAS15` | `IMAGE` — one 64x64 image as thirty moving objects | `IMAGE`, `READF` | | `aztec/AZTEC` | Aztec Challenge: run at the pyramid, duck and jump the spears | everything above at once | ## Two formats, and why `BASn.BAS` is the **source**: plain text, the thing you read and edit. `BASn.PRG` is what the machine actually loads. A text file cannot be `LOAD`ed — `LOAD` expects a two-byte load address followed by tokenised BASIC, so a text file's first two characters get taken as an address and nothing sensible happens. The `.PRG` files here were produced by typing the source into the machine and `SAVE`ing it, so they are the real tokeniser's output, not a guess at its format. CD BASIC LOAD "BAS1.PRG" RUN On the card the lessons are `/VIXEN-32/basic/BASn.BAS`: pick one in the file browser (`HELP`) and type `RUN`. From kernel 148 that makes `C:` and the lesson's own folder current, so `READF` finds `FONT16.RAW` and the other data files beside it by name alone. ## The data files `BAS3`, `BAS5` and `BAS6` load binary data with `READF` rather than grinding through `DATA` statements — which is the point of those tutorials as much as the graphics is. | File | Size | What it is | |------|------|------------| | `FONT16.RAW` | 8192 | 512 glyphs of 8x16, 1bpp. The first 480 ARE a 320x192 picture, cut into cells in reading order | | `SHIP.RAW` | 512 | one 64x64 1bpp sprite image | | `PIC256.RAW` | 114688 | 384x224 8bpp, 512-byte row stride — a test pattern | | `DEMO.RAW` | 114688 | the same layer, from a real image | | `DEMO.PAL` | 720 | its 240 colors, three bytes an entry, for `READF 5` | | `SOUND.RAW` | 8192 | two blocks of signed 8-bit samples at 8 kHz | | `IMG64.RAW` | 4096 | one 64x64 **8bpp** image — what `IMAGE` draws, *not* sprite data | `FONT16`, `SHIP` and `PIC256` are generated by `python3 gen_assets.py`. `DEMO.RAW`/`DEMO.PAL` come from `python3 gen_picture.py yourphoto.jpg DEMO` — point it at any image and it resizes, truncates to the RGB565 the hardware actually stores, quantises to the 240 colors BASIC is allowed to set, and writes both files. Nothing here is a binary blob that cannot be reproduced. ## Known limits these tutorials run into * **Only palette entries 0-31 exist at power-on.** 32-255 are black until something fills them in — which `BAS11` does and `BAS6` deliberately does not, so you can see the difference. Entries 0-15 can never be changed. * **Map 0 is the console's.** Anything poked there survives until the screen scrolls, which is why `BAS4` exists. * **A sprite image and an `IMAGE` source are both 64x64 and not the same thing.** Sprites are 1bpp (512 bytes), `IMAGE` is 8bpp (4096 bytes). Pointing `IMAGE` at sprite data draws noise. * **There is no read port for the font.** A glyph can never be `PEEK`ed back, so `WRITEF` cannot save a character set. ## Two EhBASIC traps these tutorials walk into * **`AND` is 16-bit.** `A AND 255` fails outright on a chip address above 65535, so a 24-bit address must be split with division, not masking. (The old `BAS12` hit this before `RECT` existed to do the arithmetic for it.) * **`RND(n)` re-seeds when n is not zero.** `RND(1)` returns the same number every single time. Seed once — `Z=RND(PEEK($B090)+1)` — then always `RND(0)`. `BAS12` drew 200 identical rectangles in the same spot before this was spotted. ## The Aztec Challenge demo `aztec/` holds a homage to the C64's Aztec Challenge: the man runs at the pyramid, it grows as he approaches (one `IMAGE`, rescaled every frame — the fake 3D is a single hardware scale), spearmen throw high from the left and low from the right, he ducks and jumps, and arriving swaps in the full-detail scene with its own palette. Double-buffered, all BASIC. `gen_aztec.py` converts the source art (in the same folder) into one shared 240-color palette plus the `.RAW` files. `BUGS.md` documents a real kernel bug the demo uncovered — the jiffy clock slows to a crawl under a specific sustained blitter load — which is why it paces with a `FOR` loop rather than `PEEK($B090)`.