
Pakrat v0.92  by Rof (rof@mellish.org.uk)

24th May 2005

A program for managing Half-Life 2 BSP PAK archives

---------------------------------------------------


What is Pakrat?

Pakrat is a graphical replacement for the standard bspzip program, that allows you to
view, add, and delete files that are stored inside compiled HL2 map (.BSP) files.
This allows you to embed custom texture, sound, and model files into a BSP file. The
embedded files will be automatically loaded from the map when the map is loaded by the
game, and so you do not have to distribute the custom files seperately.


Who would use Pakrat?

Pakrat is only of interest to people producing new maps for HL2, HL2DM, and CS:S (and other
mods) that wish to use custom texture, sound, and/or model files in their maps. The
program is useless to HL2 players or anyone else. Pakrat only works with Source-engine
BSP map files.


Installation

Pakrat is a Java application, and so requires the Java Runtime Environment (version 1.4.2 
or later) to be installed. If you do not already have this installed, the Windows version
can be downloaded from the Java website:

http://java.sun.com/j2se/1.4.2/

it is a 10.X Mb download. 

Note: you may be required to restart your computer to complete installation of the JRE.
Note: Pakrat is a Java application, and thus won't work as an Applet in a web browser.
Note: If you already have a later version of the JRE installed, Pakrat will work fine.

Once Java is installed, Pakrat can be installed by copying the Pakrat.jar file to any
convenient folder, such as the /SourceSDK/bin folder.

Run Pakrat by double clicking on the Pakrat.jar file. If Java is installed properly, the
program will start. If you see a Windows "choose the program you want to open the file
Pakrat.jar" message, or a message that the Main Class cannot be found, try restarting
windows to ensure that the Java installation has completed.

You can also run Pakrat from the command line, with the command "java -jar pakrat.jar".
This method takes an optional parameter, the initial map file to load.

New features

These new features were added to version 0.9 of Pakrat:

*	Viewing a VTF (texture) file now shows a bitmap representation of the file.
*	Pakrat now accepts drag-and-drop of files from any Windows Explorer window
	 onto the Pak file list.
*	Adding a directory now adds all files in the directory, and recursively adds
	 the contents of any subdirectories.
*	Auto Scan searches for all external files referenced in the map file, and adds
	 them to the Pak if neccessary.


Tutorial - an example of using Pakrat

Say you have a compiled HL2 map, "test1.bsp". The map uses two custom materials, named
"bluewall1.vmt" and "bluewall2.vmt", and one custom texture file, "bluewall.vtf". The custom
files are located in the directory "/materials/blue" relative to the "hl2" base folder.

To insert the files, run Pakrat and select the "test1.bsp" map. A list of files already in
the map's pak archive will be shown (if the map uses env_cubemaps, and the "buildcubemaps"
command has been run in-game, the list may be quite long). Now press the "Add" button at
the bottom of the main window, and a file selector will appear. Locate the custom texures;
if you wish, you may add multiple files at once by using ctrl+click, and may select folders
to include all files in that directory. Press "Open", and for each file selected a message
will appear: Fix-up path to "materials/blue/XXXXXXX.XXX". Choose "yes" for each file, or
"Yes to All" to skip the dialog.

At the end of the file list, there should be now three new entries: "bluewall1.vmt",
"bluewall2.vmt", and "bluewall.vtf". The pathname of each file should be "materials/blue".
Now go to the "File" menu, and choose "Save BSP". The file selector will appear. Press the
"Save" button, and the "test1.bsp" file will be overwritten with a new version, containing
the custom textures.

The file "test1.bsp" now can be distributed. You may verify that the map contains the
custom textures by renaming (or deleting) the custom file from disk, and loading the map
in HL2. If the custom textures show properly, then they are properly embedded in the map
file. 

Note that, if you recompile the map, you must re-add the custom textures to the .bsp file.
For this reason, it is best to add the custom textures just before distributing the final
map file.

You may also add files to the Pak by dragging-and-dropping files from Windows Explorer, or
automatically determine which files need to be included in the Pak by using the Auto Scan
feature (see below).

Details of operation

On startup, Pakrat opens a small console window. This console shows what operation Pakrat
is currently performing, and shows any error message encountered, but can otherwise be
ignored.

Unless a filename was passed to Pakrat on the command line, Pakrat will present a file
dialog to choose the map file to open. Locate any HL2 map (*.bsp) file to load it.
Once the map is loaded, the main window displays a list of all files located in the map
file's Pak archive. This archive may contain many files. Usually, all HL2 map file contain
at least one file, "cubemapdefault.vtf". This is the default cubemap (environment map)
texture for the map, and is actually a low-resolution copy of the map's skybox.
If the map has been loaded into HL2 and the command "buildcubemaps" performed, the pak
will also contain texture and material files relating to reflective materials used in the
map, and for each env_cubemap present in the map.

The main window display is a table, with a row for each file in the Pak archive. The
columns of the table are:

"In" : This column contains a checkmark for files that are currently in the loaded map's
Pak. If you have added new files to the Pak, and not yet saved the map file, the new file's
In checkmark will be blank.

"Filename": This is the filename of the file, as stored in the Pak. This will be blue
for files that have been added to be Pak, but the BSP file has not yet been saved.

"Pathname": This is the filepath of the file, as stored in the pak. The path is usually
relative the current Game Root directory (see below). Note: All backslash characters (\)
are converted to forward-slash characters (/) in this field. This is what the game expects
to see.

"Size": This is the size of the file, in bytes.

"Type": This is the type of the file, as derived from the filename, as shown in this table:

      Extension		Type		
	.vmt		Material
	.vtf		Texture
	.mdl		Model
	.vtx		Model (vertex data)
	.vvd		Model (vertex data)
	.phy		Model (physics collision data)
	.wav		Sound

Above the file list is the menu bar. This has six menu items:

"Load BSP": This loads a new map file. Any unsaved changes to the current file are lost.

"Save BSP": This saves the current map file. All changes to the Pak file are written
to disk. The program will prompt for confirmation if an already existing map file is
choosen. If you save a map with the same name and location from that it was loaded, a
backup file (<mapname>.bsp.bak) will be created. 

"Preferences": This sets the current Game Root directory, and an option to always, never,
or to ask whether to perform path fixup (see below) when adding a new file to the Pak.

"Quit": This quits Pakrat.

"About Pakrat": This gives brief help information for Pakrat.

Below the file list are six buttons. If a file in the list above is selected, all 5
buttons can be used; otherwise, only the Add button is active. The buttons are:

"View": This views the contents of the selected file. Material (.vmt) files are displayed
as text. Texture (.vtf) files show a summary of the texture's properties (size, encoding
method, etc.), and a bitmap of the contents. Note that some texture files may contain
multiple frames or faces, and these can be viewed with the controls to the left.
Model (.mdl) files show a summary of the file and any material files referenced from
within in. Unrecognised files are shown as a hex dump or ASCII text.

"Edit": This allows the editing of the selected file's filename and path. This does not
affect the name, path, or contents of the individual file on disk, but changes the reference
to the file as stored in the map's Pak. Usually the only reason to change these values would
be to alter the stored path of the file (see path fixup, below).

"Add": This adds a file to the Pak. Note that by using shift-click or ctrl-click in the file
chooser dialog, you may add multiple files at once, and choosing a directory will recursively
add all files in that directory and any subdirectories.

You may also add files to the Pak by dragging-and-dropping from any Windows file window
onto Pakrat's file list.

Nothing is actually written to the map file until the "Save BSP" menu option is used.

"Delete": This deletes a file from the Pak. As for Add, the map file is not changed until
the "Save BSP" menu item is used.

"Save": This extracts a file from the Pak, and saves it to disk. 

"Scan": This opens the scan file window (see below).

"Auto":	This scans and automatically adds any used files to the Pak (see below).


Path fixup

Path fixup is necessary to allow HL2 to find the custom files embedded in the .bsp file,
when the .bsp file is loaded by the game. Say you are using a custom material for a HL2
map, located in the file:
"C:\Steam\SteamApps\<your steam username>\half life 2\hl2\materials\blue\bluewall1.vmt"
When HL2 loads the map, it first looks in the .bsp file's Pak archive, under the name:
"materials/blue/bluewall1.vmt". The "path" part of the file's Pak entry should thus be
"materials/blue". You can edit the entry manually (using the Edit button) to change this,
but an easier way is to use the automatic path-fixup. This can be done by setting the
"path-fixup on add file" option under Preferences to "Always" or "Ask" (to be prompted
for each file). If it is set to "Never", then path-fixup is not performed when a file
is added to the Pak.

Pakrat uses the Game Root directory setting (also on the preferences screen) to determine
the correct path during fixup. For a HL2 file, for example, the game root should be set as"
"C:/Steam/SteamApps/<your steam username>/half life 2/hl2" (note that this will vary
depending on where you installed Steam/Hl2). If you do not set the game root dir, Pakrat
will guess how to do fixup depending on the type of file you add: material and texture
files will have paths starting with "materials/", sound files with "sound/" and model
files with "models/". 


Scan and Auto Scan

Pakrat's Auto Scan feature searches the currently loaded BSP file for references to
external files that are used by the map. This includes the material files used to texture
the map geometry, any model (.mdl) files used as prop_statics and other entites, and any
sound files referenced in entities.

Auto Scan also recursively checks for files referenced by the files it finds. For instance,
a model (.mdl) file may refer to several material (.vmt) files. Each of these materials will
reference one or more texture (.vtf) files. Model files are also created with a number of
associated vertex and physics data files. Auto Scan checks for the existance of all these.

Auto Scan cannot work correctly without a Game Root directory being set, that is, the base
directory of the game the map is designed for (see Path fixup, above). If you have not set
this in the Preferences screen, Pakrat will attempt to guess the correct directory from the
filename of the currently loaded map.

To start Auto Scan completely automatically, load a map file and press the "Auto" button.
After a short pause, a dialogue showing the number of files found on disk. Press "Yes" to
add them to the Pak.

If no files are found, you may have not set the game root directory correctly. 

To run a scan manually, load a map and press the Scan button.  A new window will appear.
You can alter the Game Root directory to use by typing in the "Gamedir" box at the top of
the new window. You may also choose from the drop-down list of previous settings.

For example, the gamedir setting for a HL2 single player map should typically be:
"C:/Steam/SteamApps/<your steam username>/half life 2/hl2"
or for a CounterStrike:Source map:
"C:/Steam/SteamApps/<your steam username>/counter-strike source/cstrike"
Note that these setting depend on the disk location of your Steam installation.

Once you have set the Gamedir directory, press the "Scan" button to start scanning
the map for file references. After a short pause, a list giving the filename, path,
type, and location of all files referenced in the map appears.

Note: if you have made changes to the Gamedir or to the relevant files on disk,
you may press the "Scan" button again to rescan the map and update the list.

The location for each file may be one of four values, which are colour-coded:

In Pak (green):		The file is stored in the map's Pak.
In List (blue):		The file is listed in the Pak list, but the BSP file has not
			yet been saved.
On Disk (red):		The file isn't in the Pak, but has been found on disk by the autoscan.
Not Found (grey):	The file cannot be found in the Pak or on disk.


"In Pak" files are already saved in the map's Pak data. They do not require any further action.

"In List" files are listed in the Pak, but not yet stored in the BSP file. Once the current
map file is saved with the "Save BSP" option, they will be stored in the Pak.

"On Disk" files are not in the Pak, but have been found on disk relative to the currently
set gamedir (game root directory). These files may be selected by the checkbox in the "Add"
column to the right (by default, all On Disk files are selected after a scan).

"Not Found" cannot be found in the Pak or on disk. These files may be standard (non-custom)
files that are stored inside Steam's GCF files. Since Pakrat cannot read GCF files, it 
cannot tell if the file is missing or present. Note that custom files will show as "not found" if the game root directory is set incorrectly.

Once the scan is complete, all "On Disk" files may be selected by the checkboxes in the
right-most column (the "Select All" and "Select None" buttons may also be used). If any
files are checked, pressing the "Add Selected" button adds all checked files to the Pak.
(If you have set the "ask for fixup" option, a message box will appear for each file added).
After this, the map is automatically rescanned and all "On Disk" files should change to
"In List". Use the main window's "Save BSP" option to save the BSP file and write all files
to the Pak. 

The "Done" button dismisses the Scan window.

If a row in the scan window is selected, the "Reference" button opens a sub-window showing
the name, type, diskname (filename by which the file is searched for on disk), file
location, and how the file was referenced in the map (i.e. any files that referenced this
file).


Keyboard shortcuts:

Main Window:

Ctrl+L		Load BSP file
Ctrl+S		Save BSP file
Ctrl+P		Preferences screen
Ctrl+Q		Quit Pakrat

Alt+V		View file
Alt+E		Edit file parameters
Alt+A		Add file(s) to the Pak
Alt+Delete	Delete a file from the Pak
Alt+S		Save a file from the Pak to disk
Alt+C		Scan for used files
Alt+U		Start Auto Scan

Scan Window:

Alt+S		Start scan
Alt+E		Select all "On Disk" files
Alt+N		Deselect all files
Alt+R		Check references to current file
Alt+A		Add selected files to Pak
Alt+D		Dismiss scan window




