User Tools

Site Tools


fs:pk3

update cleanup breakdown

This article provides an overview of the usage of PK3s with Doomsday. PK3 is the recommended container format to use when creating addons for Doomsday that contain a lot of resources (hires textures, MP3's, models, etc.).

PK3 format

PK3 or PAK3 is the format used by quake_3 and is a uncompressed 1) data archive format that can hold any type of file with associated directory structure. As the format is essentially an uncompressed Zip file you can infact interchange the extension .zip and .pk3 with doomsday (or use both at the same time; for example the filenames MYPAK.PK3, MYPAK.ZIP, MYPAK.PK3.ZIP will all work with Doomsday assuming the above restrictions are observed).

Doomsday supports the PK3 (i.e., ZIP) format. Compression is allowed, but encryption is not. If you try to load an encrypted or password protected ZIP/PK3 file, you will get an error message.

PK3 files can be loaded using the -file option. For example:

  1. file some.pk3

will try loading some.pk3 first from the runtime_directory and then from the data directory.

A PK3 contains a set of files organized into directories (folders). When a PK3 is loaded, all of the files in a PK3 become virtual_files that Doomsday can access just like the regular files on your hard drive. The end result is the same as if you had unpacked the PK3 into your Doomsday base directory. (Don't worry, no actual unpacking is done.) For example, the PK3 could have the file Data\jDoom\Auto\Superb.wad.

For example, the PK3 could have the file Superb.wad and due to the automatic_file_mapping_in_pk3 it is relocated to =Data\[game]\Auto=. You can also put files manually into any virtual folder under the Doomsday root folder. For example a PK3 with the file =Data\jDoom\Mywad.wad= would put =Mywad.wad= into that location within the virtual file system so it can then be accessed as if it had been physicaly installed there.

When a PK3 is read by Doomsday the root folder of a PK3 is considered to be relative to the Doomsday root folder. This means that creating a PK3 with the file Readme.txt in the *root* folder is the same as if you had put Readme.txt in the Doomsday app folder.

PK3 files can be created with just about any ZIP program, such as WinZip. Just make sure all the files have the correct paths, or otherwise Doomsday may not be able to find them. PK3 files are the same as ZIP files; only the file name extension is different. This means you will be needing an archiving program like WinZip.

Creating PK3s

To create a PK3 in WinZip you must gather your DEDs, maps and such and make the corresponding folders for them in your desktop or documents, so if you have a ded for jDoom, you would make folders called “Defs\jDoom\”.

If you want to make the deds always play you need to make 3 folders. This is what the structure should be like: “Defs\jDoom\Auto\yourded.ded” for wads its: “Data\jDoom\Auto\yourwad.wad”.

Doomsday 1.8.6 introduced some exceptions to these rules. See automatic_file_mapping_in_pk3.

Now what you need to do is put it all in a PK3:

  • Highlight your folder “Defs” that you have made (which can be anywhere, I put it on my desktop).
  • Right click on the selected folder and go to the WinZip options.
  • Click on “add to zip file” this should launch WinZip.
    • Note: Compression can be used as of Doomsday 1.8.6.
  • When it says the name of the zip file and path, rename it to a .PK3 or just leave it as .ZIP.

Also make sure that all the little boxes are unchecked, click “add” now you should have a working PK3.

NOTE: Winzip will require you to pay if you wish to use it to create .zip files. There is a free alternative called 7zip. The only thing is you'll have to choose the option make it save the file in .zip format instead of its native .7z format.

Example

For example - you have a set of hires textures for jDoom that you want to put into a PK3 - In Doomsday textures are seperated into two places, textures (ie wall textures) go into =Data\[game]\Textures\= and flats (ie floor and ceiling textures) go into =Data\[game]\Flats\=.

So with that in-mind we need the following directory structure in a PK3:

CoolTextures.PK3
	Data\
		jDoom\
			Textures\
				BigDoor1.png
				Startan2.png
				---
			Flats\
				TLite6_1.png
				---

Tip: The root_folder of a PK3 is subject to a set of automatic file mappings which make building a PK3 easier. It may be that you don't need to use the full relative path in your PK3 as an automatic mapping will move the files to where they should go.

Snowberry metadata

If there is a file named info in the root of a PK3 package, snowberry will treat it as a metadata_configuration_file. This is equivalent to the info file in bundles.

See also

Footnotes

<references/>

1) Doomsday supports compressed PK3s since version 1.8.6.
fs/pk3.txt · Last modified: 2006-07-25 15:54 by skyjake