How to pack your Mission: Difference between revisions

Latest revision as of 14:39, 15 April 2023

This article describes how to pack The Dark Mod missions into so-called PK4 files for release.

Mission PK4s

Each TDM mission must be packaged in a PK4 file (a PK4 is just a renamed ZIP archive). The PK4 contains all the files needed to run the mission, including map, cm, aas, proc files, textures, models, scripts, defs, xdata, etc. The contents of the PK4 resemble the folder structure as found in the main darkmod/ directory: textures go into textures/, .def files go to def/ and so on.

At the very minimum, a PK4 archive needs to contain the compiled map and two text files:

maps/outpost.map
maps/outpost.proc
maps/outpost.cm
maps/outpost.aas32
darkmod.txt
startingmap.txt

Easy to see, the above example list of files is based on a mission called outpost. The two text files are needed to display your mission in the "New Mission" dialog in TDM's main menu. See their description below.

Choosing a PK4 filename

It's important to come up with a unique filename for your PK4 file, as the filename is used by the in-game mission manager to distinguish the packages: it's best to choose a PK4 name that has not been used by other released missions. Furthermore, don't use foreign characters for the filename, stick with the alphanumeric characters A-Z, a-z and 0-9. Please do not include version information in the filename, future updates should have the same filename to properly update via the in-game installer.

Internationalisation (I18N)

Comment from Geep, 2021: When the i18n string table was introduced, it was to allow quick translations, with the map and other assets unaltered. Nowadays, higher-quality translations usually require changes to the map and/or assets. Given that, the benefit of the string table to translators is modest. For mappers, it has non-trivial costs, in terms of effort, but particularly complexity and opacity when working in DR. So this section might be considered Optional.

To make it easier to translate your mission into different languages, you need to prepare it for this. The most important steps are:

Use #str_XXXXXX templates instead of hard-coded English strings for inventory names, readable texts etc.
Put the contents of the strings for the #str_XXXXX templates into strings/fm/english.lang
Seperate the content of your FM from the fan mission specific dictionaries.

More details can be found in the I18N main article.

darkmod.txt

The darkmod.txt file describes your mission in the TDM's mission selection dialog:

Title: #str_20000
Description: #str_20001
Version: 1
Author: angua & greebo

The description text mustn't be too long, be sure to check the length of the texts when testing the package in the mission installation dialog. As of TDM 2.0, version numbers are only used as whole numbers.

Starting with release TDM 1.01 it will be possible for missions to specify a "required version", so that missions which are built upon undead (for example) can specify in their darkmod.txt that it needs TDM 1.01 and upwards to run. If the mission installer encounters a version mismatch, a notification appears and TDM will refuse to install it.

You can specify another line after Version:

Title: The Outpost
Description: Break into a builder outpost to retrieve a gold ingot.
Version: 1
Author: angua & greebo
Required TDM Version: 1.01

The "Required TDM Version" string is optional, so existing missions still work of course.

Note: If your mission uses #str_XXXXX templates, the minimum required version becomes v1.07!

VERSION: The internal downloader can only handle integers. So, don't update from v 1 to v 1.1, go from 1 to 2.

startingmap.txt

This file holds the name of the first mission to load when the player selects "Start Mission". This is interesting for multi-map campaigns, but for a single-map mission just put the name of your map file in here:

outpost

Before creating the PK4

You should always perform a full recompile of your map. Delete the .proc, .cm and .aas* files and run a dmap command from TDM console. Make sure the dates of these files are making sense and no old files are floating around in your maps/ folder.

Creating your PK4

A good way to create your initial PK4 is to copy the compiled map files to a temporary maps/ folder and to zip them up. You can use any compression program capable of handling ZIP files, like 7-zip, WinRAR, WinZip, whatever (important: do not create files using RAR, 7z or any other format, only the ZIP format will be recognised). The zip file can have any legal filename - it doesn't have to be the exact mission name. Then rename its suffix to .pk4. It is better to have a name with all lower case letters, otherwise there can be problems under Linux.

Be sure that the maps/ folder ends up in the root of your ZIP. Then add the darkmod.txt and the startingmap.txt to the archive.

Removing unnec. files

Make sure that you do not accidentily pack backup files like "mymap.bak", "mymap_autosave.map" or other random files into the PK4. They just increase the file size, but are not neccessary for playing the mission at all.

The _i18n.pk4 file

From v1.07 onwards: Create another PK4 file and put the files from strings/fm in it, as well as any language specific assets like GUI backgrounds. At minimum this file must contain:

strings/fm/english.lang

The filename MUST be "yourfmname_i18n.pk4", e.g. for the FM with an PK4 of outpost.pk4, this file must be named "outpost_i18n.pk4".

In case you haven't added any custom models, textures or other assets (i.e. you're just using vanilla TDM assets), you're done here. Proceed with #Testing the PK4

Adding custom Assets

Any custom models, textures, def, xdata files need to be added to the PK4. Be sure to put the files in the exact same folder structure as found in the darkmod/ main mod folder. Example: .mtr files need to go to the materials/ subfolder. If you were to extract the PK4 file to the darkmod/ folder, the files would end up in the correct place (note: don't do this actually, you might overwrite existing files in the darkmod folder).

In the (hopefully) rare case your mission needs to overwrite existing TDM content (e.g. modify a DEF file present in the main mod to change a setting), just include the modified file in your PK4. The file in your PK4 will "overrule" the ones in the mod base when the mission is installed (this is what the fs_game_base and fs_game parameters are for: "game" content will overrule "game_base" content).

Be aware that replacing files containing definitions (def, mtr, etc.) could potentially render your mission incompatible with future versions of TDM, so 'try to avoid this where possible'. Sometimes it is necessary, however.

Warning

Do not package Darkmod.cfg or autoexec.cfg with your mission. Doing so will overwrite players' own config files, potentially cause their TDM installation to break!

Testing the PK4

Once created, add a new folder in your darkmod/fms/ directory and put the PK4 in there. Then start TDM, your map should be listed now in the list of available missions. Make sure to use a "good" foldername for your PK4, not conflicting with any existing ones and without spaces, special or foreign (=non-english) characters. Numbers are fine.

Install the mission and see whether it starts correctly.

Splash Image (optional)

When browsing through the mission selection dialog, a small background screenshot can be displayed in the menu. This file is named install_splash.tga and can optionally be provided by the mission creator. Just create a small 256x256 image (must be TGA format, DDS files won't work) and put them in your PK4, next to the startingmap.txt and darkmod.txt files. The loading code will find this image and extract it just in time for display in the menu.

FM Notes (optional)

It's possible to display a couple of lines as FM notes. Just add a file called readme.txt in the PK4. When this file is available, an additional button "Notes" will be displayed next to the "Install Mission" button. This is a good place to put acknowledgements and credits.

Distributing your Mission

Now that you have your distributable PK4 file, others can play your fan mission. For the next steps, see Your Mission - From Beta Testing to Release and Beyond.

@@ Line 1: / Line 1: @@
-{{important|headline=Note|text=This article is WIP.}}
+This article describes how to pack The Dark Mod missions into so-called PK4 files for release.
-This article should describe how to pack TDM missions for release, distinguishing between missions using just vanilla (unmodified official) mod resources and those adding custom content like textures, def files and/or modifying original TDM files.
+== Mission PK4s ==
+Each TDM mission must be packaged in a PK4 file (a PK4 is just a renamed ZIP archive). The PK4 contains all the files needed to run the mission, including map, cm, aas, proc files, textures, models, scripts, defs, xdata, etc. The contents of the PK4 resemble the folder structure as found in the main <tt>darkmod/</tt> directory: textures go into textures/, .def files go to def/ and so on.
-= What you should do in any case =
+At the very minimum, a PK4 archive needs to contain the compiled map and two text files:
-Regardless of whether your mission is using custom resources or not, you should always perform a full recompile of your map. Delete the .proc, .cm and .aas* files and run a dmap command from TDM console. Make sure the dates of these files are making sense and no old files are floating around in your maps/ folder.
-= Missions basing on vanilla TDM =
-If your mission is just using TDM resources (no scripts, no custom textures, no additional models, no new def files), the packaging process is rather easy. This guide assumes your mission is called outpost, so you're starting with something like this in your maps folder:
   maps/outpost.map
   maps/outpost.proc
   maps/outpost.cm
   maps/outpost.aas32
-First step is to pack these files into your PK4 file, which can be done with any program capable of handling ZIP files (PK4s are just renamed ZIPs), like [http://www.7-zip.org 7-zip]. Create a new maps/ folder somewhere on your hard drive and copy the above files into this folder. Let's suppose this is <tt>c:\temp\outpost\maps</tt>:
+ darkmod.txt
- C:\temp\outpost\maps\outpost.map
+ startingmap.txt
- C:\temp\outpost\maps\outpost.proc
+Easy to see, the above example list of files is based on a mission called <tt>outpost</tt>. The two text files are needed to display your mission in the "New Mission" dialog in TDM's main menu. See their description below.
- C:\temp\outpost\maps\outpost.cm
- C:\temp\outpost\maps\outpost.aas32
+=== Choosing a PK4 filename ===
-Navigate to the <tt>c:\temp\outpost</tt> folder and right-click the maps/ folder. Depending on your compression program you should find an option in the context menu to add the maps/ folder to some archive. Name or rename that archive to outpost.zip and check the contents: the maps/ folder should be right at the "top-level" of that archive (no outpost/ folder in that ZIP!).
+It's important to come up with a '''unique''' filename for your PK4 file, as the filename is used by the in-game mission manager to distinguish the packages: it's best to choose a PK4 name that has not been used by other released missions. Furthermore, don't use foreign characters for the filename, stick with the alphanumeric characters A-Z, a-z and 0-9.  Please do not include version information in the filename, future updates should have the same filename to properly update via the in-game installer.
+=== Internationalisation (I18N) ===
+''Comment from Geep, 2021: When the i18n string table was introduced, it was to allow quick translations, with the map and other assets unaltered. Nowadays, higher-quality translations usually require changes to the map and/or assets. Given that, the benefit of the string table to translators is modest. For mappers, it has non-trivial costs, in terms of effort, but particularly complexity and opacity when working in DR. So this section might be considered Optional.''
+To make it easier to translate your mission into different languages, you need to prepare it for this. The most important steps are:
+# Use '''#str_XXXXXX''' templates instead of hard-coded English strings for inventory names, readable texts etc.
+# Put the contents of the strings for the '''#str_XXXXX''' templates into '''strings/fm/english.lang'''
+# Seperate the content of your FM from the fan mission specific dictionaries.
+More details can be found in the [[I18N]] main article.
-Go ahead and rename that zip file to pk4. To make the package complete, you'll need to add two more files: '''startingmap.txt''' and '''darkmod.txt'''. Use your text editor to create these two files and place them next to the outpost.pk4 file. Their content looks similar to this:
 === darkmod.txt ===
 The darkmod.txt file describes your mission in the TDM's mission selection dialog:
+ Title: #str_20000
+ Description: #str_20001
+ Version: 1
+ Author: angua & greebo
+The description text mustn't be too long, be sure to check the length of the texts when testing the package in the mission installation dialog. As of TDM 2.0, version numbers are only used as whole numbers.
+Starting with release TDM 1.01 it will be possible for missions to specify a "required version", so that missions which are built upon undead (for example) can specify in their darkmod.txt that it needs TDM 1.01 and upwards to run. If the mission installer encounters a version mismatch, a notification appears and TDM will refuse to install it.
+You can specify another line after ''Version:''
   Title: The Outpost
   Description: Break into a builder outpost to retrieve a gold ingot.
+ Version: 1
   Author: angua & greebo
-The description text mustn't be too long, be sure to check the length of the texts when testing the package in the mission installation dialog.
+ Required TDM Version: 1.01
+The "Required TDM Version" string is optional, so existing missions still work of course.
+{{infobox|'''Note:''' If your mission uses #str_XXXXX templates, the minimum required version becomes v1.07!}}
+VERSION:  The internal downloader can only handle integers. So, don't update from v 1 to v 1.1, go from 1 to 2.
 === startingmap.txt ===
-This file holds the name of the first mission to load when the player selects "Start Mission". This is interesting for multi-map campaigns, but for a single-map mission just put the name of your map file in here: outpost.map.
+This file holds the name of the first mission to load when the player selects "Start Mission". This is interesting for multi-map campaigns, but for a single-map mission just put the name of your map file in here:
+ outpost
+== Before creating the PK4 ==
+You should always perform a full recompile of your map. Delete the .proc, .cm and .aas* files and run a dmap command from TDM console. Make sure the dates of these files are making sense and no old files are floating around in your maps/ folder.
+== Creating your PK4 ==
+A good way to create your initial PK4 is to copy the compiled map files to a temporary maps/ folder and to zip them up. You can use any compression program capable of handling ZIP files, like 7-zip, WinRAR, WinZip, whatever (''important'': do not create files using RAR, 7z or any other format, only the ZIP format will be recognised). The zip file can have any legal filename - it doesn't have to be the exact mission name.  Then rename its suffix to .pk4. It is better to have a name with all lower case letters, otherwise there can be problems under Linux.
+Be sure that the maps/ folder ends up in the root of your ZIP. Then add the '''darkmod.txt''' and the '''startingmap.txt''' to the archive.
+=== Removing unnec. files ===
+Make sure that you do not accidentily pack backup files like "mymap.bak", "mymap_autosave.map" or other random files into the PK4. They just increase the file size, but are not neccessary for playing the mission at all.
+=== The _i18n.pk4 file ===
+From '''v1.07''' onwards: Create another PK4 file and put the files from strings/fm in it, as well as any language specific assets like GUI backgrounds. At minimum this file must contain:
-Together with the PK4 file, the two text files make the package complete. Put these three files into your <tt>darkmod/fms</tt> folder and test it by selecting "New Mission".
+ strings/fm/english.lang
-= Missions with Custom Content =
+The filename MUST be "yourfmname_i18n.pk4", e.g. for the FM with an PK4 of outpost.pk4, this file must be named "outpost_i18n.pk4".
-'' TODO ''
-== Starting Situation ==
-This guide assumes that you already created your TDM mission with or without custom content.
-= Old Info =
+In case you haven't added any custom models, textures or other assets (i.e. you're just using vanilla TDM assets), you're done here. Proceed with [[#Testing the PK4]]
-An easy way to release maps is to provide a PK4 archive, which can easily be dropped into the mod folder.
+== Adding custom Assets ==
+Any custom models, textures, def, xdata files need to be added to the PK4. Be sure to put the files in the exact same folder structure as found in the darkmod/ main mod folder. Example: .mtr files need to go to the materials/ subfolder. If you were to extract the PK4 file to the darkmod/ folder, the files would end up in the correct place (note: don't do this actually, you might overwrite existing files in the darkmod folder).
-All your unique assets should be packed into an archive with the same directory structure as the main mod (ie, your map file should be in the "[archive name]/maps/" folder, materials go in "[archive name]/materials/" etc).  '''The archive must be a zip.  RARs will not work.''' (You can of course use WinRAR or other RAR archive programs to create an actual ZIP file, just check the correct option - the most important thing is that the file is in ZIP format).
+In the (hopefully) rare case your mission needs to overwrite existing TDM content (e.g. modify a DEF file present in the main mod to change a setting), just include the modified file in your PK4. The file in your PK4 will "overrule" the ones in the mod base when the mission is installed (this is what the <tt>fs_game_base</tt> and <tt>fs_game</tt> parameters are for: "game" content will overrule "game_base" content).
-You can name the archive whatever you want.  Once it is packed you just rename the zip extension to pk4.  So your archive will look like '''my_map_v001.pk4'''. The result can be dropped either in the darkmod directory or in the base folder of your Doom 3 installation.
+Be aware that replacing files containing definitions (def, mtr, etc.) could potentially render your mission incompatible with future versions of TDM, so ''''try to avoid this where possible''''. Sometimes it is necessary, however.
-Make sure that the packed folders are not contained within a top folder, otherwise Doom3 will not be able to find anything in it. It has to look like this:
+{{important|headline=Warning|text=Do not package '''Darkmod.cfg''' or '''autoexec.cfg''' with your mission. Doing so will overwrite players' own config files, potentially cause their TDM installation to break!}}
- maps/
+== Testing the PK4 ==
- models/
+Once created, add a new folder in your darkmod/fms/ directory and put the PK4 in there. Then start TDM, your map should be listed now in the list of available missions. Make sure to use a "good" foldername for your PK4, not conflicting with any existing ones and without spaces, special or foreign (=non-english) characters. Numbers are fine.
- textures/
- xdata/
-Please check this by extracting your PK4/ZIP into another location and see if the maps/ folder gets created in the correct position.
+Install the mission and see whether it starts correctly.
-== Overriding Default Dark Mod Content ==
+== Splash Image (optional) ==
-Files that exist outside of PK4s take precedence over the packed files. So, placing a tdm_player_thief.def file into your PK4 won't do anything, because the file in the "real" filesystem will override the one within the PK4. This situation might change by the time The Dark Mod is released, but I thought this might be worth mentioning.
+When browsing through the mission selection dialog, a small background screenshot can be displayed in the menu. This file is named '''install_splash.tga''' and can optionally be provided by the mission creator. Just create a small 256x256 image (must be TGA format, DDS files won't work) and put them in your PK4, next to the startingmap.txt and darkmod.txt files. The loading code will find this image and extract it just in time for display in the menu.
-If you need to override default Mod content (the tdm_player_thief.def might be one of the few occasions where this might be appropriate), the files must be extracted from the PK4, possibly overwriting the vanilla Mod files. So be sure to warn your users about this, as long as no dedicated Dark Mod loader is available (which again might be obsolete by the time the Mod is released).
+== FM Notes (optional) ==
+It's possible to display a couple of lines as FM notes. Just add a file called '''readme.txt''' in the PK4. When this file is available, an additional button "Notes" will be displayed next to the "Install Mission" button. This is a good place to put acknowledgements and credits.
-==Other considerations==
+== Distributing your Mission ==
-* Mission name file
+Now that you have your distributable PK4 file, others can play your fan mission. For the next steps, see [[Your_Mission_-_From_Beta_Testing_to_Release_and_Beyond|Your Mission - From Beta Testing to Release and Beyond]].
-* Readme
-* Briefing (may be included in Readme or maybe video?)
-* Requirements - essentials to be included such as 'not for sale', copyright etc. What should be in every readme. If any.
-* A guide to what is recommended in a good info readme?
+== See also ==
+* [[I18N]] - Internationalization main article
-[[Category:Editing]]
+{{tutorial-editing}}

How to pack your Mission: Difference between revisions

Latest revision as of 14:39, 15 April 2023

Contents

Mission PK4s

Choosing a PK4 filename

Internationalisation (I18N)

darkmod.txt

startingmap.txt

Before creating the PK4

Creating your PK4

Removing unnec. files

The _i18n.pk4 file

Adding custom Assets

Testing the PK4

Splash Image (optional)

FM Notes (optional)

Distributing your Mission

See also

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools