BoulderDash Common File Format
Last modified: 26 Mar 1996
In this document:
- Overview of requirements
- Binary vs Text format files
- Cave format proposals
- Creature/object specifications
- Cave database
- Timing considerations
There are heaps of different implementations of BoulderDash and BoulderDash-lookalikes available,
all using different file formats for their caves. If there were a common cave file format, then
it would be easier to share caves between different implementations. An implementation which
supports the BoulderDash Common File Format (BDCFF) might not automatically be able to play all
caves in that format, since there may be object types used in the cave which aren't implemented by
that specific BoulderDash implementation.
This document is an attempt at developing a common file format. This is a public document; only with
input from the public will this project develop into reality.
We need a common file format used to describe BoulderDash caves. Requirements are:
- It needs to be able to potentially support all the existing caves in all the existing various implementations of BoulderDash (and there are lots). In particular:
- variable sized caves
- a largenumber (>256) of different creature/object types (because of the sheer number of different creatures/objects that exist over all different implementations, now or in the future)
- different timing requirements?
- caves vs intermissions
- different cave grouping requirements (grouping caves and intermissions together to form a game)
- It needs to be extensible, so that when we later find that there's something we've missed out of the file format, we can add it in easily and existing programs won't break (they'll just ignore the bits they don't understand, like HTML browsers ignore tags and attributes they don't understand).
- It needs to be easily cross-platform readable. This means that if it's a binary format, then:
If it's a text format, then:
- word-align things (don't have a multi-byte structure begin at an odd byte offset)
- make very explicit whether multi-byte integers are big-endian or little-endian
- include a CRC in the header of the file to ensure data is not corrupt
- restrict text to characters in the range 32-126 decimal
- ignore tabs, carriage returns, linefeeds
- should preferably be <75 characters wide per line
- avoid any common constructs that might foul up email
- It should probably support some kind of free-form text "comment" field which could include things like the cave author's name and email address, the date of creation, and any other comments.
When deciding on the overall format of a BDCFF file, we have to choose:
- Binary format
- Text format
- Dual format? (ie support both)
3.1 Advantages of binary format
- smaller files
- email agents these days permit files to be attached (and automatically uuencoded or whatever) easily and automatically
- permits CRC file integrity checking
- prevents having to parse the text
- permits a large number (>256) object types
3.2 Advantages of text format
- can develop caves with a text editor (no special cave editor required)
- may be easier to get support as a standard
What I mean by dual format is essentially that we have two file formats, one text and one binary.
That way you get the best of both worlds, but the disadvantage that you have to support both. :)
Using a binary format means that you have to have a cave editor to create caves. That's ok in
the future, but until such an editor is written by someone, it would be much easier to develop
caves using a text editor if the BDCFF format was a text file.
On the other hand, I would expect (and intend) that the first BDCFF caves created would simply
be caves that were in some other format, run through an EmeraldMines-to-BDCFF (or whatever) cave
conversion program. That way you could use the Emerald Mines (or whatever) cave editor to create
the caves until a native BDCFF cave editor is released by someone.
The format of a BDCFF file has not yet been finalised. The following is a chronological list of people's suggestions for the BDCFF file format.
There are lots of different creatures and objects in use in different BoulderDash implementations.
Sometimes the variations are intentional, such as when someone invents a new object type (perhaps
some kind of bomb). Sometimes the variations are unplanned, such as when three different people
implements bombs, and their three bombs behave in three slightly different ways. Sometimes the
variations are unintentional, such as when someone attempts to implement a butterfly, but has the
butterfly turning left by preference rather than right, or not checking nearby squares for enemies
So what we need is a very explicit specification of each creature so that when someone wants to
implement a Supaplex-style bomb, it comes out as a Supaplex-style bomb rather than a Foo-style
bomb. This is what the BDCFF Object Specification database is.
So at some time in the future we have this great BoulderDash Common File Format, and BoulderDash
implementors will support this format. That could mean that you could take a BDCFF cave and stick
it into any BDCFF-compatible player, and it'll either say "sorry, that BDCFF cave contains
creatures/objects/specifications that are unknown to this player", or "hey man, let's go!".
The obvious thing would be to have a central public place where all BDCFF caves are stored - maybe
some ftp site somewhere. There might be individual caves, and there might be groups of caves stored
together to form a complete set or game.
I am assuming that all implementations of BoulderDash run on a
frame-by-frame basis. That is, everything happens in discrete time units, which I shall call
For example, in C64 BoulderDash I, Rockford can move one space every frame. Boulders fall
one space every frame. Fireflies move one space every frame. In other implementations, the rules may be
slightly different, but hopefully still frame-by-frame. For example, I notice that
Infotron (a Mac version of Supaplex) has its zonks (boulders) falling at one space every
two frames, and same for its snik-snaks (fireflies). Yet Murphy (Rockford) can move
one space every frame, which means that Murphy can move twice as fast as the zonks and
Given that everything works on a frame-by-frame basis, it's generally not too critical
exactly how many frames per second the cave runs at. Obviously, it's easier for the player
if the cave runs slowly (at a lower number of frames-per-second) than quickly (at a a higher frames per second). Some caves (in particular,
one of the caves that comes with the C64 Construction Kit) are specifically designed to work
super-fast - in the cave I'm thinking of, it's so fast that Rockford can easily move off the
visible portion of the screen (the scrolling on the C64 BoulderDash is at a constant speed,
independant of Rockford's speed).
One critical element of timing is how long you get to complete the cave. Most BoulderDash
implementations give you a specified number of "seconds" (whether or not a second is 60 ticks
long or not is another matter). Some caves are timed very critically; you are given (say) 48
seconds to complete the cave, and it was designed to be difficult but not impossible to
complete in 48 seconds. Now, run that cave on a high frames-per-second implementation, and
it'd suddenly be easy to do in 48 seconds (except requiring better dexterity). Run it on a
low frames-per-second implementation, and the cave would probably be literally impossible to
complete in 48 seconds.
So this means that each BDCFF cave has to have two aspects of timing information:
Now, when implementing a BoulderDash player, you have to be very careful about timing. If your
implementation runs a 7.5 frame-per-second cave at 6 frames per second (ie slower than it should),
then time is going to run out prematurely, possibly making the cave impossible to finish. Or
similarly if your implementation runs a cave too quickly; it runs the 7.5 frame-per-second cave
at 8 frames per second, this might make the cave easier than intended (if timing was important
in the original cave design).
- how many fast the cave should ideally be executed (in milliseconds per frame)
- how much time is available (in real-life seconds)
So this means that you have to be careful. You can't guarantee that your game is going
to be played on a fast computer; when your Amiga implementation is run on an old 8MHz machine,
maybe it simply won't be able to go any faster than 6 frames per second. Whether the user turns
on sounds and music and graphical effects or not could have an impact on playing speed.
So be aware of this. Perhaps rather than displaying the amount of time remaining in seconds,
you might want to calculate the total number of frames available (7.5 frames per second times
48 seconds gives 360 frames to finish the cave) and decrement that each frame; when it reaches
zero, the player is out of time. Maybe you might want to show time remaining in a filler bar
rather than a digital readout.
In other words, don't judge time remaining by the computer's clock unless you can
guarantee that the cave is running at close to the intended milliseconds per frame.
Please note also that the number of frames per second (or ms per frame) that a given implementation
runs at usually varies on a cave-by-cave basis, or even within one cave, based on the
objects present in a cave. (Fill a cave with dirt and it'll usually run at a higher speed than a
cave filled with boulders; on the C64 Construction Kit the difference in speed is quite noticable.
The reason for the difference being, of course, that you have to "scan" each boulder every frame
to see whether it can roll or fall, but dirt doesn't have to be "scanned" since it's inanimate.)
For example, C64 BoulderDash I runs caves at different speeds depending on the level of difficulty;
the C64 Construction Kit permits you to set cave speed on a cave-by-cave basis.
However, that's not a big problem. Just determine approximately how many frames you get on average
in a specified cave in the amount of seconds given, and convert that to milliseconds per frame.
It's early days yet. Watch This Space. However, a watched kettle never boils, so email me with your
comments and proposals to this document. This is a public project, and that means only with public
input will this project turn into reality.
Webmaster for this page is Peter Broadribb