71d3ed2e5c8723e5a215dcef00a8c82626a92ee3
[fp-git.git] / FP / doc / FormatSpecifications
1
2                              Prince of Persia
3                                File Formats
4                               Specifications
5
6 Table of Contents
7 ~~~~~ ~~ ~~~~~~~~
8 1. Preamble ............................................................ 49
9 2. Introduction ........................................................ 58
10 3. DAT v1.0 Format Specifications ...................................... 90
11 3.1. General file specs, index and checksums ........................... 93
12 3.2. Images ........................................................... 185
13 3.2.1 Headers ......................................................... 189
14 3.2.2 Algorithms ...................................................... 214
15 3.2.2.1 Run length encoding (RLE) ..................................... 230
16 3.2.2.2 LZ variant (LZG) .............................................. 242
17 3.3. Palettes ......................................................... 300
18 3.4. Levels ........................................................... 307
19 3.4.1 Unknown blocks .................................................. 338
20 3.4.2 Room mapping .................................................... 356
21 3.4.2.1 Wall drawing algorithm ........................................ 492
22 3.4.3 Room linking .................................................... 560
23 3.4.4 Guard handling .................................................. 576
24 3.4.5 Starting Position ............................................... 624
25 3.4.6 Door events ..................................................... 638
26 3.5. Digital Waves .................................................... 682
27 3.6. Midi music ....................................................... 699
28 3.7. Internal PC Speaker .............................................. 702
29 3.8. Binary files ..................................................... 707
30 4. DAT v2.0 Format Specifications ..................................... 714
31 4.1. General file specs, index and checksums .......................... 717
32 4.1.1 The master index ................................................ 744
33 4.1.2 The slave indexes ............................................... 790
34 4.2. Levels ........................................................... 810
35 4.2.1 Room mapping .................................................... 833
36 4.2.2 Door events ..................................................... 926
37 4.2.3 Guard handling .................................................. 947
38 4.2.3.1 Static guards ................................................. 960
39 4.2.3.2 Dynamic guards ............................................... 1007
40 5. PLV v1.0 Format Specifications .................................... 1040
41 5.1. User data ....................................................... 1067
42 5.2. Allowed Date format ............................................. 1097
43 6. The SAV v1.0 format ............................................... 1111
44 7. The HOF v1.0 format ............................................... 1157
45 8. Credits ........................................................... 1180
46 9. License ........................................................... 1201
47
48
49 1. Preamble
50    ~~~~~~~~
51
52  This file was written thanks to the hard work on reverse engineering made
53  by several people, see the credits section. In case you find any mistake
54  in the text please report it. A copy of this document should be available
55  in our official site at http://www.princed.com.ar.
56
57
58 2. Introduction
59    ~~~~~~~~~~~~
60
61  There are two versions of the DAT file format: DAT v1.0 used in POP 1.x
62  and DAT v2.0 used in POP 2. In this document we will specify DAT v1.0.
63
64  DAT files were made to store levels, images, palettes, wave, midi and
65  internal speaker sounds. Each type has its own format as described below
66  in the following sections.
67
68  As the format is very old and the original game was distributed in disks,
69  it is normal to think that the file format uses some kind of checksum
70  validation to detect file corruptions.
71
72  DAT files are indexed, this means that there is an index and you can
73  access each resource through an ID that is unique for the resource inside
74  the file.
75
76  Images store their height and width but not their palette, so the palette
77  is another resource and must be shared by a group of images.
78
79  PLV files use the extension defined to support a format with only one
80  level inside.
81
82  Both versions of DAT are supported and may be manipulated by PR. This
83  program works like a file archiver and extracts the files in known formats
84  that may be handled by other programs. For more information about PR
85  check the princed home page at http://www.princed.com.ar.
86
87  In this document you will also find the SAV and HOF format specifications
88  and the algorithm used by POP1 to draw the dungeon walls.
89
90
91 3. DAT v1.0 Format Specifications
92    ~~~ ~~~~ ~~~~~~ ~~~~~~~~~~~~~~
93
94 3.1. General file specs, index and checksums
95  All DAT files have an index, this index has a number of items count and
96  a list of items.
97  The index is stored at the very end of the file.
98  The first 6 bytes are reserved to locate the index and know the file size.
99
100  Let's define the numbers as:
101   SC - Signed char: 8 bits, the first bit is for the sign and the 7 last
102        for the number. If the first bit is a 0, then the number is
103        positive, if not the number is negative, in that case invert all
104        bits and add 1 to get the positive number.
105        i.e. -1 is FF (1111 1111), 1 is 01 (0000 0001)
106        Range: -128 to 127
107        1 byte
108   UC - Unsigned char: 8 bits that represent the number.
109        i.e. 32 is 20 (0010 0000)
110        Range: 0 to 255
111        1 byte
112   US - Unsigned Short: Little endian, 16 bits, storing two groups of 8 bits
113        ordered from the less representative to the most representative
114        without sign.
115        i.e. 65534 is FFFE in hex and is stored FE FF (1111 1110  1111 1111)
116        Range: 0 to 65535
117        2 bytes
118   SS - Signed Short: Little endian, 16 bits, storing two groups of 8 bits
119        ordered from the less representative to the most representative with
120        sign. If the first byte is 0 then the number is positive, if not the
121        number is negative, in that case invert all bits and add 1 to get
122        the positive number.
123        i.e. -2 is FFFE in hex and is stored FE FF (1111 1110  1111 1111)
124        Range: -32768 to 32767
125        2 bytes
126   UL - Unsigned long: Little endian, 32 bits, storing four groups of 8 bits
127        each ordered from the less representative to the most representative
128        without sign.
129        i.e. 65538 is 00010002 in hex and is stored 02 00 01 00
130        (0000 0010  0000 0000  0000 0001  0000 0000)
131        Range: 0 to 2^32-1
132        4 bytes
133
134  Note: Sizes are always in bytes unless another unit is specified.
135
136  Index structures:
137
138  The DAT header: Size = 6 bytes
139   - Offset 0, size 4, type UL: IndexOffset
140            (the location where the index begins)
141   - Offset 4, size 2, type US: IndexSize
142            (the number of bytes the index has)
143            Note that IndexSize is 8*numberOfItems+2
144            Note that IndexOffset+IndexSize=file size
145
146  The DAT index: Size = IndexSize bytes
147   - Offset IndexOffset,   size 2, type US: NumberOfItems
148            (resources count)
149   - Offset IndexOffset+2, size NumberOfItems*8: The index
150            (a list of NumberOfItems blocks of 8-bytes-length index record)
151
152  The 8-bytes-length index record (one per item): Size = 8 bytes
153   - Relative offset 0, size 2, type US: Item ID
154   - Relative offset 2, size 4, type UL: Resource start
155            (absolute offset in file)
156   - Relative offset 6, size 2, type US: Size of the item
157            (not including the checksum byte)
158
159  Note:
160   POP1 doesn't validate a DAT file checking:
161   IndexOffset+IndexSize=FileSize
162   this means you can append data at the end of the file.
163
164   PR validates that IndexOffset+IndexSize<=FileSize.
165  It also compares IndexSize with 8*numberOfItems+2 to determine if a file
166   is a valid POP1 DAT file.
167
168  Checksum byte:
169  There is a checksum byte for each item (resource), this is the first byte
170  of the item, the rest of the bytes are the item data. The item type is not
171  stored and may only be determined by reading the data and applying some
172  filters, unfortunately this method may fail. When you extract an item you
173  should know what kind of item you are extracting.
174
175  If you add (sum) the whole item data including checksum and take the less
176  representative byte (modulus 256) you will get the sum of the file. This
177  sum must be FF in hex (255 in UC or -1 in SC). If the sum is not FF, then
178  adjust the checksum in order to set this value to the sum. The best way
179  to do that is adding all the bytes in the item data (excluding the
180  checksum) and inverting all the bits. The resulting byte will be the
181  right checksum.
182
183  From now on the specification are special for each data type (that means
184  we won't include the checksum byte anymore).
185
186 3.2. Images
187  Images are stored compressed and have a header and a compressed data area.
188  Each image only one header with 6 bytes in it as follows
189
190 3.2.1 Headers
191  The 6-bytes-image header: 6 bytes
192   Relative offset 0, size 2, type US: Height
193   Relative offset 2, size 2, type UL: Width
194   Relative offset 4, size 2: Information
195
196  Information is a set of bits where:
197   the first 8 are zeros
198   the next 4 are the resolution:
199    if it is 1011 (B in hex) then the image has 16 colours
200    if it is 0000 (0 in hex) then the image has 2 colours
201    so to calculate the bits per pixel there are in the image, just take the
202    last 2 bits and add 1. e. g. 11 is 4 (2^4=16 colours) and
203   00 is 1 (2^1=2 colours).
204   the last 4 bits are the 5 compression types:
205    from 0 to 4:
206    0 RAW_LR (0000)
207    1 RLE_LR (0001)
208    2 RLE_UD (0010)
209    3 LZG_LR (0011)
210    4 LZG_UD (0100)
211
212  The following data in the resource is the image compressed with the
213  algorithm specified by those 4 bits.
214
215 3.2.2 Algorithms
216  RAW_LR means that the data wasn't compressed, it is used for small images.
217         The format is saved from left to right (LR) serialising a line to
218         the next integer byte if necessary. In case the image was 16
219         colours, two pixels per byte (4bpp) will be used. In case the image
220         was 2 colours, 8 pixels per byte (1bpp) will be used.
221  RLE_LR has a Run length encoding (RLE) algorithm, after uncompressed the
222         image can be read as a RAW_LR.
223  RLE_UD is the same as RLE_LR except that after uncompressed the bytes in
224      the image must be drawn from up to down and then from left to right.
225  LZG_LR has some kind of variant of the LZ77 algorithm (the sliding windows
226         algorithm), here we named it LZG in honour of Lance Groody, the
227         original coder.
228         After decompressed it may be handled as RAW_LR.
229  LZG_UD Uses LZG compression but is drawn from top to bottom as RLE_UD
230
231 3.2.2.1 Run length encoding (RLE)
232  The first byte is always a control byte, the format is SC. If the control
233  byte is negative, then the next byte must be repeated n times as the bit
234  inverted control byte says, after the next byte (the one that was
235  repeated)
236  another control byte is stored.
237  If the control byte is positive or zero just copy textual the next n bytes
238  where n is the control byte plus one. After that, the next byte is the
239  following control byte.
240  If you reach a control byte but the image size is passed, then you have
241  completed the image.
242
243 3.2.2.2 LZ variant (LZG)
244  This is a simplified algorithm explanation:
245
246  Definition: "print" means to commit a byte into the current location
247              of the output stream.
248
249  The output stream is a slide window initialised with zeros.
250  The first byte of the input stream is a maskbyte.
251  For each of the 8 bits in the maskbyte the next actions must be performed:
252   If the bit is 1 print the next unread byte to the slide window
253   If the bit is a zero read the next two bytes as control bytes with the
254   following format (RRRRRRSS SSSSSSSS):
255    - 6  bits for the copy size number (R). Add 3 to this number.
256         Range: 2 to 66
257    - 10 bits for the slide position (S). Add 66 to this number.
258         Range: 66 to 1090
259    Then print in the slide window the next R bytes that are the same slide
260    window starting with the S'th byte.
261
262  After all the maskbyte is read and processed, the following input byte is
263  another maskbyte. Use the same procedure to finish decompressing the file.
264  Remaining unused maskbits should be zeros to validate the file.
265
266  This is the modus operandi of the compression algorithm
267
268  For each input byte we take a window containing the 1023 previous bytes.
269  If the window goes out of bounds (ie, when the current input byte is
270  before position 1024), we consider it filled with zeros.
271
272      00000000000000000000********************************
273                          ^                  ^
274                     input start   current input byte
275            |--------------------------------|
276                     window size=1023
277
278  The algorithm works as follows:
279
280  While there is unread input data:
281      Create a maskbyte.
282      For each bit in the maskbyte (and there is still unread input data):
283          Compare the following input bytes with the bytes in the window,
284          and search the longest pattern that is equal to the next bytes.
285          If we found a pattern of length n > 2:
286              Assign 0 to the current bit of the maskbyte.
287              In the next 2 bytes of the output, specify the relative
288              position and length of the pattern.
289              Advance output pointer by 2.
290              Advance input pointer by n.
291          Else:
292              Assign 1 to the current bit of the maskbyte.
293              Copy the current input byte in the next output byte.
294              Advance output pointer by 1.
295              Advance input pointer by 1.
296
297  For a better understanding of the algorithm we strongly recommend to read
298  the PR source files lzg_uncompress.c and lzg_compress.c that may be
299  located at http://www.cvs.fp.princed.com.ar in the PR repository module.
300
301 3.3. Palettes
302  Palettes have 100 bytes always, after 4 bytes from the beginning the
303  first 16 records of 3 bytes are the VGA colours stored in the RGB-18 bits
304  format (6 bits for each colour). Each colour is a number from 0 to 63.
305  Remember to shift the colour bytes by two to get the colour number from 0
306  to 256.
307
308 3.4. Levels
309  This table has a summary of the blocks to be used in this section,
310  you can refer it from the text below.
311
312                    Table 3.1: DAT 1.0 Level blocks
313                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
314
315   Length Offset  Block Name
316   ~~~~~~ ~~~~~~  ~~~~~~~~~~
317   720    0       wall
318   720    720     pop1_background
319   256    1440    door I
320   256    1696    door II
321   96     1952    links
322   64     2048    unknown I
323   3      2112    start_position
324   3      2115    unknown II
325   1      2116    unknown III
326   24     2119    guard_location
327   24     2143    guard_direction
328   24     2167    unknown IV (a)
329   24     2191    unknown IV (b)
330   24     2215    guard_skill
331   24     2239    unknown IV (c)
332   24     2263    guard_colour
333   16     2287    unknown IV (d)
334   2      2303    0F 09 (2319)
335
336  All levels have a size of 2305, except in the original game, that the
337  potion level has a size of 2304 (may be it was wrong trimmed).
338
339 3.4.1 Unknown blocks
340  Blocks described in this section are: Unknown from I to IV.
341
342  Unknown III and IV blocks doesn't affect the level if changed, if you find
343  out what they are used to we will welcome your specification text.
344
345  Unknown I may corrupt the level if edited.
346
347  We believe unknown II has something to do with the start position, but we
348  don't know about it.
349
350  As unknown II were all zeros for each level in the original set, it was a
351  team decision to use those bytes for format extension. If one of them is
352  not the default 00 00 00 hex then the level was extended by the team.
353  Those extensions are only supported by RoomShaker at this  moment. To see
354  how those extensions were defined read the appendix I'll write some day.
355  For the moment you may contact us if you need to know that.
356
357 3.4.2 Room mapping
358  This section explains how the main walls and objects are stored. The
359  blocks involved here are "wall" and "pop1_background"
360
361  In a level you can store a maximum of 24 rooms (also called screens) of 30
362  tiles each, having three stages of 10 tiles each. Screens are numbered
363  from 1 to 24 (not 0 to 23) because the 0 was reserved for special cases.
364
365  The wall and pop1_background blocks have 24 sub-blocks inside. Those
366  sub-blocks have a size of 30 bytes each and has a room associated. So, for
367  example, the sub-block staring in 0 corresponds to the room 1 and the
368  sub-block starting in 690 corresponds to the room 24.
369  It is reserved 1 byte from the wall block and one from the pop1_background
370  block for each tile. To locate the appropriate tile you have to do the
371  following calculation: tile=(room-1)*30+tileOffset where tileOffset is a
372  number from 0 to 29 that means a tile from 0 to 9 if in the upper stage,
373  from 10 to 19 if in the middle stage and 20 to 29 if in the bottom stage.
374  We define this as the location format and will be used also in the start
375  position.
376  Always looking from the left to the right.
377  So there is a wall and pop1_background byte for each tile in the level and
378  this is stored this way.
379
380  The wall part of the tile stores the main tile form according to the table
381  below. Note that those are just a limited number of tiles, each code has a
382  tile in the game. The tiles listed are all the ones needed to make a level
383  so the missing tiles have an equivalent in this list.
384
385  Each tile has a code id, as some codes are repeated this is how you have
386  to calculate the codes. A tile in the wall part has 8 bits in this format
387  rrmccccc, where rr are random bits and can be ignored. m is a modifier of
388  the tile. For example modified loose floors do not fall down. The rest
389  ccccc is the code of the tile tabled below. Tile names are the same as the
390  ones used by RoomShaker to keep compatibility.
391
392                    Table 3.2: Foreground Walls
393                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
394
395   Hex  Binary Group  Description
396   ~~~~ ~~~~~~ ~~~~~  ~~~~~~~~~~~
397   0x00 00000  free   Empty
398   0x01 00001  free   Floor
399   0x02 00010  spike  Spikes
400   0x03 00011  none   Pillar
401   0x04 00100  gate   Gate
402   0x05 00101  none   Stuck Button
403   0x06 00110  event  Drop Button
404   0x07 00111  tapest Tapestry
405   0x08 01000  none   Bottom Big-pillar
406   0x09 01001  none   Top Big-pillar
407   0x0A 01010  potion Potion
408   0x0B 01011  none   Loose Board
409   0x0C 01100  ttop   Tapestry Top
410   0x0D 01101  none   Mirror
411   0x0E 01110  none   Debris
412   0x0F 01111  event  Raise Button
413   0x10 10000  none   Exit Left
414   0x11 10001  none   Exit Right
415   0x12 10010  chomp  Chopper
416   0x13 10011  none   Torch
417   0x14 10100  wall   Wall
418   0x15 10101  none   Skeleton
419   0x16 10110  none   Sword
420   0x17 10111  none   Balcony Left
421   0x18 11000  none   Balcony Right
422   0x19 11001  none   Lattice Pillar
423   0x1A 11010  none   Lattice Support
424   0x1B 11011  none   Small Lattice
425   0x1C 11100  none   Lattice Left
426   0x1D 11101  none   Lattice Right
427   0x1E 11110  none   Torch with Debris
428   0x1F 11111  none   Null
429
430  The pop1_background part of the tile stores a modifier or attribute of the
431  wall part of the tile. This works independently of the modifier bit in the
432  code. The tile  modifier depends on the group the tile belongs which are
433  wall, chomp, event, ttop, potion, tapp, gate, spike and free.
434  The group event allows the 256 modifiers and will be described in 3.4.6.
435  Note + means allowed for the dungeon environment, - means allowed for the
436  palace environment.
437
438                    Table 3.3: Background modifiers by group
439                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
440
441   Group  Code Description
442   ~~~~~  ~~~~ ~~~~~~~~~~~
443   none   0x00 This value is used always for this group
444   free   0x00 +Nothing -Blue line
445   free   0x01 +Spot1   -No blue line
446   free   0x02 +Spot2   -Diamond
447   free   0x03 Window
448   free   0xFF +Spot3   -Blue line?
449   spike  0x00 Normal (allows animation)
450   spike  0x01 Barely Out
451   spike  0x02 Half Out
452   spike  0x03 Fully Out
453   spike  0x04 Fully Out
454   spike  0x05 Out?
455   spike  0x06 Out?
456   spike  0x07 Half Out?
457   spike  0x08 Barely Out?
458   spike  0x09 Disabled
459   gate   0x00 Closed
460   gate   0x01 Open
461   tapest 0x00 -With Lattice
462   tapest 0x01 -Alternative Design
463   tapest 0x02 -Normal
464   tapest 0x03 -Black
465   potion 0x00 Empty
466   potion 0x01 Health point
467   potion 0x02 Life
468   potion 0x03 Feather Fall
469   potion 0x04 Invert
470   potion 0x05 Poison
471   potion 0x06 Open
472   ttop   0x00 -With lattice
473   ttop   0x01 -Alternative design
474   ttop   0x02 -Normal
475   ttop   0x03 -Black
476   ttop   0x04 -Black
477   ttop   0x05 -With alternative design and bottom
478   ttop   0x06 -With bottom
479   ttop   0x07 -With window
480   chomp  0x00 Normal
481   chomp  0x01 Half Open
482   chomp  0x02 Closed
483   chomp  0x03 Partially Open
484   chomp  0x04 Extra Open
485   chomp  0x05 Stuck Open
486   wall   0x00 +Normal  -Blue line
487   wall   0x01 +Normal  -No Blue line
488
489  Note: Some modifiers have not been tested, there may be any other unknown
490        tile type we didn't discover.
491
492
493 3.4.2.1 Wall drawing algorithm
494  This section doesn't have a direct relation with the format because it
495  describes how the walls must be drawn on the room. However, as this
496  information should be useful to recreate a cloned room read from the
497  format we decided to include this section to the document.
498
499  Wall drawing depends on what is in the right panel. If the right panel
500  is not a wall (binary code ends in 10100) a base wall will be drawn and
501  other random seed will be used. If the right panel is a wall then the main
502  base wall will be drawn and the described seed will be used.
503
504  When the base wall is drawn, the modifiers should be blitted over it.
505  There are 53 different types of walls using the same base image.
506  We will call the seed array to the one having the modifier information of
507  those 53 panels. This array has indexes from 1 to 53 included.
508
509  To calculate what value take from the array this calculation must be
510  performed: panelInfo=seedArray[roomNumber+wallPosition]
511  where panelInfo is the result modifier information that will be applied to
512  the base image; seedArray is this array that will be described above as a
513  table; roomNumber is the number of the room the wall is (from 1 to 24)
514  and wallPosition is the position the wall is (from 0 to 29), using the
515  location format specified in section 3.4.2. This means the first value is
516  1 (roomNumber=1 and wallPosition=0) and the last is 53 (roomNumber=24
517  and wallPosition=29).
518
519  Modifiers affects the corners of a stone. There are three stone rows per
520  wall. If the modifier is activated this corner will appear different
521  (seems to be darker). Another modifier is the grey stone.
522
523                    Table 3.4: Stone modifiers on seed position
524                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
525   Modifier       Seed Positions
526   ~~~~~~~~       ~~~~ ~~~~~~~~~
527      (First row modifiers)
528   Grey stone     2, 5, 14, 17, 26, 32, 35, 50
529   Left, bottom   2, 11, 36, 45
530   Left, top      37
531   Right, bottom  27, 33
532   Right, up      4, 10, 31, 37
533
534      (second row)
535   Grey stone     none 
536   Left, bottom   34, 47
537   Left, top      9, 10
538   Right, bottom  2, 8, 25, 35
539   Right, top     6, 12, 23, 29, 39
540
541      (third row)
542   Grey stone     none 
543   Left, bottom   none
544   Left, top      16
545   Right, bottom  none
546   Right, top     none
547
548  Another modifiers are saved in the seed too. Those modifiers are not
549  boolean values, they are offsets and sizes. As each stone has a different
550  size the stone separation offset is saved in the seed.
551  For the first row, the stones are all the same size and the seed is not
552  needed.
553  For the second row we've got the first 20 values, ordered from 1 to 20. 
554  position        1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20
555  offsets:        5,4,3,3,1,5,4,2,1, 1, 5, 3, 2, 1, 5, 4, 3, 2, 5, 4
556  separator size: 0,1,1,0,0,0,1,1,0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0
557
558  We'll be adding the next values as soon as we count the pixels ;)
559  This information can be found in walls.conf file from FreePrince.
560
561 3.4.3 Room linking
562  This section describes the links block.
563
564  Each room is linked to another by each of the four sides. Each link
565  is stored. There is no room mapping, just room linking.
566
567  The links block has 24 sub-blocks of 4 bytes each. All those sub-blocks
568  has its own correspondence with a room (the block starting at 0 is
569  related to the room 1 and the block starting at with 92 is related to
570  room 24).
571  Each block of 4 bytes stores the links this room links to reserving one
572  byte per each side in the order left (0), right (1), up (2), down (3).
573  The number 0 is used when there is no room there.
574  Cross links should be made to allow the kid passing from a room to
575  another and then coming back to the same room but it's not a must.
576
577 3.4.4 Guard handling
578  This section specifies the blocks: guard_location, guard_direction,
579  guard_skill and guard_colour.
580
581  Each guard section has 24 bytes, each byte of them corresponds to a room
582  so byte 0 is related to room 1 and byte 23 is related to room 24.
583  This room is where the guard is located. The format only allows one
584  guard per room. Each block describes a property or attribute of the guard.
585
586  The guard_location part of a guard describes where in the room the guard
587  is located, this is a number from 0 to 29 if the guard is in the room or
588  30 if there is no guard in this room. Other values are allowed but are
589  equivalent to 30. The number from 0 to 29 is in the location format
590  specified in section 3.4.2
591
592  The guard_direction part describes where the guard looks at. If the value
593  is 0, then the guard looks to the right, if the value is the hex FF (-1 or
594  255) then he looks left. This is the direction format, and will be used in
595  the start position too.
596
597  The guard_skill is how the guard fights, style and hit points. Note that
598  the hit points also depends on the level you are. Allowed numbers are from
599  0 to 9.
600
601  TODO: add a skill table
602
603  The guard_colour is the palette the guard has (see 4.8).
604  The default colours are in this table:
605
606                    Table 3.4: Default Guard colours
607                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608
609   Code Pants     Cape
610   ~~~~ ~~~~~     ~~~~
611   0x00 Light     Blue Pink
612   0x01 Red       Purple
613   0x02 Orange    Yellow
614   0x03 Green     Yellow
615   0x04 Dark Blue Beige
616   0x05 Purple    Beige
617   0x06 Yellow    Orange
618
619  Other codes may generate random colours because the game is reading
620  the palette from trashed memory. This may also cause a game crash.
621  It should (never tested) be possible to add new colours in the guard
622  palette resource (see 4.8) avoiding the crash due to this reason.
623
624
625 3.4.5 Starting Position
626  This section describes the start_position block.
627
628  This block stores where and how the kid starts in the level. Note that all
629  level doors that are on the starting room will be closed in the moment
630  the level starts.
631
632  This block has 3 bytes.
633  The first byte is the room, allowed values are from 1 to 24.
634  The second byte is the location, see the section 3.4.2 for the location
635  format specifications.
636  The third byte is the direction, see 3.4.4 for the direction format
637  specifications.
638
639 3.4.6 Door events
640  This section explains how the doors are handled and specifies the blocks
641  door I and II.
642
643  First of all he have to define what an event line is in this file. An
644  event line is a link to a door that will be activated. If the event was
645  triggered with the action close, then the event will close the door, if
646  the action was open then the event will open the door. An event line has
647  also a flag to trigger the next event line or not.
648  An event is defined as a list of event lines, from the first to the last.
649  The last must have the trigger-next-event-line flag off. This is like a
650  list of doors that performs an action.
651  An event performs the action that it was called to do: open those doors or
652  close them. This action is defined by the type of tile pressed.
653  Each event line has an ID from 0 to 255. An event has the ID of the first
654  event line in it.
655
656  In section 3.4.2 it is explained how a door trigger is associated to an
657  event ID. Those are the tiles that starts the event depending on what are
658  them: closers or openers.
659
660  How events are stored:
661  Each door block has 256 bytes, one per event line. Each event line is
662  located in an offset that is the event line ID, so event line 30 is
663  located in the byte 30 of each block.
664  There is a door I part of an event line and a door II part of it. We'll
665  define them as byte I and byte II.
666  You can find there: the door room, the door location, and the
667  trigger-next flag. The format is the following:
668
669  Let's define:
670   Screen as S and it is a number from 1 to 24 (5 bits)
671    S = s1 s2 s3 s4 s5
672     where sn is the bit n of the binary representation of S
673   Location as L and is a number from 0 to 29 (5 bits)
674    L = l1 l2 l3 l4 l5
675     where ln is the bit n of the binary representation of L
676    This number is according to the location format specifications.
677   Trigger-next as T and is a 1 for "off" or a 0 for "on" (1 bit)
678    T = t1
679
680  Byte I  has the form: t1 s4 s5 l1 l2 l3 l4 l5
681  Byte II has the form: s1 s2 s3  0  0  0  0  0
682
683 3.5. Digital Waves
684  Read them as raw digital wave sound using the following specifications:
685
686                    Table 3.4: Wave Specifications
687                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
688   Size of Format: 16
689   Format:         PCM
690   Attributes:     8 bit, mono, unsigned
691   Channels:       1
692   Sample rate:    11025
693   Bytes/Second:   11025
694   Block Align:    1
695
696  GNU/Linux users can play the raw waves just dropping them inside /dev/dsp
697  As dat headers are very small it is valid to type in a shell console with
698  dsp write access: cat digisnd?.dat>/dev/dsp to play the whole wave files.
699
700 3.6. Midi music
701  Standard midi files
702
703 3.7. Internal PC Speaker
704  We are not so sure about it, but we think it is:
705   2 unique bytes for headers
706   3 bytes per note (2 for frequency and 1 for duration)
707
708 3.8. Binary files
709  Some binary files contains relevant information
710  The resource number 10 in prince.dat has the VGA guard palettes in it
711  saving n records of a 16-colour-palette of 3 bytes in the specified
712  palette format.
713
714
715 4. DAT v2.0 Format Specifications
716    ~~~ ~~~~ ~~~~~~ ~~~~~~~~~~~~~~
717
718 4.1. General file specs, index and checksums
719  POP2 DAT files aren't much different from their POP1 predecessors.
720  The format is similar in almost each way. The main difference is in the
721  index. As DAT v1.0 used an index in the high data, the DAT v2.0 indexes
722  are two level encapsulated inside a high data. So there is an index of
723  indexes.
724
725  We will use the same conventions than in the prior chapter.
726  The checksum validations are still the same.
727
728  High data structures:
729
730  The DAT header: Size = 6 bytes
731   - Offset 0, size 4, type UL: HighDataOffset
732            (the location where the highData begins)
733   - Offset 4, size 2, type US: HighDataSize
734            (the number of bytes the highData has)
735            Note that HighDataOffset+HighDataSize=file size
736
737  This is similar to DAT v1.0 format, except that the index area is now
738  called high data.
739
740  The high data part of the file contains multiple encapsulated indexes.
741  Each of those index is indexed in a high data index of indexes. We will
742  call this index the «master index» and the sub index the «slave indexes».
743  Slave indexes are the real file contents index.
744
745 4.1.1 The master index
746  The master index is made with:
747   - Offset HighDataOffset,   size 2, type US: NumberOfSlaveIndexes
748            (the number of the high data sections)
749   - Offset HighDataOffset+2, size NumberOfSlaveIndexes*6: The master index
750            record (a list of NumberOfSlaveIndexes blocks of 6-bytes-length
751            index record each corresponding to one slave index)
752
753  The 6-bytes-length index record (one per item): Size = 6 bytes
754   - Relative offset 0, size 4, type sting: 4 ASCII bytes string denoting
755            the Slave Index ID. The character order is inverted.
756   - Relative offset 4, size 2, type US: SlaveIndexOffset
757            (slave index offset relative to HighDataOffset)
758
759  From the end of the DAT High Data Master Index to the end of the file
760  we will find the High Data section contents (where the HighDataOffset
761  relative offsets points to). This content has a set of second indexes
762  each called Slave Index. So, to find a Slave Index offset you have to
763  add the file HighDataOffset to the SlaveIndexOffset for the desired
764  index.
765
766  There are different 4-byte-length ASCII strings called Slave Index IDs.
767  When the string is less than 4 bytes, a tailing byte 0x00 is used. We will
768  denote it with the cardinal # symbol. The character order is inverted, so
769  for example the text SLAP becomes PALS, MARF becomes FRAM, #### becomes
770  empty or RCS# becomes SCR. They must be in upper case.
771
772                    Table 4.1: Slave Index ID strings
773                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
774
775    ID     Stored Description
776    ~~     ~~~~~~ ~~~~~~~~~~~
777    "cust" TSUC   Custom 
778    "font" TNOF   Fonts
779    "fram" MARF   Frames
780    "palc" CLAP   CGA Palette
781    "pals" SLAP   SVGA Palette
782    "palt" TLAP   TGA Palette
783    "piec" CEIP   Pieces  
784    "psl"  LSP#   ? 
785    "scr"  RCS#   Screens (images that have the full room)
786    "shap" PAHS   Shapes (normal graphics)
787    "shpl" LPHS   Shape palettes
788    "strl" LRTS   Text
789    "snd"  DNS#   Sound
790    "seqs" SQES   Midi sequences
791    "txt4" 4TXT   Text
792    ""     ####   Levels
793
794 4.1.2 The slave indexes
795  All encapsulated sections pointed by the Master Index are Slave Indexes.
796  The slave index is specified with:
797   - Offset SlaveIndexOffset,   size 2, type US: NumberOfItems
798            (the number of the records referring to the file data)
799   - Offset SlaveIndexOffset+2, size NumberOfItems*11: The slave index
800            record (a list of NumberOfItems blocks of 11-byte-length index
801            record each corresponding to one slave index)
802
803  The 11-byte-length slave index record (one per item): Size = 11 bytes
804   - Relative offset 0, size 2, type US: Item ID
805   - Relative offset 2, size 4, type UL: Resource start
806            (absolute offset in file)
807   - Relative offset 6, size 2, type US: Size of the item
808            (not including the checksum byte)
809   - Relative offset 8, size 3, type binary: A flags mask
810            (in "shap" indexes it's always 0x40 0x00 0x00;
811            in others 0x00 0x00 0x00)
812
813  Finally, we can locate whatever item we want if we have the
814   - Slave Index ID
815   - Item ID
816  this is not a unique key, unfortunately we have found repeated pairs of
817  IDs for different items, so we have to use the "order" as a third key.
818
819  So, the way to find an item is: first read the High Data Offset, go there,
820  read the number of slave items, iterate the master index to find the
821  desired slave item comparing it with the Slave Index ID. Then go to the
822  found Slave Index offset (remember to add the High Data Offset) and read
823  the number of items for this index. Finally iterate the slave index to
824  find the desired item comparing the Item ID and read the offset and size.
825  Now you will have the offset of the desired item's checksum, increasing
826  the offset by one will give you the beginning of the item content.
827
828 4.2. Levels
829
830  This table has a summary of the blocks to be used in this section.
831
832                    Table 4.2: DAT 2.0 Level blocks
833                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
834
835   Length Offset  Block Name
836   ~~~~~~ ~~~~~~  ~~~~~~~~~~
837   960    0       wall
838   3840   960     pop2_background
839   1280   4800    pop2_doors
840   128    6080    links (as explained in section 3.4.3 but having 32 rooms)
841   32     6208    unknown I
842   3      6240    start_position (as explained in section 3.4.5)
843   4      6243    unknown II (00 01 00 02) (check pop1)
844   3712   6247    pop2_static_guard
845   1088   9959    pop2_dynamic_guard
846   978    11047   unknown III
847
848  All levels have a size of 12025.
849
850 4.2.1 Room mapping
851  You should read section 3.4.2 before reading this one.
852  A POP2 level can store a maximum of 32 rooms of 30 tiles each, having 
853  three stages of 10 tiles each. Rooms are numbered from 1 to 32 (not 0 to 
854  31) because the 0 is be reserved to the null-room.
855
856  The wall block has 32 sub-blocks inside. Each sub-block has a size of 30
857  bytes and has a room associated. For each byte in this room there is a
858  tile in the game. Each byte has a code to represent a tile. There are
859  additional attributes to this tile also.
860  
861  To locate the 7th tile in the bottom floor of the room 27 you have to do
862  the same calculation as in 3.4.2:
863   tile=(room-1)*30+tileOffset=(27-1)*30+2*10+7=807
864  
865
866                    Table 4.3: Foreground Walls
867                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
868
869  Dec Hex   Bin     Caverns             Ruins              Temple
870  ~~~ ~~~   ~~~     ~~~~~~~             ~~~~~              ~~~~~~
871            
872  00  0x00  000000  Empty               Empty              Empty
873  01  0x01  000001  Floor               Floor              Floor
874  02  0x02  000010  Spikes              (?)                Spikes
875  03  0x03  000011  Pillar              Pillar             Pillar
876  04  0x04  000100  Door                Gate               Gate
877  05  0x05  000101  (?)                 Raised Button      Raised Button
878  06  0x06  000110  (?)                 Drop Button        Drop Button
879  07  0x07  000111  (?)                 Tunnel             (?)
880  08  0x08  001000  Bottom Big Pillar   Bottom Big Pillar  Bottom Big Pillar
881  09  0x09  001001  Top Big Pillar      Top Big Pillar     Top Big Pillar
882  10  0x0A  001010  Potion              Potion             Potion
883  11  0x0B  001011  Loose Floor         Loose Floor        Loose Floor
884  12  0x0C  001100  (?)                 Slicer Left Half   Slicer Left Half
885  13  0x0D  001101  (?)                 Slicer Right Half  Slicer Right Half
886  14  0x0E  001110  Debris              Debris             Debris
887  15  0x0F  001111  (?)                 Drop Floor         (?)
888  16  0x10  010000  Exit Half Left      Exit Half Left     Exit Half Left
889  17  0x11  010001  Exit Half Right     Exit Half Right    Exit Half Right
890  18  0x12  010010  Magic Carpet        (?)                (?)
891  19  0x13  010011  Torch               (?)                Torch
892  20  0x14  010100  Wall                Wall               Wall
893  21  0x15  010101  (?)                 Skeleton           (?)
894  22  0x16  010110  (?)                 Sword              (?)
895  23  0x17  010111  Lava Pit Left       (?)                (?)
896  24  0x18  011000  Lava Pit Right      (?)                (?)
897  25  0x19  011001  (?)                 (?)                Squash Wall
898  26  0x1A  011010  (?)                 (?)                Flip Tile
899  27  0x1B  011011  (?)                 (?)                (?)
900  28  0x1C  011100  (?)                 (?)                (?)
901  29  0x1D  011101  (?)                 (?)                (?)
902  30  0x1E  011110  (?)                 (?)                (?)
903  31  0x1F  011111  (?)                 (?)                (?)
904  32  0x20  100000  Torch w/Debris      (?)                Torch w/Debris
905  33  0x21  100001  Exit Door Top Left  (?)                (?)
906  34  0x22  100010  Pressure Plate      (?)                (?)
907  35  0x23  100011  Exit Door Top Right (?)                (?)
908  36  0x24  100100  Dart Gun            (?)                (?)
909  37  0x25  100101  (?)                 (?)                (?)
910  38  0x26  100110  (?)                 (?)                (?)
911  39  0x27  100111  (?)                 (?)                (?)
912  40  0x28  101000  (?)                 (?)                (?)
913  41  0x29  101001  (?)                 (?)                (?)
914  42  0x2A  101010  (?)                 (?)                (?)
915  43  0x2B  101011  (?)                 (?)                Blue Flame
916  44  0x2C  101100  Rope Bridge         (?)                (?)
917  45  0x2D  101101  (?)                 (?)                (?)
918  46  0x2E  101110  (?)                 (?)                (?)
919  47  0x2F  101111  (?)                 (?)                (?)
920
921  The pop2_background is an expansion if the pop1_background and it is sized
922  4 times bigger. For each tile there are 4 additional bytes in the 
923  pop2_background block to specify further actions or attributes. This block
924  is sized 4 bytes/tile * 10 tiles/floor * 3 floors/room * 32 rooms that is
925  3840 bytes.
926  We call background mask to each block of 4 bytes associated to a tile. To
927  locate a background mask you have to do the following operation:
928   960+(room-1)*30*4+tileOffset*4
929  Background masks are stored consecutively each after another until the
930  960 tiles are specified.
931  
932  The first byte is an unsigned char (UC) association to one of the 256 door
933  event registers (see section 4.2.2) if the tile is an activator.
934  In any other case this byte is an extra attribute information byte.
935  For example in wall (0x14) having this byte in 0x04 means the wall is
936  curved.
937  
938  The second byte in a background mask is the attribute byte. For example
939  0x18 modifies the tile 0x01 and adds two small stalactites.
940  
941  We believe the special images uses the 3rd or 4th byte.
942
943 4.2.2 Door events
944  This section explains how doors are handled and specifies the block
945  pop2_door.
946
947  The pop2_door block has 1280 bytes. It is divided in 256 registers of
948  5 bytes called door events. Like pop1 events have associations to doors
949  and activate them. In POP2 events can also activate a floor shooter.
950  
951  An event is triggered when an activator button (0x22) is pressed. As it is
952  specified in the section 4.2.1, the first byte of the attribute mask
953  belonging to a button tile points it to a door event that is triggered
954  when the button is pressed.
955  There is a maximum of 256 events because of the unsigned char of the first
956  byte if the attribute mask in the pop2_background block and the 256
957  registers in the pop2_door block.
958
959  Each event register is of the form "LL SS TT FD FD" which activates the
960  normal door (0x04), right exit door (0x11) or shooter (0x24) located in
961  the tile LL of the screen SS. TT is 00 for normal activation and FF for
962  exit doors.
963
964 4.2.3 Guard handling
965  This section explains how guards are handled. In POP2 there are two
966  different types of guards. We'll call them static and dynamic guards.
967  Static guards are the normal guards that are waiting in a room like in
968  POP1. In the other hand, dynamic guards are the ones who appear in the
969  room running from one of the sides. Each type of guard is attached to a
970  room and is handled in a different way, so a room can have both types of
971  guards, one or none depending on the specifications. There is a block for
972  each type of guard, pop2_static_guard is the specification of the static
973  guards and pop2_dynamic_guard is the specification of the dynamic ones.
974  Each block has different specifications and sizes as it is mentioned
975  bellow.
976  
977 4.2.3.1 Static guards
978  
979  In this item static guards are explained and the pop2_static_guard is
980  specified.
981  
982  For each screen there is reserved memory space for a maximum of 5 guards.
983  
984  The pop2_static_guard block has a size of 3712 divided in 32 sub-blocks of
985  116 bytes each. As there is a correspondence between each sub-block and
986  the room with this number, we'll call them "room guard blocks".
987  
988  A room guard block has a size of 116 divided this way:
989  - 1 byte for the number of guards present in this room.
990    This byte may take values from 0 to 5.
991  - 5 block divisions of 23 bytes for each guard.
992    The first divisions have the guard information, if the number is less
993    than 5, then the latest divisions corresponding to the missing guards
994    will be filled with zeros or garbage.
995  
996  If there is a static guard corresponding to this division of 23 bytes,
997  the following bytes from 0 to 22 will specify the guard:
998  
999  Byte 0 is a UC showing the location in this room (same as explained in
1000   3.4.4) of the current guard.
1001  Bytes 1 and 2 are a SS with an offset in pixels to reallocate the guard in
1002   the floor.
1003  Byte 3 is the facing direction as specified in 3.4.4.
1004  Byte 4 is the skill
1005  Byte 5 is unknown
1006  Bytes 6,7 and 8 are always 0, probably because 5 is a long from 0 to 255.
1007  Byte 9 is the guard colour in levels where it is needed (0-3),
1008   ie. 1 white+blue, 2 white+black, 3 red.
1009  Byte 10 is the guard number (0 for the first one, 1 for the second, etc).
1010  Bytes 11,12,13 and 14 are unknown, mostly 0, but in 10 guards it is
1011   0x52756e2d.
1012  Byte 15 is the type (0-8 and 84), but doesn't apply in all levels,
1013   ie. 5 head, 8 snake.
1014  Byte 16 is the hit points of the guard (0 to 8).
1015  Bytes 17 and 18 are the activate triggers for skeletons, byte 17 is
1016   (0,1,-1) and 18 is (0,-1). Normal value is 0x0000 for a sleeping
1017   skeleton. When set to -1 (0xffff) a trigger will be waiting to wake the
1018   skeleton up, for example the exit door open. Other possible values are
1019   0x0100 that is the skeleton already awake and 0xff00 that seems to be
1020   similar than 0x0000.
1021  Bytes 19,20,21 are always 0.
1022  Byte 22 is unknown (mostly 0, but 1 and 3 where found for some guards).
1023
1024 4.2.3.2 Dynamic guards
1025  
1026  The dynamic guards are the ones who appear running throw a room's corner
1027  and they are defined in the pop2_dynamic_guard block.
1028  This block has 34 bytes for each of the 32 rooms, so it is sized 1088
1029  bytes. Each room has a specification about those guards.
1030  There is only one different type of dynamic guard per room, but it is
1031  possible to set the number of guards that will appear running.
1032  
1033  The bytes are from 0 to 33:
1034  Bytes from 8 to 17 may take the value 0x5a and 0. Bytes 8,9,10,15,16 are
1035   always 0.
1036  Byte 18 activates dynamic guard. 1 is true and 0 is false.
1037  Byte 19 is the skill (0-7, 8 to make it passive)
1038  Bytes 20, 21 and 22 are always 0.
1039  Byte 23 is the dynamic guard mode: 0 or 1 to make the guard wait until all
1040   guards are dead to spawn and 2 to spawn even when the prior guard is
1041   still alive.
1042  Byte 24 is the floor the guard will appear on. 0 is the upper one and 2 is
1043   the lower. Another number will kill the guard playing the sound.
1044  Byte 25 is the initial location of the guard. ie. 0 is the left side of
1045   the screen, 9 is the right side, it is possible to locate them in the
1046   middle of the screen, they will magically spawn in a position between 1
1047   and 8. As they will run to the center of the screen, this byte also sets
1048   the facing direction up (0 to 5 is right, 6 to 9 is left).
1049  Byte 26 is the time in ticks the first guard will wait to spawn.
1050  Byte 27 is the time in ticks between guards spawn.
1051  Bytes 28 and 29 are unknown.
1052  Byte 30 is the number of guards that will appear, there is a maximum of 5
1053   per room, including static guards.
1054  Byte 31 is the hit points the guards will have.
1055
1056
1057 5. PLV v1.0 Format Specifications
1058    ~~~ ~~~~ ~~~~~~ ~~~~~~~~~~~~~~
1059
1060  PLV v1.0 files are defined in this table:
1061
1062                    Table 5.1: PLV blocks
1063                    ~~~~~~~~~~~~~~~~~~~~~
1064
1065    Size Offset Description                  Type   Content
1066    ~~~~ ~~~~~~ ~~~~~~~~~~~                  ~~~~   ~~~~~~~
1067       7      0 Magic identifier             text   "POP_LVL"
1068       1      7 POP version                  UC     0x01
1069       1      8 PLV version                  UC     0x01
1070       1      9 Level Number                 UC
1071       4     10 Number of fields             UL
1072       4     14 Block 1: Level size (B1)     UL     2306/2305
1073      B1     18 Block 1: Level code          -
1074       4  18+B1 Block 2: User data size (B2) UL
1075      B2  22+B1 Block 2: User data           -
1076
1077  Level code is the exact level as described in 4.4 including the checksum
1078  byte. Note that Level size (B1)  also includes the checksum byte in the
1079  count.
1080  POP version is 1 for POP1 and 2 for POP2.
1081  PLV version is 1 for PLV v1.0.
1082  Only one level may be saved in a PLV, the level number is saved inside.
1083
1084 5.1. User data
1085
1086  User data is a block of extensible information, Number of fields is the
1087  count of each field/value information pair. A pair is saved in the
1088  following format:
1089   field_name\0value\0
1090  where \0 is the null byte (0x00) and field_name and value are strings.
1091
1092  There are mandatory pairs that must be included in all PLV files.
1093  Those are:
1094
1095                    Table 5.2: Mandatory Fields
1096                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1097
1098   Field name              Description
1099   ~~~~~~~~~~              ~~~~~~~~~~~
1100   Editor Name             The name of the editor used to save the file
1101   Editor Version          The version of the editor used to save the file
1102   Level Author            The author of the file
1103   Level Title             A title for the level
1104   Level Description       A description
1105   Time Created            The time when the file was created
1106   Time Last Modified      The time of the last modification to the file
1107   Original Filename       The name of the original file name (levels.dat)
1108   Original Level Number   Optional. The level number it has when it was
1109                           first exported
1110  
1111  The content values may be empty. There is no need to keep an order within
1112  the fields.
1113
1114 5.2. Allowed Date format
1115  To make easy time parsing the time format must be very strict.
1116  There are only two allowed formats: with seconds and without.
1117  With seconds the format is "YYYY-MM-DD HH:II:SS"
1118  Without seconds the format is "YYYY-MM-DD HH:II"
1119  Where YYYY is the year in 4 digits, MM is the month in numbers, MM the
1120  months, DD the days, HH the hour, II the minute and SS the second in the
1121  military time: HH is a number from 00 to 23.
1122
1123  If the month, day, hour or second have only one digit, the other digit
1124  must be completed with 0.
1125  i.e. 2002-11-26 22:16:39
1126
1127
1128 6. The SAV v1.0 format
1129    ~~~ ~~~ ~~~~ ~~~~~~
1130
1131  SAV v1.0 saves kid level, hit points and remaining time information in
1132  order to restart the game from this position.
1133
1134  SAV files are 8 bytes length in the following format:
1135
1136                    Table 6.1: SAV blocks
1137                    ~~~~~~~~~~~~~~~~~~~~~
1138
1139    Size Offset Description                  Type
1140    ~~~~ ~~~~~~ ~~~~~~~~~~~                  ~~~~
1141       2      0 Remaining minutes            US   (i)
1142       2      2 Remaining ticks              US   (ii)
1143       2      4 Current level                US   (iii)
1144       2      6 Current hit points           US   (iv)
1145
1146  Remaining minutes (i)
1147   Range values:
1148    0     to 32766 for minutes
1149    32767 to 65534 for NO TIME (but the time is stored)
1150    65535 for game over
1151
1152  Remaining ticks (ii)
1153   Seconds are stored in ticks, a tick is 1/12 seconds. To get the time in
1154   seconds you have to divide the integer "Remaining ticks" by 12.
1155
1156   Range values:
1157    0.000 to 59.916 seconds
1158                    (rounded by units of ~83 milliseconds or 1/12 seconds)
1159    0     to 719    ticks
1160
1161  Level (iii)
1162   Range values:
1163    1  to 12 for normal levels
1164    13 for 12bis
1165    14 for princess level
1166    15 for potion level
1167
1168  Hit points (iv)
1169   Range values:
1170    0 for an immediate death
1171    1 to 65535 hit points
1172
1173
1174 7. The HOF v1.0 format
1175    ~~~ ~~~ ~~~~ ~~~~~~
1176  HOF files are used to save the Hall of Fame information.
1177
1178  All HOF v1.0 files have a size of 176 bytes. The first 2 bytes belongs to
1179  the record count. The format is US. The maximum number of records allowed
1180  is 6, so the second byte is always 0x00.
1181  Following those bytes there is an array of records. This array has a full
1182  size of 29 bytes distributed according to the following table.
1183
1184                    Table 7.1: HOF blocks
1185                    ~~~~~~~~~~~~~~~~~~~~~
1186
1187    Size Offset Description                  Type
1188    ~~~~ ~~~~~~ ~~~~~~~~~~~                  ~~~~
1189      25      0 Player name                  text
1190       2     25 Remaining minutes            US (similar to SAV format)
1191       2     27 Remaining ticks              US (similar to SAV format)
1192
1193  In case there is no record, the 29 bytes spaces must be filled with zeros
1194  in order to complete the whole file and give it the size of 2+29*6 = 176.
1195
1196
1197 8. Credits
1198    ~~~~~~~
1199
1200  This document:
1201   Writing . . . . . . . . . . . . . . . . . . . . . . . . . Enrique Calot
1202   Corrections . . . . . . . . . . . . . . . . . . . . .  Patrik Jakobsson
1203
1204  Reverse Engineering:
1205   Indexes . . . . . . . . . . . . . . . . . . . . . . . . . Enrique Calot
1206   Levels . . . . . . . . . . . . . . . . . . . . . . . . .  Enrique Calot
1207                                                             Brendon James
1208   Images . . . . . . . . . . . . . . . . . . . . . . .  Tammo Jan Dijkema
1209   RLE Compression . . . . . . . . . . . . . . . . . . . Tammo Jan Dijkema
1210   LZG Compression . . . . . . . . . . . . . . . . . . . . . Anke Balderer
1211                                                              Diego Essaya
1212   Sounds . . . . . . . . . . . . . . . . . . . . . . . Christian Lundheim
1213
1214  PLV v1.0:
1215   Definition . . . . . . . . . . . . . . . . . . . . . . .  Brendon James
1216                                                             Enrique Calot
1217
1218 9. License
1219    ~~~~~~~
1220
1221       Copyright (c)  2004, 2005, 2006 The Princed Project Team
1222       Permission is granted to copy, distribute and/or modify this document
1223       under the terms of the GNU Free Documentation License, Version 1.2
1224       or any later version published by the Free Software Foundation;
1225       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1226       Texts.  A copy of the license is included in the section entitled
1227       "GNU Free Documentation License".
1228