BoulderDash Common File Format

In this document:

1. Introduction
2. Overview of requirements
3. Binary vs Text format files
4. Cave format proposals
5. Creature/object specifications
6. Cave database
7. Timing considerations
8. Conclusion

1.0 Introduction

2.0 Overview of requirements

• 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:
  • 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
  If it's a text format, then:
  • 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.

3.0 Binary vs Text format files

• 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

3.3 Discussion

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.

4.0 Cave format proposals

• Peter Broadribb's proposal for a binary format
• Grant Walker's proposal for a text format

5.0 Creature/object specifications

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.

6.0 Cave database

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.

7.0 Timing considerations

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 snik-snaks.

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:

1. how many fast the cave should ideally be executed (in milliseconds per frame)
2. 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.

8.0 Conclusion