diff --git a/_config.yml b/_config.yml index dd05e49..d00a005 100644 --- a/_config.yml +++ b/_config.yml @@ -61,6 +61,9 @@ callouts: doom3: title: Doom 3 Only color: doom3 + doom3bfg: + title: Doom 3 BFG Edition Only + color: doom3 wolf09: title: Wolfstein (2009) color: wolf09 diff --git a/docs/engine/cm/cm.md b/docs/engine/cm/cm.md index d097bb9..a836ead 100644 --- a/docs/engine/cm/cm.md +++ b/docs/engine/cm/cm.md @@ -35,8 +35,8 @@ From this point the `.cm` file must be named and placed in the same directory as # Note {: .etqw} -> Enemy Territory: Quake Wars encrypt its files so its hard to see what change and what not. -> Encrypted models has the post fix of `b` in this case `.cm**b**` +> Enemy Territory: Quake Wars binarizes its files so its hard to see what change and what not. +> Binarize models has the post fix of `b` in this case `.cmb` {: .wolf09} > This system is deprecated in Wolfstein (2009) \ No newline at end of file diff --git a/docs/engine/fileformats/ase.md b/docs/engine/fileformats/ase.md new file mode 100644 index 0000000..7d97bb3 --- /dev/null +++ b/docs/engine/fileformats/ase.md @@ -0,0 +1,95 @@ +--- +layout: default +title: Ascii Scene Export (.ase) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 1 +--- + +# Overview + +--- +ASE stands for Ascii Scene Export. This is an ascii text based format associated with 3DS Max. It is not limited to that application, but support in other applications is dependent on import/export scripts or plugins. + +The Doom 3 engine uses the ASE format for static meshes. + +# Export + +--- +- iddevnet model export page +- Maya can export ASE’s using the ActorX plugin. +- Blender via [export plugin](https://github.com/FriskTheFallenHuman/D3ModdingKit/tree/master/blender) + +# File Format Syntax + +--- +**Format:** The format is based on identifiers, as in: + +```cpp + *AN_IDENTIFIER +``` + +This is followed by zero or more values, or a subset of more identifiers surrounded by curly braces. + +Most of the time when working with ASE’s, you will find that you have to open them to manually link the materials to a specified material shader. For example, the format for the material list may look like this when exported from actorx: + +```cpp + *MATERIAL_LIST { + *MATERIAL_COUNT 2 + *MATERIAL 0 { + *MATERIAL_NAME "myMaterial" + *MATERIAL_CLASS "Standard" + *MAP_DIFFUSE { + *MAP_CLASS "Bitmap" + *BITMAP "None" + } + } + } +``` + +Where it says: + +```cpp + *BITMAP "none" +``` + +You must replace this with a reference to a doom material shader, like so: + +```cpp + *BITMAP "//base/models/mapobjects/myModel/myShader" +``` + +Occasionally, for some unknown reason this reference doesn’t work in which case you should try… + +```cpp + *BITMAP "//purgatory/purgatory/models/mapobjects/myModel/myShader" +``` +…or… + +```cpp + *BITMAP "//doom3/base/models/mapobjects/myModel/myShader" +``` + +{: .quake4} +> Instead of `//base` or `//purgatory/purgatory` QuakeIV seems to use +> +> `C:\Ritual\Q4ritual\game\q4base` +> +> `*BITMAP "C:\Ritual\Q4ritual\game\q4base\material\name"` + +{: .etqw} +> use `*MATERIAL_NAME "material/name"` +> +> eg `*MATERIAL_NAME "textures/models/mymodel"` + +{: .note} +> Subpatch a.k.a. subdivision surfaces are not supported. +> +> Models must be composed entirely of triangles. +> +> Smoothing groups are ignored by the engine. + +# Further information + +--- +Format Specification, a bit more complete than above: [Inofficial File Format Specification at BeyondUnreal](https://wiki.beyondunreal.com/Legacy:ASE_File_Format) \ No newline at end of file diff --git a/docs/engine/fileformats/cfg.md b/docs/engine/fileformats/cfg.md new file mode 100644 index 0000000..2bb5219 --- /dev/null +++ b/docs/engine/fileformats/cfg.md @@ -0,0 +1,31 @@ +--- +layout: default +title: Configuration Files (.cfg) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 5 +--- + +# Overview + +--- + +The .cfg files are ASCII text configuration files present in `/base` and used by id tech 4 based games for setting CVars, mapping player input to keys or buttons (see note below), and executing console commands. Usually the following files are available (by reading order of the engine): + +- `DoomConfig.cfg`: Stores all the game’s options. It’s auto-generated by the engine so manual editing is not recommended. If you delete this file the engine will revert to a `default.cfg` file located inside one of the .pk4 files. +- `editor.cfg`: Optional. Stores all the DoomEdit relevant options. It’s auto-generated by the engine so manual editing is not recommended. +- `autoexec.cfg`: Optional. This file is read last and will override any options set elsewhere. It’s meant for user-manipulation so you can set any CVars here that you’d have to otherwise set in the game or editor shortcuts. + +You can also create your own custom configuration files to load custom settings and execute console commands in notepad. You can then load these files by using the exec console command in the shortcut or adding the following line to your `autoexec.cfg`: + +```cpp +exec myconfig.cfg +``` +You can use two forward slashes to write comments: + +```cpp +// This is a comment +``` + +{: .note} +> Mapping player input is accomplished through the use of the bind console command which accepts console commands, cvars, and impluses as valid input. \ No newline at end of file diff --git a/docs/engine/fileformats/demo.md b/docs/engine/fileformats/demo.md new file mode 100644 index 0000000..3fb06a7 --- /dev/null +++ b/docs/engine/fileformats/demo.md @@ -0,0 +1,15 @@ +--- +layout: default +title: Demo Files (.demo) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 5 +--- + +# Overview + +--- + +These files are recordings usually done for benchmark purposes, they can have live gameplay or static scenes and are stored in / demos. Even after the introduction of LZW compression in v1.3 they remain big files. These files are created with two console commands: `demoShot` for static scenes and `recordDemo` for rolling demos. Use the `stopRecording` console command to stop a the recording of a rolling demo. + +You can playback demos with the playDemo console command (it works on both types of demos). If you wish to benchmark using a demo see the `timeDemo` and `timeDemoQuit` console commands (you should set `"com_compressDemos 0"` in the console to avoid any slowdowns during the benchmark due to decompression). \ No newline at end of file diff --git a/docs/engine/fileformats/formats_index.md b/docs/engine/fileformats/formats_index.md new file mode 100644 index 0000000..b48e567 --- /dev/null +++ b/docs/engine/fileformats/formats_index.md @@ -0,0 +1,18 @@ +--- +layout: default +title: File Formats +parent: Engine Documentation +has_children: true +nav_order: 2 +--- + +# Overview +{: .fs-9 } + +Idtech 4, supports a variety of file formats, most of them in human readable text. +{: .fs-6 .fw-300 } + +--- + +{: .todo } +> Write more about this section. \ No newline at end of file diff --git a/docs/engine/fileformats/lang.md b/docs/engine/fileformats/lang.md new file mode 100644 index 0000000..3df6a6b --- /dev/null +++ b/docs/engine/fileformats/lang.md @@ -0,0 +1,28 @@ +--- +layout: default +title: Language Files (.lang) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 6 +--- + +# Overview + +--- + +`.lang` files are used for localization purposes. For every language there is a different set of files available. Each of these files contains a numbered string that is referenced from within code, GUIs or maps. Each string has to have a unique number so there are no conflicts when referenced. Language strings are simply referenced by typing `"#str_20000"` in the textfield. Replace 20000 with the intended string number. + +{: .doom3bfg} +> `#font_` specify the font to be use in the sfw shell, not use in the old GUI system. +> BFG Edition does't uses hashes, instead it uses full names like `#str_adil_exis_pda_01_audio_info` + +## Syntax + +--- + +```cpp +{ + "#str_20000" "Placeholder" + "#str_20001" "Placeholder2" +} +``` \ No newline at end of file diff --git a/docs/engine/fileformats/lwo.md b/docs/engine/fileformats/lwo.md new file mode 100644 index 0000000..a410d00 --- /dev/null +++ b/docs/engine/fileformats/lwo.md @@ -0,0 +1,114 @@ +--- +layout: default +title: LightWave Object (.lwo) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 2 +--- + +# Overview + +--- +LWO: LightWave Object file format is a propriatary binary file format and is the standard export format used with LightWave 3D and Modo . Support in other applications is dependant on import/export scripts or plugins. LWO files cannot be editied outside of a 3D application that supports the format, i.e. they cannot be edited in Notepad or similar. + +The id Tech 4 engine uses the LWO format for static meshes. + +More information on the LWO format can be found in the LightWave SDK . + + +# Export + +--- + +## Static Models + +--- +Getting a static model (like a trash can or a shrubery) in to the game is really easy. The engine reads lwo (lightwave) and ase (3dsmax) files natively so you simply save out the model in one of those two formats and you can use it in the game. + +The material that is used in game is the diffuse texture specified in the model. + +The relative material name is determined by searching for `"base"` in the texture path. For example, if the texture specified in the .ase is `"C:\Doom\base\textures\base_trim\red1.tga"` Then it would use the material named `"textures\base_trim\red1"` + +If you are running a custom mod, then it will look for the mod name if it can't find `"base"` so `"C:\Doom\jailbreak\textures\base_trim\red1.tga"` would also work in the jailbreak mod. + +The path cannot have spaces in it. Doom 3 should be installed in `"C:\Doom\"` or some other place without spaces. If Doom 3 is in the default location of `"C:\Program Files\Doom 3\"` it will not work because of the space in `"Program Files"` and the space in `"Doom 3"` + +Generally speaking, as long as you keep all your assets in the final directory that it will be in, then you should just be able to use it in game without having to touch anything. Problems tend to arise if you edit your assets in one directory, then move them in to the base directory or your mod directory after you export. + +If you are working on a new chair, you should work on it in + +```cpp +C:\Doom3\mymod\models\mapobjects\chairs\mychair\ +``` +rather than working on it in + +```cpp +C:\My Stuff\Models\Cool Models\Stuff For My Mod\Chair +``` + +then moving to the proper directory after it's been exported. + +Spaces in file names are bad. + +## Animated Models + +--- +Animated models are quite a bit more complex. The only animation system supported in Doom 3 is skeletal (no vertex animation like in Quake), and the only file format supported is `.mb` (Maya binary). The files have to be processed using a built in tool to convert the Maya files to `.md5mesh` and `.md5anim` files. + +**Note for 3dstudio max:** Although Doom3 does not support animated models from max "out of the box", the people over at Doom3World wrote some nice importers and exporters, which you can find here. + +This built in tool is `exportModels`. By default, it will export any models that have been modified since the last time the command was run, but you can pass it a `.def` file and it will only export the models defined in that def file. You can speed up the exportModels command by using the `g_exportMask` cvar and specifying some magic string after the export declaration (as we will see later). Setting `g_exportMask fred` will only export fred's animations, skipping all the others. + +You must have Maya installed on the machine that you are exporting on otherwise it won't do anything. + +The syntax for an export section looks complex at first, but is actually quite simple when you break it down into the different parts. Unlike some other declarations, the commands in an export block are executed as they are encountered. This means the order DOES matter. + +There are two systems at work when you export a file. The first is the actual exporter, this is the piece that does all the work. The second is what I'm going to call the `parser`. This piece reads the export sections and passes the commands to the exporter for actual exportation. + +The parser only has 5 commands, and they are really very simple: + +| Command | Description +|:----------------------------|:--------------------------------| +| options [options] | Stores default options that will be used for all future export actions. Note that an options command will override any previously set options. | +| addoptions [options] | Adds a default option to the current set of default options. This is very similar to the options command, but it appends rather than overwriting the current options. | +| mesh [options] | Exports a object from a .mb file. The options specified here will be appended to the options specified previously with "options" or "addoptions" commands. | +| anim [options] | TODO | +| camera [options] | TODO | + +Here is a list of all the options along with a brief description of what they do: + +Option |Description +-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +\-force |Ignored +\-game |Specify the mod name, which is where the relative paths are defined from. This should get set automatically in 1.2 +\-rename [joint name] [new name] |Rename a joint +\-prefix [joint prefix] |If you have multiple characters/objects in your scene, you can give them each their own prefix so the exporter can distinguish which goes to which. Example: ZSEC \_ IMP \_ ENV_ +\-parent [joint name] [new parent] |Reparent a joint +\-sourcedir [directory] |Tell exporter where to get files from +\-destdir [directory] |Tell exporter where to put files after export +\-dest [filename] |Give a new name to the file you are exporting. Default will be the same name as the Maya file. +\-range [start frame] [end frame] |Frame range for what you would like to export. Example: -range 1 10 +\-cycleStart [first frame of cycle]|Shift the cycle to start on a different frame. Example: Frame 1 has left foot forward, and frame 10 has right foot forward. So if you would like your cycle to start with the right foot forward, use -cycleStart 10 to shift the cycle. +\-scale [scale amount] |Scale up or down your character during export. Example: -scale 2 will double the size of the character (scaled up from the origin). +\-align [joint name] |Will align your animation to a certain bone. +\-rotate [yaw] |Allows you to manually rotate your animation. Example: -rotate 90 +\-nomesh | +\-clearorigin | +\-clearoriginaxis | +\-ignorescale |Ignore any scales you may have on some bones. +\-xyzprecision [precision] |Will take even tiny movements (translations) into consideration if you make this number lower. The default will try to compress down the animations, getting rid of tiny movements. +\-quatprecision [precision] |Will take even tiny movements (rotations) into consideration if you make this number lower. The default will try to compress down the animations, getting rid of tiny movements. +\-jointthreshold [min joint weight]| +\-skipmesh [name of mesh] |Allows you to skip certain models during export. + +# Notes + +- A LWO to MD5 conversion utitlity can be obtained at ~~~www.doom3world.org~~~ dead link. +- An MD5camera export script can be downloaded from ~~~www.pcgamemods.com~~~ dead link. +- Subpatch a.k.a. subdivision surfaces are not supported. +- Surface properties are not parsed by Doom 3. +- Models must be composed entirely of triangles. +- All mesh data must be on a single layer. +- Each mesh must have exactly one UV map. Doom 3 will not crash if you have more, but textures will behave in unexpected ways, mixing UV maps, using the wrong UV map, etc. +- Smoothing angle is not supported. In game, smoothing occurs across welded triangles. Seams must be created manually by unwelding vertices. +- The surface name of each surface in LightWave 3D must match the name of the corresponding material shader in Doom 3. diff --git a/docs/engine/fileformats/md5.md b/docs/engine/fileformats/md5.md new file mode 100644 index 0000000..ab05071 --- /dev/null +++ b/docs/engine/fileformats/md5.md @@ -0,0 +1,52 @@ +--- +layout: default +title: Model 5 (.md5) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 3 +--- + +# Overview + +Not be consufed by [MD5](https://en.wikipedia.org/wiki/MD5) used in hashing. + +MD5 is a proprietary but open format specific to any Idtech4 game and allows models to be animated by the use of an internal skeleton. Generally two files are needed to make a functional MD5 model; `md5mesh` and `md5anim`. The 3rd, `md5camera`, allows the creation and use of complex camera paths used during cut scenes. See the different pages for syntax explanation + +## . MD5MESH +Low resolution polygonal mesh exported from a 3D application. + +## . MD5ANIM +Contains animation sequence data, the positions of bones etc. during animation. + +## . MD5CAMERA +Animated cameras for use in cut scenes. + +{: .doom3bfg } +{: .lh-0 } +> ## . BMD5MESH +> `MD5MESH` compressed into a binary format. + + +{: .doom3bfg } +{: .lh-0 } +> ## . BMD5ANIM +> `MD5ANIM` compressed into a binary format. + +## MD5 Header + +All MD5 format files start with the MD5 header, regardless the specific filetype. The header is the first section in the file and is as such... + +```cpp +MD5Version +commandline "" +``` +- `MD5Version`: An integer that defines the current MD5 specification version. This should always read 10. +- `commandline`: A string that contains the command line parameters passed to the exportmodels console command. + +## Export + +Maya 4.5 was the 3D package primarily used for the creation of animated characters during the development of Doom 3, Quake 4, and possibly Prey. Models were saved in `.mb (Maya Binary)` format and converted through the use of an export declaration , the console command `exportModels` , and a DLL by the name of `MayaImportx86`. + +It goes without saying that you stand the best chance for success if you follow the same workflow. However, there are third party tools and alternative versions of MayaImportx86.dll listed below you can use should you be working with a package other than Maya version 4.5. + +It’s also important to note that the alternate versions of `MayaImportx86.dll` were intended for use with Doom 3 and there have been reports that they do not function correctly with other Idtech4 engine based games. In other words, if you only have Quake 4 or Prey at your disposal, you may encounter some compatibility issues that have yet to be resolved. You may be forced to borrow a copy of Doom 3 for export purposes. \ No newline at end of file diff --git a/docs/engine/fileformats/md5_anim.md b/docs/engine/fileformats/md5_anim.md new file mode 100644 index 0000000..4ada7f3 --- /dev/null +++ b/docs/engine/fileformats/md5_anim.md @@ -0,0 +1,129 @@ +--- +layout: default +title: Model 5 Animations (.md5anim) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 5 +--- + +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +# Overview + +--- +`.md5anim` files are ascii (plain text) files that contain skeletal animation data. + +# Model Format Syntax + +--- + +## Filetype Specific Parameters + +This section contains filetype specifc parameters. The filetype specific parameters make up the second section in the file. +In the case of `.md5anim` the filetype specific parameters are as such... + +```cpp +numFrames +numJoints +frameRate +numAnimatedComponents +``` + +- `numFrames`: The total number of frames in the animation. +- `numJoints`: The number of joints in the model. +- `frameRate`: The rate of playback in frames per second. +- `numAnimatedComponents`: The number of animated components. + +## Ordered Lists + +The third section in the file contains ordered lists. These lists contain data relevant to the type declared. + +```cpp + { + [element 1] + [element 2] + [element 3] + ... ect ... +} +``` + +First, the type of list is declared (``). Then the body of the list is contained within curly brackets. +The list is constructed of a series of elements each on a new line. The number of elements varies depending on type. +In the case of `.md5anim` there are three basic ordered lists followed by an ordered list for every frame in the animation. + +## Hierarchy + +Each element of the hierarchy ordered list is structured like so … + +```cpp +"[boneName]" [parentIndex] [numComp] [frameIndex] // [parentName] ( [tX] [tY] [tZ] [qX] [qY] [qZ] ) +``` + +- `boneName`: The name of this bone. +- `parentIndex`: The index of this bone’s parent. +- `numComp`: a flag that defines what components are keyframed. +- `frameIndex`: index into the frame data, pointing to the first animated component of this bone +- `parentName`: The name of the parent bone +- `[tX]`: Optional placeholder just to provide a visual of what components are animated +- `[tY]`: Optional placeholder just to provide a visual of what components are animated +- `[tZ]`: Optional placeholder just to provide a visual of what components are animated +- `[qX]`: Optional placeholder just to provide a visual of what components are animated +- `[qY]`: Optional placeholder just to provide a visual of what components are animated +- `[qZ]`: Optional placeholder just to provide a visual of what components are animated + +## Bounds + +There is one line for each frame of the animation that holds the bounding box information at that frame. + +```cpp +( [minX] [minY] [minZ] ) ( [maxX] [maxY] [maxZ] ) +``` + +- `minX`: The X component of the frames’s minimum bounding box XYZ position. +- `minY`: The Y component of the frames’s minimum bounding box XYZ position. +- `minZ`: The Z component of the frames’s minimum bounding box XYZ position. +- `maxX`: The X component of the frames’s maximum bounding box XYZ position. +- `maxY`: The Y component of the frames’s maximum bounding box XYZ position. +- `maxZ`: The Z component of the frames’s maximum bounding box XYZ position. + +## Baseframe + +Each bone’s position and orientation for the baseframe is listed here. + +``` +( [xPos] [yPos] [zPos] ) ( [xOrient] [yOrient] [zOrient] ) +``` + +- `xPos`: The X component of this bone’s XYZ position relative to parent bone’s position. +- `yPos`: The Y component of this bone’s XYZ position relative to parent bone’s position. +- `zPos`: The Z component of this bone’s XYZ position relative to parent bone’s position. +- `xOrient`: The X component of this bone’s XYZ orentation quaternion. +- `yOrient`: The Y component of this bone’s XYZ orentation quaternion. +- `zOrient`: The Z component of this bone’s XYZ orentation quaternion. + +{: .note} +> For coders: it is not usually possible to create and render a skeleton using only the baseframe data. +> Without first applying the animated components to it from a frame (see below) the skeleton will not usually resemble the model when rendered. + +## Frame 0,1,2, ect... + +For each frame the animated components values are listed. Values that are not animated have the same value as their baseframe value, over the whole animation time. +Each of these 6 numbers is optional, lines don’t necessarily have to list 6 values. The `"numModComponents"` value of a joint flags which components are listed here. + +[xPos] [yPos] [zPos] [xOrient] [yOrient] [zOrient] + +- `xPos`: The X component of this bone’s XYZ position in relation to the baseframe. +- `yPos`: The Y component of this bone’s XYZ position in relation to the baseframe. +- `zPos`: The Z component of this bone’s XYZ position in relation to the baseframe. +- `xOrient`: The X component of this bone’s XYZ orentation quaternion in relation to the baseframe. +- `yOrient`: The Y component of this bone’s XYZ orentation quaternion in relation to the baseframe. +- `zOrient`: The Z component of this bone’s XYZ orentation quaternion in relation to the baseframe. \ No newline at end of file diff --git a/docs/engine/fileformats/md5_camera.md b/docs/engine/fileformats/md5_camera.md new file mode 100644 index 0000000..546fe5f --- /dev/null +++ b/docs/engine/fileformats/md5_camera.md @@ -0,0 +1,86 @@ +--- +layout: default +title: Model 5 Camera (.md5camera) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 6 +--- + +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +# Overview + +--- + +`.md5camera` files are ascii (plain text) files that contain camera path data. This data controls the position, rotation, and field of view for cinematic cameras. + +# Model Format Syntax + +--- + +## Filetype Specific Parameters + +This section contains filetype specifc parameters. The filetype specific parameters make up the second section in the file. +In the case of `.md5camera` the filetype specific parameters are as such... + +```cpp +numFrames +frameRate +numCuts +``` +- `numFrames`: An integer that defines the total number of frames in the animation. +- `frameRate`: An integer that defines the rate of playback in frames per second. +- `numCuts`: An integer that defines the number of cuts in the animation. + +Ordered Lists + +The third section in the file contains ordered lists. These lists contain data relevant to the type declared. + +```cpp + { + [element 1] + [element 2] + [element 3] + ... ect ... +} +``` + +First, the type of list is declared (``). Then the body of the list is contained within curly brackets. +The list is constructed of a series of elements each on a new line. The number of elements varies depending on type. +In the case of `.md5camera` there are two ordered lists. + +## Cuts + +Each element of the cuts ordered list is structured like so... + +```cpp +[frameNumber] +``` +- `frameNumber`: An integer that defines the frame where a cut takes place. + +The number of elements is dependant on the number of cuts. +For instance, if there are five cuts, there should be five frame indexes listed. +Camera + +Each element of the camera ordered list is structured like so... + +```cpp +( [X Pos] [Y Pos] [Z Pos] ) ( [Orientation] ) [FOV] +``` +- `X Pos`: a floating point number that defines the position of the camera on the X axis. +- `Y Pos`: a floating point number that defines the position of the camera on the Y axis. +- `Z Pos`: a floating point number that defines the position of the camera on the Z axis. +- `Orientation`: a rotational quaternion that defines the orientation of the camera. (Only the X, Y, and Z components are stored. W is calculated on the fly.) +- `FOV`: a floating point number that defines the field of view of the camera. + +The number of elements is dependant on the number of frames. +If there are five frames total, there should be five camera keyframes listed. \ No newline at end of file diff --git a/docs/engine/fileformats/md5_mesh.md b/docs/engine/fileformats/md5_mesh.md new file mode 100644 index 0000000..eae1377 --- /dev/null +++ b/docs/engine/fileformats/md5_mesh.md @@ -0,0 +1,143 @@ +--- +layout: default +title: Model 5 Mesh (.md5mesh) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 4 +--- + +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +# Overview + +--- +`.md5mesh` files are ascii (plain text) files that contain mesh and skeletal data. + +# Model Format Syntax + +--- + +## Filetype Specific Parameters + +This section contains filetype specifc parameters. The filetype specific parameters make up the second section in the file. +In the case of MD5Mesh the filetype specific parameters are as such… + +```cpp +numJoints +numMeshes +``` +- `numJoints`: An integer that defines the number of bones in the model. +- `numMeshes`: An integer that defines the number of meshes in the model. + +## Ordered Lists + +The third section in the file contains ordered lists. These lists contain data relevant to the type declared. + +```cpp + { + [element 1] + [element 2] + [element 3] + ... ect ... +} +``` + +First, the type of list is declared (``). Then the body of the list is contained within curly brackets. +The list is constructed of a series of elements each on a new line. The number of elements varies depending on type. +In the case of MD5Mesh there are two ordered lists. + +## Joints + +Each element of the joints ordered list is structured like so... + +```cpp +"[boneName]" [parentIndex] ( [xPos] [yPos] [zPos] ) ( [xOrient] [yOrient] [zOrient] ) +``` + +- `boneName`: The name of this bone. +- `parentIndex`: The index of this bone’s parent. +- `xPos`: The X component of this bone’s XYZ position. +- `yPos`: The Y component of this bone’s XYZ position. +- `zPos`: The Z component of this bone’s XYZ position. +- `xOrient`: The X component of this bone’s XYZ orentation quaternion. +- `yOrient`: The Y component of this bone’s XYZ orentation quaternion. +- `zOrient`: The Z component of this bone’s XYZ orentation quaternion. + +The number of elements is dependant on the number of joints. +For instance, if there are five joints, there should be five joint descriptors listed. + +## Mesh + +The mesh ordered list contains 3 indexed lists: vertices, triangles, and weights. + +```cpp +// meshes: [meshName] +shader "[materialName]" +``` +- `meshName`: The name of the mesh. +- `materialName`: The material shader to apply to this mesh. + +{: .etqw} +> After the parameters, an extra ordered list follows for specifying extra flags. + +## Flags + +{: .etqw} +> This type of ordered list only exists in ET:QW. + +The ordered list should be defined even when empty. Each line may specify one of the following known flags: + +```cpp +noAnimate +vertexColor +``` + +## Vert + +```cpp +numverts +vert [vertIndex] ( [texU] [texV] ) [weightIndex] [weightElem] +``` +- `numverts`: The number of vertices. Coorisponds to the number of elements to follow in the list. +- `vertIndex`: The index of this vertex. +- `texU`: The U component of the UV texture coordinates. +- `texV`: The V component of the UV texture coordinates. +- `weightIndex`: The index into the weight array where this vertex’s first weight is located. +- `weightElem`: The number of elements in the weight array that apply to this vertex. + +## Tri + +```cpp +numtris +tri [triIndex] [vertIndex1] [vertIndex2] [vertIndex3] +``` +- `numtris`: The number of triangles. Corrisponds to the number of elements to follow in the list. +- `triIndex`: The index of this triangle. +- `vertIndex1`: The index of the first vertex for this triangle. +- `vertIndex2`: The index of the second vertex for this triangle. +- `vertIndex3`: The index of the third vertex for this triangle. + +## Weight + +```cpp +numweights +weight [weightIndex] [jointIndex] [weightValue] ( [xPos] [yPos] [zPos] ) +``` +- `numweights`: The number of weights. Corrisponds to the number of elements to follow in the list. +- `weightIndex`: The index of this weight. +- `jointIndex`: The index of the joint to which this weight applies. +- `weightValue`: The value of the weight. +- `xPos`: The X component of this weight’s XYZ position. +- `yPos`: The Y component of this weight’s XYZ position. +- `zPos`: The Z component of this weight’s XYZ position. + +The number of mesh ordered lists is dependant on the number of meshes. \ No newline at end of file diff --git a/docs/engine/fileformats/pk4.md b/docs/engine/fileformats/pk4.md new file mode 100644 index 0000000..e8cfee7 --- /dev/null +++ b/docs/engine/fileformats/pk4.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Pak Files (.pk4) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 7 +--- + +# Overview + +--- + +Ideally, every asset used by the idTech 4 engine is stored in a `.pk4` file (also known as a "pack" or "pak" file). Pack files are just normal `.zip` files with the `.pk4` extension - you can use WinRar, Winzip, 7-Zip or a similar utility to browse or create new `.pk4` files. + +{: .wolf09} +> The `.pk4` files used in the single player component have a modified header which prevents them from being opened by a standard archive program with the exception of WinRar which seems capable of “repairing” these files. + +If you have more than one pack file or assets in a mix of pack files and individual files here is the expected behavior of the engine: + +1. Assets inside pack files that come later in alphabetical order override assets with the same name in Pack files that come earlier. +2. Assets as individual files override assets inside pack files. +3. Assets in pack files or modfolders override assets with the same name in the base folder + +# Compression + +--- + +As renamed `.zip` files, `.pk4` can have compressed files inside but also uncompressed ones by using the store option in the `.zip` format. The pack files that come with Doom 3 and the Doom 3: Resurrection of Evil expansion feature compression. Although compressed pack files increase loading times, this penalty is small while the filesize difference is significant: Doom 3’s assets are 3.6Gb uncompressed, and only 1.44Gb in their original `.pk4` form. + +# Achieving Better Compression For Distribution + +--- + +Even if you use the maximum compression possible in `.pk4` files it will never rival the compression ratios possible by WinRar for instance. However the following will: + +1. Create your `.pk4` files with the store compression factor. +2. RAR all your `.pk4` files with maximum compression. (You may want to create a SFX archive, instead of straight `.rar` so people won’t have to download WinRar to open it; which can also double as an installer for your mod.) + +You should now be able to distribute a much smaller file than if you had used max compression for the `.pk4` files. However, once installed your files will be as large as if not in a `.pk4` file because they are uncompressed thanks to the store option. + +On a side note: 7zip's compression ratio is even better, but not as wide-spread as the WinRar format. \ No newline at end of file diff --git a/docs/engine/fileformats/roq.md b/docs/engine/fileformats/roq.md new file mode 100644 index 0000000..b6461f3 --- /dev/null +++ b/docs/engine/fileformats/roq.md @@ -0,0 +1,30 @@ +--- +layout: default +title: RoQ (.roq) +parent: File Formats +grand_parent: Engine Documentation +nav_order: 8 +--- + +# Overview + +--- + +RoQ is a video file format that originated in [The 11th Hour game.](http://en.wikipedia.org/wiki/The_11th_Hour_(computer_game)) After Graeme Devine, the creator of the format joined id Software, the RoQ file format has been in use in every game the company has released such as Quake III, Return to Castle Wolfenstein and DOOM 3. As it applies to id Tech 4, these files are used for video sequences and animated materials and are stored in `/base/video`. + +# Technical details + +--- + +The format runs at a fixed 30 frames per second with an optional `22050 Hz` mono or stereo sound track. Videos may technically be up to `65520 x 65520` pixels with both dimensions divisible by 16 and produce a valid RoQ file, but none of id Software’s games will play back a video with dimensions that aren’t a power of two, most likely because of OpenGL’s texture sizing restrictions. + +{: .note} +> It’s been reported that movies with dimensions greater than `512 x 512` cause issues in various id Software games. Until this can be positively confirmed or denied it’s best to avoid higher resolutions. + +RoQ is a motion compensating vector quanitizer format, similar to Cinepak, but higher quality due to the use of the ITU-R BT.601 colorspace (the same one used in component video, PAL televisions, JPEG and MPEG), whereas Cinepak uses a low-quality YUV-like colorspace designed for faster decoding that often results in gamut degradation before compression even begins. + +Because it’s a vector quantizer, RoQ files are very fast to decode and very slow to encode. Decoding involves nothing more than converting the colorspace of the codebooks and then copying data, whereas encoding involves using several complicated schemes to produce a “palette” of image fragments that will result in the least degradation. + +RoQ uses two codebooks per frame, with the second being constructed from pieces of the first, with up to 256 entries each. Due to this, only 1024 new colors can be introduced each frame, severely limiting the color gamut. This could arguably be improved by better predicting which sections will be motion compensated, but doing so is difficult, since codebook entries are generated from non-motion-compensated image sections, but whether or not they’ll be used depends on the quality of them compared to motion compensated sections, resulting in a chicken-and-egg problem. This is made worse by the fact that all three major RoQ codecs are single-pass. + +While the format is limited and much lower quality than MPEG and Indeo Video, it was presumedly preferred by id Software because of the lack of royalties, the lack of patent liability that presents a serious problem with most video formats, and the absence of complex platform-specific APIs. \ No newline at end of file diff --git a/docs/wolf09/binarization.md b/docs/wolf09/binarization.md new file mode 100644 index 0000000..630ac9f --- /dev/null +++ b/docs/wolf09/binarization.md @@ -0,0 +1,6 @@ +--- +layout: default +title: File Binarization +parent: Wolfstein (2009) +nav_order: 1 +--- diff --git a/docs/wolf09/wolf09_index.md b/docs/wolf09/wolf09_index.md new file mode 100644 index 0000000..c2ae471 --- /dev/null +++ b/docs/wolf09/wolf09_index.md @@ -0,0 +1,17 @@ +--- +layout: default +title: Wolfstein (2009) +nav_order: 5 +has_children: true +--- + +# Wolfstein (2009) +{: .fs-9 } + +Wolfstein (2009) is a loosely sequel to Return To The Castle Wolfenstein. +{: .fs-6 .fw-300 } + +--- + +{: .warning } +> This is a **WIP** Wiki. \ No newline at end of file