Skip to content

XPK Technical Documentation

Jump to bottom
Charlotte Koch edited this page Jul 16, 2022 · 8 revisions

Introduction

XPK is a raster graphics format. The format is not only used in Purple Moon games; Presage Software seemed to use it in other games from the same era. In fact, Anthony Kozar and Toastline have previously described the XPK format as it's used in Lode Runner 2. However, there's a key difference between how XPK is used in Lode Runner 2 versus Purple Moon's games ("C02" versus "B01") so I'll try to describe the entire format in this document, without requiring the reader to consult Toastline's research.

General Principles

A single XPK file may specify one or more individual graphics. For example, it may specify a single still image, or perhaps the individual frames of an animation. It's not currently well understood how the multiple-image format works, so this document currently describes the structure of a single image. With that in mind:

  • A single XPK graphic describes a raster of pixels.
  • Each pixel is either fully opaque with a color, or fully transparent. ("Boolean" transparency, no alpha blending to worry about.)
  • When decoding the image, one starts with a fully transparent canvas, and then fills in some, all, or none of the canvas with "paint" according to the instructions listed in the XPK file. I.e., there's no such thing as "transparent paint."
  • The dimensions of the canvas, and other such metadata, is accessible in a header which precedes the drawing instructions.
  • Color information is never stored directly in a XPK. Instead, colors are identified only by an index in a color lookup table (CLU). Therefore, one must "attach" a CLU to a XPK in order to properly decode the XPK.

Instructions

Luna Purpura has not consulted source code nor documentation of any kind from Presage Software. Therefore, the names of instructions are entirely Luna Purpura's invention.

In the following table, (NEWLINE) means: "Go to the beginning of the next line", that is: x := 0 and y := y+1

Prefix Name Description
0x0n (n != 1) XPKINST_REPEAT (see "The Repeat-Stack")
0x01 XPKINST_REPEAT_END (see "The Repeat-Stack")
0x1n XPKINST_BIGREPEAT (see "The Repeat-Stack")
0x2n XPKINST_XSKIP Skip n bytes in the x direction
0x3n XPKINST_BIGXSKIP Skip n+16 bytes in the x direction
0x4n XPKINST_RLE The following color will be painted n times
0x5n XPKINST_BIGRLE The following color will be painted n+16 times
0x6n XPKINST_DIRECT The following n bytes represent individual colors
0x7n XPKINST_BIGDIRECT The following n+16 bytes represent individual colors
0x8n (n != 1) XPKINST_LINEREPEAT (see "The Repeat-Stack")
0x81 XPKINST_LINEREPEAT_END (see "The Repeat-Stack")
0x9n XPKINST_BIGLINEREPEAT (see "The Repeat-Stack")
0xA0 XPKINST_SETXNL (NEWLINE), but the next 2-byte word is the new x coordinate
0xAn (n != 0) XPKINST_SETXNL (NEWLINE), but n is the new x coordinate
0xBn XPKINST_BIGSETXNL (NEWLINE), but n+16 is the new x coordinate
0xCn XPKINST_RLENL (NEWLINE), and the following color will be painted n times
0xDn XPKINST_BIGRLENL (NEWLINE), and the following color will be painted n+16 times
0xEn XPKINST_DIRECTNL (NEWLINE), and the following n bytes represent individual colors
0xFn XPKINST_BIGDIRECTNL (NEWLINE), and the following n+16 bytes represent individual colors

The Repeat-Stack

Some instructions are to be interpreted as if there is a simple sort of stack machine.

The instructions XPKINST_REPEAT and XPKINST_BIGREPEAT indicate the beginning of a range of instructions, and XPKINST_REPEAT_END marks the end of that range.

Similarly, the instructions XPKINST_LINEREPEAT and XPKINST_BIGLINEREPEAT indicate the beginning of a different sort of range of instructions -- and XPKINST_LINEREPEAT_END marks the end.

  • XPKINST_REPEAT (0x0n, n != 1) means: the instructions within the range will be repeated n times.

  • XPKINST_BIGREPEAT (0x1n) means: the instructions within the range will be repeated n+16 times.

  • XPKINST_LINEREPEAT (0x8n, n != 1) means: the instructions within the range will be repeated n times, but with a (NEWLINE) after each iteration.

  • XPKINST_BIGLINEREPEAT (0x9n) means: the instructions within the range will be repeated n+16 times, but with a (NEWLINE) after each iteration.

Clone this wiki locally