The DarkMod Wiki - User contributions [en]

A - Z Beginner Full Guide Start Here!

2019-03-01T14:45:12Z

Teh saccade: /* Folder Structure */

{{A-Z Beginner Guide TOC}}
'''''PLEASE NOTE: THIS GUIDE CONTAINS SPOILERS FOR THE "THIEF'S DEN" DEMO MISSION RELEASED JAN 18TH, 2008.'''''

Mappers might also be interested in Sotha's excellent video tutorial showcasing the creation of a small mission from start to finish: [https://www.youtube.com/watch?v=gem2sHGhfZE Let's Map With Sotha]

Springheel also has a video tutorial showcasing how to speed up your mission-building using existing prefabs and modules: [https://www.youtube.com/watch?v=n9Bbp7fFljc Springheel's Speed Build Challenge]

== Introduction ==

Since writing this I've created a [[Startpack Mappers' Guide]] which is a ready made FM template with a set of ready made components to make it even easier to make a Dark Mod FM because it already includes things like objectives, briefing, readables, etc. etc and you just modify them and concentrate on building. However, I recommend you first follow this guide so you have some understanding of the basics and then the startpack will make more sense.

This is an easy guide for complete beginners to Dark Mod. It will lead you from start to finish, 'push that button, click that menu' and at the end you will have a fully working (but tiny) Dark Mod mission with all the main essential features including objectives all zipped up. You will be able to include variations of your own as you progress if you wish. Links to more detailed info is included but ignore those first time if you wish. Creating this mission is a learning process: although others will be able to play it, it will be too simple for that purpose - though it might be fun to see how varied the results might be from different players following the same instructions! When finished you can modify it and customise it to learn more or just shelve it for reference while you start your ''real'' mission!

This tutorial does not describe how to make your mission architecturally beautiful - just the opposite; the build may be as crude, quick, and ugly as you like. Nor does it advise how to design for good gameplay, etc. For that you should go to [[Mission Design Tips]] after you have mastered the basics. This is a ''method'' tutorial, not a ''design'' tutorial. Nor can it answer every question. It will merely present the most basic information for making a complete mission.

Feel free to experiment, add to, or even skip parts you already know or seem obvious, especially if you have a background producing Doom or Quake maps.

This guide was inspired by Komag's famous tutorial which helped a great many Dromeders (including myself) to get started producing Thief 2 FMs. If you are or were a Dromeder then you might first like to browse quickly through [[Dromed - Dark Mod Differences]] before proceeding - though it is not essential for this tutorial as I am trying to make few assumptions of prior knowledge. It will refer to default keys/mouse settings in Dard Radiant (editor - see later) so if you have changed any hot keys in Dark Radiant's help menu then keep that in mind. Also note that any screenshots might be in a different colour to your settings of course.

== Installation ==

This tutorial assumes that you have Dark Mod already installed. If not, please refer to [http://www.thedarkmod.com The Dark Mod] website for information.

Alternatively you can use the limited Dark Mod resources provided by the pre-release demo mission [[Thief's Den]]

== The Dark Mod Editor ==

To edit Dark Mod missions you will need a game editor. '''This tutorial is based on the [[Dark Radiant]] editor''' (hereinafter may be called DR) but you can possibly follow most of it in other editors like DoomEd. Variations might be shown where possible but it will mainly assume Dark Radiant. If you haven't got Dark Radiant yet, consult the [[Dark Radiant]] sections, install it and set it up how you like it. If you want to use DoomEd then you need to look elsewhere first. DoomEd of course is supplied with Doom.

You might wish to open the [[Dark Radiant Controls, Keys & Mouse|DR Controls]] page in a new window in your web browser for quick reference while following this tutorial. I'll try to make it so you don't need to!

Make sure you can run Dark Mod and your editor before proceeding. In particular remember you can undo your last step(s) (edit menu or {{key|CTRL}}+{{key|Z}})

== Folder Structure ==

[Added by Destined]
This section was added later and overlaps with the contents of the section "Dmap: Compiling the Mission"
* All main resources and executables are stored in the TDM root folder (this is where you have installed The Dark Mod, e.g. C:/Darkmod). The recources are stored in pk4-files. These are simply renamed zip-files and can be opened with any common unpacking program like Winzip, Winrar or 7zip.
* The "maps" folder is where Dark Radiant saves maps by default.
* All fan missions are stored in the "fms" folder as pk4-files. Upon installing a mission in-game, a sub-folder is created and the pk4-file as well as the readme.txt, the description file, and any savegames belonging to this mission are saved there.
* If you open a mission pk4-file (e.g. the Training Mission or Tears of St. Lucia), you can see the folder structure used for fan missions. It contains folders like "maps", "textures", or "materials", that you need for custom assets in your mission.
* Create a folder for your new map in "fms" and name it accordingly (e.g. Tut), then create a sub-folder "maps" and open Dark Radiant.
* With File->Select Game... you can open a window to configure basic settings (this might open automatically when you start Dark Radiant for the first time).
* For "Select a Game" choose "The Dark Mod 2.0 (Standalone).
* For "Engine Path" browse to the root folder of your installation (the path to the folder with your TheDarkMod.exe). (e.g. C:/Darkmod)
* "Mod(fs_game)" is the path to your current FM (e.g. fms/Tut). This path is relative to the given "Engine Path". You can leave this blank if you are not working on a FM.
* Now the editor will use resources you point to in this folder. Otherwise a pk4-package in the root folder would be needed.
* In order to have these new settings take effect, restart Dark Radiant.
* Save the blank file under fms/yourmapfolder/maps (e.g. fms/Tut/maps). It is recommended to choose a short name for your mission as you will type it a lot in the game console.
* An overview of all files possible to be included in a packaged mission, with a collection of links to other resources and appropriate wiki pages, can be found in the [[Mission Filestructure|Mission Filestructure]] entry.

== Your First Mission ==

Let's get started.

* Open Dark Radiant (hereinafter DR) and also open Dark Mod for quick testing.
* If you have a mission already open in DR then select File menu > New Map to clear it.
* Save it now as any suitable name. You might prefer to save later but I always do it immediately. All missions must go (with exceptions I will describe later in [[A - Z Beginner Full Guide Page 5#Managing your Mission Files|Managing your Mission Files]]) in the darkmod\maps folder or a folder within that. I urge you to create a new folder for each project within that maps folder. In this case:
# Open File Menu > Save As
# Make sure you are in the 'maps' folder.
# Select 'Create Folder' and type in say 'tutorial'. You might prefer 'Tut' or even 'T' because you have to keep typing it over and over in the Dark Mod console when testing!
# Select that folder
# Enter the name of your mission at the top.
* The game will be saved as a 'map' file with a .map suffix and is commonly called a 'map' in Doom circles. But I will use the term 'mission' or 'FM' (Fan Mission) or maybe 'game' for the map file to try to avoid confusion with actual 'city' or 'treasure' maps within the mission.

First, let's consider our rough storyline so we have some idea what to build...

== Story, Briefing ==

Formal mission objectives will be described much later in this tutorial. But before you begin your mission you will obviously need to have at least some idea of storyline and plot else you will have no idea what to build. You might have a detailed story or just some simple ideas which you can develop later.

Ultimately, you will need to brief the player with information about the story, characters, and the main purpose of the mission. It probably makes sense to write that fully when you are nearly finished the mission because new ideas or even technical difficulties might make you change your story. However, in this tutorial I'll describe it early so as you build the mission the layout and objects make sense.

Your briefing text should eventually be entered as described at [[Briefing]] but temporarily you might just write it in a plain text document for reference.

This mini tutorial mission is called 'Thief's Den' so here is an example briefing ('''not''' in correct format for the gui or .xd file):

"I had a nice haul the other night including a grand scepter from Lord Frothley. But a low-life named Creep who had given me the info, then stole it from ME! Never trust a thief I say. But I know where he lives...

I also still have his message in his own hand, giving the low-down. If I can dispose of Creep and drop the message nearby then he should take the heat for the heist diverting all suspicion from me.

Creep is a nasty piece of work who is handy with a blade. He can be dangerous and may be expecting me - may even have recruited a thug or two as back up - but he has badly underestimated my stealth skills..."

== Preparing to Build ==

When you open Dark Radiant it will default to a grid size (in the XYZ orthoview) of 8 units by 8 (changeable from version 0.9.5 onwards.) These [[Conversion of Game Units|units]] are 1.1 inches. Check your preference (default key P) in DR as it will be easier during this tutorial if you have the following checked (ticked) in Preferences > Orthoview...

* Show Grid
* Show Size Info
* Show Coordinates

'''Important:''' It is recommend you generally build with the grid set reasonably to a large size such as the default 8 or 16 for all walls, floors, etc. This makes alignment easier. You can reduce this in the grid menu for fine placement but don't leave it like that generally or you will have complexity problems. Snap to grid ([[Image:DRsnapGrid.jpg]], {{key|CTRL}}+{{key|G}}) will re-align a selection to the current grid size.

We'll mostly be working in the XYZ grid orthoview but if you have room for the camera view at the side so much the better. The camera view does a rough render in 3D (F3 toggles a better rendering with lighting etc but keep that off if it slows things down which it is likely to and just use it now and again.)

* Note the origin icon of the 'world' at 0,0,0 in the grid view
* Zoom in and out with the mouse wheel
* Right mouse drag the grid view to scroll around (zoom out further to scroll around faster)
* Use ''Change views'' tool ([[Image:DRnextViewBut.jpg]], {{key|CTRL}}+{{key|Tab}}) to toggle between top (XY), front (XZ), and side (YZ) views (you can open aditional windows using menu <tt>View > New XY view</tt>).

The blank windows in the grid and camera views can be regarded as empty void - the space in which we shall build. We have to build in bubbles sealed off from that void like an airtight spaceship or a submarine. Any gaps will cause leaks and crash your game so it's obviously the first major rule to learn: always build inner spaces sealed off from the outer void

Apart from special materials like water and weather, all the raw material you will use is 'solid' to form different shapes. So we can make panels and place them together to form lots of floating airtight boxes and these can be linked together. The entire game then takes place inside those boxes. One box can hold a tiny cupboard or an entire cathedral and a lot of boxes can hold a city. Inside those boxes you cannot see the void.

A shortcut to putting panels together is to make one solid block and hollow it out to form a box and this is what we are going to do now to form our first room.

== Making Your First Room ==

First we make a rough solid block...

* Select the top view (XY) in the grid view (toggle with [[Image:DRnextViewBut.jpg]]).
* Left mouse drag out a rectangle any few grid units across in the middle somewhere.
* This rectangle is called a 'brush' and used to define raw shapes for walls, floors etc.
* Left drag ''within'' that brush to drag the brush around
* Select the ''Resize'' tool ([[Image:DRdragResize.jpg]], {{key|Q}}).
* Now left drag ''outside'' that brush to resize it.

Now we adjust its top view area...

* Left drag outside that brush to resize it to 256 across left to right (X direction) by 192 up and down (Y direction in top view.) You should see those dimensions at the sides of the rectangle if you have 'Show Size Info' set in Edit > Preferences > Orthoview. The position of the top left corner is in brackets at top left.
* Left drag within the brush to move it so its sides fit on the bigger grid. If all sides don't fit then check your dimensions and that you are still in grid size 8 (see grid menu.)
* I prefer to build up in the top right corner from the world 0,0,0 so none of the values are negatives but you decide for yourself. Move it where you want but ideally so the sides are on the big grid.

Now we adjust its height to get our finished block (brush)...

* Use [[Image:DRnextViewBut.jpg]] ({{key|CTRL}}+{{key|Tab}}) to switch to side (YZ) or front (XZ) view and left drag outside the brush to change its height to 128
* Left drag inside the brush to move it up and down so its sides are on a big grid same as you did in the top view.
* You should now have brush 256 x 192 x 128 (see [[Conversion of Game Units#Tips|Unit Tips]])

<center>[[Image:AZblock.jpg]]</center>

== Selecting and DEselecting ==

We only have one item in our view but eventually many. Operations only work on what is currently selected. When you have just created something as we just have it is automatically the current selection and should be highlighted in your views (see DR Preferences for colour.)

* To DEselect it, point your mouse at it in either the grid or camera view and use {{key|SHIFT}}+{{key|ALT}}+{{LMB}} (or just press the {{key|Esc}} key.)
*To select it again, point your mouse at it and use {{key|SHIFT}}+{{key|ALT}}+{{LMB}} again.

Selecting is something you'll do a lot of so get familiar with that {{key|SHIFT}}+{{key|ALT}}+{{LMB}}. It's an exclusive select to get just one item. There are other selects I'll describe later. The {{key|Esc}} key always deselects and it is vitally important to get into the habit of DEselecting before you select or create something new or in some cases you will have multiple selections without knowing it and can delete or change something you didn't want to. This is why the {{key|SHIFT}}+{{key|ALT}}+{{LMB}} is the safest select as it is exclusive and will automatically DEselect anything else that was left selected. But it won't protect an item when creating. Yes, it is possible to have say a brush selected, forget it is selected, then create say, a new light. Oh! what happened to the brush? It's gone - replaced by the light. Develop a nervous habit of keep hitting {{key|Esc}} to deselect when you go to create!

From now on I'll use LMB, MMB, and RMB to refer to the mouse buttons.

== Camera View ==

You should be able to see this block in the camera view. If the camera view is just black remember {{key|F3}} toggles true light rendering and we don't yet have a light so hit {{key|F3}} to get a constant bright test light throughout. I won't go into details of all the camera controls suffice to say use the arrow keys and {{key|D}} and {{key|C}} to move vertically. But scroll down to 'camera' in [[Dark Radiant Controls, Keys & Mouse]] and you will see a fantastic amount of control you have in DR's camera view - especially with the mouse. It will take time to get used to them all so for now perhaps just learn enough to move around to see what you've done so far.

If you can see your block(brush) in the camera view then it is likely not to have any particular texture unless you were doing something before this tutorial. Close up you may see it is covered in a checkered blue 'shader not found' message. Don't worry if it's covered in something else like stone or wood though. Since it will eventually be hollowed out to form a room, let's paint it now with some material more suitable to the Dark Mod universe...

== Materials, Textures, Painting the Block ==

This is the tiny home of a cheap thief so we'll use some old stonework.

I've mentioned 'textures', 'shaders', and 'materials'; what do these terms mean? A 'material' or 'shader' is the properties of a surface, including (but not necessarily) texture, sound, and others. To 'paint' our block we...

* Select the Media Browser. This is one of the tabs on a panel. Pressing N or T hides/shows the whole panel but I guess most people leave the panel showing all the time and just select the tab they want.
* Allow a few seconds for DR to read in the media first time and then you should see 'textures' listed
* Click 'textures' and it opens up to show all available textures. Many of the ones you see are Doom textures. Scroll down and select 'darkmod' which reveals the ones most suitable for our use. Scroll down to stone, open it, then cobblestones and select blocks_mixed_multicolour. Right click it and select 'Apply to selection'. This covers all surfaces of the block because we have still got selected the whole block not just one surface. You should see this in the camera view. Use this throughout the house (and eventually on its outside surface for consistency.)
* Select the Texture Browser. This is one of the tabs on the same panel as Media Browser. The Texture Browser only shows recently used textures. You should see only the one texture you selected so it's handy for future use. Odds are you will want to re-use the same textures. It will also show other textures if you clicked on them in the media browser plus any others if you were using DR before this tutorial. You can also copy and paste textures onto single or multiple surfaces (see later.)
* Hover the mouse over the four little buttons at the top of the Texture Browser and read the text so you have some idea of what features are there for the future. For now, click on the one that says 'Flush and Reload Shaders' and it should clear all of them except the one we put on our brush. As we add others they will appear in the texture browser so you can get to them more quickly.
* Now, press S for Surface Inspector (or View menu)
* If you have only one face selected (more about this later) you can set Horiz and Vert scale. Value like 0.3 makes it harder for the player to see any pattern repetition (in this situation and in my opinion - use your own judgement with other textures and wall sizes.) In the mean time you can use arrow buttons to adjust the scale for the whole selected brush. Whatever scale you use, generally you should be consistent with it for the same texture wherever used in a mission. If you use copy and paste then it will transfer the scale as well which is far easier.
* There will be more on texture adjustment later in this tutorial.

== Hollowing out a Room from the Block ==

Building to a large grid size helps performance. The outside of our block will never be seen in the game. Once we hollow it out then the player will only see the inside so that is the surface that is rendered and that we need to align to the large grid. There are two tools to hollow out a block, both activated by a button on the left button bar: one called 'hollow' and the other 'room'. Don't use 'hollow' as it reduces the internal sides so they don't fit the big grid AND it overlaps the corners which can cause rendering errors like so....

<center>BAD!</center> 
<center>[[Image:AZhollow.jpg]]</center> 

Instead use the 'room' button which does the job right (note the increased size so the ''internal'' dimensions will be the same as our original block and align to the big grid... 

<center>GOOD!</center> 
<center>[[Image:AZroom.jpg]]</center> 

All brushes in Doom must be convex. They cannot have any inward angles (like an L shape which would have to be two brushes together) and cannot actually be hollow. The above tools really create new side panel brushes to replace the original brush. In the case of our six-sided block that is six new brushes positioned as walls, floor, and ceiling. ''The walls they create are one small grid line wide so their width will vary depending on your grid size setting.''

Examine the block in the camera view and zoom right inside so you can see it internally which is where it will be seen in game. Note the texture aligns nicely because we stuck to a big grid size. The stone is appropriate for all four walls (which is why I textured the whole block in one go rather than one surface at a time) but now we need different textures for floor and ceiling...

== Selecting and Texturing Individual Surfaces ==

'''You cannot select a surface in the grid view''' so move inside the room in the camera view.

'''To texture the floor...'''

* Press Esc to make sure everything is DEselected
* Point at the floor and use {{key|SHIFT}}+{{LMB}}. Repeat a few times and you will see it selects/DEselects the surface. Keep it selected.
* Select the Media Browser again (on the tabbed panel)
* In the darkmod section select say stone/cobblestones or maybe you would like some wood/boards/worn_01 ? You choose but something like carpet might need special alignment so stick with stones or boards maybe for now? Remember - RIGHT click the texture name and select 'Apply to Selection'
* Alternatively you can click on several possibles then select them with one LMB in the Texture Browser on the other tab. In the Texture Browser you can enlarge the textures if preferred to see them better.
* Esc to DEselect so you can see it better in camera view.

'''To texture the ceiling...'''

* Press Esc to make sure everything is DEselected
* Point at the ceiling and use {{key|SHIFT}}+{{LMB}} again to select its surface.
* Select the Media Browser again (on the tabbed panel)
* In the darkmod section select say plaster/plaster01 and apply it.

'''If you change your mind about the walls you can change them to something else...'''

* Press Esc to make sure everything is DEselected
* Point at one wall and use {{key|SHIFT}}+{{LMB}} again to select its surface.
* Point at another wall use {{key|SHIFT}}+{{LMB}} again so now both surfaces are selected
* 'Accidentally' select the ceiling. No problem. Just use {{key|SHIFT}}+{{LMB}} on it again to DEselect it but the walls are still selected. In this way you can select which surfaces you want to select.
* Select the Media Browser again and just apply another type of stone, perhaps brick, to the walls if you want or just leave it as it is.

Now press {{key|CTRL}}+{{key|S}} to resave the mission or use the File menu. Get into the habit of doing this often unless you have autosave set. Now and again you can also save with a new name so you can go back to an earlier one if you totally mess up. Note: There is also a backup file made automatically by DR.

== Adding the Player's Start Point ==

One more thing is ''essential'' to play this in Dark Mod and that is the Player's starting position.

* Press Esc to DEselect everything.
* In the TOP grid view, point the mouse in the middle of the room and RMB to get a pop up menu. This menu is important so glance at some of the other items on it while you're here. 'Entities' are special function items and the player start is amongst them but there is a shortcut on the menu so instead...
* Select "Create Player Start here" on the menu. This will create the playerstart entity (red box) and put it where you clicked. Drag the entity around to the point where you want the player to start.
* You should see an arrow on the red box indicating the way the player will face at the start. If you cannot see the arrow then menu <tt>View > Show > Show Angles</tt> will reveal it. You can rotate the player by selecting ''Rotate'' tool ([[Image:DRrotate.jpg]], {{key|R}}) and dragging with the mouse.
* Use {{key|CTRL}}+{{key|Tab}} to switch to the side view (YZ) and use LMB to drag the ''inside'' of the player start box so its base is on the floor of the room (you can also use ''Translate'' tool, [[Image:DRtranslate.jpg]], {{key|W}}). Make sure you do not go below or the floor or the player might be stuck with his feet in concrete! Tip: In Thief games it was common to start just dropping over a wall with this player start a few feet above the ground. You might note that entities do not directly resize like brushes so LMB dragging on the ''outside'' of the box does nothing (unless you have selected the ''Translate'' tool).
* RMB in the grid view again and you will see there is now a ''Move player start here'' option so you can quickly move its position while testing different areas of your mission. But always remember to check both the side and top view when moving things around, to make sure the vertical position is also valid. (Also note that ''Move player start here'' does not ''select'' the player start - you will need to select it if you need to adjust its position by dragging.)
* With the player start still selected you can select the Entity Inspector (on the panel, or {{key|N}} to hide/show it) and see the properties of your first entity.

The game could now be played but it will be totally dark so we need to create at least one light.....

== Creating a Light ==

* Press Esc to DEselect everything.
* In the TOP grid view, point the mouse in the ''middle'' of the room and RMB to get the pop up menu.
* Select "Create Light" on the menu.
* A large red box appears with diagonals representing the light's centre and its rough 'radius'. The default light is more like six pyramids pointing out to their peaks in the centre of each side of the box. This gives a rough impression of a sphere of light and helps performance.
* {{key|CTRL}}+{{key|TAB}} to get a side view and LMB drag ''right in the centre of the light'' to move it up/down to centre it in the room if it is not already. Just dragging inside the radius box won't move it - you have to point at the centre.

== Resizing a Light ==

Resizing a light is awkward because dragging any side moves the centre (this might be changed in a later Dark Radiant.) Two ways of dealing with this. Just roughly drag it about and keep moving the light back to where you want it. But if you have very precisely positioned a light then you don't want to have to keep doing that so this is what I do...

* Select the Entity Inspector on the panel
* You should see it has a light radius property with three values for XYZ for the three dimensions. They are north and south for Y, east and west for X, and up and down for Z. (those are the compass directions in game by the way.)
* Click on the light radius property to highlight it.
* Note that its values appear in a choice of inputs at the bottom - You can type new values in a line with a space in between then click the check(tick) button or enter them as separate values or even use the little scrolly buttons at the side and then click the Apply button.
* The room interior is 192 x 256 x 128 (in XYZ order) so give the light radius the values 200 260 133 so it protrudes outside the walls (we're setting radius - so the light diameter will be twice that size). We may well change this again later if we want the light to spill out through a doorway or something.
* You can now toggle light rendering in the preview using {{Key|F3}} (or an icon in the preview toolbar) to see how the light affects the walls.

The light radius is not just a cut-off point. It can be regarded as a 'fade to zero point'. What this means is that the light is at maximum brightness at its centre and fades to zero at the limit of the radius. So in a big open area, if you extend the radius you will 'stretch the brightness' further. Imagine the scale from max to min compacted in a small radius or expanded in a large one. More on this later when we place wall torches.

== Changing a Light's Brightness ==

The light may be a little bright. To change it...

* Press L (or View menu)* to call up the Light Inspector
* Click on the white rectangle button just below where it says 'Colour'
* The brightness value is called 'Lum:' (luminosity) and should default to 100. Reduce it to 90, by overtyping it or using the slider to the far right. It might not matter. I'm just showing you where the control is for now.
* Fool around with the colours if you want - there are extensive features I won't cover here.

Hey! We should have your first working mission! Do a {{key|CTRL}}+{{key|S}} to save it and then follow the next sections in Dark Mod itself not in Dark Radiant.....

== Sound ==

There is no need to do anything special about ''hearing'' sounds such as footsteps, collision sounds, etc. at this stage as it will work automatically. Adding custom sounds will be dealt with later.

== Pathfinding ==

Pathfinding data to tell the AI characters where they can move is created by dmap by default when compiling in the next section...

== Dmap: Compiling the Mission ==
* Your mission file cannot be played itself; it is simply the directions to create a game file. To do this...
* Start up The Dark Mod. From any Dark Mod menu go to the console. By default, the console is {{key|CTRL}}+{{key|ALT}}+{{key|~}} (US Keyboards) or {{key|CTRL}}+{{key|ALT}}+{{key|'}} (UK Keyboards). This key is the top left below Esc and to the left of "1" on all keyboards I believe. But most people set up a shortcut to just use the ~ (` in UK) on its own so:

For single key click to get the console:
In your desktop shortcut to TheDarkMod.exe add this argument to its properties (right click shortcut): '''''+set com_allowConsole 1''''' so the target line would be something like:

'''''C:\Darkmod\TheDarkMod.exe +set com_allowConsole 1'''''

(plus any other arguments you might want)
* In the console type and Enter dmap Tut/T001 where you should substitute your subfolder name for Tut and your mission filename for T001. So, if you created your mission file directly in the maps folder then you do not need a folder name and can put dmap T001. If you made a subfolder in maps called MyMaps and named your mission MissionImpossible999.map then enter dmap MyMaps/MissionImpossible999. I recommend you do not use upper case in filenames in Doom as I think it can cause problems on other platforms.
* Wait while dmap compiles the mission. This should only be a few seconds with this tiny mission but will be much longer for big missions.
* If you get a 'leaked' error or some other serious red warning then recheck your work; look for gaps in the wall or a wrong texture like nodraw or have you got an entity outside in the void? See [[Performance: Essential Must-Knows#How to detect and fix leaks|HERE]] for more about fixing leaks but at this stage of this tutorial it might be easier just to redo. What I have laboured over is basically make a block, texture it, hollow it, stick in a player start and a light. As you get more proficient you can do it in less than a minute.
* Assuming there were no dmap red "ERROR"s then you should be returned to the Dark Mod menus and are now able to play the mission.
* Return to the console.
* Type and Enter map Tut/T001. Tip: Press the up arrow key toggles back through the history of what you have typed before so your dmap should re-appear. Just press the Home key and delete the 'd'. An alternative is to use 'testmap' instead of dmap which does both dmap and map but I prefer to see dmap's results.
* You should now be able to walk around in the room. If you have a player shadow set then you might notice that walking through that light looks odd so keep that in mind for light placement. But most lights you will place close to a visible source like a gaslight or wall torch.

That's the first part done!

{{A-Z Beginner Guide TOC}}

[[Category:Editing]]
[[Category:Tutorial]]
[[Category:Mapping Tutorials]]

Stim/Response Editor

2018-03-06T01:20:33Z

Teh saccade: /* Stims */ subject caps consistency /sp.

= Stim / Response Editor =

The Stim/Response Editor was introduced to save typing each arg for every stim and response on the page, [[Stim/Response Key/Values]] that also contains more specific descriptions as to what each Stim/Response [[Glossary#Spawnarg|arg]] does.

For more general reading on stims and responses, please see also the pages [[Stim/Response]] and [[Stim/Response Key/Values]].

= Stims =

To add a Stim or Response to an entity, open the Stim/Response editor:
Select the entity and - from the menu bar - go to Entity > Stim/Response.
The Stim/Response Editor has three tabs: Stims, Responses and Custom Stims.
As stated on the [[Stim/Response]] page, an entity can have either or both Stims and Responses, but is not able to create a Response through a Stim fired on itself.

To add a non-custom Stim, select the "Stims" tab.
From here, it is possible to add a Stim from the drop-down menu next to the "Add" button, clicking the Add button and choosing a stim from the "Type" drop-down menu at the top ("Frob" being the default) or using a keyboard shortcut by pressing the initial letter of the Stim type you'd like to add.

Select the Stim to edit from the numbered list on the left.
If no Stim type is selected, all options presented on the right are greyed out.
The options on the right side of the editor allow changes to all key values of the Stim, removing the need to type and enter manually all key values as listed and described in [[Stim/Response Key/Values]].

= Responses =

The Response Editor is a simplified way to create basic scripts without need for deeper knowledge in scripting for TDM.
It works similar to the Stim Editor, but for adding Stims that will act as entity Responses.
In the Responses tab, the Stim to which the selected entity should respond is selected in the same way as the Stims tab.

However, this only tells the entity that it must show a Response to a certain Stim type. For a Response to happen, there must be an effect. 
To add an effect, right-click in the "Response Effects" window and press, "Add new Effect". 
Double-clicking the numbered Response (or right-clicking it and choosing "Edit") will open the "Edit Response Effect" box, in which it is possible to select the target entity, type of Stim (as args) and the Response effect itself.

== Available effects ==

* '''Activate Response:''' Activates the Response for the stated Stim Type on the stated Entity.
** E.g. the player must give a fire stim to a furnace in order to have a door react to a frob Stim.
* '''Activate Shooter:''' Activates the named Shooter entity.
** E.g. Can be used to activate a trap.
* '''Activate Stim:''' Activates the Stim for the stated Stim Type on the named Entity.
** E.g. Adds a damage stim to the furnace after a fire stim is given.
* '''Add Target: ''' Adds the stated Target to the named Entity.
** E.g. Add a new path_corner to a patrol route.
* '''Apply Stim:''' Fires a Stim of the stated Stim Type to the named Target.
** The Source can be changed, but is not necessary.
* '''Blind AI:''' Blinds the named AI as if a flash bomb has been used on it.
* '''Clear Targets:''' Removes all Target-args from the named Entity.
* '''Damage:''' Applies a damage type to the stated Target.
** Damage Defs can be found in the def file "darkmod/tdm_defs01.pk4/defs/tdm_damage.def".
* '''Deactivate Response:''' Deactivates the Response for the stated Stim Type on the named Entity.
* '''Deactivate Shooter:''' Deactivates the stated Shooter.
** E.g. Can be used to disarm a trap.
* '''Deactivate Stim:''' Deactivates the Stim for the stated Stim Type on the named Entity.
* '''Disable Effect:''' Disables only one Effect on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response number 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Enable Effect:''' Enables only one Effect on the stated Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is enabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Fade Light Color:''' Changes the colour of the named Target Light to the stated Color over a time of Fade Time seconds.
* '''Frob:''' Frobs the named Entity as if it had been frobbed by the player.
* '''Gas Knockout:''' Knocks out the named Target as if it had been hit with a gas arrow.
* '''Heal:''' Heals the named Target by the stated Amount.
* '''Kill:''' Kills the named Target.
* '''Knockout:''' Knocks out the named Target as if it had been hit with the blackjack.
* '''Turn extinguishable Light Off:''' Extinguishes the named extinguishable Light.
* '''Turn extinguishable Light On:''' (Re)ignites the named extinguishable Light.
* '''Turn Light Off:''' Turns off the named Light.
* '''Turn Light On:''' Turns on the named Light.
* '''Move To Position:''' Moves the named Entity to the stated Position (coordinates: X Y Z).
** If the box "Relative to old origin" is ticked, the Entity is moved (X Y Z) units from its current location.
* '''Move To Random Position:''' Moves the named Entity to a random position inside the "Within Radius" range.
* '''Play Animation:''' Plays the stated Animation for the stated Entity.
** The Animation can be limited to only one channel (such as only the head or similar), but is best left this blank, unless sure of intent.
* '''Play Sound:''' Play the named entity's stated Sound.
** The channel can be limited (e.g. to the player voice or ambient), but this can also be left blank.
* '''Play Sound Shader:''' Plays the named Sound Shader on the stated channel (as before the channel does not need not be defined). This is not limited to inherited sounds of the entity.
* '''Remove:''' Removes the named Target from the map.
* '''Run Script:''' Runs the named Script. For more information on scripts refer to [[Scripting basics]].
* '''Set AI Team:''' Change the named AI's team to the stated Team.
** For a list of which AI belongs to which team by default, refer to [[AI_Relations_(Editing)#AI_Types_.28Teams.29|AI Relations]]
* '''Set Angles:''' Set the named Target's rotation to the stated Angles (in pitch/yaw/roll).
** As with Move To Position, this is also possible relative to the entity's current angles.
* '''Set Frobable:''' Sets the named Entity as frobable (box checked) or unfrobable (box unchecked).
* '''Set Light Color:''' Changes the colour of the named Target Light to the stated Color.
** In contrast to "Fade to Color", this happens without any transition.
* '''Set Model:''' Changes the current model of the named Target to the stated Model.
** E.g. Can be used to change a model to a broken model after recieving damage.
* '''Set Skin:''' Changes the current skin of the stated Target to the stated Skin.
* '''Set Spawnarg:''' Changes the value of a Key (Spawnarg) on the stated Target to a stated Value.
* '''Spawn Entity:''' Creates an [[entity]] of the stated Entity Class at a given location Origin (X Y Z). E.g. can be used to create new loot through an event.
* '''Spawn Particle:''' Creates an emitter that will emit the named [[Particles|particle]] (including its .prt extension) at the location Origin (X Y Z) that stay there for stated Lifetime seconds. If no Lifetime is given it stays infinitely.
* '''Start Stim Timer:''' Starts the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Stop Stim Timer:''' Stops the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Teleport (Set Origin):''' Moves the named Entity to the stated location's New Origin (coordinates: X Y Z).
** If the box "Relative to old origin" is checked, the Entity is moved (X Y Z) units from its current location.
* '''Toggle Effect:''' Disables the stated Effect if enabled or enables the stated Effect if disabled on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Toggle Light:''' Turns off the named Light if on or turns on the named Light if off.
* '''Trigger:''' Activates the named Target Trigger entity as if activated by the stated Activator. (If I remember correctly, this does not count as a trigger Stim. For this you would have to target a trigger entity, that then targets the entity you wish to receive the trigger Stim).

The Response list gives a variety of options that allows for many effects without the need to write scripts.

It is possible to add several effects with one response type by checking the box, "Random Effects" and entering the number of random effects to be used.
Note that each effect can be used multiple times. E.g. Selecting only one effect and setting "Random Effects: 3" will use the same effect three times.

= Examples =

== Arrow Trap ==

First, create an "atdm:func_shooter" entity and position it so that the arrow points in the desired direction to shoot.
''Note that this entity does not have a model. If a model is required, the shooter can be placed in front of the approriate model''.
Define the projectile to be fired (the default is a fire arrow) and check the pitch for the projectile's trajectory.

Next, it is necessary to create an activator, that can be achieved with the Stim/Response Editor as follows:
* Create a brush, giving it a NoDraw texture and convert it to a [[Glossary#func_static|func_static]].
* Place this func_static entity, where the shooter is to be activated (note that the radius of the Player Stim is 350 with a Falloff Exponent of 3 around the player. This results in an effective radius of around 100 [[Limits,_Max,_Min,_Stats,_etc#Conversion_of_game units|units]]).
* Open the Stim/Response Editor.
* Add a Response "Player" to the NoDraw func_static entity.
* To that Response, add the Effect "Activate Shooter" with the name of the shooter as "Shooter Entity".

Now the shooter will start firing as soon as the player comes within 100 units of the NoDraw func_static entity.

There are three options:

* If the the setup is left as it is, the shooter will continuously fire.
* If the shooter is given an ammo value that is not -1, the shooter will stop firing some time, depending on if the ammo is depleted, after the player moves away from the NoDraw func_static entity.
* If the shooter is to fire only once, it is necessary to add the Effect, "Disable Effect" and target the first effect that activates the shooter or give an ammo value of 1.

It may also possible for the player to disarm the trap:

* Create a response on another entity that the player will use to do to disarm the trap.

''E.g. Frob, if the player is to push a button or use a switch or lever, or a Water response if the player is to shoot a water arrow on a circuit board or a furnace. The possibilities are endless.''

* Add the same "Disable Effect" effect as before.
* It is also possible to use the Effect, "Remove shooter". But if this is used, the shooter will not be reactivated (E.g. if the player re-arms the trap, as above).
''Note that using this setup, where the Response is "Player", the trap will exclusively react to the player and not to any AI.''

== Change Patrol ==

An AI's behaviour, such as its [[AI_Patrol|patrol route]], may be altered through a response.
E.g. If the player has taken a specific loot item.

* Give the loot item a Response "Frob".
* Add the effect "Add Target".
* As the "Entity" do not use the AI, but the path_corner from which the AI is to leave its original path to enter the new one.
* As "Target" put in the first path_corner of the new path.

If the new path circles back to the original path, the path will fork at this point:
if the new path does not target any path_corner of the original path, the AI will remain patrolling the new path.

Stim/Response Editor

2018-03-06T01:17:10Z

Teh saccade: /* Responses */ / gram.syntx.'C'onsist.

= Stim / Response Editor =

The Stim/Response Editor was introduced to save typing each arg for every stim and response on the page, [[Stim/Response Key/Values]] that also contains more specific descriptions as to what each Stim/Response [[Glossary#Spawnarg|arg]] does.

For more general reading on stims and responses, please see also the pages [[Stim/Response]] and [[Stim/Response Key/Values]].

= Stims =

To add a stim or response to an entity, open the Stim/Response editor:
Select the entity and - from the menu bar - go to Entity > Stim/Response.
The Stim/Response Editor has three tabs: Stims, Responses and Custom Stims.
As stated on the [[Stim/Response]] page, an entity can have either or both Stims and Responses, but is not able to crate a Response through a Stim fired on itself.

To add a non-custom Stim, select the "Stims" tab.
From here, it is possible to add a Stim from the drop-down menu next to the "Add" button, clicking the Add button and choosing a stim from the "Type" drop-down menu at the top ("Frob" being the default) or using a keyboard shortcut by pressing the initial letter of the Stim type you'd like to add.

Select the Stim to edit from the numbered list on the left.
If no Stim type is selected, all options presented on the right are greyed out.
The options on the right side of the editor allow changes to all key values of the Stim, removing the need to type and enter manually all key values as listed and described in [[Stim/Response Key/Values]].

= Responses =

The Response Editor is a simplified way to create basic scripts without need for deeper knowledge in scripting for TDM.
It works similar to the Stim Editor, but for adding Stims that will act as entity Responses.
In the Responses tab, the Stim to which the selected entity should respond is selected in the same way as the Stims tab.

However, this only tells the entity that it must show a Response to a certain Stim type. For a Response to happen, there must be an effect. 
To add an effect, right-click in the "Response Effects" window and press, "Add new Effect". 
Double-clicking the numbered Response (or right-clicking it and choosing "Edit") will open the "Edit Response Effect" box, in which it is possible to select the target entity, type of Stim (as args) and the Response effect itself.

== Available effects ==

* '''Activate Response:''' Activates the Response for the stated Stim Type on the stated Entity.
** E.g. the player must give a fire stim to a furnace in order to have a door react to a frob Stim.
* '''Activate Shooter:''' Activates the named Shooter entity.
** E.g. Can be used to activate a trap.
* '''Activate Stim:''' Activates the Stim for the stated Stim Type on the named Entity.
** E.g. Adds a damage stim to the furnace after a fire stim is given.
* '''Add Target: ''' Adds the stated Target to the named Entity.
** E.g. Add a new path_corner to a patrol route.
* '''Apply Stim:''' Fires a Stim of the stated Stim Type to the named Target.
** The Source can be changed, but is not necessary.
* '''Blind AI:''' Blinds the named AI as if a flash bomb has been used on it.
* '''Clear Targets:''' Removes all Target-args from the named Entity.
* '''Damage:''' Applies a damage type to the stated Target.
** Damage Defs can be found in the def file "darkmod/tdm_defs01.pk4/defs/tdm_damage.def".
* '''Deactivate Response:''' Deactivates the Response for the stated Stim Type on the named Entity.
* '''Deactivate Shooter:''' Deactivates the stated Shooter.
** E.g. Can be used to disarm a trap.
* '''Deactivate Stim:''' Deactivates the Stim for the stated Stim Type on the named Entity.
* '''Disable Effect:''' Disables only one Effect on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response number 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Enable Effect:''' Enables only one Effect on the stated Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is enabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Fade Light Color:''' Changes the colour of the named Target Light to the stated Color over a time of Fade Time seconds.
* '''Frob:''' Frobs the named Entity as if it had been frobbed by the player.
* '''Gas Knockout:''' Knocks out the named Target as if it had been hit with a gas arrow.
* '''Heal:''' Heals the named Target by the stated Amount.
* '''Kill:''' Kills the named Target.
* '''Knockout:''' Knocks out the named Target as if it had been hit with the blackjack.
* '''Turn extinguishable Light Off:''' Extinguishes the named extinguishable Light.
* '''Turn extinguishable Light On:''' (Re)ignites the named extinguishable Light.
* '''Turn Light Off:''' Turns off the named Light.
* '''Turn Light On:''' Turns on the named Light.
* '''Move To Position:''' Moves the named Entity to the stated Position (coordinates: X Y Z).
** If the box "Relative to old origin" is ticked, the Entity is moved (X Y Z) units from its current location.
* '''Move To Random Position:''' Moves the named Entity to a random position inside the "Within Radius" range.
* '''Play Animation:''' Plays the stated Animation for the stated Entity.
** The Animation can be limited to only one channel (such as only the head or similar), but is best left this blank, unless sure of intent.
* '''Play Sound:''' Play the named entity's stated Sound.
** The channel can be limited (e.g. to the player voice or ambient), but this can also be left blank.
* '''Play Sound Shader:''' Plays the named Sound Shader on the stated channel (as before the channel does not need not be defined). This is not limited to inherited sounds of the entity.
* '''Remove:''' Removes the named Target from the map.
* '''Run Script:''' Runs the named Script. For more information on scripts refer to [[Scripting basics]].
* '''Set AI Team:''' Change the named AI's team to the stated Team.
** For a list of which AI belongs to which team by default, refer to [[AI_Relations_(Editing)#AI_Types_.28Teams.29|AI Relations]]
* '''Set Angles:''' Set the named Target's rotation to the stated Angles (in pitch/yaw/roll).
** As with Move To Position, this is also possible relative to the entity's current angles.
* '''Set Frobable:''' Sets the named Entity as frobable (box checked) or unfrobable (box unchecked).
* '''Set Light Color:''' Changes the colour of the named Target Light to the stated Color.
** In contrast to "Fade to Color", this happens without any transition.
* '''Set Model:''' Changes the current model of the named Target to the stated Model.
** E.g. Can be used to change a model to a broken model after recieving damage.
* '''Set Skin:''' Changes the current skin of the stated Target to the stated Skin.
* '''Set Spawnarg:''' Changes the value of a Key (Spawnarg) on the stated Target to a stated Value.
* '''Spawn Entity:''' Creates an [[entity]] of the stated Entity Class at a given location Origin (X Y Z). E.g. can be used to create new loot through an event.
* '''Spawn Particle:''' Creates an emitter that will emit the named [[Particles|particle]] (including its .prt extension) at the location Origin (X Y Z) that stay there for stated Lifetime seconds. If no Lifetime is given it stays infinitely.
* '''Start Stim Timer:''' Starts the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Stop Stim Timer:''' Stops the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Teleport (Set Origin):''' Moves the named Entity to the stated location's New Origin (coordinates: X Y Z).
** If the box "Relative to old origin" is checked, the Entity is moved (X Y Z) units from its current location.
* '''Toggle Effect:''' Disables the stated Effect if enabled or enables the stated Effect if disabled on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Toggle Light:''' Turns off the named Light if on or turns on the named Light if off.
* '''Trigger:''' Activates the named Target Trigger entity as if activated by the stated Activator. (If I remember correctly, this does not count as a trigger Stim. For this you would have to target a trigger entity, that then targets the entity you wish to receive the trigger Stim).

The Response list gives a variety of options that allows for many effects without the need to write scripts.

It is possible to add several effects with one response type by checking the box, "Random Effects" and entering the number of random effects to be used.
Note that each effect can be used multiple times. E.g. Selecting only one effect and setting "Random Effects: 3" will use the same effect three times.

= Examples =

== Arrow Trap ==

First, create an "atdm:func_shooter" entity and position it so that the arrow points in the desired direction to shoot.
''Note that this entity does not have a model. If a model is required, the shooter can be placed in front of the approriate model''.
Define the projectile to be fired (the default is a fire arrow) and check the pitch for the projectile's trajectory.

Next, it is necessary to create an activator, that can be achieved with the Stim/Response Editor as follows:
* Create a brush, giving it a NoDraw texture and convert it to a [[Glossary#func_static|func_static]].
* Place this func_static entity, where the shooter is to be activated (note that the radius of the Player Stim is 350 with a Falloff Exponent of 3 around the player. This results in an effective radius of around 100 [[Limits,_Max,_Min,_Stats,_etc#Conversion_of_game units|units]]).
* Open the Stim/Response Editor.
* Add a Response "Player" to the NoDraw func_static entity.
* To that Response, add the Effect "Activate Shooter" with the name of the shooter as "Shooter Entity".

Now the shooter will start firing as soon as the player comes within 100 units of the NoDraw func_static entity.

There are three options:

* If the the setup is left as it is, the shooter will continuously fire.
* If the shooter is given an ammo value that is not -1, the shooter will stop firing some time, depending on if the ammo is depleted, after the player moves away from the NoDraw func_static entity.
* If the shooter is to fire only once, it is necessary to add the Effect, "Disable Effect" and target the first effect that activates the shooter or give an ammo value of 1.

It may also possible for the player to disarm the trap:

* Create a response on another entity that the player will use to do to disarm the trap.

''E.g. Frob, if the player is to push a button or use a switch or lever, or a Water response if the player is to shoot a water arrow on a circuit board or a furnace. The possibilities are endless.''

* Add the same "Disable Effect" effect as before.
* It is also possible to use the Effect, "Remove shooter". But if this is used, the shooter will not be reactivated (E.g. if the player re-arms the trap, as above).
''Note that using this setup, where the Response is "Player", the trap will exclusively react to the player and not to any AI.''

== Change Patrol ==

An AI's behaviour, such as its [[AI_Patrol|patrol route]], may be altered through a response.
E.g. If the player has taken a specific loot item.

* Give the loot item a Response "Frob".
* Add the effect "Add Target".
* As the "Entity" do not use the AI, but the path_corner from which the AI is to leave its original path to enter the new one.
* As "Target" put in the first path_corner of the new path.

If the new path circles back to the original path, the path will fork at this point:
if the new path does not target any path_corner of the original path, the AI will remain patrolling the new path.

Stim/Response Editor

2018-03-06T01:08:00Z

Teh saccade: /* Arrow Trap */ sp.

= Stim / Response Editor =

The Stim/Response Editor was introduced to save typing each arg for every stim and response on the page, [[Stim/Response Key/Values]] that also contains more specific descriptions as to what each Stim/Response [[Glossary#Spawnarg|arg]] does.

For more general reading on stims and responses, please see also the pages [[Stim/Response]] and [[Stim/Response Key/Values]].

= Stims =

To add a stim or response to an entity, open the Stim/Response editor:
Select the entity and - from the menu bar - go to Entity > Stim/Response.
The Stim/Response Editor has three tabs: Stims, Responses and Custom Stims.
As stated on the [[Stim/Response]] page, an entity can have either or both Stims and Responses, but is not able to crate a Response through a Stim fired on itself.

To add a non-custom Stim, select the "Stims" tab.
From here, it is possible to add a Stim from the drop-down menu next to the "Add" button, clicking the Add button and choosing a stim from the "Type" drop-down menu at the top ("Frob" being the default) or using a keyboard shortcut by pressing the initial letter of the Stim type you'd like to add.

Select the Stim to edit from the numbered list on the left.
If no Stim type is selected, all options presented on the right are greyed out.
The options on the right side of the editor allow changes to all key values of the Stim, removing the need to type and enter manually all key values as listed and described in [[Stim/Response Key/Values]].

= Responses =

The Response Editor is a simplified way to create basic scripts without need for deeper knowledge on scripting for TDM.
It works similar to the Stim Editor, but for adding Stims that will act as entity responses.
In the Responses tab, the Stim to which the selected entity should respond is selected in the same way as the Stims tab.

However, this only tells the entity that it must show a response to a certain Stim type. For a response to happen, there must be an effect.
To add an effect, right-click in the "Response Effects" window and press, "Add new Effect".
Double-clicking the numbered Response, or right-clicking it and choosing "Edit", open the "Edit Response Effect" box in which it is possible to select the target entity, type of Stim (as args) and the Response effect itself.

== Available effects ==

* '''Activate Response:''' Activates the Response for the stated Stim Type on the stated Entity.
** E.g. the player must give a fire stim to a furnace in order to have a door react to a frob Stim.
* '''Activate Shooter:''' Activates the named Shooter entity.
** E.g. Can be used to activate a trap.
* '''Activate Stim:''' Activates the Stim for the stated Stim Type on the named Entity.
** E.g. Adds a damage stim to the furnace after a fire stim is given.
* '''Add Target: ''' Adds the stated Target to the named Entity.
** E.g. Add a new path_corner to a patrol route.
* '''Apply Stim:''' Fires a Stim of the stated Stim Type to the named Target.
** The Source can be changed, but is not necessary.
* '''Blind AI:''' Blinds the named AI as if a flash bomb has been used on it.
* '''Clear Targets:''' Removes all Target-args from the named Entity.
* '''Damage:''' Applies a damage type to the stated Target.
** Damage Defs can be found in the def file "darkmod/tdm_defs01.pk4/defs/tdm_damage.def".
* '''Deactivate Response:''' Deactivates the Response for the stated Stim Type on the named Entity.
* '''Deactivate Shooter:''' Deactivates the stated Shooter.
** E.g. Can be used to disarm a trap.
* '''Deactivate Stim:''' Deactivates the Stim for the stated Stim Type on the named Entity.
* '''Disable Effect:''' Disables only one Effect on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response number 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Enable Effect:''' Enables only one Effect on the stated Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is enabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Fade Light Color:''' Changes the colour of the named Target Light to the stated Color over a time of Fade Time seconds.
* '''Frob:''' Frobs the named Entity as if it had been frobbed by the player.
* '''Gas Knockout:''' Knocks out the named Target as if it had been hit with a gas arrow.
* '''Heal:''' Heals the named Target by the stated Amount.
* '''Kill:''' Kills the named Target.
* '''Knockout:''' Knocks out the named Target as if it had been hit with the blackjack.
* '''Turn extinguishable Light Off:''' Extinguishes the named extinguishable Light.
* '''Turn extinguishable Light On:''' (Re)ignites the named extinguishable Light.
* '''Turn Light Off:''' Turns off the named Light.
* '''Turn Light On:''' Turns on the named Light.
* '''Move To Position:''' Moves the named Entity to the stated Position (coordinates: X Y Z).
** If the box "Relative to old origin" is ticked, the Entity is moved (X Y Z) units from its current location.
* '''Move To Random Position:''' Moves the named Entity to a random position inside the "Within Radius" range.
* '''Play Animation:''' Plays the stated Animation for the stated Entity.
** The Animation can be limited to only one channel (such as only the head or similar), but is best left this blank, unless sure of intent.
* '''Play Sound:''' Play the named entity's stated Sound.
** The channel can be limited (e.g. to the player voice or ambient), but this can also be left blank.
* '''Play Sound Shader:''' Plays the named Sound Shader on the stated channel (as before the channel does not need not be defined). This is not limited to inherited sounds of the entity.
* '''Remove:''' Removes the named Target from the map.
* '''Run Script:''' Runs the named Script. For more information on scripts refer to [[Scripting basics]].
* '''Set AI Team:''' Change the named AI's team to the stated Team.
** For a list of which AI belongs to which team by default, refer to [[AI_Relations_(Editing)#AI_Types_.28Teams.29|AI Relations]]
* '''Set Angles:''' Set the named Target's rotation to the stated Angles (in pitch/yaw/roll).
** As with Move To Position, this is also possible relative to the entity's current angles.
* '''Set Frobable:''' Sets the named Entity as frobable (box checked) or unfrobable (box unchecked).
* '''Set Light Color:''' Changes the colour of the named Target Light to the stated Color.
** In contrast to "Fade to Color", this happens without any transition.
* '''Set Model:''' Changes the current model of the named Target to the stated Model.
** E.g. Can be used to change a model to a broken model after recieving damage.
* '''Set Skin:''' Changes the current skin of the stated Target to the stated Skin.
* '''Set Spawnarg:''' Changes the value of a Key (Spawnarg) on the stated Target to a stated Value.
* '''Spawn Entity:''' Creates an [[entity]] of the stated Entity Class at a given location Origin (X Y Z). E.g. can be used to create new loot through an event.
* '''Spawn Particle:''' Creates an emitter that will emit the named [[Particles|particle]] (including its .prt extension) at the location Origin (X Y Z) that stay there for stated Lifetime seconds. If no Lifetime is given it stays infinitely.
* '''Start Stim Timer:''' Starts the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Stop Stim Timer:''' Stops the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Teleport (Set Origin):''' Moves the named Entity to the stated location's New Origin (coordinates: X Y Z).
** If the box "Relative to old origin" is checked, the Entity is moved (X Y Z) units from its current location.
* '''Toggle Effect:''' Disables the stated Effect if enabled or enables the stated Effect if disabled on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Toggle Light:''' Turns off the named Light if on or turns on the named Light if off.
* '''Trigger:''' Activates the named Target Trigger entity as if activated by the stated Activator. (If I remember correctly, this does not count as a trigger Stim. For this you would have to target a trigger entity, that then targets the entity you wish to receive the trigger Stim).

The Response list gives a variety of options that allows for many effects without the need to write scripts.

It is possible to add several effects with one response type by checking the box, "Random Effects" and entering the number of random effects to be used.
Note that each effect can be used multiple times. E.g. Selecting only one effect and setting "Random Effects: 3" will use the same effect three times.

= Examples =

== Arrow Trap ==

First, create an "atdm:func_shooter" entity and position it so that the arrow points in the desired direction to shoot.
''Note that this entity does not have a model. If a model is required, the shooter can be placed in front of the approriate model''.
Define the projectile to be fired (the default is a fire arrow) and check the pitch for the projectile's trajectory.

Next, it is necessary to create an activator, that can be achieved with the Stim/Response Editor as follows:
* Create a brush, giving it a NoDraw texture and convert it to a [[Glossary#func_static|func_static]].
* Place this func_static entity, where the shooter is to be activated (note that the radius of the Player Stim is 350 with a Falloff Exponent of 3 around the player. This results in an effective radius of around 100 [[Limits,_Max,_Min,_Stats,_etc#Conversion_of_game units|units]]).
* Open the Stim/Response Editor.
* Add a Response "Player" to the NoDraw func_static entity.
* To that Response, add the Effect "Activate Shooter" with the name of the shooter as "Shooter Entity".

Now the shooter will start firing as soon as the player comes within 100 units of the NoDraw func_static entity.

There are three options:

* If the the setup is left as it is, the shooter will continuously fire.
* If the shooter is given an ammo value that is not -1, the shooter will stop firing some time, depending on if the ammo is depleted, after the player moves away from the NoDraw func_static entity.
* If the shooter is to fire only once, it is necessary to add the Effect, "Disable Effect" and target the first effect that activates the shooter or give an ammo value of 1.

It may also possible for the player to disarm the trap:

* Create a response on another entity that the player will use to do to disarm the trap.

''E.g. Frob, if the player is to push a button or use a switch or lever, or a Water response if the player is to shoot a water arrow on a circuit board or a furnace. The possibilities are endless.''

* Add the same "Disable Effect" effect as before.
* It is also possible to use the Effect, "Remove shooter". But if this is used, the shooter will not be reactivated (E.g. if the player re-arms the trap, as above).
''Note that using this setup, where the Response is "Player", the trap will exclusively react to the player and not to any AI.''

== Change Patrol ==

An AI's behaviour, such as its [[AI_Patrol|patrol route]], may be altered through a response.
E.g. If the player has taken a specific loot item.

* Give the loot item a Response "Frob".
* Add the effect "Add Target".
* As the "Entity" do not use the AI, but the path_corner from which the AI is to leave its original path to enter the new one.
* As "Target" put in the first path_corner of the new path.

If the new path circles back to the original path, the path will fork at this point:
if the new path does not target any path_corner of the original path, the AI will remain patrolling the new path.

Stim/Response Editor

2018-03-05T14:50:47Z

Teh saccade: / page format / index [header] nesting

= Stim / Response Editor =

The Stim/Response Editor was introduced to save typing each arg for every stim and response on the page, [[Stim/Response Key/Values]] that also contains more specific descriptions as to what each Stim/Response [[Glossary#Spawnarg|arg]] does.

For more general reading on stims and responses, please see also the pages [[Stim/Response]] and [[Stim/Response Key/Values]].

= Stims =

To add a stim or response to an entity, open the Stim/Response editor:
Select the entity and - from the menu bar - go to Entity > Stim/Response.
The Stim/Response Editor has three tabs: Stims, Responses and Custom Stims.
As stated on the [[Stim/Response]] page, an entity can have either or both Stims and Responses, but is not able to crate a Response through a Stim fired on itself.

To add a non-custom Stim, select the "Stims" tab.
From here, it is possible to add a Stim from the drop-down menu next to the "Add" button, clicking the Add button and choosing a stim from the "Type" drop-down menu at the top ("Frob" being the default) or using a keyboard shortcut by pressing the initial letter of the Stim type you'd like to add.

Select the Stim to edit from the numbered list on the left.
If no Stim type is selected, all options presented on the right are greyed out.
The options on the right side of the editor allow changes to all key values of the Stim, removing the need to type and enter manually all key values as listed and described in [[Stim/Response Key/Values]].

= Responses =

The Response Editor is a simplified way to create basic scripts without need for deeper knowledge on scripting for TDM.
It works similar to the Stim Editor, but for adding Stims that will act as entity responses.
In the Responses tab, the Stim to which the selected entity should respond is selected in the same way as the Stims tab.

However, this only tells the entity that it must show a response to a certain Stim type. For a response to happen, there must be an effect.
To add an effect, right-click in the "Response Effects" window and press, "Add new Effect".
Double-clicking the numbered Response, or right-clicking it and choosing "Edit", open the "Edit Response Effect" box in which it is possible to select the target entity, type of Stim (as args) and the Response effect itself.

== Available effects ==

* '''Activate Response:''' Activates the Response for the stated Stim Type on the stated Entity.
** E.g. the player must give a fire stim to a furnace in order to have a door react to a frob Stim.
* '''Activate Shooter:''' Activates the named Shooter entity.
** E.g. Can be used to activate a trap.
* '''Activate Stim:''' Activates the Stim for the stated Stim Type on the named Entity.
** E.g. Adds a damage stim to the furnace after a fire stim is given.
* '''Add Target: ''' Adds the stated Target to the named Entity.
** E.g. Add a new path_corner to a patrol route.
* '''Apply Stim:''' Fires a Stim of the stated Stim Type to the named Target.
** The Source can be changed, but is not necessary.
* '''Blind AI:''' Blinds the named AI as if a flash bomb has been used on it.
* '''Clear Targets:''' Removes all Target-args from the named Entity.
* '''Damage:''' Applies a damage type to the stated Target.
** Damage Defs can be found in the def file "darkmod/tdm_defs01.pk4/defs/tdm_damage.def".
* '''Deactivate Response:''' Deactivates the Response for the stated Stim Type on the named Entity.
* '''Deactivate Shooter:''' Deactivates the stated Shooter.
** E.g. Can be used to disarm a trap.
* '''Deactivate Stim:''' Deactivates the Stim for the stated Stim Type on the named Entity.
* '''Disable Effect:''' Disables only one Effect on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response number 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Enable Effect:''' Enables only one Effect on the stated Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is enabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Fade Light Color:''' Changes the colour of the named Target Light to the stated Color over a time of Fade Time seconds.
* '''Frob:''' Frobs the named Entity as if it had been frobbed by the player.
* '''Gas Knockout:''' Knocks out the named Target as if it had been hit with a gas arrow.
* '''Heal:''' Heals the named Target by the stated Amount.
* '''Kill:''' Kills the named Target.
* '''Knockout:''' Knocks out the named Target as if it had been hit with the blackjack.
* '''Turn extinguishable Light Off:''' Extinguishes the named extinguishable Light.
* '''Turn extinguishable Light On:''' (Re)ignites the named extinguishable Light.
* '''Turn Light Off:''' Turns off the named Light.
* '''Turn Light On:''' Turns on the named Light.
* '''Move To Position:''' Moves the named Entity to the stated Position (coordinates: X Y Z).
** If the box "Relative to old origin" is ticked, the Entity is moved (X Y Z) units from its current location.
* '''Move To Random Position:''' Moves the named Entity to a random position inside the "Within Radius" range.
* '''Play Animation:''' Plays the stated Animation for the stated Entity.
** The Animation can be limited to only one channel (such as only the head or similar), but is best left this blank, unless sure of intent.
* '''Play Sound:''' Play the named entity's stated Sound.
** The channel can be limited (e.g. to the player voice or ambient), but this can also be left blank.
* '''Play Sound Shader:''' Plays the named Sound Shader on the stated channel (as before the channel does not need not be defined). This is not limited to inherited sounds of the entity.
* '''Remove:''' Removes the named Target from the map.
* '''Run Script:''' Runs the named Script. For more information on scripts refer to [[Scripting basics]].
* '''Set AI Team:''' Change the named AI's team to the stated Team.
** For a list of which AI belongs to which team by default, refer to [[AI_Relations_(Editing)#AI_Types_.28Teams.29|AI Relations]]
* '''Set Angles:''' Set the named Target's rotation to the stated Angles (in pitch/yaw/roll).
** As with Move To Position, this is also possible relative to the entity's current angles.
* '''Set Frobable:''' Sets the named Entity as frobable (box checked) or unfrobable (box unchecked).
* '''Set Light Color:''' Changes the colour of the named Target Light to the stated Color.
** In contrast to "Fade to Color", this happens without any transition.
* '''Set Model:''' Changes the current model of the named Target to the stated Model.
** E.g. Can be used to change a model to a broken model after recieving damage.
* '''Set Skin:''' Changes the current skin of the stated Target to the stated Skin.
* '''Set Spawnarg:''' Changes the value of a Key (Spawnarg) on the stated Target to a stated Value.
* '''Spawn Entity:''' Creates an [[entity]] of the stated Entity Class at a given location Origin (X Y Z). E.g. can be used to create new loot through an event.
* '''Spawn Particle:''' Creates an emitter that will emit the named [[Particles|particle]] (including its .prt extension) at the location Origin (X Y Z) that stay there for stated Lifetime seconds. If no Lifetime is given it stays infinitely.
* '''Start Stim Timer:''' Starts the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Stop Stim Timer:''' Stops the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Teleport (Set Origin):''' Moves the named Entity to the stated location's New Origin (coordinates: X Y Z).
** If the box "Relative to old origin" is checked, the Entity is moved (X Y Z) units from its current location.
* '''Toggle Effect:''' Disables the stated Effect if enabled or enables the stated Effect if disabled on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Toggle Light:''' Turns off the named Light if on or turns on the named Light if off.
* '''Trigger:''' Activates the named Target Trigger entity as if activated by the stated Activator. (If I remember correctly, this does not count as a trigger Stim. For this you would have to target a trigger entity, that then targets the entity you wish to receive the trigger Stim).

The Response list gives a variety of options that allows for many effects without the need to write scripts.

It is possible to add several effects with one response type by checking the box, "Random Effects" and entering the number of random effects to be used.
Note that each effect can be used multiple times. E.g. Selecting only one effect and setting "Random Effects: 3" will use the same effect three times.

= Examples =

== Arrow Trap ==

First, create an "atdm:func_shooter" entity and position it so that the arrow points in the desired direction to shoot.
''Note that this entity does not have a model. If a model is required, the shooter can be placed in front of the approriate model''.
Define the projectile to be fired (the default is a fire arrow) and check the pitch for the projectile's trajectory.

Next, it is necessary to create an activator, that can be achieved with the Stim/Response Editor as follows:
* Create a brush, giving it a NoDraw texture and convert it to a [[Glossary#func_static|func_static]].
* Place this func_static entity, where the shooter is to be activated (note that the radius of the Player Stim is 350 with a Falloff Exponent of 3 around the player. This results in an effective radius of around 100 [[Limits,_Max,_Min,_Stats,_etc#Conversion_of_game units|units]]).
* Open the Stim/Response Editor.
* Add a Response "Player" to the NoDraw func_static entity.
* To that Response, add the Effect "Activate Shooter" with the name of the shooter as "Shooter Entity".

Now the shooter will start firing as soon as the player comes withing 100 units of the NoDraw func_static entity.

There are three options:

* If the the setup is left as it is, the shooter will continuously fire.
* If the shooter is given an ammo value that is not -1, the shooter will stop firing some time, depending on if the ammo is depleted, after the player moves away from the NoDraw func_static entity.
* If the shooter is to fire only once, it is necessary to add the Effect, "Disable Effect" and target the first effect that activates the shooter or give an ammo value of 1.

It may also possible for the player to disarm the trap:

* Create a response on another entity that the player will use to do to disarm the trap.

''E.g. Frob, if the player is to push a button or use a switch or lever, or a Water response if the player is to shoot a water arrow on a circuit board or a furnace. The possibilities are endless.''

* Add the same "Disable Effect" effect as before.
* It is also possible to use the Effect, "Remove shooter". But if this is used, the shooter will not be reactivated (E.g. if the player re-arms the trap, as above).
''Note that using this setup, where the Response is "Player", the trap will exclusively react to the player and not to any AI.''

== Change Patrol ==

An AI's behaviour, such as its [[AI_Patrol|patrol route]], may be altered through a response.
E.g. If the player has taken a specific loot item.

* Give the loot item a Response "Frob".
* Add the effect "Add Target".
* As the "Entity" do not use the AI, but the path_corner from which the AI is to leave its original path to enter the new one.
* As "Target" put in the first path_corner of the new path.

If the new path circles back to the original path, the path will fork at this point:
if the new path does not target any path_corner of the original path, the AI will remain patrolling the new path.

Stim/Response Editor

2018-03-05T09:53:39Z

Teh saccade: /* = Stim / Response Editor */ rem =

=== Stim / Response Editor ===

The Stim/Response Editor was introduced to save typing each arg for every stim and response on the page, [[Stim/Response Key/Values]] that also contains more specific descriptions as to what each Stim/Response [[Glossary#Spawnarg|arg]] does.

For more general reading on stims and responses, please see also the pages [[Stim/Response]] and [[Stim/Response Key/Values]].

== Stims ==

To add a stim or response to an entity, open the Stim/Response editor:
Select the entity and - from the menu bar - go to Entity > Stim/Response.
The Stim/Response Editor has three tabs: Stims, Responses and Custom Stims.
As stated on the [[Stim/Response]] page, an entity can have either or both Stims and Responses, but is not able to crate a Response through a Stim fired on itself.

To add a non-custom Stim, select the "Stims" tab.
From here, it is possible to add a Stim from the drop-down menu next to the "Add" button, clicking the Add button and choosing a stim from the "Type" drop-down menu at the top ("Frob" being the default) or using a keyboard shortcut by pressing the initial letter of the Stim type you'd like to add.

Select the Stim to edit from the numbered list on the left.
If no Stim type is selected, all options presented on the right are greyed out.
The options on the right side of the editor allow changes to all key values of the Stim, removing the need to type and enter manually all key values as listed and described in [[Stim/Response Key/Values]].

== Responses ==

The Response Editor is a simplified way to create basic scripts without need for deeper knowledge on scripting for TDM.
It works similar to the Stim Editor, but for adding Stims that will act as entity responses.
In the Responses tab, the Stim to which the selected entity should respond is selected in the same way as the Stims tab.

However, this only tells the entity that it must show a response to a certain Stim type. For a response to happen, there must be an effect.
To add an effect, right-click in the "Response Effects" window and press, "Add new Effect".
Double-clicking the numbered Response, or right-clicking it and choosing "Edit", open the "Edit Response Effect" box in which it is possible to select the target entity, type of Stim (as args) and the Response effect itself.

----

=== Available effects are: ===

* '''Activate Response:''' Activates the Response for the stated Stim Type on the stated Entity.
** E.g. the player must give a fire stim to a furnace in order to have a door react to a frob Stim.
* '''Activate Shooter:''' Activates the named Shooter entity.
** E.g. Can be used to activate a trap.
* '''Activate Stim:''' Activates the Stim for the stated Stim Type on the named Entity.
** E.g. Adds a damage stim to the furnace after a fire stim is given.
* '''Add Target: ''' Adds the stated Target to the named Entity.
** E.g. Add a new path_corner to a patrol route.
* '''Apply Stim:''' Fires a Stim of the stated Stim Type to the named Target.
** The Source can be changed, but is not necessary.
* '''Blind AI:''' Blinds the named AI as if a flash bomb has been used on it.
* '''Clear Targets:''' Removes all Target-args from the named Entity.
* '''Damage:''' Applies a damage type to the stated Target.
** Damage Defs can be found in the def file "darkmod/tdm_defs01.pk4/defs/tdm_damage.def".
* '''Deactivate Response:''' Deactivates the Response for the stated Stim Type on the named Entity.
* '''Deactivate Shooter:''' Deactivates the stated Shooter.
** E.g. Can be used to disarm a trap.
* '''Deactivate Stim:''' Deactivates the Stim for the stated Stim Type on the named Entity.
* '''Disable Effect:''' Disables only one Effect on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response number 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Enable Effect:''' Enables only one Effect on the stated Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is enabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Fade Light Color:''' Changes the colour of the named Target Light to the stated Color over a time of Fade Time seconds.
* '''Frob:''' Frobs the named Entity as if it had been frobbed by the player.
* '''Gas Knockout:''' Knocks out the named Target as if it had been hit with a gas arrow.
* '''Heal:''' Heals the named Target by the stated Amount.
* '''Kill:''' Kills the named Target.
* '''Knockout:''' Knocks out the named Target as if it had been hit with the blackjack.
* '''Turn extinguishable Light Off:''' Extinguishes the named extinguishable Light.
* '''Turn extinguishable Light On:''' (Re)ignites the named extinguishable Light.
* '''Turn Light Off:''' Turns off the named Light.
* '''Turn Light On:''' Turns on the named Light.
* '''Move To Position:''' Moves the named Entity to the stated Position (coordinates: X Y Z).
** If the box "Relative to old origin" is ticked, the Entity is moved (X Y Z) units from its current location.
* '''Move To Random Position:''' Moves the named Entity to a random position inside the "Within Radius" range.
* '''Play Animation:''' Plays the stated Animation for the stated Entity.
** The Animation can be limited to only one channel (such as only the head or similar), but is best left this blank, unless sure of intent.
* '''Play Sound:''' Play the named entity's stated Sound.
** The channel can be limited (e.g. to the player voice or ambient), but this can also be left blank.
* '''Play Sound Shader:''' Plays the named Sound Shader on the stated channel (as before the channel does not need not be defined). This is not limited to inherited sounds of the entity.
* '''Remove:''' Removes the named Target from the map.
* '''Run Script:''' Runs the named Script. For more information on scripts refer to [[Scripting basics]].
* '''Set AI Team:''' Change the named AI's team to the stated Team.
** For a list of which AI belongs to which team by default, refer to [[AI_Relations_(Editing)#AI_Types_.28Teams.29|AI Relations]]
* '''Set Angles:''' Set the named Target's rotation to the stated Angles (in pitch/yaw/roll).
** As with Move To Position, this is also possible relative to the entity's current angles.
* '''Set Frobable:''' Sets the named Entity as frobable (box checked) or unfrobable (box unchecked).
* '''Set Light Color:''' Changes the colour of the named Target Light to the stated Color.
** In contrast to "Fade to Color", this happens without any transition.
* '''Set Model:''' Changes the current model of the named Target to the stated Model.
** E.g. Can be used to change a model to a broken model after recieving damage.
* '''Set Skin:''' Changes the current skin of the stated Target to the stated Skin.
* '''Set Spawnarg:''' Changes the value of a Key (Spawnarg) on the stated Target to a stated Value.
* '''Spawn Entity:''' Creates an [[entity]] of the stated Entity Class at a given location Origin (X Y Z). E.g. can be used to create new loot through an event.
* '''Spawn Particle:''' Creates an emitter that will emit the named [[Particles|particle]] (including its .prt extension) at the location Origin (X Y Z) that stay there for stated Lifetime seconds. If no Lifetime is given it stays infinitely.
* '''Start Stim Timer:''' Starts the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Stop Stim Timer:''' Stops the timer of the stated Stim on the named Entity.
** For information about how a timer on a Stim works, refer to [[Stim/Response Key/Values]], E.g. Key: sr_timer_time_N.
* '''Teleport (Set Origin):''' Moves the named Entity to the stated location's New Origin (coordinates: X Y Z).
** If the box "Relative to old origin" is checked, the Entity is moved (X Y Z) units from its current location.
* '''Toggle Effect:''' Disables the stated Effect if enabled or enables the stated Effect if disabled on the named Entity.
** The Effect is defined by two numbers (e.g. 2_3), meaning that the Effect numbered 3 on the Response numbered 2 is disabled. The respective numbers can be found in the first column of the Response Effects window.
* '''Toggle Light:''' Turns off the named Light if on or turns on the named Light if off.
* '''Trigger:''' Activates the named Target Trigger entity as if activated by the stated Activator. (If I remember correctly, this does not count as a trigger Stim. For this you would have to target a trigger entity, that then targets the entity you wish to receive the trigger Stim).

The Response list gives a variety of options that allows for many effects without the need to write scripts.

It is possible to add several effects with one response type by checking the box, "Random Effects" and entering the number of random effects to be used.
Note that each effect can be used multiple times. E.g. Selecting only one effect and setting "Random Effects: 3" will use the same effect three times.

----

=== Examples: ===

== Arrow Trap: ==

First, create an "atdm:func_shooter" entity and position it so that the arrow points in the desired direction to shoot.
''Note that this entity does not have a model. If a model is required, the shooter can be placed in front of the approriate model''.
Define the projectile to be fired (the default is a fire arrow) and check the pitch for the projectile's trajectory.

Next, it is necessary to create an activator, that can be achieved with the Stim/Response Editor as follows:
* Create a brush, giving it a NoDraw texture and convert it to a [[Glossary#func_static|func_static]].
* Place this func_static entity, where the shooter is to be activated (note that the radius of the Player Stim is 350 with a Falloff Exponent of 3 around the player. This results in an effective radius of around 100 [[Limits,_Max,_Min,_Stats,_etc#Conversion_of_game units|units]]).
* Open the Stim/Response Editor.
* Add a Response "Player" to the NoDraw func_static entity.
* To that Response, add the Effect "Activate Shooter" with the name of the shooter as "Shooter Entity".

Now the shooter will start firing as soon as the player comes withing 100 units of the NoDraw func_static entity.

There are three options:

* If the the setup is left as it is, the shooter will continuously fire.
* If the shooter is given an ammo value that is not -1, the shooter will stop firing some time, depending on if the ammo is depleted, after the player moves away from the NoDraw func_static entity.
* If the shooter is to fire only once, it is necessary to add the Effect, "Disable Effect" and target the first effect that activates the shooter or give an ammo value of 1.

It may also possible for the player to disarm the trap:

* Create a response on another entity that the player will use to do to disarm the trap.

''E.g. Frob, if the player is to push a button or use a switch or lever, or a Water response if the player is to shoot a water arrow on a circuit board or a furnace. The possibilities are endless.''

* Add the same "Disable Effect" effect as before.
* It is also possible to use the Effect, "Remove shooter". But if this is used, the shooter will not be reactivated (E.g. if the player re-arms the trap, as above).
''Note that using this setup, where the Response is "Player", the trap will exclusively react to the player and not to any AI.''

----

== Change Patrol: ==
An AI's behaviour, such as its [[AI_Patrol|patrol route]], may be altered through a response.
E.g. If the player has taken a specific loot item.

* Give the loot item a Response "Frob".
* Add the effect "Add Target".
* As the "Entity" do not use the AI, but the path_corner from which the AI is to leave its original path to enter the new one.
* As "Target" put in the first path_corner of the new path.

If the new path circles back to the original path, the path will fork at this point:
if the new path does not target any path_corner of the original path, the AI will remain patrolling the new path.

Mission Filestructure

2018-02-21T14:40:14Z

Teh saccade: /* script */ $target

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
: .dds font is used for compression only - it is a hack-wrapper for the game to read the .ttf font. As such, it is unclear if it can contain additional maps (normal / specular).
: Not being a commonly used format for fonts in the game (.dat is preferable in nearly every instance as to be convention), it might be suggested that the .dds .ttf font-wrapper is a remnant of Doom3 that yet lingers.
: More information on altering existing, adding new or creating custom fonts can be found here: http://forums.thedarkmod.com/topic/19308-how-to-open-and-edit-the-dat-file-safely-and-successfully-purposes-font-editing/

 

== 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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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.

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2018-02-21T14:30:15Z

Teh saccade: /* script */ formatting... :/

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
: .dds font is used for compression only - it is a hack-wrapper for the game to read the .ttf font. As such, it is unclear if it can contain additional maps (normal / specular).
: Not being a commonly used format for fonts in the game (.dat is preferable in nearly every instance as to be convention), it might be suggested that the .dds .ttf font-wrapper is a remnant of Doom3 that yet lingers.
: More information on altering existing, adding new or creating custom fonts can be found here: http://forums.thedarkmod.com/topic/19308-how-to-open-and-edit-the-dat-file-safely-and-successfully-purposes-font-editing/

 

== 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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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.

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2018-02-21T14:29:17Z

Teh saccade: /* script */ added example of override base script / links

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
: .dds font is used for compression only - it is a hack-wrapper for the game to read the .ttf font. As such, it is unclear if it can contain additional maps (normal / specular).
: Not being a commonly used format for fonts in the game (.dat is preferable in nearly every instance as to be convention), it might be suggested that the .dds .ttf font-wrapper is a remnant of Doom3 that yet lingers.
: More information on altering existing, adding new or creating custom fonts can be found here: http://forums.thedarkmod.com/topic/19308-how-to-open-and-edit-the-dat-file-safely-and-successfully-purposes-font-editing/

 

== 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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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.

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2018-02-21T11:32:38Z

Teh saccade: /* strings */ link to russian text hex offset

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
: .dds font is used for compression only - it is a hack-wrapper for the game to read the .ttf font. As such, it is unclear if it can contain additional maps (normal / specular).
: Not being a commonly used format for fonts in the game (.dat is preferable in nearly every instance as to be convention), it might be suggested that the .dds .ttf font-wrapper is a remnant of Doom3 that yet lingers.
: More information on altering existing, adding new or creating custom fonts can be found here: http://forums.thedarkmod.com/topic/19308-how-to-open-and-edit-the-dat-file-safely-and-successfully-purposes-font-editing/

 

== 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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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.

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2018-02-21T11:29:50Z

Teh saccade: /* fonts */ updated .dds font info; added link

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
: .dds font is used for compression only - it is a hack-wrapper for the game to read the .ttf font. As such, it is unclear if it can contain additional maps (normal / specular).
: Not being a commonly used format for fonts in the game (.dat is preferable in nearly every instance as to be convention), it might be suggested that the .dds .ttf font-wrapper is a remnant of Doom3 that yet lingers.
: More information on altering existing, adding new or creating custom fonts can be found here: http://forums.thedarkmod.com/topic/19308-how-to-open-and-edit-the-dat-file-safely-and-successfully-purposes-font-editing/

 

== 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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2017-12-20T07:10:57Z

Teh saccade: /* video */ added rich's info

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|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 [[Briefing|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.

Mission Filestructure

2017-12-17T06:04:35Z

Teh saccade: /* video */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos (iirc, 640x480 was best resolution for video..?).

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

;../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 [[Briefing|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.

Mission Filestructure

2017-12-17T06:02:36Z

Teh saccade: /* video */ additional link

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

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

;../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 [[Briefing|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.

Mission Filestructure

2017-12-17T06:01:00Z

Teh saccade: /* video */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip [now 404'd] - instead 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

;../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 [[Briefing|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.

Mission Filestructure

2017-12-17T06:00:29Z

Teh saccade: /* video */ update roq video encoder

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip [404] - 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

;../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 [[Briefing|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.

Mission Filestructure

2017-07-17T18:25:32Z

Teh saccade: /* guis */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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.
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. 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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[Briefing|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.

Mission Filestructure

2017-05-29T20:27:58Z

Teh saccade: /* Conclusion */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[Briefing|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.

Mission Filestructure

2017-05-29T20:26:47Z

Teh saccade: /* the end */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[Briefing|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.

Mission Filestructure

2017-05-29T20:23:50Z

Teh saccade: /* xdata = */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[Briefing|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).

 

== the end ==

Mission Filestructure

2017-05-29T20:22:43Z

Teh saccade: /* xdata = */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[http://wiki.thedarkmod.com/index.php?title=Briefing|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).

 

== the end ==

Mission Filestructure

2017-05-29T20:22:21Z

Teh saccade: /* xdata = */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../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 [[http://wiki.thedarkmod.com/index.php?title=Briefing|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).

 

== the end ==

Mission Filestructure

2017-05-29T20:18:00Z

Teh saccade: /* video */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 [[Setting_up_Campaigns#Briefing_Videos|video briefing or debriefing]], these files are placed here.

TDM uses .roq format for its videos.

The encoder may be found here: ftp://ftp.idsoftware.com/idstuff/quake3/tools/roq.zip

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

;../video/levelname_briefing.roq
;../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 ==

Mission Filestructure

2017-05-29T20:13:46Z

Teh saccade: /* levelname */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 ==

/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 ==

Mission Filestructure

2017-05-29T20:11:14Z

Teh saccade: /* textures */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 ==

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 ==

Mission Filestructure

2017-05-29T20:01:54Z

Teh saccade: /* strings */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.

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

 

== 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 ==

Mission Filestructure

2017-05-29T20:01:38Z

Teh saccade: /* strings */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 [[Mission_Title_Screen_while_Loading|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) and the standard [[fonts]] do not accept international characters such as ñ or è.
DR's readables editor does not produce this convention as standard.

 

== 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 ==

Mission Filestructure

2017-05-29T19:57:55Z

Teh saccade: /* strings */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

[[How_to_pack_your_Mission#Internationalisation_.28I18N.29|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 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) and the standard [[fonts]] do not accept international characters such as ñ or è.

 

== 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 ==

Mission Filestructure

2017-05-29T19:39:34Z

Teh saccade: /* sound */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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 ==

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 ==

Mission Filestructure

2017-05-29T19:37:40Z

Teh saccade: /* sound */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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

 

== 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 ==

Mission Filestructure

2017-05-29T19:37:29Z

Teh saccade: /* sound */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 [[Adding_ambient_Sounds_to_your_Map|.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

 

== 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 ==

Mission Filestructure

2017-05-29T19:29:25Z

Teh saccade: /* script */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

These scripts are most often called using triggers in Dark Radiant.

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

 

== 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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:26:35Z

Teh saccade: /* script */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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.

The scripts for "mylevel" (ie, you FM) are placed here:

;../script
../script/custom_ai.script
../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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:22:16Z

Teh saccade: /* particles */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:22:04Z

Teh saccade: /* particles */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:08:00Z

Teh saccade: /* md5 */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:06:37Z

Teh saccade: /* guis */ gram.

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T19:05:29Z

Teh saccade: /* guis */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T18:40:01Z

Teh saccade: /* md5 */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T18:39:41Z

Teh saccade: /* md5 */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T18:36:27Z

Teh saccade: /* materials */

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_Mappers'_Guide#Defining_the_Map_Filename_for_Dark_Mod|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|.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 ==

[[EntityDef|Entity definitions]] are predefined [[Spawnarg|spawnargs]], used in the creation of, eg, custom loot.
A more complete list of values to use might be found [[DEF_Files|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 [[Skybox_Basic_Details|default prefab]].

;../env
: Contains the custom skybox.
;../env/custom
: The tutorial for creating which can be found [[Skybox_Tutorial|here]].

 

== fonts ==

;/fonts/fontimage_<size>.dat
: In the case that a custom [[Fonts_Screenshots|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_Entities|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 [[In-game_Map_Entities|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 ==

[[Basic_Material_File|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 ==

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 [[Creating_Multiple_Skins_For_A_Model|here]].

<s>skins tutorial is bookmarked for clear-up</s>

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 ==

Mission Filestructure

2017-05-29T18:20:22Z

Teh saccade: /* maps */

Mission Filestructure

2017-05-29T18:17:56Z

Teh saccade: /* guis */

Mission Filestructure

2017-05-29T18:16:12Z

Teh saccade: /* guis */

Mission Filestructure

2017-05-29T18:12:27Z

Teh saccade: /* lights */

Mission Filestructure

2017-05-29T18:11:17Z

Teh saccade: /* map */

Mission Filestructure

2017-05-29T18:10:38Z

Teh saccade: /* map */

Mission Filestructure

2017-05-29T18:10:12Z

Teh saccade: /* splash */

Mission Filestructure

2017-05-29T18:09:58Z

Teh saccade: /* guis */

Mission Filestructure

2017-05-29T18:08:43Z

Teh saccade: /* map */