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