The Dink Network

...And hello Reference/Slot.

Windemere PAK Files
29 December 2004

After analyzing the formats used for graphics in the Dink Smallwood engine I determined it was necessary to work up a new system. Seq and frame, as they are commonly called, are ways to reference a particular image. This system is very confusing and one wrong mistake can cause the engine to come crashing down hard.

And then the creator created the PAK file.

PAK files are similar to FastFiles. The two are both single-file archives and have similar file layouts. However, PAK files are designed to be quick – no memory mappings are necessary and the code is based upon the C++ STL, a proven platform. Let's first take a look at the file format.

The first four bytes of the file contain the letters “WPAK”, for Windemere PAK. This is to ensure not only that the file is a PAK file, but mainly that the file is not compressed. If the file does not contain “WPAK” as the first four bytes it will be passed through the decompressor.

The next four bytes contain the number of files in the PAK.

The next amount of bytes are variable so that there are no name length restrictions. If your name is 13 characters long, 13 bytes will be used. If your name is 281 characters long, 281 bytes will be used. So, for as many files as there are in the PAK, these bytes are filled:

4 – The length of the file header
4 – The length of the name
x – The actual name
4 – The size of the file

File data follows after each header.

Now the question: What is a PAK good for? The main purpose is to store image files in one place. Earlier in this article I stated that the seq/frame system was confusing. I have instead implemented a better system which I call the File Reference System. There are two components to this system (Kind of like Seq and Frame): Reference and Slot. Let's see a real-life example (yes – it's actually already coded)...

PAK.Define(“Trees.pak”, “Trees”);
PAK.DefineFile(“Trees”, “Tree1.png”, 0);
PAK.DefineFile(“Trees”, “Tree2.png”, 1);
PAK.DefineFile(“Trees”, “Tree3.png”, 2);
PAK.DefineFile(“Trees”, “Tree4.png”, 3);
PAK.DefineFile(“Trees”, “Tree5.png”, 4);
PAK.DefineFile(“Trees”, “Tree6.png”, 6);

This is placed in the main.c file (or whatever I may change the name to) in a function that is called at program startup). In the scripting engine, <something><dot> indicates either a Nil Reference or a Library Reference. In this case it is referencing the PAK library (Nils will be covered in a later scripting article). So, the first line calls the Define function from the PAK library. Let's go through it one-by-one.

PAK.Define(“Trees.pak”, “Trees”);

The first argument to this function is a path to the actual PAK file. The second argument is a user-defined string to reference the PAK with. I could've called it “SabreIsfabulous”, for instance, but I thought “Trees” was a little better-fitting.

After assigning your string you can now tell the engine that the PAK file has other files.

PAK.DefineFile(“Trees”, “Tree1.png”, 0);

This assigns the “Tree1.png” file to slot 0 in the “Trees” PAK.

PAK.DefineFile(“Trees”, “Tree2.png”, 1);
PAK.DefineFile(“Trees”, “Tree3.png”, 2);
PAK.DefineFile(“Trees”, “Tree4.png”, 3);
PAK.DefineFile(“Trees”, “Tree5.png”, 4);

Ditto for these four.

PAK.DefineFile(“Trees”, “Tree6.png”, 6);

Now, on this one, Tree6.png is assigned to slot 6. Notice how slot 5 was skipped. You can assign a file to any positive integer you wish, even 123456789, as long as:

1)That number does not exceed 4294967296.
2)That number is not negative.

If you were to tell the engine to use a negative number it would be casted positive and you would, for say -1, probably get a number like 4294967295. Stay positive.

Now that this is done, how is it referenced? In a function, either:

Draw(“Trees”, 6, Xpos, Ypos);

OR

Draw(“Trees:6”, Xpos, Ypos);

Finally, one last function:

PAK.Remove(“Trees”, 0);

Great, that removes the PAK file, but what is the 0 for? If you specify 1 the loaded images in the PAK will be unloaded but the PAK will stay referenced. If you specify a 0 the engine will never have known a PAK even existed. I will probably remove this later but it's kinda fun to have it now.

What's to come:

* Sprites will reference these PAKs. You could specify Dink's Left Walk Sequence as “Dink”, {12, 13, 14, 15, 16}; or maybe you would rather do “DinkLeft”, {0, 1, 2, 3, 4}. It's up to you.
* You can stuff other things in the PAKs, like music or scripts. Well, you can already do that, but it's not coded for DinkC++.