RPG format (2024)

RPG file format (also known as data mismanagement 101)[edit]

The RPG file format is the format used by the OHRRPGCE to store games. This page is intended as a reference for people who want to write utilities to manipulate or convert RPG files, for those working with the source code, and for those who just wish to poke and prod their data. This file is also an interesting case study in bad data structuring, and should provide a wealth of cautionary examples of what not to do. It tracks progress from "not having a clue how to manage data" to "knowing how to manage data but being unable to do it right because of backwards compatibility", to "not caring one way or the other", and finally to "taking the time to re-do things right".

Lump Format[edit]

An RPG file is in the OHRRPGCE lumped file format, which is a concatenation of many files lumped together. These files are referred to as "lumps".

An RPG file starts with a null-terminated file (lump) name: the RPG file as a whole has no header, it just begins immediately with the first lump.

Lump names may be up to 50 characters long, from the set [a-zA-Z0-9._-~ ]. Lump names are case insensitive and the lump file format is non-case-preserving: current versions of Custom/relump will convert file names to upper case when lumping, and the lumps names are then converted to lowercase when unlumping. Each lump should have a unique name. (Very old implementations of the RPG format supported directory paths in the lump name, both relative and absolute. This would have made it possible for an RPG file to overwrite critical system files in other directories-- luckily, I found this flaw before anyone else did, so it was never exploited:)

Anyway. Null-terminated filename. 4 bytes of size information, then the data, repeat:

The following example Python code converts a 4-byte string into a size:

import struct# the on-disk size format can alternatively be thought of as two little-endian unsigned 16bit integershisize, losize = struct.unpack ('<2H', rawsizestring)size = losize | (hisize << 16)

The reverse (converting a size into a 4-byte string) is similarly simple:

import structlosize = size & 0xffffhisize = (size >> 16) & 0xffffrawsizestring = struct.pack ('<2H', hisize, losize)

Assumptions to make[edit]

Unless otherwise noted, numbers are stored in sane-right-thinking-normal-moral-christian-good-to-their-mothers byte ordering of

 0,1 A,B low byte, high byte

Unless otherwise noted, 16 and 32-bit numbers are signed, as the goodly creators of QuickBasic decided that nobody would ever really need an unsigned value for anything. (the same people, if I recall correctly who decided that 640k of RAM would be all anyone ever needed)

Assumptions not to make[edit]

Once again, even though lump names are converted to UPPERCASE by Custom and relump, don't assume they have to be.

Even though lumps may appear to come in a specific predefined order in the RPG file, don't assume they will always come in that order. The lumping code puts ARCHINYM.LMP and BROWSE.TXT first to improve browsing speed, but that's not written in stone.

Lump naming rules[edit]

Lump names vary depending on the file name of the RPG file. It was moronic of me to design in that way, but I didn't know any better at the time, and I have to maintain backwards compatibility with my past screwups.

eg. If the filename of the RPG file is WANDER.RPG it will contain many lumps named WANDER.???

In an attempt to fix this silliness without breaking backwards compatibility, I added a new all-important lump. ARCHINYM.LMP

ARCHINYM.LMP Is a text file, which contains the Internal name used by all of the flexible-named lumps in the file. Then it has a CR/LF pair, and a string that tells the version number of CUSTOM.EXE that the file was created with (or the version of RPGFIX that first added the ARCHINYM.LMP)

So. Read the first line of ARCHINYM.LMP to get the correct prefix of most of the other lumps.

If ARCHINYM.LMP does not exist, you know you are dealing with an obsolete file, and you can assume that the variable-named lumps will use the RPG filename as a prefix.

All new lumps added in the future are likely to have fixed arbitrary names.

Note: new versions now always use 'ohrrpgce' as the internal name, to cut this mess down to an absolute minimum. This is obviously can never be assumed. And since Etheldreme, when ARCHINYM.LMP is missing the engine will autodetect what it should be instead of assuming the filename, so that renamed .rpg files work too.

List of Lumps[edit]

WARNING: The documentation on any page in the "Unfinished Articles" category might be not just incomplete, but down-right WRONG. Any other page may still contain errors or be out-of-date... but we don't expect many errors!

Any lump marked Obsolete has been replaced with a newer lump file. The obsolete lump is read only if the newer lump is missing. When upgrading a game the engine generally keeps obsolete lumps if their filesize is negligible, to make it easier to use obsolete 3rd-party utilities. Those lumps can be safely deleted.

ARCHINYM.LMP Internal game nameATTACK.BIN More attack data, in addition to DT6BINSIZE.BIN Binary record lengths for newer binary lumpsBROWSE.TXT Long game title and descriptionDEFPAL#.BIN Default palettes, one for each of PT0 through PT8COMMANDS.BIN (inside HSP lump) Builtin script command namesDEFPASS.BIN Default passability for tilesetsFIXBITS.BIN Bitsets that indicate whether format fixes have been appliedSCRIPTS.BIN (inside HSP lump) New script names and dataSCRIPTS.TXT (inside HSP lump) Obsolete script namesLOOKUP1.BIN Script trigger lookup tableSFXDATA.BIN Sound effect dataSONGDATA.BIN Song data, currently just the name of each (replaces SNG)PALETTES.BIN 256-colour master palettesPLOTSCR.LST Plotscript names and ID numbersMENUITEM.BIN Menu items for user-defined main menu and submenusMENUS.BIN User-defined main menu and submenusUICOLORS.BIN User interface colorsslicetree_#_#.reld Saved slice collectionsSLICELOOKUP.TXT User defined names for looking up slicesdistrib.reld Meta-data used for exporting distribution filesheroes.reld Hero definitionsheroform.reld Hero formation dataNew graphics lumps:attacks.rgfx Attack spritesetsbackdrops.rgfx Backdropsboxborders.rgfx Box border spritesetsenemies.rgfx Enemy spritesetsheroes.rgfx Hero spritesetsportraits.rgfx Portrait spritesetswalkabouts.rgfx Walkabout spritesetsweapons.rgfx Weapon spritesets

(The following are the extensions of the variably-named lumps. See #Lump naming rules)GEN General misc data and record-counts.## .1 .2 .3 and so on, up to .99 are BAM songs..T## / ##.T tilemap for map ## (See Map Format).P## / ##.P passability (wallmap) for map ##.E## / ##.E enemy positions (foemap) for map ## .D## / ##.D door links for map ##.L## / ##.L NPC locations for map ##.N## / ##.N NPC definitions for map ##.Z## / ##.Z Zonemaps for map ##DOR Obsolete door locationsDOX Door locationsDT0 Obsolete hero dataDT1 Enemy DataDT6 (Partial) Attack DataEFS Enemy formation setsFOR Enemy formationsFNT FontHSP PlotscriptsHSX / HSZ (inside HSP lump) Single compiled PlotscriptITM Item dataMAP General Map dataMAS Obsolete Master paletteMN Map namesMXS Obsolete BackdropsPAL 16-color palettesPT0 Obsolete Hero picturesPT1 Obsolete Small Enemy GraphicsPT2 Obsolete Medium Enemy GraphicsPT3 Obsolete Large Enemy GraphicsPT4 Obsolete Walkabout GraphicsPT5 Obsolete Weapon GraphicsPT6 Obsolete Attack GraphicsPT7 Obsolete Box Border GraphicsPT8 Obsolete Character Portrait graphicsSAY Text boxesSHO Shop definitionsSNG Obsolete music name listSTF Shop "stuff" (items and heroes for purchase/sale/hire)STT Global Text StringsTAP Tile animation patternsTIL Maptile setsTMN Tag namesVEH Vehicle definitions

Map Format Describes what lumps you need to load a map.

Other non-lump files[edit]

RSAV RELOAD-based saved game filesSAV Obsolete saved game filesHS HSpeak-produced .HS files are simply .HSP files with a different extensionOHF Exported font files are just .FNT files with a different extensiontilemap A .tilemap file, exported from the map editor, is just a .T## file with a different extension.slice A .slice file, exported from the slice collection editor, is just a slicetree_#_#.reld file with a different extensionBMD A .BMD file is just a temporary MIDI file, which has been converted from a BAM fileohrkey Replayable recorded user inputgameconfig.ini Holds config settings for a single game customised by the player.editorconfig.ini Holds config settings for Custom (shared between all games).joyset.ini Created next to game.exe, stores the joystick settings from the CTRL+J menu. A relic of the DOS days but still used, will eventually be replaced.persist.reld Holds persistent data for a single game which doesn't belong in saved games, such as in-app purchases.session_info.txt.tmp Created in the working.tmp folder by Custom while editing a game. It provides information about the unlumped game and the instance of Custom editing it.

Plus temporary map state files in Game's temporary directory, named map#_<suf>.tmp (normal map saves, where # is the map ID) or state#_<suf>.tmp (save map state with "custom ID" #), where <suf> is one of "map", "n", "t", "z", "p", or "l.reld" which, aside from NPC location data which is a RELOAD format, is the same format as the map data.

Places where tags are used[edit]

(Warning: we're likely to forget to update this.)

SAY 9 conditional checks, 2 settable tags, 2 choicebox tagsN 2 checkable tags per NPC definitionD 2 checkable tags per door linkMENUITEM.BIN 2 checkable tags, 1 settable tag, 1 toggleable tagTAP Optional tag check command in tile animation patterns, tag to disable the animationDT0 Have hero, is alive, is leader, is in party nowDT6 2 checkable tags, for 2 settable tagsITM own item, is in inventory, is equipped, is equipped by active heroSTF 2 check tags, 2 settable tags per shop item/heroVEH Currently riding vehicleHSZ Scripts use tags with check tag and set tagFOR Battle formation Victory tag

Places where scripts are used[edit]

(Warning: we're likely to forget to update this.)

GEN 4 scripts: New game, game over, load game, menu actionMAP 5 scripts: map autorun, after-battle, instead-of-battle, each-step, on-keypressMENUS.BIN 1 On-close script triggerMENUITEM.BIN 1 script for each menu item (provided that the menu item is type 4)N 1 NPC script triggerSAY 2 script triggers, one instead-of-box, one after-boxSHO Inn animation scriptVEH 4 scripts: use button, cancel button, on-mount, on-dismount