.pk3

.PK3 files are used in games based on the Quake III engine. They are just simple ZIP files that have been renamed to have the file extension ".pk3" instead of ".zip". (For this reason and overall security improvement, Windows users are urged to turn the display of file extensions on. In any file explorer window, go to the "Tools" menu, select "Folder Options". At the top of that new window, click on "View" and then scroll down until you see the option "Hide extensions for known file types". Turn it off and click "Ok" at the bottom of the window.)

.pk3 files can contain any game assets like weapons, textures, music and so forth. They are just containers for more files. .pk3 files can be created/opened with any archive program that supports the ZIP file format. There are also programs specially designed to create .pk3 files (like for example pakscape), but they are not necessary to make a proper file.

The most common use of .pk3 files in the Tremulous world is to store/distribute game maps.

A map .PK3 file contains the map, textures, sounds, shaders, the arena file, and the levelshot which is displayed while the map is being loaded. (also see File Extensions)

File Names and Uniqueness
It is important to know that, on program start, the Tremulous clients read the content list of all .pk3 files that are in the game's "base" folder(s) into a list that is held in memory. The file "map-atcs-1.1.0.pk3" file, for example, contains the standard folder "maps" which contains the file "atcs.bsp". The bsp file is the actual 3D map environment in which you play. This ("atcs") is the real name of the map that you can use with the /map command. The long name "A.T.C.S.", which is displayed in the map vote menu and in the map list you see when you create a server, is not the name of a file. The long name is created by the arena file which is stored in the standard folder "scripts" of this .pk3 file.

All of these files are known to the Tremulous client when it starts. But there is a catch: Because of the .pk3 approach to file storing, it is possible to have a file with the same path and name existent several times. The Tremulous client will "forget" the previous occurrences of a file once it encounters another file with the same path and name. This is the reason that you might have .pk3 files with names like "zzzchristmastextures.pk3". This example would be a file that is explicitly designed to override existing textures with new ones, therefore a name was chosen that would be dealt with after most other files.

'''You have to keep this file behaviour in mind when you create a map. You have to choose unique names, or your maps will cause trouble or get into trouble with other maps. This is also especially important for a newer version of your own map: You cannot expect people to delete all older versions of your map from their servers and game computers, so when you release a newer version of a map, the changed files (e.g. the shaders) MUST have a different name.''' One way to deal with this is to add the version number of the next map release to the new file that you add to your map. So, if your next map release will be "mymap_003", the texture you add now into your map could have the name "brickwall_003.jpg" to ensure that you stay compatible with your own creation. This does not mean that the file is meant to be valid only for release 003. It is meant to say that this file was added to the map between release 002 and 003. If you change this file between release 005 and 006, you would delete the ..._003.jpg and name the new one ..._006.jpg. Obviously, you would have to replace all occurrences of the old version of the texture in your map with the new one, but that's not as much work as you would think: Make a backup of your .map file, open the original map file with a text editor that has a "search and replace" feature, and use it to swap the old texture name for the new one. It's really that simple. (It might be even simpler: In NetRadiant's texture browser, there is a "tools" drop down menu with the function "find/replace". That might do the trick, but I never tested it.)

The uniqueness problem is even more complicated: The shaders contained in the shader file(s) also create entries in the Tremulous clients' temporary file list. So, this list is not just filled with the content lists of the .pk3 ZIP files but also with the content of all found shader files. The first shader in the file "atcs.shader" in the "scripts" standard folder inside of the atcs .pk3 file, for example, is called "textures/atcs/skybox_s". This means that the short shader description text that follows underneath this name will be handled as if it were a real existing file called "skybox_s" stored in a real folder "atcs" in a real folder "textures", even though none of these really exist. They only exist in the .pk3 file. '''If any other .pk3 file contains a shader file with a shader named "textures/atcs/skybox_s", it will interfere with the atcs map. You really have to make sure that you choose proper directory and file names, even though these files are only virtual.'''

So, when you change a shader from one map release to the next, you would have to deal with that just in the way that you deal with a texture update - as described further up. Give them version names. And replace the occurrences.

''Actually, I don't know if the shader files themselves do also have to have unique names. Theoretically, the client would read all shader files in all .pk3 files and would add the contained shaders to the file list in memory. So, the shaders themselves definitely have to be treated with the described uniqueness thinking. Maybe the shader files themselves can have the same name, for example from map release to map release, even if they change. I don't know. But there's nothing wrong with playing it safe. Changing a shader file name does not even require you to change anything in the map, so better safe than sorry.''

The root directory that the Tremulous client uses to think about these directory and file names is the "base" folder of the Tremulous installation. There can be multiple "base" folders, for example one in the installation folder and one in the user data folder.

The files and folders found in the .pk3 are used by the Tremulous client as if they were really existing, and so it is no surprise that you can have real existing "textures", "maps", "sound", "scripts", "env" etc. folders in your "base" folder. And, just like in the .pk3 files, you would have subfolders in your physical "textures" folder named like the maps those textures are an asset of.

These physically existing folders (which are not existing in a fresh Tremulous installation but which can just normally be created by you) actually are the source of all those .pk3 files that you meet on the Internet: Someone made a map and then copied all physically existing files from the really existing folders (like "textures"), but only the ones needed by the map, into a separate temporary folder tree, upholding the original directory structure and the file names. Then they created a .zip file from this temporary folder tree (whereas all the mentioned assed folders must be directly in the root of that .zip file), and then they renamed it to .pk3 - that's really all there is to it!

While we're at it: If you make a .pk3 file, you should properly test it. This means: Delete the file "data-radiant-1.1.0.pk3" from your base folder(s). Also, delete all non-standard maps from your base folder(s) - only leave the ones that came with the original Tremulous 1.1.0 installation (arachnid2, atcs, karith, nexus6, niveus, transit, tremor, uncreation). Copy your new .pk3 into the base folder. Start the Tremulous client and try to create a server choosing your new map from the map list. Look around if you see missing textures. Missing textures are usually easy to recognize: They are grey with a white square grid. Check for missing sounds: If you start a lift which uses a missing sound file, an error message is temporarily displayed on your game screen and stored in the console text buffer.

If you really want to make sure that your test is proper, you'd want to rename your asset folders (textures, sound, ...), too. The files in those folders should be ignored automatically if your client is set to sv_pure=1, but it's simple to create a batch file that renames the folders.

Map PK3 Name Conventions
The .pk3 file should have a name like this: "map-atcs-1.1.0.pk3". It consists of three parts plus the file extension. The parts are separated by a "-". The first part ensures that all the map files in one folder stay together alphabetically, also it tells a human reader that this file is a map which is helpful because a .pk3 file can contain any game asset, not just maps. The second part is the name of the map itself. It should be perfectly identical to the name of the actual map file in the .pk3 (but without the .bsp extension). The third part tells the Tremulous version for which this map was designed. This does not refer to the Tremulous client version but to the actual Tremulous rules and behaviours that are used. You are probably aware that Tremulous 1.2 is in the works. Some changes will affect the way old maps play. The battlesuit, for example, is slightly taller, and so it does not fit through small openings that the 1.1.0 battlesuit would have fit through. A "1.1.0" in the name does not mean that the map will not work with later Tremulous versions. It just expresses which version the map authors had in mind when they made the map.

Choosing a good map name is of course very tricky. You should definitely stick to the name that you chose once you have had a public release of the map. Also, as said, you should keep the name of the .bsp file (which is the map itself) and the second part of the .pk3 file name perfectly identical.

The problem of name uniqueness can easily be overcome if you decide to add an author name to the beginning of each map name. Sadly, no one does this, so the global map name space probably has at least five maps called "reactor" or "spacestation". If you have a player or forum name like "j4ck", why not use this as part of your map names? This would also keep all your maps alphabetically in one place in the map repositories that hold hundreds of maps. Your map distribution file would be called "map-j4ck_spacestation-1.1.0.pk3", the map file itself (in the "maps" folder of the .pk3) would be called "j4ck_spacestation.bsp". Definitely use "_" and not "-" to separate these multiple parts.

A file name like "map-j4ck_spacestation_003-1.1.0.pk3" (The 003 is for the release version.) might seem very complicated, but the Tremulous world deals with many files from many people, and so we have to keep it somewhat systematic.