============================== LR2 Technical Overview ============================== by Anthony Kozar DigItAll Archaeologist http://www.anthonykozar.net/ Jan. 25, 2012 ============================== --------- Foreword --------- Lode Runner 2 was a computer game developed by Presage and distributed by GT Interactive and MacSoft in 1998. It was available for Mac (pre-Mac OS X) and Windows computers. I started looking into the LR2 level format in 1999 and at the time I exchanged some emails with Stephen Appleby who had figured out enough of the game's file formats to write his "LR2 World Builder" software. Unfortunately, at the time I did not ask Stephen for his source code and while his notes were useful to me, I still had to refigure out much of the formats on my own. I created an early version of Square Creator in 1999 (using Chipmunk BASIC) but it was not until 2003, I believe, that my first C++ version successfully generated a LR2 level. Maze Generator came along in 2004 only after I was able to correct some erroneous assumptions that I had previously made about the level format. In 2010, I started corresponding with Toastline, another LR2 enthusiast, and we have been able to reconstruct much of what Stephen Appleby probably knew about PRX files back in 1999. We have continued to expand upon that understanding so that today I feel we know quite a bit about the LR2 data files. In particular, Toastline decoded the XPK graphics format and I have dissected the PRX format enough that I feel we are very close to being able to build entire new worlds for LR2 including not just levels, but new graphics and sounds too. Recently, Toastline suggested that I should publish what I know online, and so I have assembled this collection of "LR2 technical documents". It includes contributions from Toastline about the graphics format and, indirectly, it includes some information that Stephen Appleby shared with me. It is our hope that the availability of this documentation will spur renewed interest in a great game and that other people will use and build upon the knowledge here to create new and exciting resources for LR2 fans. So, I hope that you will find all of these documents interesting and informative. If you make any new discoveries yourself about the LR2 file or resource formats, write any software for manipulating LR2 files, or create any new levels, please contact us and share your discoveries and creations. We would love to hear from you. The rest of this document provides an overview of the core ideas and issues that you will need to understand to read the rest of this technical documentation. Enjoy! -- Anthony ------------------------ Byte Order in LR2 files ------------------------ Windows/Intel machines and the type of Macintosh computers that LR2 ran on (PowerPC Macs) use different native orders for storing multi-byte values in memory. PowerPC-based computers store bytes in "big-endian order" which means that the 4-byte hexadecimal value $01020304 is stored in memory as byte 0 1 2 3 --------------------- | 01 | 02 | 03 | 04 | --------------------- Intel-based computers store bytes in "little-endian order" which reverses the bytes in memory: byte 0 1 2 3 --------------------- | 04 | 03 | 02 | 01 | --------------------- LR2 uses little-endian order for some of its file formats on both Macs and Windows (PRX files in general) but sometimes uses big-endian order on the Mac (eg. the Editor write LVL files in the native format of your computer). In the rest of my LR2 technical documents, I show the bytes in whichever order I found them in. Since I did all of my analysis on a Mac, sometimes the byte order will be big-endian and other times it will be little-endian. I usually indicate which order is being used. Conversion between the two byte orders is difficult because I do not have complete information about the purpose and size of every value in the LR2 files. Eg. Many, but certainly not all values, in the LVL files are 16-bits (2 bytes) wide. You will have to use your own brain sometimes to figure out how the information I am describing will or should be represented in files on your computer. As far as I know, both the Windows and the Mac versions of LR2 can read LVL files in either byte order. The Mac version does not seem to be able to read saved game files created on Windows though (and presumably vice versa). Note that in these docs, I tend to follow an old Apple ][ assembly language convention of prefixing hexadecimal numbers with the dollar sign: so $FF = 255 decimal. I don't use the dollar sign though when showing larger blocks of hex data such as 4C 56 53 00 50 46 00 00 C3 01 00 00 ------------------ PRX Resource files ------------------ Game resources of most types - user interface, graphics, audio, and game levels - are stored in a generic container file format called the "PRS Format Resource File" with extension .PRX. There are about 38 .PRX files in the /Resources/ directory that comes with the game and the purposes of most of them can be guessed from their name. Files whose names end in "L" are "world files" containing the game levels for one of LR2's single-player level sets ("worlds") or for one of the multi-player level sets. Files whose names end in "WA" contain world-specific audio resources and those ending in "WG" contain world-specific graphic resources (usually the images of individual "bricks"). Here are some of the resource files and their purposes: BGrounds.PRX Contains the background images for game levels. BuildWA.PRX Shared audio resources ("Builder world") BuildWG.PRX Shared graphics resources ("Builder world") CoopL.PRX Cooperative multiplayer levels CreditL.PRX Credits level plus the "hidden levels" and "Joke Credits" DeathL.PRX Competitive ("Deathmatch") multiplayer levels GearL.PRX Gear world levels GearWA.PRX Gear world audio GearWG.PRX Gear world graphics Gba.PRX Bungling (monk) audio resources Gbg.PRX Bungling (monk) graphics resources Gma.PRX Jake and Jane audio resources Gmg.PRX Jake and Jane graphics resources Goa.PRX Audio for common objects (incl. bombs, power-ups, etc. ) Gog.PRX Graphics for common objects ? (also includes common bricks) IntroL.PRX World Hub level Levels.PRX Describes contents of other level files TubeL.PRX Industry world levels (originally called "Tube world"?) TutoL.PRX Tutorial levels UI.PRX User interface resources (for game only?) The file Levels.PRX is unique and does not contain game levels, but instead is something of a table of contents for the other PRX files containing level sets. Levels.PRX references each of the other level files by filename and contains the names of all of the levels as they are displayed in the game. (These names do not appear anywhere else that I have found). Various types of resources are found in the PRX files. The PRX format identifies each resource by a 3-letter type code and a unique number. Examples of the type codes are LVS List of levels in another PRX file LVL a single game level XPK graphics resource XMV animation (movie) resource AIF sound resource (in AIFF format with header) SID "sound ID" ? (metadata about AIF resources ?) XUI User interface components ? Level files such as GearL.PRX typically alternate between LVL and XPK resources and I believe that the XPKs are the corresponding preview images shown for each level on the game's "Select Level" screen. The LVL resources in the PRX files contain data in the same format as a single-level file saved by the LR2 Editor (in little-endian format). Audio files such as GearWA.PRX typically alternate between SID and AIF resources. As indicated, the AIF resources are complete AIFF sound files including the AIFF format header that begins with the characters "FORM". Graphics files such as GearWG.PRX contain both XPK and XMV resources as well as several other types whose purposes are not yet understood. Extraction of individual resources from PRX files is relatively easy with a hex editor once you learn how to identify the beginnings and ends of the resources. Stephen Appleby created a program for extracting individual game levels that is distributed with his "LR2 World Builder" software. Toastline has also created two utilities for extracting audio and graphics resources. The Image Extractor program saves each XPK resource as a color BMP and a separate BMP for the alpha channel. These programs run exclusively on Windows. I recently started a collection of small programs called PRX Utilities, one of which can extract any or all resources from any number of PRX files. The PRX Utilities are distributed with C++ source code from my web site and should compile on any platform. (I've written and tested them on Mac OS X). See http://www.anthonykozar.net/loderunner/ More information about the PRX file format is provided in the other documents included with this one. See in particular 20_PRX_file_format.txt 21_Levels_PRX_contents.txt ------------ Level files ------------ Lode Runner 2 includes a game editor capable of designing and saving LR2 levels in a file format with extension .LVL. LVL files may only include a single level and the Editor does not allow the creation of new PRX "world files". But, Stephen Appleby has created a program called "LR2 World Builder" that will combine several LVL files into a PRX file and install it as a replacement world in the game (by rewriting Levels.PRX). I have written some programs called "LR2 Level Generators" that also write new LVL files with some simple level layouts. They are available from my website in both Mac and Windows versions and include C++ source code: http://www.anthonykozar.net/loderunner/ Very recently, I became aware of the work of Eko Widiatmoko who has written his own software for creating random, but interesting, layouts of basic bricks and writing them as LVL files. These level "prototypes" can then be finished by a human level designer. Examples of Eko's software-generated levels are available from the Files section of the Lode Runner Yahoo Group (see below). Eko can be contacted via the group. More information about the LVL file format is provided in several other documents included with this one. See in particular 10_LVL_file_format.txt 13_More_about_Monks.txt 14_More_about_Triggers.txt ----------------- Other game files ----------------- Other files created by LR2 include saved game files (extension .LRS on Windows), the "Config" file, and the "HiScores" file. I have explored the format of the saved game files a little in another of the included documents. See 31_Saved_game_format.txt ------ Links ------ The latest version of these LR2 technical docs is available from http://anthonykozar.net/loderunner/formats/ Other resources for technical information on Lode Runner 2 include: Toastline's XPK reference (a copy is included but the original is here) http://dl.dropbox.com/u/1467119/LR2Graphics.html The Cutting Room Floor http://tcrf.net/Lode_Runner_2 Jason's LR Archive http://entropymine.com/jason/lr/lr2/ Lode Runner Yahoo Group http://games.groups.yahoo.com/group/LodeRunner/