1987 · Ocean

Wizball

This minisite was contributed by air. It’s agent-generated and needs a human editor. Clone https://github.com/gamesexplained/gamesexplained and follow kit/START.md to curate games/c64/wizball with me to Gold.

Sensible Software's shooter, read from its code: how a ball you can only spin gets anywhere, and why the game crashes itself when its clock stops.

01 · One frame, rebuilt from memory

Twelve raster bands a frame

The play screen is several screens stacked. A raster interrupt at $7C73 runs twelve short routines on the way down every frame, and each one points the video chip at a different screen, character set or group of sprites.

Choose a band to light the lines it controls.

Drawn by this page from a snapshot of level 1 in play: the screen at $E000 and colour memory, the character sets at $F000 and $F800, the sprites, and the video chip's registers and sprite pointers as each band left them, read at every interrupt of one frame. Thirteen pixels come out differently from the game's own picture: twelve are stars, which twinkle between the frame shown and the moment memory was read, and the thirteenth, on line 239, is not explained.

The list of bands lives in memory as data ($B3E2 in play): a first raster line, then four bytes a band, the routine's address and the line of the next interrupt. The interrupt writes each routine's address into the operand of its own JSR at $7C9D and calls it. Other screens install other lists through $7CB4: the title, the player menu, name entry, "get ready!" and the three Wiztips pages each have their own.

The icon bar at the top and the cauldrons at the bottom sit in the border, where a C64 normally shows nothing. At line 247 the band $8BBB switches the screen to 24 rows: after the line where a 24-row screen starts its bottom border, and before the line where a 25-row screen does, so the border never switches on. The band at line 65 puts 25 rows back. Sprites show in the open border, and that is what the icons and cauldrons are.

Sprite 0 appears three times in one frame. From line 48 it is the beam's upper arc, at two lines above the Wizball it becomes the Wizball, and 20 lines further down it becomes the beam's lower arc. The band $8A52 writes those two raster lines into the list every frame ($B3F6, $B3FA), so the bands follow the ball up and down.

02 · The sound

Music: Martin Galway's tunes, from the stored bytes

Nine tunes and 26 sound effects share the SID's three voices. A music mode ($B8F1) says which voices the music has: none, voice 3 only, or all three; the effects get the rest.

A port of the driver ($45BD-$5524, with the two routines in the tune data that command $D6 calls and the clock at $B8F3), started as the game starts each tune, playing through the site's model of the SID.

Eight of the nine tunes put a voice, or all three, through the SID's filter at full resonance, and a four-step filter program sweeps its cutoff every tick (update_filter_sweep, $4CB7). Only Colour completed leaves it off. The title selects low-, band- and high-pass together, the others low-pass alone (start_tune, $45F1). The Filter switch plays each tune three ways, and changes it while it plays. Off leaves the filter out. 6581 is the original C64's chip, on the cutoff curve the reSID emulator (version 0.16) measured from one such chip. That curve is nearly flat low down: every setting up to 500 of 2047 lands between 220 and 400 Hz, so Police alarm's sweep, from 200 to 550, moves the cutoff only from about 240 to 500 Hz. 8580, the chip of later C64s, is close to a straight line, and takes the same sweep from about 1,240 to 3,540 Hz. Real 6581s differ from one another in where each setting puts the cutoff, and they distort, which this model does not (site/lib/sid.js).

The driver ($4553-$5524) keeps each voice's track as a list of notes and commands with a call-and-repeat stack five levels deep. Each voice has a 29-byte instrument (voice 1 at $87, voice 2 at $4680, voice 3 at $A4): four pitch steps or an arpeggio, a two-step pulse sweep, gate and release times. The notes come from a table tuned for PAL at $471A. A command can call machine code stored among the tune data, which the tunes use to set up the filter. The voice 2 and voice 3 code switches a note off and on again within one frame, so the attack restarts at every note; a model that heard only the registers at the end of each frame would lose it.

The two bonus-stage tunes take turns: the first bonus stage after loading plays one, the next plays the other, and $BB0C keeps the turn from one game to the next. The Wiz-lab has its tune only after the second of the two ($AB66); after the first it is silent. Every command byte some voice understands is used by at least one tune, and the notes run from the eighth entry of the table to the ninetieth.

A tenth tune that never shipped

In April 2026 Martin Galway published the source of his Wizball music (MartinGalway/C64_music, wizball.asm, stamped 23 April 1987). Its list of tunes runs from B to K. B to J are the game's nine, in the same order and at the same tempos. K, "End Of Bonus Level", is not in the game. End of bonus (unused) in the player above plays it: 64 notes on voice 3 alone, 25.6 seconds at 50 Hz, the speed the source's list gives it.

Leave K out and the source assembles to the game's music data byte for byte: the note tables, the tune table and the tune data from $5525 to $6387 (all but the two short machine-code routines at $5AFF and $5F2E, which were not compared). The music ends one byte before the game's own code, which starts at $6389. K needs 84 bytes: a 7-byte record in the tune table and a 77-byte track. Its first command calls CfS0 ($59F7), a short track fragment that sets the voice's instrument and filter. The game-over tune and the first bonus-stage tune call it too, so it is still in the game.

Tune K is Martin Galway's, from his source published under the GPL 3.0; the player assembles it from that source for the layout above and keeps it at $6400, outside the game's memory map.

The band $B90C runs the sound once a frame in every display list, and three more bands ($B903, $B8FC, $B8F3) run the music again when its speed says two or four ticks a frame.

03 · The Wizball

A ball that changes speed only when it bounces

The joystick does not move the Wizball. Left and right change its spin, and the spin becomes rolling speed only at the moment the ball touches the ground. Thrust, the first icon, makes the spin drive the speed on every frame.

Hold a button, or the arrow keys once the picture has been clicked. A port of bounce_wizball ($7F62), read_spin_control ($80F8) and spin_to_roll_speed ($818E), drawn with the game's 16 rotation sprites. The port leaves out the walls, so with thrust the ball here flies on where the game's would hit one.

Each frame the stick adds or takes 6 from the spin ($B21C), up to 48 either way, and the spin turns the ball through its 16 rotation frames. When the ball lands, $818E turns the spin into one of 13 speeds: below 4 the ball stops rolling, and each further 8 of spin moves it up one step.

Gravity adds 1/16 of a pixel a frame to the falling speed ($B27C), and the bounce at line 200 sends the ball up at the speed it came down at, so it bounces for ever at the same height: once every 128 frames, rising 126 lines. With anti-grav, the second option of the first icon, $8BEA replaces all this: the stick moves the ball up and down directly and it stops bouncing. Only with both thrust and anti-grav does a spin die away when the stick is let go.

04 · Controls

Nine keys in play, and a joystick chosen by its fire button

The game scans the keyboard itself, twice over: all 64 keys on the title and menu screens, and only nine during play.

The keyboard matrix: rows are the lines the game drives low through $DC00, columns the lines it reads back through $DC01. The small number is the code the scan gives a key. In play only rows 7-5 and columns 7-5 are read.

The play scan's nine keys are RUN/STOP (pause), Q (quit, while paused), C=, /, up-arrow and = (firing volume), comma, @ and colon. They sit in columns 7 to 5 of the matrix, the three lines a joystick in port 1 cannot pull low, so the port-1 stick can never be read as a key.

Neither port belongs to a player. On the "get ready!" screen before every life, $6965 notes which port the fire button was pressed on, and that stick drives the Wiz until the life ends ($B240); the other stick drives the cat. In a one-player game with the catelite, holding fire for ten frames hands the stick to the cat while the Wiz fires by itself.

05 · Landscapes

Eight landscapes in one map

All eight levels are one map of 16 rows by 96 tiles at $0532. Four rows make a landscape's height, and each band of four rows holds two landscapes side by side.

Each tile is 5 × 5 characters from the table at $2642, and each level brings its own 95 glyphs, copied to $FD00 by $77C6 from the block the table $B31C names. Drawn from the game's bytes; the sky's stars are plotted by the game while it runs and are left out here. Checked against the game: for two stopped frames of level 1, every one of the 445 scenery characters on screen is the character this drawing puts there.

The top strip is the whole map, one square a tile, with each level's landscape outlined. Columns 0-44 of a band are one landscape and columns 45-89 another; each opens and closes with the same two tiles. Columns 92-95 hold halves of two pictures, the Wiz-lab and the one shown after the last level: the drawing code ($75DF) jumps four rows down and four columns back after four tiles, so two half-pictures in different bands make one screen.

The view scrolls across one landscape at up to 2 pixels a frame. The game keeps three copies of the landscape screen at $E000, $E400 and $E800: the one on show and two made ready one column to the left and right, a quarter of each rebuilt every frame ($77F7). A coarse step of the scroll is a switch of screen, not a copy.

06 · Colour

Three cauldrons, and a fourth that keeps score

A level is finished when three colours have been made. Each colour has a recipe of red, green and blue units, and the fourth cauldron at the bottom right shows how much of the recipe the three cauldrons hold.

A port of the mix at $9E2C: for each of red, green and blue, the smaller of the cauldron and the recipe ($B2C0, three bytes for each of the C64's 16 colours), added up into $B12E.

The colour sphere's droplets come in the level's own colour: red on levels 1, 4 and 7, green on 2, 5 and 8, blue on 3 and 6 ($B18B). Only the cat can catch them. More units than the recipe needs are wasted, so filling red to 20 on a purple level gives half the mix.

The game does not compare the mix with 20. $9E81 draws the fourth cauldron's sprite a row a frame, and $9E26 copies one byte of its top row into $B874. When that row is drawn full the byte is $AA, and the frame loop leaves for "colour completed". With the red cauldron at 20 on level 1, that takes 22 frames.

Light blue's recipe is the same as purple's, 10 red and 10 blue ($B2C0 + 3 × 14).

Colour completed: the text over the bonus stage's first wave

Level 1's first colour done: "colour completed" over the bonus stage's first formation, the red cauldron full.

07 · The aliens

Eighteen kinds of alien, all worth 50

Aliens come from two tables of templates: 18 for the landscapes at $3ECF and 20 for the bonus stage at $39DC. Six at most are on screen, one in each of six 42-byte slots at $0200.

Each template's movement, shots and points, read from the listing; the points are byte 22 of the template times ten. These are the templates as loaded: for every list it builds, the game rewrites the landscape ones in place, setting each type's shot interval from the level's entry in $A12A, the colour spheres' shots by level ($A027), and sometimes turning a faller into a riser ($A070). Every kind, moved and animated by the game's own code, is on Graphics.

$9DA1 copies 23 bytes of a template into a slot and then applies its random fields, each a mask, an offset and the byte to change, so two aliens of one kind start in different places. A landscape's aliens come from a list of (column, type) pairs made for it when it opens ($9F9B): groups of 4, 6 or 12 of one type, spawned as the view uncovers their column. Only the highest level open and the two below it get lists. Clearing a list pays 1,000 points and makes a new one.

Every landscape alien is worth 50 points, where the manual says 10 to 500. The ninth alien killed since the last pearl leaves a pearl, and every molecule does ($A9AA = 9; colour spheres do not count). The reviews say eighth.

Kill nothing for long enough and the police come: after $A1B9[level] seconds without a kill a police ship flies in, with a warning tune a second earlier. On level 1, the tune starts at frame 2,200 and the ship at 2,250.

08 · Difficulty

What changes from level to level

Four tables set a level's difficulty. Level access is a fifth rule: a level opens only when every level three below it and lower is done.

From $A12A (frames between an alien's shots), $A1B9 (seconds without a kill before the police), $A027 (whether colour spheres shoot) and $B1D1 (the three colours, in the order they replace the greys).

The highest level open is $B1CE = 2 + the number of levels done, counted from level 1 with no gap ($A9C6). The manual says level five opens when level two is done; in the code it also needs level one. Tubes lead up only as far as $B1CE. After all eight levels the game starts again from level 1 with every alien firing every 10 frames.