A Koala file is a Commodore 64 program file holding the three blocks of memory the C64’s video chip, the VIC-II, reads in multicolour bitmap mode, plus the background colour. It has no header beyond the load address and no compression.
Fields
| Offset | Size | Name | Description |
|---|---|---|---|
| 0 | 2 | load address | where the C64 loads the rest, low byte first; usually 00 60, address $6000 |
| 2 | 8,000 | bitmap | 1,000 cells of 8 bytes, two bits per pixel (below) |
| 8,002 | 1,000 | screen memory | one byte per cell: high four bits colour 1, low four bits colour 2 |
| 9,002 | 1,000 | colour memory | one byte per cell: low four bits colour 3 |
| 10,002 | 1 | background | low four bits: the colour shared by the whole picture |
The file is 10,003 bytes. Relative to the load address the blocks are at
$0000, $1F40, $2328 and $2710. A
reader should not insist on $6000: other programs that write the same
layout use other load addresses. The C64’s colour memory is only four bits wide, so
the high four bits of each colour memory byte mean nothing. The border colour is not
stored.
Cells and the bitmap
The screen is 40 × 25 cells. Each cell is 4 pixels wide and 8 high in multicolour mode, each pixel twice as wide as it is tall, making a 160 × 200 picture that fills a 320 × 200 screen. Cells are numbered left to right, then top to bottom, from 0 to 999.
The bitmap stores cell 0’s 8 bytes, top row first, then cell 1’s, and so on. Each byte is one row of 4 pixels: bits 7–6 are the leftmost pixel, then bits 5–4, 3–2 and 1–0. For the pixel at column x (0 to 159) and line y (0 to 199):
| What | File offset |
|---|---|
| bitmap byte | 2 + 320 × floor(y / 8) + 8 × floor(x / 4) + (y mod 8) |
| its two bits | bits 7 − 2(x mod 4) and 6 − 2(x mod 4) |
| cell number c | 40 × floor(y / 8) + floor(x / 4) |
| screen memory byte | 8,002 + c |
| colour memory byte | 9,002 + c |
Choosing the colour
The two bits of a pixel choose where its colour comes from. This is the C64’s multicolour bitmap mode, and every Koala reader decodes it this way:
| Bits | Colour comes from |
|---|---|
00 | the background byte, shared by the whole picture |
01 | the high four bits of the cell’s screen memory byte |
10 | the low four bits of the cell’s screen memory byte |
11 | the low four bits of the cell’s colour memory byte |
So each 4 × 8 cell can show up to four colours: the background and three of its own.
Colours
Every colour value is an index, 0 to 15, into the C64’s fixed palette. The exact shades differ between machines and emulators, so the file gives only the index.
| Value | Colour | Value | Colour |
|---|---|---|---|
| 0 | black | 8 | orange |
| 1 | white | 9 | brown |
| 2 | red | 10 | light red |
| 3 | cyan | 11 | dark grey |
| 4 | purple | 12 | grey |
| 5 | green | 13 | light green |
| 6 | blue | 14 | light blue |
| 7 | yellow | 15 | light grey |
Example
| Offset | Bytes | Field | Value |
|---|---|---|---|
| 0 | 00 60 | load address | $6000 |
| 2 | 1B | cell 0, row 0 | bits 00 01 10 11: one pixel of each source |
| 8,002 | 26 | cell 0 screen memory | colour 1 red (2), colour 2 blue (6) |
| 9,002 | 05 | cell 0 colour memory | colour 3 green (5) |
| 10,002 | 00 | background | black (0) |
The top row of the top-left cell shows black, red, blue and green, left to right.
Not covered
Compressed Koala files exist, using simple run-length schemes, but no public description of their layout was found, so they are not described here.