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