}
```
This is the header chunk of the original file. It is there intentionally, and **you must not touch it**. This data is critical for correctly serializing the file.
# Essential Tools
Tools you should use when making Dark Ages level mods.
### EntitySlayer
An editor for Doom Eternal and Dark Ages mapentities files. [Download EntitySlayer here.](https://github.com/FlavorfulGecko5/EntitySlayer/releases)
EntitySlayer has a number of useful tools that streamline the level modding process. Recent updates have added a diff-checking system that automates updating your level mods after a game update! Check out EntitySlayer's [README](https://github.com/FlavorfulGecko5/EntitySlayer/blob/master/README.md) for more information.
### Kaibz Mod
Kaibz Mod is the Dark Ages equivalent to Doom Eternal's Meathook mod. It adds a number of console commands useful to level modding. [Download Kaibz Mod here.](https://www.nexusmods.com/doomthedarkages/mods/27?tab=description)
| **Command** | **Description** |
| k\_spawninfo | Copies the player's spawnPosition and spawnOrientation to your clipboard.
This command is equivalent to `mh_spawninfo` from Doom Eternal's Meathook mod. Currently, this command only works when playing as the Slayer.
|
| k\_activeEncounters | Prints a list of active idEncounterManagers to the console. This is extremely helpful for figuring out what encounter managers are orchestrating the current combat encounter.
|
| k\_noclip | Toggles noclip
|
| k\_hotReload | See [Hot Reloading](https://wiki.eternalmods.com/books/dark-ages-modding/page/hot-reloading) for instructions on the proper usage of this command.
|
| setviewpos <x> <y> <z> | Teleports you to the desired location. The vanilla `teleportposition` command does not work in Dark Ages. Use this instead.
(This is a vanilla command, but it's included here for reference)
|
### Connecting EntitySlayer to Kaibz Mod
Doom Eternal's Meathook mod possesses an RPC interface. This lets other processes communicate with the game to execute console commands. EntitySlayer uses this interface to enable several convenient editor features, like setting an entity's spawnPosition from the player's current position.
Kaibz Mod offers equivalent functionality using a Windows Pipe interface. To enable this feature:
1. Launch the game, and open the Kaibz Mod menu by pressing the `F8` Key.
2. Open the `MISC.` menu. In that menu, set `Enable Mod Interface` to `YES`
3. You're good to go! Kaibz Mod saves your settings, so you don't need to turn the interface on every time you launch the game.
Kaibz Mod does not support every feature offered by Meathook. A small number of options in EntitySlayer still won't work because of this.
# Hot Reloading
How to use Atlan Mod Loader and Kaibz Mod to reload modded entities files without restarting the game.
This is an experimental feature. It may or may not be broken on Linux. If you attempt this procedure, please report whether it's successful or not.
The biggest problem with editing level mods is iteration time. Each time you want to test new changes, you must re-install the mod and restart the game. It's a time-consuming process that grinds down development. But with the power of Kaibz Mod and Atlan Mod Loader, this inconvenience can be eliminated!
#### Install Kaibz Mod
You must install [Kaibz Mod](https://www.nexusmods.com/doomthedarkages/mods/27?tab=description) to perform hot reloading! It is recommended you enable it's Mod Interface while developing level mods. See [Connecting EntitySlayer to Kaibz Mod](https://wiki.eternalmods.com/books/dark-ages-modding/page/essential-tools) to learn how to enable the mod interface.
#### Before Launching the Game
Atlan Mod Loader will engage "Hot Reload Mode" under the following conditions:
1. An **unzipped and unpackaged** .mapentities file exists in your mods folder.
2. No other mod files exist in your mods folder.
Let's say you want to edit the mission *Hebeth*. Your mods folder should look like this. **Do not add any files besides the mapentities.**
```
- Steam/steamapps/common/DOOMTheDarkAges/
- mods/
- hot_reload/
- mapentities@maps@game@sp@m2_hebeth@m2_hebeth.mapentities
```
Once this is setup, run Atlan Mod Loader and launch the game.
#### Reloading the File
Let's say you've made some changes to the Hebeth mapentities file and you're ready to reload it. Run the console command `k_hotReload` to reload the map!
Notes:
1. This may alt-tab you out of the game for several seconds. The alt-tabbing is most severe when running the game in `Full Screen` mode. If it gets annoying, try changing to `Borderless Windowed` mode.
2. You may notice a command prompt briefly pop up and close. This is Atlan Mod Loader running due to Kaibz Mod.
#### Quick Test
The first time you attempt hot reloading, you should do something simple to verify it works on your system. The following code snippet will place a floating text entity at the start of Hebeth.
1. Paste this into Hebeth's mapentities file. **Make sure you paste it somewhere AFTER submap 0's world entity.**
2. Edit the entity's `edit/headerText/text` property.
3. Trigger a hot reloading using the above procedure.
4. Verify that the text you see in-game has changed to reflect your edits.
```
entity 0 {
entityDef hot_reload_test {
inherit = "entityDef/gui/text";
expandInheritance = false;
editorVars = {
placeable = false;
}
systemVars = {
entityType = "idGuiEntity_Text";
}
edit = {
headerText = {
text = "Hot Reload Test!";
}
canvasFile = "ui/shapes/worldgui_text";
useSWFTransform = true;
swfScale = 0.016667;
spawnPosition = {
x = -1245.702881;
y = -1230.202271;
z = -77.942009;
}
spawnOrientation = {
mat = {
mat[0] = {
x = -0.000000;
y = -1.000000;
}
mat[1] = {
x = 1.000000;
y = -0.000000;
}
}
}
flags = {
noknockback = false;
}
renderModelInfo = {
model = "editors/models/gui_text.lwo";
scale = {
y = 15.000000;
}
}
clipModelInfo = {
type = "CLIPMODEL_NONE";
}
}
}
}
```
#### Reloading the File (Without Kaibz Mod)
Hot Reloading without Kaibz Mod is NOT RECOMMENDED! This section is here purely for documentation purposes! Please use the above method instead of this one!
To Hot Reload without using Kaibz Mod, perform the following steps:
1. Alt-Tab out of the game.
2. Run Atlan Mod Loader and wait for it to complete
3. Quit out to main menu, then load back into Hebeth using Mission Select.
4. The changes you've made to the file should be reflected in-game.
# MapExecutions Decls
Location: `rs_streamfile/generated/decls/mapexecution/`
These decls are new to idTech8, and define object pools for hundreds of different entity types. It's unknown how important they are compared to the `aipoolnumbers` decls. If you ever run into a problem with entities not spawning or the game crashing when too many of an entity are spawned, consider experimenting with these files.
# Dark Ages Audio Mods
### Getting Started
Make sure you've run [Atlan Resource Extractor](https://github.com/FlavorfulGecko5/EntityAtlan/releases/tag/Extractor) to extract audio files from the categories you wish to edit.
### Converting Your Audio Tracks
Dark Ages uses WEM OPUS encoding for all SFX and Music tracks. To convert your custom audio samples into this format, you must install and use WWise.
Follow [this guide](https://wiki.eternalmods.com/link/65#bkmrk-wwise-launcher-%28-mus) to learn how to do this, with the following adjustments
- When editing the Default Conversion Settings (step 2 of the linked guide): select "WEM Opus" as the format. Do **NOT** select "Vorbis".
- No other changes to the default conversion settings appear to be necessary. However, feel free to experiment and see if anything effects the quality of your audio when in-game.
### Naming Rules
The rules for naming your audio files are much different than the rules for naming other types of mod files. You'll notice in the extracted audio files, each sample has a number at the end of it's filename. For example:
```
audio/MUSIC/MUS_Combat_UnchainedPredator_Heavy_2_Main_B_105bpm_MIX_633792027.wav
```
Take note of the number `633792027` at the end of the name. This is the sample ID. Your modded audio files can be named anything, so long as:
1. The path begins with `audio/`
2. The name ends with the ID of an **existing** audio sample. (In theory, you *can* create entirely original samples. But then you'll need to edit the Sound Banks binaries to make the game use them. This is very complicated, and likely not worth the effort)
Anything in-between `audio/` and the sample ID does not matter. The file extension does not matter.
The following are all examples of valid modded audio sample paths. All of them modify the same sample. It is recommended that you give your custom samples an easily identifiable name, that clearly illustrates what sample is being replaced.
```
audio@633792027 .wem
audio@My_Cool_Sample_633792027.wem
audio/music/unchained_heavy_2_main_b_633792027.wem
```
# Dark Ages Texture Mods
### Getting Started
Creating texture mods requires the following resources:
1. [Atlan Resource Extractor](https://github.com/FlavorfulGecko5/EntityAtlan/releases/tag/Extractor) - Use this to extract material2 decls from the game. These plaintext files define the game's materials and directly reference image assets.
2. [Valen](https://github.com/jandk/valen/releases) - A resource extractor that can extract vanilla image files from the game. Atlan Resource Extractor does *NOT* support extracting textures. Use this instead.
3. [Atlan Mod Packager](https://github.com/FlavorfulGecko5/EntityAtlan/releases/tag/Extractor) - Packages your custom texture PNG files into a format the game recognizes. This is a necessary step to reduce mod loading times, as converting the images is an expensive process. You must use Atlan Mod Packager to prepare your finished texture mods for distribution
4. [Mod Config File](https://wiki.eternalmods.com/link/267#bkmrk-mod-config.-file) - It is *highly recommended* you use the aliasing system provided by your mod's configuration file! Image files have long names that don't clearly describe what piece of a mesh they're for! The aliasing system is helpful for organization, and prevents you from needing to change the extension on your PNGs to match the vanilla filename!
Supplemental resources may also exist for common areas of texture modding:
1. Custom Slayer Skins: Check out Kuddly Kraken's [Creation Kit](https://www.nexusmods.com/doomthedarkages/mods/132?tab=description)
### Assembling Your Mod Zip
All image mods must have `image/` at the beginning of their filepath (or configuration alias). After this, simply recreate the path of the image file you want to replace. **This includes the extension properties.** For Example:
```
image/models/customization/characters/doomslayer/set_b/1001/doomslayer_set_b_torso_1001.tga$streamed$mtlkind=albedo
image/models/customization/characters/doomslayer/set_b/1001/doomslayer_set_b_torso_1001.tga
```
Path #1 refers to a vanilla image file. However, Path #2 does not exist and the game will not recognize your image. **Extension metadata is important! It must be recreated perfectly when you want to replace an existing image.**
As with other resource types, an `@` or a `\` can be used in place of a `/` character.
##### Aliasing
As you can see, these image names grow long and complicated very quickly. The aliasing system can alleviate this problem. Lets say we have an image called `helmet_doodles.png` and we want it to replace the above image. Using our config aliasing system:
```
aliasing = {
"helmet_doodles.png" = "image/models/customization/characters/doomslayer/set_b/1001/doomslayer_set_b_torso_1001.tga$streamed$mtlkind=albedo"
}
```
This is equivalent to renaming your PNG to that filepath.
##### Developing and Packaging
Rinse and repeat this process until you've built out your entire texture mod folder. When you're ready to ship, run AtlanModPackager to package it into a zip file ready for loading your mods!
While developing and testing your mod, remember to take advantage of Atlan Mod Loader's [unzipped mod loading capabilities.](https://wiki.eternalmods.com/link/267#bkmrk-unzipped-mod-folders)
##### Sample Mod
The following link takes you to a sample mod implementing the above example! It uses the aliasing system to replace the Nightmare Slayer skin's helmet texture! To test this mod:
1. Download and unzip it's contents
2. Run AtlanModPackager on the unzipped folder
3. Use Atlan Mod Loader to load the newly created mod!
[Google Drive Link](https://drive.google.com/file/d/11lEZWkEFLLYPT4fgFZpGKjC6azsEk9Cw/view?usp=sharing)
### Adding New Images
Adding original images to the game is more complicated than replacing existing textures. Please pay careful attention to all of the information in this section. If all you're doing is replacing existing textures, you can skip this section
If you want to add an original image to the game, instead of replacing an existing image, you'll need to follow several more steps:
1. Reference your new images inside one (or multiple) material2 decls.
2. Determine the correct extension properties for your image
3. Specify your image's encoding information. This step is not always necessary depending on the image.
##### Material2 Decls
Once you've loaded your new image assets into the game, you must reference them in one or more material2 decls! You can edit a vanilla decl to use your texture, or create an entirely new material2 to reference in other files. As the mod author, you make the design decisions!
##### Extension Properties
When deciding the asset name of your new image, you can choose any unique name:
```
image/my_awesome_image.tga
image@your_username_here@your_modname_here@image_1.tga
image/cool_skin/helmet/helmet_albedo.png
```
However, the extension properties **must be written correctly.** If you fail to write them accurately, the game will not be able to find and load your modded image!
The exact type varies by the type of image you're adding, and by the inherited template of the material2 decl you're using it in. For example, if you're adding an albedo image, your extension properties should be `$streamed$mtlkind=albedo`
There is no exhaustive list of correct extension properties. The best way to be certain you're correct, is by studying the names of vanilla images produced by that particular material2 template. More obscure templates may require some trial and error to get the extension properties correct.
##### Encoding Information
When adding a new image, Atlan requires two key pieces of information: the image format (i.e. BC7, BC1, etc.) and the material type (i.e. albedo, normal, specular, etc.)
For *most* cases, you probably won't need to worry about this. Atlan will analyze the extension properties discussed above, and correctly deduce these settings. However, there are cases where the extension properties are insufficient for multiple reasons:
1. Ambiguity: Depending on the material template, the format cannot be determined with absolute certainty! For example an image with properties `$streamed$mtlkind=blendmask` can use different formats depending on the material type!
2. Absence: Some material templates omit extension properties from their images entirely!
3. In very rare cases, the extension properties may flat-out lie about the type or format used.
In these circumstances, you must specify the correct type and format by adding them to the end of the image name (or alias name, if it has an alias). For Example:
```
aliasing = {
"my_blendmask.png" = "image/my_blendmask.tga$streamed$mtlkind=blendmask~FMT_BC7~TMK_BLENDMASK"
}
```
As you can see, the format is `~FORMAT_CODE~MATERIAL_TYPE_CODE`
The following code block lists all possible values for these fields. Determining the correct values for a given image may take some careful analysis, depending on the material template.
```c++
enum textureMaterialKind_t {
TMK_NONE = 0,
TMK_ALBEDO = 1,
TMK_SPECULAR = 2,
TMK_NORMAL = 3,
TMK_SMOOTHNESS = 4,
TMK_COVER = 5,
TMK_SSSMASK = 6,
TMK_COLORMASK = 7,
TMK_BLOOMMASK = 8,
TMK_HEIGHTMAP = 9,
TMK_DECALALBEDO = 10,
TMK_DECALNORMAL = 11,
TMK_DECALSPECULAR = 12,
TMK_LIGHTPROJECT = 13,
TMK_PARTICLE = 14,
TMK_DECALHEIGHTMAP = 15,
TMK_AO = 16,
TMK_UNUSED_3 = 17,
TMK_UI = 18,
TMK_FONT = 19,
TMK_LEGACY_FLASH_UI = 20,
TMK_UNUSED_4 = 21,
TMK_BLENDMASK = 22,
TMK_PAINTEDDATAGRID = 23,
TMK_COUNT = 24,
};
enum textureFormat_t {
FMT_NONE = 0,
FMT_RGBA32F = 1,
FMT_RGBA16F = 2,
FMT_RGBA8 = 3,
FMT_RGBA8_SRGB = 32,
FMT_ARGB8 = 4,
FMT_ALPHA = 5,
FMT_L8A8_DEPRECATED = 6,
FMT_RG8 = 7,
FMT_LUM8_DEPRECATED = 8,
FMT_INT8_DEPRECATED = 9,
FMT_BC1 = 10,
FMT_BC1_SRGB = 33,
FMT_BC1_ZERO_ALPHA = 54,
FMT_BC3 = 11,
FMT_BC3_SRGB = 34,
FMT_BC4 = 24,
FMT_BC5 = 25,
FMT_BC6H_UF16 = 22,
FMT_BC6H_SF16 = 36,
FMT_BC7 = 23,
FMT_BC7_SRGB = 35,
FMT_DEPTH = 12,
FMT_DEPTH_STENCIL = 13,
FMT_DEPTH16 = 31,
FMT_X32F = 14,
FMT_Y16F_X16F = 15,
FMT_X16 = 16,
FMT_Y16_X16 = 17,
FMT_RGB565 = 18,
FMT_R8 = 19,
FMT_R11FG11FB10F = 20,
FMT_R9G9B9E5 = 57,
FMT_X16F = 21,
FMT_SMALLF = 60,
FMT_MAINVIEW_SMALLF = 61,
FMT_RG16F = 26,
FMT_R10G10B10A2 = 27,
FMT_RG32F = 28,
FMT_R32_UINT = 29,
FMT_RG32_UINT = 58,
FMT_R16_UINT = 30,
FMT_R8_UINT = 55,
FMT_ASTC_4X4 = 37,
FMT_ASTC_4X4_SRGB = 38,
FMT_ASTC_5X4 = 39,
FMT_ASTC_5X4_SRGB = 40,
FMT_ASTC_5X5 = 41,
FMT_ASTC_5X5_SRGB = 42,
FMT_ASTC_6X5 = 43,
FMT_ASTC_6X5_SRGB = 44,
FMT_ASTC_6X6 = 45,
FMT_ASTC_6X6_SRGB = 46,
FMT_ASTC_8X5 = 47,
FMT_ASTC_8X5_SRGB = 48,
FMT_ASTC_8X6 = 49,
FMT_ASTC_8X6_SRGB = 50,
FMT_ASTC_8X8 = 51,
FMT_ASTC_8X8_SRGB = 52,
FMT_DEPTH32F = 53,
FMT_RGBA16_UINT = 56,
FMT_RG16_UINT = 62,
FMT_RGBA16 = 59,
FMT_NEXTAVAILABLE = 63,
};
```
# Dark Ages Font Mods
### Overview
DOOM: The Dark Ages uses Slug Fonts to render in-game text.
To get a list of all slug font files, use [Atlan Resource Extractor](https://github.com/FlavorfulGecko5/EntityAtlan/releases/tag/Extractor) to extract resources of type `slug_font`
To load your custom slug font:
1. Get your desired font file (a .ttf or a .otf)
2. Download the Slug Font Demo at [https://sluglibrary.com/ ](https://sluglibrary.com/)and use it to convert your font file to a .slug
3. Rename your .slug to the name of the font resource you want to replace. You can leave the file extension as .slug, as the mod loader will ignore it.
For English Characters:
1. UI text uses `slug_font/cantoria_regular` and `slug_font/cantoria_semibold`.
2. Subtitles use `slug_font/calibri`
Many of the custom HUDs introduced in Dark Ages also have their own dedicated font files.