Introduction

You've probably heard people talking about packing their data files (e.g. images, music, models etc.) in order to make later distributions of their programs easier. Packers are also used to protect data from being misused by others. The most common packer of the community and imho the best one out there for free is the "Terabit DataPacker" from Lee Page. This tutorial explains how to use it in order to store your project files correctly.

Tutorial Version: 1.01 (for Packer Version 2.5+).

Part A will deal with making and using an external data file. Where Part B will show you how to append your data to an executable.

What is the Terabit DataPacker?

The title gives it away, really -- but here's a statement from Lee:

"The TeraBit DataPacker and Extraction functions habe been designed to allow you to protect the media which ships with your projects from pilfering hands! It's not crack proof (what is!?) but it will be more trouble than it's worth for most people to break into it! If you want to have a MODable game, then simply allow the users to create their own packs and give them some (different) keys."

General Issues to remember

Hint: It is highly recommended that you yourself try to keep your data files as small as possible. The Terabit DataPacker itself does not compress these!

Usually image files are saved in PNG format. If you have big colorful images that need no transperancy check use JPG instead. Music files are regularly saved in OGG or MP3 format (the latter is copyrighted!).

Preparation

To follow this tutorial you need these files:

Datapak.zip - Terabit DataPacker (also contains further examples)

Grisu1.bb - Example1 (normal program)

Grisu2.bb - Example2 (using external data.pak)

Grisu3.bb - Example3 (single exe distribution)

Grisu.png - small image (64x64) that serves as example data

Getting started

Download and extract the DATAPAK.ZIP to a temporary directory. We don't need all files from the distribution package. Create a second directory named BC_TUTORIAL. Copy BONES.BB and the PACKMAKER.EXE to the Tutorial directory. Finally place GRISU.PNG in a new subdirectory of BC_TUTORIAL called DATA.

Hint: You should always place your data files in an extra directory separated from the main source code dir. This keeps all clean and makes packing easier. In bigger projects you could subdivide the main DATA directory further into IMAGES, MEDIA; MUSIC, MODELS etc. Just as you need it! But for us this single directory will do fine.

Part A: Program uses an external Data.pak

Step One: Write your program

First we need a program that makes use of an external file. Nothing easier than that. I have prepared a tiny one: Click Here

The program only uses the GRISU.PNG in our DATA directory as background. Loading is done via an extra function as in big projects you have more than one file to handle. So we structure our code right from the start.

Step Two: Creating your own Data.pak

Leave the source code aside and start the GUI (PACKMAKER.EXE). It should look something like this:

• Now simply select the files you want to store from the folder window to the right by left-clicking them. Here we only need one file to be selected DATA\GRISU.PNG.
• We also want our data to be encrypted. So activate "Secure my Data with Encryption"
• You can create a new Encryption key for each of your projects or different data files. For this tutorial use: 9FAF43FB as "Basic Key" and 629FC914 as "Header Mask". Notice that the Initialisation Code at the bottom changes according to your inputs.
• Hit "Create Pak Archive" and a file named DATA.PAK is created containing all the files you selected
• Finally write down the "Initialisation Code" for later usage or simply select and copy & paste it when needed.

Step Three: Modify your program

Now we have a DATA.PAK file. But our program won't be able to read the data stored inside without some modifications to the source code.

• Blitz must recognise the Terabit Packer functions. So add "Include Bones.bb" to the top of the source code.
• We also need to set an output directory where the files will be extracted: " PakOutputDir="" ". It can be set anywhere. By default the files will be extracted inside the main directory where your program is located.
• Now add the Initialisation Code you should have written down before... ;)
• Set "PakBulkoverwrite=True", old data files with the same name will be overwritten. Useful when the files change during development.

Your header should then look like this:

Our program knows the basics how to handle our DATA.PAK. Only thing that is missing: we need to modify our LoadData() function. Each time we want to access the DATA.PAK we need to change the native Blitz commands used for it. Only add "PAK(" - ")" to the commands used. Beware the brackets must only include the filename and not the whole command parameters!

Examples:

Here we only have one image to load. Therefore the changed line is:

The program now works without your data files. In our case the GRISU.PNG image. But as you might have noticed, the temporary file that is extracted when used (TMPGRISU.PNG) is still present at the DATA directory. Even if the program has been terminated! So how about cleaning?

Each time you need a resource from your DATA.PAK you can right afterwards call the DlPAK() function. It will always delete the last file extracted.

If you don't want to call this function each time. You can also call PakClean() at the very end of your code. This cleans out all files that have been unpacked to date, but have not been cleaned up yet.

DLPak() may also slow down your code during runtime if used to often!

Grisu2.bb contains all modifications made to this point.

Conclusion A

You should now be able to store your data files in one large pack and use them in your programs.

In case you want to pack your executables too, a freeware tool named UPX Packer can do it!

Part B: Append Data to the executable

Why should I want that?!?

It's pretty nice to only have one single file to distribute. Very adviseable for small gfx demos!

Step One: Modify your program

The only thing we need to change here is the Initialisation line. Instead of pointing to the DATA.PAK change it to the name your program has. As this is the third example in the tutorial call it "GRISU3.EXE". Create an executable out of the GRISU3.BB source code. But don't start the program yet!

Hint: If you use UPX, apply it before going to the next step! Else you compress both data and exe which will result in a crash!

Step Two: Appending data

Now head back to the GUI. There select "Append Data to the .EXE File" and name it "Grisu3.exe".

At last hit "Create Pak File". GRISU3.EXE should now run on its own!

See Grisu3.bb for details.

Conclusion B

You should now be able to append data to your executable programs directly. I advise only using this technique when your program is finished from the coding point of view. Testing your code is really ugly this way!

Changing Data.pak filename possible?

Yes you can change the data.pak file to every filename you like to. Only make sure you also change your Initialisation line in your source code accordingly!

Post Scriptum

That's it! Hope it's been useful. - Even as this is my first tutorial. :)

If you'd like to discuss a point out or have found a bug inside, drop me a line via email: Flame Grisu here.

Thanks for reading! Special thanks to Krylar!