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