HSP

The .HSP/.HS lump contains compiled scripts, and optionally also the original script source code. HSpeak saves its output as an .HS file, and the extension is changed to .HSP when imported into an .RPG, but no changes are made.

It is actually a lumped file itself, and is unlumped upon loading a game. See RPG format#Lump Format for details.

HS

The lump of filename "HS" contains the header. It is always the first lump in the file so that its filename followed by the length can also be used to identify an HSP/HS file. That is, the first four bytes of the .hsp/.hs file will be "HS\0\0", then two variable bytes, then the 12 bytes "HamsterSpeak". The length of the HS lump could change in future, but won't become long enough to change the first four bytes.

There are two different header file formats:

New Format

Used since HSpeak 3P (2012-08-18, Beelzebufo). This new format is a text file with Unix newlines, with one string or integer on each line, numbers expressed in decimal.

Line number	Type	HSHeader member name	Meaning
1	String (12)		Header text, must be equal to "HamsterSpeak" (no trailing space allowed)
2	String (3)	.hspeak_version	HSpeak version as a three-character code such as "3P " or "3Qa". The third character is a space if the version code would otherwise be two characters long.
3	Integer	.hsp_format	HSP format version (CURRENT_HSP_VERSION in the source). The version is 1 for all .hsp files with the new header (and those without this header have no version number)
4	String (3)	.plotscr_version	plotscr.hsd version. This is the first string in the "plotscr version" block of plotscr.hsd.
5	Integer	.script_format	The HSX format version number; will be the same as in each .hsz header. Currently 3 (CURRENT_HSZ_VERSION in the source).
6	Integer	.max_function_id	The maximum ID number of any builtin function (from the definefunction block) which is actually used in a script. Used to catch version mismatches early.

Old Format

The older format is binary, either 14 or 16 bytes long, and was used before HSpeak 3P.

About Formal Specs

Data	Meaning
STR (12)	Header text "HamsterSpeak"
INT	Compiler major version (1, 2 or 3)
STR (2)	Compiler minor version, eg "Gd" or "H ". The second character is a space if the version code is 1 character long. This field is not added by versions earlier than 3H (2009-06-18)

SCRIPTS.TXT

This lump is a plain text file and contains the name, id, and number of args of all scripts in the .HSP file. It is processed when a .HS file is imported via custom.exe to produce PLOTSCR.LST

For each script (in any order) this file contains, each on a new line

• The name of the script
• The decimal id number of the script
• The number of arguments of the script
• For each argument, a number is printed to a line

The list of numbers is nothing but garbage in old versions of HSpeak. Since HSpeak 2I, the numbers are the default arguments of the script, but you need to confirm HSpeak 2I or greater was used before considering using them (they are not used anywhere within the the current engine). 2I was the version that added the script argument number to HSZ lump headers, so you could check the length of the header of any HSZ lump.

walkherotox
32767
2
1
2

The text file ends on a newline.

SCRIPTS.BIN

Scripts.bin is a replacement for scripts.txt that contains similiar data in a 16-bit binary format, also holds trigger type info. It contains a header and a record for each script, which are in arbitrary order.

Header

Offset	Data	Meaning
0	INT	Header size in bytes (currently 4)
1	INT	Record size in bytes (currently 42)

The header size is read to determine whether the file format is supported; it'll be changed next time the file format changes (which will happen).

Record

Offset	Data	Meaning
0	INT	Script ID number
1	INT	Script trigger type: -1 = 'subscript' 0 = 'script' 1 = 'plotscript'
2-20	FVSTR(1i+36b=19i)	Script name (lowercase, whitespace trimmed)

COMMANDS.BIN

This lump commands the names of functions defined in define function blocks. It has three parts: header, offset table to find function records, and the function records.

Header

Offset	Data	Meaning
0	INT	Header size in bytes (currently 6), ie position of the offset table
1	INT	File format version (currently 0)
2	INT	Number of records in Offset Table

Offset Table

This is a simple array of 16-bit INTs, indexed by function id number, containing the absolute file position for the record for a function, or 0 if that function id wasn't declared. Always starts at id 0.

Function Record

Offset	Data	Meaning
0	INT	Number of arguments, or -1 if variable
1+	VSTR(1i+b..)	Function name

#.HSX or #.HSZ

Each script is separately compiled into a binary lump composed of a binary header followed by raw script data. The name of the file is the id number of the script with extension .hsx or .hsz, which are equivalent.

The format of this lump is documented at HSZ

SOURCE.TXT

This optional lump added by HSpeak 3I to 3Ja inclusive (unless run with the -n option) is just the script source preprocessed to inline included files, except for plotscr.hsd. It is not used by Game or Custom, but purely for backup.

SOURCE.LUMPED

This is an optional lump added by 3K onwards (unless run with the -n option). It is a lumped file of all the script source files (including plotsrc.hsd), with files renamed to avoid collisions, and newlines changed to LF (Unix).

SRCFILES.TXT

This article or section discusses a future engine feature which has not been completed or possibly even started yet, and is not yet available in nightly builds/SVN wip branch. If you wish to discuss this feature, feel free to use the talk page or contact the developers.

This optional lump (currently only created by HSpeak if outputting debug info) contains information on the original script files, and in particular is used to map the source markers used in debugging info source markers to files and file positions in source.lumped. It is a text file and all the lines in the file are of the form "tag=data". Unrecognised tags will be ignored. A file tag starts the entry for a new file. Global data may appear before the first file entry (none defined yet). Aside from file the appearance of each tag in a particular file entry is optional.

Tag	Meaning
file	The original (absolute) path and name of the file.
lump	The name of this file as lumped in source.lumped.
offset	A value used when decoding a srcpos source marker.
length	The length of the file. Required if offset is present.

List of Lumps in the RPG file format

ARCHINYM.LMP . ATTACK.BIN . BINSIZE.BIN . BROWSE.TXT . DEFPAL#.BIN . DEFPASS.BIN . distrib.reld . FIXBITS.BIN . general.reld . heroes.reld . heroform.reld . LOOKUP1.BIN . MENUITEM.BIN . MENUS.BIN . PALETTES.BIN . PLOTSCR.LST . SFXDATA.BIN . SLICELOOKUP.TXT . slicetree_#_#.reld . SONGDATA.BIN . UICOLORS.BIN
Map Format : E . D . L . N . P . T . Z
BAM . DOR . DOX . DT0 . DT1 . DT6 . EFS . FNT . FOR . GEN . HSP . HSZ . ITM . MAP . MAS . MN . MXS . PAL . PT0 ... PT8 . RGFX . SAY . SHO . SNG . STF . STT . TAP . TIL . TMN . VEH

List of other OHRRPGCE file formats

gameconfig.ini . ohrkey . ohrrpgce_config.ini . persist.reld . RELOAD . RELOAD common formats . RSAV . SAV