Freescape Analysis

Document last updated on 2024-10-22

Introduction

Acknowledgment: The data on this page owes a lot to the research done by John Elliott and expands on that with results from my own research efforts and focusses more on the PC version than the 8-bit version John has focussed on.

Driller (a.k.a. Space Station Oblivion in the US) was the first of Incentive Software's games using the Freescape system. The data format for the various Freescape games is likely similar for each one and the data format for the 3D Construction Kit (a.k.a. Virtual Reality Studio in the US) 1 and 2 is an evolution of the Freescape format.

Executables

On the PC version of Driller, the main executable, DRILLER.EXE loads customised executables for each graphics mode. DRILLC.EXE for CGA 4 colour mode, DRILLE.EXE for EGA 16 colour mode, DRILLH.EXE for Hercules Monochrome and DRILLT.EXE for Tandy 16 colour mode. Although they are valid DOS MZ executables, they cannot be run directly and are loaded as needed by the main DRILLER.EXE program. Directly following the MZ header block (calculated by taking the number of paragraphs in the header, which is 16-bit word at offset 0x0008, and then multiplying it by the number of bytes in a paragraph, which is 16 - for most MZ executables, including all the Driller ones, this ends up being 512 bytes or offset 0x0200) there is a 16-bit word that specifies the offset from the start of the EXE data to the main game database. In the EGA version, this is 0x9940, meaning the game database starts at file offset 0x9B40. In the CGA version, these are 0x79B0 and 0x7BB0 respectively. When absolute file offsets are mentioned in this document, they always refer to the EGA version.

3D coordinates

The coordinate system of each area covers a half cube with a square base of 127x127 grid units, allowing all coordinates to exist in a 7-bit value, avoiding ambiguity between signed or unsigned coordinates in 8-bit values. The height of the room is 63 grid units. As movement by grid units would be far too coarse, each grid unit is subdivided in 64 subunits, resulting in player coordinates during gameplay ranging from 0..8128 horizontally and from 0..4032 vertically. These finer coordinates are also displayed for the player on the instrument panel. The internal coordinate system uses the X axis running in the eastern direction, the Y axis to run in the up direction and the Z axis running in the northern direction. Thus internally the coordinates on the ground plane are the X, Z coordinates and the Y coordinate is the elevation, the ground plane coordinates are displayed as X,Y to the player and the elevation is labelled with an ↑ arrow.

Performance

The Freescape engine in Driller is capped at a frame rate of 10fps. While it may run slower, it will never run faster. For performance reasons, the game does not run the global and room scripts every 100ms game tick, but only:

1. On a change in the 3D perspective (which happens only when the camera position or direction changes - not upon shooting, nor when an object is shown or hidden, nor when the REDRAW opcode is issued or even when switching to/from the info screen)
2. On the tick where the minute counter on the clock changes (i.e. whenever the clock changes to read HH:MM:59).

For player movement, collision detection does not check the actual geometry, Freescape uses only an object's bounding box. When shooting the lasers, however, a pixel accurate check is made against the actual polygons drawn. The difference is noticeable only for pyramids, rectangles and polygons (especially when their data is invalid and they are non-planar).

Bitmapped images

Driller contains two bitmap images. One for the title screen, and another for the background of the cockpit surrounding the 3D view (which is also used as the menu screen). You'd be forgiven for never having seen the title screen, as it was displayed only during loading and unless you were running on an extremely slow system with a similarly slow storage device (e.g. running on an IBM XT from floppy disk) it would flash by in an instant, if it was even visible at all.

The title image is stored in a separate file, SCN1E.DAT for EGA, SCN1C.DAT for 4-colour CGA, and SCN1H.DAT for Hercules Monochrome. The border image is embedded in the overlay executable at offset 0x0210. These bitmaps are 320x200 pixels (CGA and EGA) or 720x348 (Hercules Monochrome) and stored using a form of RLE and the image data (regardless of whether it is) is always preceded by the size of the RLE data in big-endian format.

For Space Station Oblivion, the US version of Driller, the title image is stored in EGATITLE.RL for EGA and CGATITLE.RL for both CGA and Hercules. These are encoded with a similar but different compression method.

Compression scheme (main)

The data is compressed per line from top to bottom. Each line is split up into bitplanes, according to the bit depth of the display. Hercules Monochrome has a single bitplane, CGA 4-colour has 2 bitplanes, and EGA 16-colour has 4 bitplanes. Within each bitplane line, the data is compressed as pairs of bytes. The first byte is a command code, where the upper bit 0x80 specifies a mode, and the lower 7 bits are used to set a repeat count. The second byte in each pair is always raw data for 8 adjacent pixels, with the leftmost pixel stored in the upper bit(s) of the data byte.

Compression scheme (alternate)

The title screens for Space Station Oblivion are compressed according to a highly similar scheme. Again, the data is compressed from top to bottom, but there is no splitting into bitplanes. The pixels are just packed from left to right in the byte data, with the leftmost pixel stored in the upper bits of a byte. Unlike the main compression scheme, which operates on a byte of pixel data (2, 4 or 8 pixels) at a time, the alternate compression scheme operates on 16-bit words of pixel data (4 or 8 pixels) at a time. Each line's data starts with a start-of-line marker of 0x02 and a value of 0x00 indicates there are no more lines. Both the values 0x02 and 0x00 are also found in the actual pixel data. Since the number of pixels in a 16-bit word is 4 or 8, both of which evenly divide 320, the encoding scheme allows 320 pixel wide images to always be stored without over- or underrun.

Main database format

Note: 16-bit values are in little endian, as is commonly used on x86 and compatible processors. This is the default for DOS and Windows.

Palette

The table below specifies the 16-colour CGA text mode palette, which was also the default palette in the EGA standard and the Tandy/PCjr's graphics cards. The data from the palette entries in the EGA and Tandy versions of the Freescape files allow the use of any 15 of the colours in this palette. The method in which it does so is slightly different for the EGA and Tandy versions. For the CGA display mode, further restrictions apply.

As the Freescape geometry data assigns materials from 1 through 15 and uses 0 to indicate that a face is invisible, it would be impossible for Driller to have black as anything other than the background colour unless another palette entry is mapped to black. This means that effectively only 15 of the total 16 colours in the CGA palette can be used.

EGA palette data

Each of the four bytes in a palette entry is either 00 or FF, no other values are used. Byte 0 is red, byte 1 is green, byte 2 is blue, byte 3 toggles high intensity. One could calculate the index with simple bitwise operations:

Since black is a useful colour, but material index 0 is already used to mark a face as invisible, the EGA version maps material index 1 to black. It also maps white to index 4, rather than the expected 15. Since there are only 15 indices available, one of the 16 colours in the CGA palette is unused. The colour left out is yellow (colour 14).

Tandy palette data

All four bytes in a palette entry are identical and index the palette directly:

CGA palette data

CGA can display only 4 colours simultaneously in 320x200 graphics mode, selected from 2 different official 4-colour palettes (and one unofficial one that is not used by Freescape games). All the CGA palettes are available in normal and high-intensity modes. Driller and Darkside use only the normal variations of the palette, but Castle Master and Total Eclipse prefer the high-intensity modes. The resulting 4 different palette options are seen below:

Which of the two palettes is used depends solely on the lower bit of the room ID. If the room ID is odd, palette 0 is used. If the room ID is even, palette 1 is used.

As there are 15 possible material values, but only 4 possible colours in CGA graphics mode, Freescape uses dithering to distinguish the 15 different materials. the palette entries instead define dither patterns. Each byte of a palette entry defines 4 adjacent 2-bit pixel values, making for a 4x4 pixel pattern. The pixels are stored left-to-right in a byte with the leftmost pixel in the most significant two bits, and the rows are stored bottom-to-top. Driller at least only uses either solid colours or dither patterns of 2 colours, even though the 4x4 blocks could technically use all 4 colours in it. Most of those are standard checkerboards, but one of them is a bit more elaborate. For material index 12 (0x0C) it uses the pattern definition 30 0C 3C C3. In the bottom-to-top, left-to-right ordering, that produces the following pattern on screen:

In areas that use palette 1, the brown colour is replaced by light grey.

Room data

The structure of a room definition starts with a small header immediately followed by the object data. The structure of the header is as follows:

As an example, the starting location in Driller is called Amethyst and its room header is located at file offset 0x9Cb4, with the objects starting at 0x9CCD with the cube that triggers the doorway to Obsidian living at 0x9D17.

Note: the indices in the room header at offsets 06 and 07 are indexed into the default CGA/EGA palette, not the altered palette defined in the game database header.

Object data

Every object has a header of at least 9 bytes, the first of which determines the type of object. All objects object types other than the entrance will have more data in an extended header which is longer than the 9-byte basic header. If the object record length in the header is larger than this (extended) header size, the object is followed by some bytecode. This bytecode is executed when the player touches or shoots the object. The basic header format is as follows:

Materials

All visible object types include in their extended header the material specifiers for each face of a 3D object or both sides of a flat object. These are stored as nibbles in a byte, though the order of the faces is apparently inconsistent. When a material is 0, the corresponding face is invisible and not rendered (in case of a sensor, it also will not fire at the player). Freescape uses this to improve performance by disabling faces which cannot possibly be seen, such as the bottom face of a cube that sits on a floor plane or the backside of a wall that bounds the current room.

The LONIBBLE() and HINIBBLE() notations used below might be implemented using the following macros in C:

Object type 0 - Entrance

An entrance is the odd one out of the object types. An entrance ID can (and in Driller, does) conflict with an other object ID without issue. An entrance has no visual representation itself and is therefore always marked invisible. This results in the type selector always being C0. Also, instead of bytes 4..6 defining an axis-aligned bounding box, they are interpreted as the initial orientation of the player when entering through this entrance. The values then represent rotations around the X, Y and Z axes respectively in 5-degree increments.

Because it is impossible to collide with or shoot an entrance, it does not make sense for there to be any bytecode routines attached to the object.

Object type 1 - Cube

Cubes are the most basic primitives in the object types. The corner coordinates and bounding box dimensions fully define the geometry. In fact, that bounding box is the geometry.

The size of a cube's extended header is 12 bytes. If the header indicates a larger size, the remaining data is the bytecode script that is executed on collision with or shooting the cube.

Object type 2 - Sensor

Sensors are the primary hazards encountered in Driller as they will continuously shoot at the player at regular intervals as long as the player is within range and they have direct line of sight to the player. The distance is calculated not as a Euclidian distance (i.e. with the Pythagorean theorem), but as a Manhattan distance, simply adding the absolute value of the differences in the x, y and z coordinates together, leading to the target volume being a square-based pyramid with its center point at the sensor coordinates and the tip pointing directly along each axis that the sensor can sense.

The size of a sensor's extended header is 14 bytes. If the header indicates a larger size, the remaining data is the bytecode script that is executed on shooting the sensor. Yes, it is possible, if exceedingly difficult, to shoot that single pixel.

Object type 3 - Rectangle

A rectangle's bounding box should be flat, i.e. exactly one of its dimensions should be 0. When the X dimension is zero, the plane of the rectangle is perpendicular to the X axis, its front face material being applied to the eastern (positive X) side of the rectangle and the back face material being applied to the western (negative X) side of the rectangle. Analogously, for a rectangle perpendicular to the Y axis, the front face material is applied to the upper (positive Y) side, and the back face material is applied to the lower (negative Y) side. And for a rectangle perpendicular to the Z axis, the front face material is applied to the northern (positive Z) side, and the back face material is applied to the southern (negative Z) side of the rectangle.

Note: If the bounding box has all non-zero dimensions and is thus a rectangular cuboid, the rectangle is rendered as a slope at an angle with the plane of the polygon being parallel to the X axis (its lower edge extends from the base corner along the positive X direction). In that case, when the player is at a Z coordinate greater than (i.e. north of) the base corner, it is rendered in the front face material, otherwise it is rendered in the back face material. This implies that the engine does its material selection as though it were a rectangle perpendicular to the Z axis.

The size of a rectangle's extended header is 10 bytes. If the header indicates a larger size, the remaining data is the bytecode script that is executed on collision with or shooting the rectangle.

Object types 4..9 - Pyramid

Object types 10..14 - Polygons

Script data

Although the main gameplay in the Freescape games appears to be hardcoded into the engine, each object can also have an associated bytecode script, which is executed when the player either touches or shoots an object. As an object can only have a single script, it actually uses the same script for both, with the bytecode itself having a flag per instruction to distinguish between either case. Rooms can also have associated scripts, which run every script tick. And finally there can be global bytecode scripts, too. These are also run every script tick, regardless of which room the player is in. Global scripts and room scripts are specified in a table which can theoretically have up to 255 entries.

There is no "end of script" marker. In the case of object scripts, the length of the bytecode data is determined by taking the total length of the object record and subtracting the size of the object header. For global and room scripts, each bytecode table starts with a one-byte value specifying the number of routines in the bytecode table. This count is followed immediately be the routines themselves. Each routine in turn starts with a one-byte value specifying the length of the routine in bytes, followed by that exact number of bytes for the actual bytecode data.

The scripts are extremely limited in what they can do, with little or no flow control, math, nor access to player or object coordinates or indeed anything but the most basic checks. The few conditions that can be checked will either result in the script continuing or stopping execution. They do, however, make it possible to toggle other objects' visibility or destroy them, even in rooms other than the current ones. Another major use for the bytecode scripts is having objects act as doorways into other rooms. Some of the available instructions seem to be game-specific at least for Driller, though I've not evaluated those for the other games. Despite the severe limitations, the level of interactivity that could be achieved is pretty impressive.

Game state

There are 256 variables and 256 bit flags available to the bytecode interpreter. This does not include the player score, shield or energy levels (the probe and the jet have separate energy and shield levels), nor any positional data, not even the player position. The various opcodes that reference these flags or variables do so by index, with the index itself being an 8-bit byte value. A flag can be either 0 (false) or 1 (true). A variable can have any value from 0x00 to 0xFF. Whether the values are treated as signed or unsigned is irrelevant, as the only operations available on variables are incrementing or decrementing, setting to a specific value and checking against a constant value for equality. These operations perform identically regardless of whether the values are signed or unsigned.

Very few of the variables appear to actually be used by the bytecode. Certain variables and flags will appear to have a special meaning and seem to be set by the main game logic to communicate certain events to the bytecode scripts. I've been able to discern for Driller:

Opcodes

For object scripts, the upper bit 0x80 is set when the opcode is to be interpreted when an object is shot, rather than touched. When the bit is clear, the opcode is to be interpreted only when the object is touched, rather than shot. This allows for two separate behaviours for a single object, despite it having just a single associated bytecode script.

Each parameter is a single byte. These usually represent IDs or indices and should be interpreted as 8-bit unsigned values unless otherwise noted.

Demo data

Driller runs a gameplay demo when the game is left on the title screen after a game session (but not if this is done before starting at least one game). The gameplay demo is a simple list of input commands that are carried out sequentially. A command may be executed once, taking one game tick (1/10th of a second). This is useful for things like teleporting in a drilling rig, making a U-turn or firing the lasers. Alternatively it may be repeated multiple times. For things like rotation or movement, the command would then be repeated for the specified number of game ticks. For things like moving the targeting cursor, the repeat count simply specifies by how many pixels to move the cursor, taking 0 time.

The demo data is just a stream of bytes. The stream ends when a NUL byte is encountered. If a byte has the high bit clear, it is a command to be executed. If a byte has the high bit set, the lower seven bits determine the repeat count. If the lower seven bits are all 0, this is actually interpreted as being 255. All other values should be increased by 1. A command byte will always follow the repeat counter immediately.

Not all commands seem to have been defined or applicable. The ones I've been able to determine are: