Space Plumber File Format Reference

Data pack file (splumber.pck)

The data pack file (splumber.pck) is a binary archive containing all the files used by the game. Archives in this format may be created using the xpck tool.

It has a six byte header signature containing the string <xpck> or <zpck>, identifying it as a Space Plumber data file, followed by any number of structures like this:

/* data pack file entry structure (in pseudo-C) */

struct _xpck_entry
{
	long nsize;	   /* name size of the file,
			      including the \0 */
	char name[nsize];  /* the name of the file with
			      ending \0 */
	long fsize;	   /* file size */
	char file[fsize];  /* the actual file */
};

The string name includes a relative path to a directory. These directories are graph/ for textures, graphics and palettes, sound/ for sounds and etc/ for the rest of components.

Note that this is not really a C structure, as name and file have variable sizes. The long values are 32 bit wide.

If the signature string is <zpck>, then each file has been compresed with gzip and is decompressed on-the-fly before using it (gzip must be accesible on the system).

Level definition file (etc/levels.def)

The level definition file (etc/levels.def) is a text file (created with a standard text editor) containing the description of each level in a line. Each line contains a number between 0 and 999999 (the access code for that level), a colon and a comma-separated list of parameters. The parameters are those described in the document Space Plumber Command Line Parameters (in spanish).

This is an example of a line describing a level. If this is the seventh line in the file, it describes level 7.

253657:ambient_light=7,num_pumps=2,num_consoles=1,area_num=3

The number 253657 is the access code for that level. A line with access code 999999 must appear at the end of the file marking the previous level as the last one. Note also that there isn't any spaces between the parameters and the commas.

Area definition files (etc/a?.def)

The area definition files (etc/a?.def) describes the overall look of an area, including graphics, palette, sounds and effects. These files are text files. The ? in the name of the file is the number of each area.

Basically, these files are a sequence of lines in the form command=value. Lines with a semicolon as the first character are assumed as comments.

Each area file has two distinct parts: the first defines general information about the area and the second describes one or more styles inside the area. The first part is assumed until a definition of a style (delimited by the keyword [style]) is found.

General information commands

`name=AREA NAME`	Defines the name of the area (must be in capitals).
`palette=palette_file`	Defines the file that contents the palette for the area.
`water_texture=texture_file`	Defines the texture used in rendering the water.
`snd_underwater=sound_file`	The background sound under the water.
`snd_water=sound_file`	The background sound over the water.
`snd_left_step=sound_file snd_right_step=sound_file snd_wleft_step=sound_file snd_wright_step=sound_file`	The sounds used in the left and right steps, outside and inside the water.
`snd_player_dead=sound_file`	The sound launched when the player dies.
`snd_pump=sound_file`	The sound launched when a pump is activated.
`snd_console=sound_file`	The sound launched when a console is deactivated.
`snd_water_go=sound_file`	The sound launched when all pumps are opened and the level of the water begins to decrease.
`over_water_sounds=sound_file under_water_sounds=sound_file`	These commands define sounds played randomly when the player is over or under the water, respectively. Many of these commands may appear in a file, but are silently restricted to 10 over and 10 under water sounds.

Style information commands

`[style]`	Marks the start of a style definition.
`wall=texture_file step=texture_file floor=texture_file ceiling=texture_file pump1off=texture_file pump1on=texture_file pump2off=texture_file pump2on=texture_file console1=texture_file console2=texture_file consoleoff=texture_file`	These commands defines the textures used in the walls, the steps, the floors, the ceilings, the 1 and 2 styles of pumps (on and off) and the console animation, respectively. They may appear only once per style.
`effect=effect_type`	Defines the begining of the definition of an effect. The effect type must be one of the words `static`, `lit`, `blink`, `blink_light`, `animation` or `sequence`. These commands must be followed by commands from `texture1` to `texture4`, defining the textures used in the effect. `static` and `lit` use only one texture, `blink` and `blink_light` use two and `animation` and `sequence` may use upto four textures.
`texture1=texture_file texture2=texture_file texture3=texture_file texture4=texture_file`	See description in `effect`.

Sound files (sound/*.wav)

Sound files are usual .wav mono files, sampled at any frequency.

Texture files (graph/*.pcx)

Texture files are usual 256 color .pcx graphic files with a 128x128 pixel resolution. The palette must be a Space Plumber normalized palette, and all the graphics in the same area must share the same palette. The palette defined inside these .pcx files is not used.

Other graphic files (graph/*.pcx)

The screens are standard 256 colors .pcx files, with a resolution of 320x200. There must exist a palette file with the same name and extension pal, because the palette defined inside these files is not used. The menu screen is like these, having palette entry 0 as the transparency color. The pump shaped cursor use the same transparency color, with a 32x32 resolution.

Palette files (graph/*.pal)

Palette files use the JASC format defined in Paint Shop Pro documentation. Briefly, they are text files defining the RGB of each color in a line. These colors must be ordered by luminance. The utility xpal must be used to transform a normal palette (previously reduced to 128 colors) to a luminance-ordered Space Plumber palette.