Mission Filestructure: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
Line 209: Line 209:
== maps ==
== maps ==


as stated in preamble
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                                          //dmap output (richard gere and lemmiwinks).
/maps/levelname.aas32                                        //required to play game
/maps/levelname.cm 
/maps/levelname.map 
/maps/levelname.proc
/maps/levelname.script   


;../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 ==
== materials ==

Revision as of 18:20, 29 May 2017

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

/fonts/fontimage_<size>.dat
In the case that a custom font is to be used, <size> is in points (eg <24>), the .dat file is created from a standard .ttf zip archive renamed to .dat.
There is further reading and a font creation tool for Doom3 engine here: https://web.archive.org/web/20080705204959/http://www.q3f.com/q3font.html
It is still unclear how the .dds for fonts are packaged, or if they are even required for custom fonts.


guis

This one will require a few links to wiki pages that req. clarification. *messy, requires deeper links.


../guis
../custom_readable_slab.gui
Custom readable slabs (eg, signs w/decals, etc...)
.. /guis/mainmenu_briefing.gui
The main briefing screen. Can find extended version by Sotha via fidcal's (http://www.fidcal.com/DarkModContributions/guis/briefings/briefing_button.zip)
.. /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 well explained and require some knowledge of how not only GUI's work, but how they work 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

so many different - many wiki pages to link. Perhaps best to use general definition.


/materials
/materials/custom_ai.mtr                                              //material files for several
/materials/custom_light.mtr                                         //purposes, definition to include
/materials/custom_map.mtr                                             //new textures, light, game map,
/materials/custom_obj_lod.mtr                                         //models, fixes, behaviour, etc...
/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                         // I nicked this one as example of custom.mtr
/materials/models
/materials/models/darkmod
/materials/models/darkmod/decorative                                            //3DSMax / Blender / DR exported .ase files here
/materials/models/darkmod/category                                        //all ase requires definition through material (.mtr) and parent to (.skin).
/materials/models/darkmod/category/custom_model.ase  
/materials/models/darkmod/loot/custom loot model.ase  
/materials/models/darkmod/misc/system/skybox_model.lwo                             //lightwave model/mesh - references texture where? (unclear pointer) - 2D or 3D as with source vtf but to lwo instead? https://developer.valvesoftware.com/wiki/Skybox_(2D) / https://developer.valvesoftware.com/wiki/Making_3D_Skyboxes


this is out of sequence and without parent directory - needs double-check. These are materials/models/darkmod

/weapons/custom_weapon(nonplayer).lwo

possible child directory of materials that has lost structure in copy-pasta...

/levelname/custom_model.ase


md5

not getting into modelling - forums.

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


particles

link to particles

/particles/
/particles/customparticle.prt                                      //particle info - can be created
/particles/tdm_alter_existing_particle.prt                          //using in-game console


script

link to scripts


/script
/script/custom_ai.script                                          //script files here
/script/levelname.script
/script/tdm_ai_event.script
/script/tdm_custom_scripts.script  

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

link to sound shader article

/sound //sound shader replacement pointers

/sound/doorsounds.sndshd  
/sound/effects.sndshd  
/sound/footsteps.sndshd
/sound/music.sndshd
/sound/voices.sndshd  
/sound/effects/                                                //the sound files themselves
/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


strings

link to #str article


/strings/fm                                                     //each translation requires new                            
/strings/fm/de.lang                                              //repack. Game items must be named
/strings/fm/eng.lang                                             //#str or look-up-replaced using...
/strings/fm/es.lang                                             //i forgot the name...
/strings/fm/pyc.lang                                           //ebatc


textures

alternative to dds for non-alpha, simple texture


/textures                         
/textures/darkmod/                                                //new textures go here.
/textures/darkmod/custom texture.jpg                                     //normals and other maps must
/textures/darkmod/custom texture.tga  
/textures/darkmod/weapons/sword01.tga                                //be packaged as .dds - unclear on optimal dimension or resolutions (512x512 appears fine for tiling surface).
/textures/decals/                                                
/textures/decals/blood                                             //alpha channel. 24 or 32bit only - appears black / loses alpha transparency if not.
/textures/decals/blood/custom_blood.jpg                       // jpegs do not contain alpha channels, but appears to retain EXIF - possible intrusion risk via stegosploit [untested].
/textures/decals/blood/custom_blood.tga                       // even if game does not allow for intrusion, JS or other access of file may run, RAT, embedded.
/textures/decals/dirt/dirt/custom_dirt.jpg                          // malicious level design: https://conference.hitb.org/hitbsecconf2015ams/wp-content/uploads/2015/02/D1T1-Saumil-Shah-Stegosploit-Hacking-with-Pictures.pdf
/textures/decals/dirt/custom_dirt.tga                          // considering older engine, perhaps worth test for guard in VM.

levelname

alternate custom places

/levelname/customtexture.jpg  
/levelname/customtexture.tga  


video

/video/levelname_briefing.roq //format for in-game video (encoder: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip / decoder: https://github.com/i...client/cl_cin.c)

/video/levelname_credits.roq


xdata =

/xdata
/xdata/briefing.xd                                             //text only briefing - use gui for moving image, timed sequence, etc...
/xdata/levelname.xd                                              //readables data


the end