Mission Filestructure: Difference between revisions

Latest revision as of 17:02, 30 March 2024

This page lists the internal structure of TDM's mission .pk4 files, including file naming conventions, so that all files and folders are correctly packed.

There are also external links to further reading and useful files (eg, .roq video encoder).

Mission.pk4 filenaming

It is important to come up with a unique filename for your mission's PK4 file, as the filename is used by the in-game mission manager to distinguish the packages: it is best to choose a .pk4 name that has not been used by other released missions.

Furthermore, do not use international characters or symbols for the filename. Alphanumeric only (A-Z, a-z and 0-9).

Symbol _ (underscore) may be used if necessary, however be aware that using - (dash) or & (ampersand) will cause assets in def files to not load and will break your mission.

Please do not include version information in the filename (this is why there is a readme). Future updates must have the same filename to properly update via the in-game installer.

Mission .pk4's

../darkmod/fms/mymissionname_001.pk4

This is your mission file, containing everything required to play your mission.
All TDM missions must be packaged in a .pk4 file (a renamed .zip archive).
The contents of the PK4 resemble the folder structure as found in the main ../darkmod/ directory (eg, textures go into ../textures/, .def files go to ../def/).
The PK4 contains all the files needed to run the mission, and must comprise the minimum content, as below.

Required content of a .pk4

In order for the FM to be correctly installed and played, a .pk4 archive needs to contain, at minimum, the compiled maps (dmap output) and two text files:

levelname.pk4/maps/levelname.map
levelname.pk4/maps/levelname.proc
levelname.pk4/maps/levelname.cm
levelname.pk4/maps/levelname.aas32
levelname.pk4/darkmod.txt
levelname.pk4/startingmap.txt

The above example list of files is based on a mission called 'levelname'.: All instances of 'levelname' in the .pk4 must be renamed accordingly.

The two text files are needed to display your mission in the "New Mission" dialog of TDM's main menu, as described in the Startpack Mapper's Guide.

Internal Structure of a .pk4

What follows is an alphabetical list of all files and folders that might be found in an FM's .pk4, along with some description and with links to relevant internal wiki pages.

There are some links to external sites that might be of use or contain downloads for software required to create any custom or additional files (fonts, videos) for an FM.

If any associated external link is dead (especially to game-specific tools such as .roq encoder or font converter) - please report in the forum so that it might be updated.

It is assumed that ../ is the root of your archive (ie, "levelname.pk4") and all directory and file listing branches from this.

While certain folders may be used for other purposes, for organisation and ease of reference - maintaining the standard directory structure, working methodically, allows for easier internal reference and location of assets.

Text files

../credits.txt: Credit given where it is due.
../darkmod.txt: Mission title / pre-briefing intro, displayed on main menu (~50 words max).
../list.txt: This list.
../readme.txt: A readme file, that someone might read.
../startingmap.txt: Contains the name of your map (as described in Startpack Mapper's Guide).

dds

These folders contain texture maps for use in the mission. TDM has some particular requirements for including custom .dds, that can be found on the .dds creation guidline page.

There is no stated optimal resolution for textures. 512x512 appears decent for most tiling or repeating patterns.

../dds/: ../dds/textures; ../dds/textures/darkmod; ../dds/textures/darkmod/custom_texture.dds; ../dds/textures/darkmod/decals/; ../dds/textures/darkmod/decals/custom decal.dds; ../dds/textures/darkmod/decals//building_facades; ../dds/textures/darkmod/decals//building_facades/levelname_eg.window.dds; ../levelname/customtexturemaps.dds

def

Entity definitions are predefined spawnargs, used in the creation of, eg, custom loot. A more complete list of values to use might be found here.

Please remember that using - (dash) or & (ampersand) in the directory structure will cause your mission to break when the .def's are loaded by the game.

../def/: ../def/custom_AI_head_and_skin.def; ../def/custom_AI_inc_props.def; ../def/custom_npc_model_inherit_custom_ai.def; ../def/tdm_ai_custom_ai.def; ../def/tdm_lod_custom_level_of_detail_for_model.def; ../def/custom_loot_001.def

env

This folder serves to contain the environment for any custom skybox other than the default prefab.

../env: Contains the custom skybox.
../env/custom: The tutorial for creating which can be found here.

fonts

A FM can provide a new custom font (typically, for inclusion in a readable), or override an existing one. See Font Files for the directory structure and files involved. This will be rare in practice, outside of specialized font-testing FMs, because of the effort involved in font development.

guis

This one will require a few links to wiki pages that req. clarification. *messy, requires deeper links. Some guis requiring only .tga may be also located in ...dds/guis, for unknown reasons (compression?)

../guis

../custom_readable_slab.gui: Custom readable slabs (eg, signs w/decals, etc...)
../guis/mainmenu_briefing.gui: The main briefing screen. See this wiki page for advanced versions.
../guis/mainmenu_custom_defs.gui: This file might contain many variable and adjustments to windowdefs, also to enable the game shop / [item] persistence over campaign / advanced briefing & debrief (success screen) / start points / replacement/music[voiceover] / video (wiki documentation). *incl. links to wiki docs.; May contain many #define or #undefines, "set [on windowdef]", etc... that might be found inside TDM's basefiles (inc. "success" that constitutes the debriefing screen).
../guis/assets: Contains GUI assets
../guis/assets/briefingX.tga: The default TDM briefing background.
../guis/assets/generic_loading_bar1.tga: Standard loading bar.
../guis/assets/levelname_loading.tga: The loading background. Can be changed through altering mainmenu_custom *incl. wiki links.
../guis/assets/next_arrow.tga
../guis/assets/previous_arrow.tga
../guis/assets/stop_cross.tga: These are the default GUI interface arrows, can be altered, referred from mainmenu_briefing.gui. *links

../guis/assets/game_maps/map_of_levelname.tga: This is the in-game map for a player to use. In-game map creation
../guis/assets/game_maps/map_of_levelname_icon.tga: The inventory icon for the in-game map for a player. *link

../guis/hud
..In-game HUD changes are not (yet) well explained and require some knowledge of how GUI's work - specifically in TDM.
../guis/hudcustom_hud.tga
../guis/hud/inventory_icons
../guis/hud/custom_inv_item.tga: Here is where any custom objects inventory icons may be placed (eg, special loot or items).
../guis/map/levelname.gui: This is where custom loading screens, loading tips, changes to any of TDM's windowdefs #define / #undefine, etc... are set *insert wiki links for custom background, loading tips, etc... there is no page on def/undef nor set for adjustment of windowdef to change this in mainmenu_custom.gui.

This section is not well documented and the information is fragmented throughout the wiki, with little explanation as to how it might work, copy-pasta.

splash

../splash/levelname_loading.tga: .. splash (loading screen) for TDM levels, dimensions are 640x480 for images or 512x512 for videos, auto-scaled.

map

A subdirectory of GUIS that requires special attention - it is the ingame map for players

..guis/map
../map/map_of_levelname.gui: This is required (along with the inventory icon, if necessary), for a player to have an in game map - the details may be found here
.. /guis/assets/game_maps/map_of_levelname_icon.tga: .. The inventory icon for the in-game map for a player. *link req. re: custom inv. icon/model

lights

../lights/custom_light_colour.tga
../lights/custom_light_nocolour.tga: .. Custom light shaders point here (tga contains alpha channel for transparency).

maps

These are the required output from Dark Radiant and TDM's DMAP of the .map file, in order to play your level, at minimum. Please note MAPS not MAP.

../maps/levelname.aas_rat
../maps/levelname.aas32
../maps/levelname.cm
../maps/levelname.map
../maps/levelname.proc

../maps/levelname.script: If the FM contains scripts - this file is required.

materials

Material Files are parent and child to many other files in TDM, without them, textures, sounds, models, skins and others will not be defined correctly. Please read the basic articles regarding the creation of the specific type of material file required.

What follows are example material files (.mtr) that cover a vartiety of different things that might be included in an FM, from lights, sounds, AI to models, to fixes, to textures, to skyboxes. These files are important, so they are worth reading up on in order to understand the relationship between eg, .mtr and .dds, .skin and .ase, if - for example - including a new model in your FM.

../materials
../materials/custom_ai.mtr
../materials/custom_light.mtr
../materials/custom_map.mtr
../materials/custom_obj_lod.mtr
../materials/frobhighlight_textures_example.mtr
../materials/ghost_collision_draw_fix.mtr
../materials/levelname (new textures.surfaces).mtr
../materials/levelname_light_textures.mtr
../materials/levelname_textures (modified textures).mtr
../materials/levelname_video.mtr
../materials/stolen_AI_base_WS1ghost.mtr

For new models - it is important to compartmentalise for ease of navigation and organisation. The model files accepted are in .ase format. These may either be compiled in other software, or by using Dark Radiant's plugin-script to create an .ase from brush/meshwork completed in the programme. Exporting models From DR as .ase will reduce entity count, but will not inherit DR functions (ie, the doors and windows will no longer open). As mentioned elsewhere, all .ase models are definted through material files (.mtr) and must be parented to skin files (.skin) in order to inherit (eg, metallic/wood) properites and also texture.

../materials/models
../materials/models/darkmod
../materials/models/darkmod/decorative
../materials/models/darkmod/category
../materials/models/darkmod/category/custom_model.ase
../materials/models/darkmod/loot/custom loot model.ase
../materials/models/darkmod/misc/system/skybox_model.lwo: If creating a skybox model in this way, it is important that it is an .lwo and not as mentioned in the more simple tutorial above (.env).
..materials/weapons/custom_weapon(nonplayer).lwo
../levelname/custom_model.ase: To remain organised and for future reference, it is advisable to create your directory structre around your "levelname" and not dump all files into "custom".

md5

.md5 is the mesh and bone depot for character animation for Doom 3's models. http://tfc.duke.free.fr/coding/md5-specs-en.html For help with this, if not already known, it is best to ask in the forums if wishing to include custom characters.

../md5
../md5/chars/body/npc/custom_npc_body.md5mesh
../md5/heads/npc/custom_npc_head.md5mesh

particles

Particles are textures with special properties. They might be edited using the Particle Editor, where it is possible to affect shape, time, size and gravity. Particles are affected by the world axis. It is possible to create custom particles, although these must be saved according to the instructions in the aforementioned, relevant articles.

../particles/: ../particles/customparticle.prt; ../particles/tdm_alter_existing_particle.prt

script

Scripts affect many functions in TDM. Events, actions, AI, mechanics, movers, conversations, etc... Unfortunately, scripting is not currently well documented outside of specific areas.

The best place to find answers to scripting questions is using a contextual search of the wiki or posting in the forums. Basics for TDM scripting appears in Python for mappers, although there are some elements of c# used in certain instances. Officially, similar to C++.

An intro to scripting can be found here: http://wiki.thedarkmod.com/index.php?title=Scripting_basics And a reference to all scripts pulled from the game here: http://wiki.thedarkmod.com/index.php?title=TDM_Script_Reference

These scripts are most often called using triggers in Dark Radiant. Objects are referenced with $name where "name" is the name of the object/entity. (eg, $player1).

The scripts for "levelname" (ie, your FM) are placed here:

../script: ../script/custom_ai.script; ../script/levelname.script; ../script/tdm_ai_event.script; ../script/tdm_custom_scripts.script; ../script/name_of_script_from_TDM_base_files <--- will be used in place of any script included in the game's base .pk4s (eg, tdm_alarm.script, found in tdmbase01.pk4, to change interval, delay, relighting torches, etc...).

skins

Skins are required to link textures to .ase models (placed in ../materials or ../md5), and also require material definition (../def). The creation of a .skin file and process of application in DR through the entity inspector can be found here.

~~skins tutorial is bookmarked for clear-up~~

Process is similar to Quake: http://www.misfitcode.com/misfitmodel3d/olh_quakemd3.html#textures

../skins: ../skins/custom_ai.skin; ../skins/custom_loot.skin; ../skins/custom_obj_model.skin; ../skins/tdm_replace_model_texture.skin; ../skins/texture for model.skin; ../skins/zombie_replacement.skin

sound

Sound shaders are required in order to play (custom) sounds in any FM. For more detail, see the wiki article.

The standard format is .ogg and these are defined by the .sndshd files, althought it appears .wav is also acceptable (although these files are much larger in size).

It is possible to #undefine (or set windowdef) those sounds default to the game and #define custom sounds through TDM's .gui's.

../sound: ../sound/doorsounds.sndshd; ../sound/effects.sndshd; ../sound/footsteps.sndshd; ../sound/music.sndshd; ../sound/voices.sndshd

These are the sound shader files that point the game to the correct .ogg files

../sound/effects/: ../sound/effects/custom.effect.ogg; ../sound/effects/footsteps; ../sound/effects/footstepscustomstep.surface.ogg; ../sound/effects/music; ../sound/effects/musiclevelmusic.ogg
../sound/effects/voices: ../sound/effects/voices/charvoice.ogg; ../sound/effects/voices/conversation.ogg

Again, it is useful to compartmentalise sounds for the sake of organisation.

strings

Strings can be very useful in the creation of in-game text, to facilitate changes and also transation of the FM into other languages. Instead of having to change every single readable that is created, using #str_xxxxxx from a single file, as noted in the article, it is possible to change the readable into languages other than English with greater ease.

For more information on how this works, please read Internationalization.

These strings - the .lang files - are contained in an additional .pk4, eg "levelname_i18n.pk4" that would be contained in the same directory as "levelname.pk4".

It is also useful, outside of internationalization, for some scripting - as in such things as loading tips or "random" notes and readables.

../strings/fm

../strings/fm/de.lang

#str_20000 halo, wie gehts?

../strings/fm/eng.lang

#str_20000 hello, how are you?

../strings/fm/es.lang

#str_20000 hola, como estas?

../strings/fm/fr/lang

#str_20000 salut, comment ca va?

../strings/fm/pyc.lang

#str_20000 privet, kak dela?

Please remember that TDM's character input is a-z, A-Z and 0-9, without any interntational characters (except maybe Pycckii, that might require some offset: http://wiki.thedarkmod.com/index.php?title=Font_Conversion_%26_Repair#I18N_.28Internationalization.29) and the standard fonts do not accept international characters such as ñ or è.

DR's readables editor does not produce this convention as standard.

subtitles

This feature is introduced in TDM 2.10 and refined through 2.12

After you have created custom AI sound files (.ogg or .wav) that advance your story, you can also create corresponding English-language subtitles. See Subtitles for the files and directory structure involved.

textures

The textures directory serves as a depository for any texture files used in the FM that are not packaged as .dds. They contain no specular / bump / normal maps - they are merely flat textures.

Please remember, .jpg's contain no alpha channel and as such contain no transparency.

Anything other than 24 or 32 bit textures that contain transparency may appear to have black alpha channels, rather than transparent. 512x512px appears to be a decent resolution for most tiling patternage or surface texture.

Again, all textures must be defined by a materials file (.mtr) and/or .skin file (if applied to model), regardless of format. It is possible to compress .jpg and .tga files into .dds for smaller size and faster download.

../textures: ../textures/darkmod/; ../textures/darkmod/custom texture.jpg; ../textures/darkmod/custom texture.tga; ../textures/darkmod/weapons/sword01.tga; ../textures/decals/; ../textures/decals/blood; ../textures/decals/blood/custom_blood.jpg; ../textures/decals/blood/custom_blood.tga; ../textures/decals/dirt/dirt/custom_dirt.jpg; ../textures/decals/dirt/custom_dirt.tga

EXIF data is retained in these files.

Nb, structural organisation for ease of future reference.

levelname

If there are very few additional files, there is no reason to not simply place them into a single directory.

../levelname/customtexture.jpg

../levelname/customtexture.tga

However, most files are required to be placed correctly in the directory structure (so the game knows where to look by default) and to prevent a "custom" folder becoming cluttered.

video

If you wish to include a video briefing or debriefing, these files are placed here.

TDM uses .roq format for its videos (512x512 is a good starting resolution).

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip [now 404'd] - instead use roq.exe from elsewhere and follow tutorial: https://jkhub.org/topic/2718-creation-of-roq-files/ or use this to convert an AVI file: https://jkhub.org/tutorials/article/26-creating-a-roq-video/

The decoder here: https://github.com/id-Software/Quake-III-Arena/blob/master/code/client/cl_cin.c

There is additional information and ffmpeg available in this thread: http://forums.thedarkmod.com/topic/12607-converting-avi-to-roq/#entry254712

../video/levelname_briefing.roq
../video/levelname_credits.roq

xdata

Xdata files (.xd) contain text-only readables information (eg, the briefing and in-game notes and letters).

For moving image, timed sequence or video briefings, please see the relevant articles on how to configure the .gui's for this.

../xdata: ../xdata/briefing.xd; The text-only briefing.; ../xdata/levelname.xd; All readables data (either #str, if you choose this or plain-text if otherwise or using readables editor).

Conclusion

This page contains the directory tree of a complete and full .pk4 for a mission for TDM. It is not expected that all files would be used - as the wiki develops, it is hoped that more links to pertinant information will be inserted in the relevant sections for futher reading on each subject.

The page merely serves as a reference and index, collecting links and data that might otherwise be fragmented or more easily overlooked.