akbasic/examples/megademo/README.md

AKLABS MEGADEMO '85

A demoscene production for akbasic, written as if it were 1985 and this dialect were the machine under the tree. Code and FX by Tachikoma, dedicated to GameCube, megagreetz to starfort.

./build-akgl/basic examples/megademo/megademo.bas

Q or ESC quits. Seven scenes: a title card, a Lissajous braid, a spinning wireframe cube and octahedron — which drift together, ignite a pulsing origin point strobing the next scene's colours, swallow the camera as the perspective scale outgrows the window, and split that origin into the first two raster bars — the raster bars proper, a full-screen vaporwave sunset decompressed out of the listing itself, the sprite bank going supernova — the letters fall into the middle, a fireball throws them at the walls, and a black hole drags everything back into the centre as the transition out — and a finale that composes all of it. A sawtooth chiptune in A minor throughout, with a noise drum break, if a SID answers.

What it leans on

This is a tour of the interpreter's edges, on purpose:

• No RND — it carries Chapter 17's LCG, seeded from TI#.
• No palette writes — the "colour cycle" on the logo is an honest redraw of the same strokes in the next colour, and the raster bars are erased and redrawn two scanlines at a time. The palette is sixteen fixed colours and the demo says so on screen.
• Eight sprites — so the lettering is the sprite bank. Each letter of GAMECUBE is drawn with the stroke font from examples/breakout, captured with SSHAPE, installed with SPRSAV, and tinted with SPRITE.
• SOLID walls and COLLISION 2 — the supernova registers four rectangles and reverses a bearing per RCOLLISION(n, 7). The interpreter does the physics; BASIC does one subtraction. The letters leave the blast on MOVSPR's continuous form, eight bearings fanned evenly around the compass.
• The black hole is RSPPOS plus one rotation — read each letter's position back, rotate the offset from centre, shrink it by 0.86, put it there. Thirty-four frames later everything is in the middle. The screen goes with it: an iris of collapsing black CIRCLEs, which works because the drawing verbs clip silently at the window edge — a fireball and an iris can both start bigger than the screen.
• The camera is a multiplier — the wireframe zoom-through is nothing but the perspective scale growing fourteen percent a frame until the solids' edges leave the window, which the silent clipping permits. The pulsing origin point strobes through the bar ramp table because it is the next scene: it splits, rides the Y axis to the band edges, and stretches into the first two raster bars in place.
• The picture is strings, because DATA is a straw — the pool is 512 items and the font owns ~350, so the full-screen sunset rides in string literals: 160x120 cells, sixteen colours, run-length encoded two characters a run and decoded with INSTR into 5x5 blocks — about 2 KB for the whole base frame. vaporwave.py composes the image in palette space — dithered by row, not pixel, so the gradients band like a CRT instead of shattering the RLE — and owns the generated block between the PICTURE-BEGIN/PICTURE-END markers. Do not hand-edit it; rerun the script. The bird gliding over it is the counterpoint: a genuine 24x21 SPRSAV type-in sprite, 63 bytes, which is everything DATA has room to say. The paint is the reveal, and the exit is a stride-63 column dissolve — 63 is coprime to 160, so the walk hits every column once and looks random while carrying no state. The strings come in 64-character chunks because a source line is 80 columns, like the machines this pretends to be — the decoder carries its cursor from one IM$ entry to the next, and the generator refuses to cut inside a run.
• And then the picture is video. Six delta frames loop the floor grid toward you and crawl the sun's slice pattern — full motion video, 1.3 KB total, about 220 bytes a frame. A delta re-encodes only the rows that changed: an R record jumps the decoder's cursor (two base-36 digits of row), Q skips what stayed, and black draws, which is how a moved grid line is erased. The rays are not in the encoding at all; they are struck live over every frame, which is the difference between a thirty-run grid row and a five-run one. The loop is mathematically exact: line k sits at B*(r^(k+t)-1) so six frames advance t by one and land the set on itself, and the slice period divides the frame count. The generator simulates the decoder and asserts base-plus-deltas reproduces every frame before it will emit a byte.
• 3D with no matrices — the wireframe scene rotates fourteen pooled vertices through two composed axis rotations and a perspective divide, all of it SIN, COS and one division, with the float kept on the left of every product because the left operand decides the arithmetic. Erase is the raster bars' trick: redraw the previous frame's twenty-four edges in black.
• PLAY is one queue — every note holds it for its length and the whole batch plays on one instrument, so three V tracks come out end to end, not layered. The soundtrack is therefore beeper music, the way single-channel tracker tunes were written: sixteenths that take turns being the kick (an O1 root), the pumping bass (O2/O3 octaves) and the rolling arpeggio (O4 and up), two alternating eight-beat batches — Am F C G, then Am F Dm E with the G sharp — and every third batch a bar of noise drums. Noise is real: ENVELOPE's sixth argument is a waveform, 0 to 3, which Chapter 7 forgot to mention. Voice 1 carries the tune so the collision blips (voice 2) and scene sweeps (voice 3) never steal its channel. A batch is four PLAY statements, one bar each — the 80-column line limit will not hold four bars in one string, and it does not need to: the parser's voice, envelope and duration state persists across statements and every PLAY appends to the same queue, so four bars queue exactly as one line would.

It also probes for its hardware like a proper boot loader, with one TRAP per device: no graphics refuses by name and exits, no audio mutes the soundtrack, no text grid drops the status row, and a host that never sets the clock — which is exactly what tools/screenshot.c is — renders each scene as a still and leaves the finale as the picture. The same file runs everywhere; nothing hangs.

The ones that bit

A scalar first assigned inside a GOSUB dies with that call's scope. The first cut computed text centring in a subroutine and read the result after RETURN; every line of text rendered flush left, because the variable read back as a fresh zero. Reads climb the scope chain, so a nested subroutine can use your globals — but a write to a name that exists nowhere creates it in the current scope, and the scope is not coming back. That is why Chapter 18's listings predeclare.

Then the predeclaring bit back. The obvious lesson — predeclare everything — ran the 128-slot variable pool dry the moment the wireframes arrived: Maximum runtime variables reached. A predeclared scratch variable occupies a slot forever; a scoped one gives its slot back at RETURN. So the rule is narrower than it first looks: predeclare a subroutine's outputs and nothing else. This program predeclares four.

And the raster wait strangled the SID. The VSYNC label used to spin on TI# until the jiffy turned — romantic, and fatal. The host releases at most one queued PLAY note per frame, and a frame of 256 executed spin statements is slow enough to drop the release rate below the tune's fifteen notes a second. The queue never reclaims slots until it drains completely, so the backlog compounded quietly for two scenes and then PLAY queue is full killed the show. VSYNC now sleeps a frame — SLEEP holds at no per-step cost — and TUNE traps the overflow on hosts slower than this one, dropping a bar instead of the whole demo. TODO.md §4 carries the measurement.

What it wanted and could not have

Recorded properly in TODO.md §4, "What a demoscene program wanted and could not have": RND as a real function, palette writes, GSHAPE XOR stamping, a way to ask whether PLAY has drained, per-voice PLAY queues so three voices can actually sound together, and a frame-edge wait that is not a busy loop. None of them blocked the demo; all of them left a routine behind that every future game will carry too.