@database PakMan

@node MAIN
@title "PakMan v1.0ß"

                                  PakMan v1.0ß

                                       by
                                 Rune Jacobsen

       A simple Amiga program to browse, edit and create Quake PAK files.

    @{" Introduction     " link INTRO }
    @{" Using PakMan     " link USING }
    @{" ** IMPORTANT **  " link IMPORTANT }
    @{" About PAK files  " link PAK }
    @{" The AQUA Project " link AQUA }

@endnode

@node INTRO
@title "Introduction"

                             Introduction to PakMan

PakMan is a rather simple program that will help you manage PAK files,  as  used
by  games  such  as  id  Software  /  clickBOOM's Quake. A PAK is simply one big
"archive" of stuff to avoid cluttering the users hard drive with lots  of  small
files.

For people to be able to create their  own  modifications  and  conversions  for
Quake,  a  PAK  utility  is  one of the essentials. This is the primary reason I
wrote PakMan - it will hopefully be a useful little stepping stone for people to
get  divine  inspiration  and  start making cool stuff for Amiga Quake. PakMan's
simple MUI interface makes it easy to browse PAK contents, extract, add,  delete
and rename PAKs, and hopefully soon, optimize them.

PakMan is in no way a finished program, it will  continue  to  be  extended  and
modified until such time that I find it good enough. If you have any suggestions
please do not hesitate to mail  me  at  shitlips@fido.euroline.no,  and  I  will
consider implementing it.

@endnode

@node Using "Using PakMan"

                                  Using PakMan

Using PakMan should be fairly intuitive and straight forward, but here is a
run down of the different buttons and menu items just in case:

GUI buttons:

'Extract':
   Use this to extract the selected file(s) and/or director(y/ies) from the PAK
   onto your Amigas hard disk or whereever. It will ask you where to extract
   the stuff. Any subdirectories will be created to keep the structure intact.

'Add':
   Add a file to the current directory. Will currently only add one file at a
   time.

'Delete':
   Delete currently selected file(s) and director(y/ies). No mercy, doesn't
   even ask ;)

'Make dir':
   Create a new subdirectory in the current dir. Can also create multiple
   levels of directories in one go; If you enter something like this ..
      extra/fun/directory/creation
   .. it will create extra, then fun under it, directory under it again,
   and finally creation at the "bottom" level.

'Rename':
   Renames currently selected file(s) / director(y/ies). There is nothing to
   prevent you from having several files with the same name in one directory,
   Quake will simply select the first one.

'Quit':
   Duh.

Menu items, Project menu:

'Create new PAK'     Amiga-C
   Create a new PAK file. You will be asked where to create it.

'Open PAK file'      Amiga-O
   Open an existing PAK file.

'PAK Info Window'    Amiga-I
   Open a little window with information about the opened PAK.

'Optimize PAK'       Amiga-P
   Optimize the open PAK file. This is the same as defragmenting a file
   system. It might save you some space.

'About PakMan'       Amiga-?
   Display silly information about PakMan.

'About MUI'
   Information about the excellent MagicUserInterface by Stefan Stuntz.

'Quit'               Amiga-Q
   Still duh.

@endnode

@node IMPORTANT "Stuff you really should know"

                          Stuff you really should know

Currently, PAKs touched by PakMan seems to be poison  for  QuakePlayer/Quake  by
clickBOOM. The "Quake Render Process" seems to crash 100% of the time here, both
in QuakePlayer v0.95/v0.96 and Quake. Since PakMan's PAK files  works  great  on
the  PC  version of Quake, this seems to be a problem with clickBOOM's versions,
but there is a general rule of programming that goes "It's your fault!", so  I'm
not  really  too sure about it. There are currently no known bugs in PakMan, and
all tests show that files in a PakMan-manipulated PAK are exactly the same  when
they come out as they were when they went in.

I have performed a simple test to check things; I made a copy of clickBOOMs  PAK
and  optimized  it with PakMan. Then I extracted the PAKs into two dirs, and ran
the utility "diff" to check for any differences. There were none. This tells  me
that  PakMan  does not mess up the files, but there can of course be bugs in the
code that saves the directory structure that does not affect PakMan,  but  might
destroy QuakePlayer.

What does this mean for you? ALWAYS back up your PAK file  before  modifying  it
with  PakMan.  No matter who is to blame for the error, the fact remains that it
IS there and its better to be careful.


@endnode

@node PAK "About PAK files"

                            The theory of PAK files

A PAK file is just a collection  of  files  stuck  together,  much  like  a  lha
archive,  but without the compression. There are basically three items making up
the PAK; The header, the directory structure, and the storage area.  The  header
occupies  the first 12 bytes of the file, and basically just identifies the file
as a PAK and tells you where the directory structure is  stored.  The  directory
structure  is stored whereever is possible, but normally at the end of the file,
and contains information about the name, placement  and  size  of  each  of  the
files. It is, in many ways, quite similar to a file system. This also means that
it has some flaws. The biggest of these is fragmentation.

Imagine that you have a PAK containing these three files:

start.bsp   1,532,630 bytes
intro.wav      94,794 bytes
player.mdl    191,852 bytes

They're stored in the PAK file in this order. Now, say that the  start.bsp  file
needs  to  be replaced with a new one, and that this new one is 1,615,400 bytes.
First we have to delete the original start.bsp, leaving an open space  of  1,5MB
at  the  beginning  of  the  file. Then we have to add the new one, but since it
doesn't fit in the space left by the old one, we have to extend the end  of  the
file  and put it there instead. Suddenly, we have a fragmented PAK file. Another
common situation is that the directory structure is stored in the middle of  the
file,  then  the  file  grows,  and the directory structure is too large for its
previous spot. This spot is then left vacant while the structure is rewritten at
the end of the file.

The bad news is that this is very hard to avoid, and not  really  something  you
want  a program like PakMan to fix for you automatically. The reason for this is
that these files are huge (id Software's original files are 18  and  34MB).  The
good  news  is  that  new, smaller files will automatically be stuffed into this
smaller space. And the even better news  is  that  PakMan  has  an  optimization
feature, but it has to be activated manually.

Now, does this fragmentation really mean a lot of grief? Depends. id's  original
PAK0.PAK  (the  one  you get with the shareware PC version) wastes over 400kB of
disk space. If this is a lot to you, optimize it with PakMan.  If  you  write  a
total  conversion  or  modification for Quake, released as a or with an included
PAK, optimize it so that users won't be annoyed with your space wasting.

Another of the built-in limitations of a PAK file is the file name space. Even
tho PakMan displays it this way, there really is no directory structure in a PAK
file. Each file has a 50 character string to describe both the placement and
the file name, like this:

sound/items/r_item1.wav

This means that the total length of the directory names and the file name cannot
exceed  49  characters  (one  is  used for the '\0' termination). PakMan sets no
limitations to the amount of subdirs  you  can  have,  but  when  it  saves  the
directory structure, anything that is longer than 49 characters is dealt with in
a very simple way; It is put  in  a  directory  called  trunc.  So  if  you  had
something like this in your PAK:

sound/monsters/huge_ones/dragon/flames/initialflame.wav

It would end up like this:

trunc/initialflame.wav

Just be aware of this limitation when you build your PAKs, and you'll  be  fine.
Also  note that because of the way this works, empty directories will NOT appear
in the PAK.

@endnode

@node AQUA "The AQUA Project"
@endnode