BoulderDash I raw cave data and info

In this document:

Cave size info
Object codes
Format of the raw cave data
Raw cave data

Cave size info

Cave size
- Logical size: 40 x 22
- Playing area: 38 x 20
- Visible area: 19.5 x 11.5 (I think)
Intermission size
- Logical size: 22 x 12
- Playing area: 20 x 10
- Visible area: the whole thing

The cave size is 40 (horizontally) x 22 (vertically) including the bounding steel wall; that is, a playing area of 38 x 20. This appears to be based on the C64's actual screen size: the C64 has 25 lines of 40 columns. My guess is that caves are only 22 lines high rather than 25 lines high because when playing the game, one line is given over to the status bar at the top of the screen, and one line is lost because of the way that the border of the screen is made larger in order to facilitate smooth scrolling by the C64's VIC chip. Anyway, when the game is in progress, the screen is magnified by 2 in each direction: one object occupies a 2 x 2 space on the C64's screen. This means that at any time, the player can see a (I think) 19.5 x 11 portion of the cave (19.5 objects horizontally takes 39 character spaces, one character space is lost to horiztontal scrolling; 11 objects vertically takes 22 character spaces, plus 1 character space for the status bar, plus one lost to vertical scrolling). During an intermission, the border is shrunk back to its normal size, permitting viewing of the entire cave.

Object codes

BoulderDash uses a 6-bit code to represent which object is at each cave position as the game runs. Some of the available 64 codes aren't used in BoulderDash I, however later versions added some more objects. Here are the codes used in BoulderDash I.

$00 Space
$01 Dirt
$02 Brick wall
$03 Magic wall
$04 Pre outbox (ie before it starts flashing)
$05 Flashing outbox
$06 *
$07 Steel wall
$08 Firefly position 1
$09 Firefly position 2
$0A Firefly position 3
$0B Firefly position 4
$0C Firefly position 1, scanned this frame
$0D Firefly position 2, scanned this frame
$0E Firefly position 3, scanned this frame
$0F Firefly position 4, scanned this frame
$10 Boulder, stationary
$11 Boulder, stationary, scanned this frame
$12 Boulder, falling
$13 Boulder, falling, scanned this frame
$14 Diamond, stationary
$15 Diamond, stationary, scanned this frame
$16 Diamond, falling
$17 Diamond, falling, scanned this frame
$18
$19
$1A
$1B Explode to Space stage 0
$1C Explode to Space stage 1
$1D Explode to Space stage 2
$1E Explode to Space stage 3
$1F Explode to Space stage 4
$20 Explode to Diamond stage 0
$21 Explode to Diamond stage 1
$22 Explode to Diamond stage 2
$23 Explode to Diamond stage 3
$24 Explode to Diamond stage 4
$25 Pre Rockford stage 1 (ie when inbox morphs into Rockford)
$26 Pre Rockford stage 2
$27 Pre Rockford stage 3
$28 Pre Rockford stage 4
$29
$2A
$2B
$2C
$2D
$2E
$2F
$30 Butterfly position 1
$31 Butterfly position 2
$32 Butterfly position 3
$33 Butterfly position 4
$34 Butterfly position 1, scanned this frame
$35 Butterfly position 2, scanned this frame
$36 Butterfly position 3, scanned this frame
$37 Butterfly position 4, scanned this frame
$38 Rockford
$39 Rockford, scanned this frame
$3A Amoeba
$3B Amoeba, scanned this frame
$3C
$3D
$3E *
$3F *

Notes on the object types

The pre-outbox (object $04) looks and acts exactly like a steel wall (object $07) until Rockford has collected enough diamonds, at which point it morphs into a flashing outbox (object $05).
The fireflies and butterflies have four positions (can face in four directions); see the section on fireflies and butterflies for more info.
The "scanned this frame" bit is to prevent a single object being scanned more than once per frame. For example, as a scan of the cave takes place, a boulder might be found. The boulder might fall down one space. When the scan continues, it will reach that same boulder again in its new position, so the boulder has to be marked as already scanned, to prevent it being moved more than one once per frame.
Boulders and Diamonds have two states: stationary and falling. A falling boulder can kill Rockford whereas a stationary boulder can't.
When something explodes, it can explode either into space (eg a firefly, Rockford) or into diamonds (butterfly). See the section on Explosions for an explanation for why the "zeroth" stage exists.
There are four pre-Rockford stages: when the inbox turns into Rockford, it takes four frames for Rockford to "be born".
For some reason, I have character code $06 marked for slime, $3E for expanding wall, and $3F for expanding wall "scanned this frame". I can't remember if these are the actual codes used in later versions of BoulderDash.

Format of the raw cave data

Jeff Bevis and Peter Broadribb have written a C program which will decode the C64's BoulderDash cave data into human readable instructions and ASCII diagrams. Things too look at are:

decodecaves.c - the program that does the conversion
cavedata.h - an include file that contains the raw cave data
the raw cave data web page (further down this page)
the decoded cave data web pages

Offset  Description 
------  ----------- 
$00     Cave number 
$01     Magic wall milling time, also max amoeba time at 3% growth. 
$02     Initial diamond value 
$03     Extra diamond value 
$04     Initial randomiser seed value for difficulty level 1 
$05     Initial randomiser seed value for difficulty level 2 
$06     Initial randomiser seed value for difficulty level 3 
$07     Initial randomiser seed value for difficulty level 4 
$08     Initial randomiser seed value for difficulty level 5 
$09     Diamonds needed on difficulty level 1 
$0A     Diamonds needed on difficulty level 2 
$0B     Diamonds needed on difficulty level 3 
$0C     Diamonds needed on difficulty level 4 
$0D     Diamonds needed on difficulty level 5 
$0E     Cave time for difficulty level 1 
$0F     Cave time for difficulty level 2 
$10     Cave time for difficulty level 3 
$11     Cave time for difficulty level 4 
$12     Cave time for difficulty level 5 
$13     Background colour 1 
$14     Background colour 2 
$15     Foreground colour 
$16     unused 
$17     unused 
$18     Random object number 1 
$19     Random object number 2 
$1A     Random object number 3 
$1B     Random object number 4 
$1C     Probability of object 1 
$1D     Probability of object 2 
$1E     Probability of object 3 
$1F     Probability of object 4 
$20 onwards: cave data, deliminated with $FF.

The cave data (beginning at offset $20) is broken into variable sized records where the first byte contains the object to store (low 6 bits only) and the kind of structure to create (upper 2 bits). Depending on the structure to create, there are 2, 4 or 5 bytes of parameters that follow.

The object codes in the low six bits are discussed elsewhere. Since the cave data can specify any of the 64 object types, this means, for example, that flies can start facing any direction.

The four structure codes are:

00 = store a single object
- param byte 1: column
- param byte 2: row
01 = draw a line of that object
- param byte 1: begin column
- param byte 2: begin row
- param byte 3: length
- param byte 4: direction code (0=up, 1=up/right, 2=right, 3=down/right, 4=down, 5=down/left, 6=left, 7=up/left)
10 = draw a rectangle of that object, filled with a second object
- param byte 1: top left column
- param byte 2: top left row
- param byte 3: length
- param byte 4: height
- param byte 5: object to fill with
11 = draw a rectangle of that object, don't modify the insides.
- param byte 1: top left column
- param byte 2: top left row
- param byte 3: length
- param byte 4: height

Decoding "randomly placed" objects

All caves have the opportunity to place up to four objects in "random" positions. They aren't really random, in the sense that the randomiser is set to a given seed value, and probabilities are checked against a given probability code; this way, objects will be "randomly" placed in the same positions each time you try the cave. Method: For each cave position (20 lines x 40 columns), pick a "random" number (0-255). If the random number is less than any of the four probability codes given at offsets $1C to $1F in the cave data, then put the object code given at the corresponding offset from $18 to $1B at the current position. (If the random number is less than more than one of the given probabilities, preference is given to the later object codes - in order of offsets $1B, $1A, $19, $18). Note that after this routine has finished, the bounding steel wall is placed over the extremeties of the cave (effectively DrawRect(0,2,40,22)).

Raw Cave Data

Cave A B C D Intermission 1
Cave E F G H Intermission 2
Cave I J K L Intermission 3
Cave M N O P Intermission 4

BoulderDash I raw cave data and info

Cave size info

Object codes

Notes on the object types

Format of the raw cave data

Decoding "randomly placed" objects

Raw Cave Data

Cave 1 (Cave A)

Cave 2 (Cave B)

Cave 3 (Cave C)

Cave 4 (Cave D)

Cave 5 (Cave E)

Cave 6 (Cave F)

Cave 7 (Cave G)

Cave 8 (Cave H)

Cave 9 (Cave I)

Cave 10 (Cave J)

Cave 11 (Cave K)

Cave 12 (Cave L)

Cave 13 (Cave M)

Cave 14 (Cave N)

Cave 15 (Cave O)

Cave 16 (Cave P)

Cave 17 (Intermission 1)

Cave 18 (Intermission 2)

Cave 19 (Intermission 3)

Cave 20 (Intermission 4)