Skip to main content

Atlan Texture Modding

Documentation on creating texture mods with Atlan. This information applies to both DOOM: The Dark Ages and DOOM: Eternal. For DOOM: Eternal, it's preferable to create texture mods using idStudio. If you can't use idStudio, this guide offers an alternative approach.

Getting Started

Creating texture mods requires the following resources:

  1. Atlan Resource 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 - 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 - Packages your custom texture PNG files into a format the game recognizes. You must use Atlan Mod Packager to prepare your finished texture mods for distribution
  4. Mod Config File - When adding new images, it is highly recommended you use the aliasing system provided by your mod's configuration file! 

Supplemental resources may also exist for common areas of texture modding:

  1. Dark Ages Slayer Skins: Check out Kuddly Kraken's Creation Kit

Workflow Overview

This is a basic overview of how to create a texture mod:

  1. Assemble your modded textures using the techniques described below. Your finalized images must be PNGs.
  2. When you're ready to publish your mod, use Atlan Mod Packager to package it into a zip file! This step is required. Atlan Mod Loader will not convert PNGs it finds in zip files. It expects zipped images to be converted in-advance. This is necessary for having reasonable mod loading times, as converting images is an expensive process.

While developing and testing your mod, remember to take advantage of Atlan Mod Loader's unzipped mod loading capabilities. This should reduce iteration time.

Replacing Existing Images

Replacing existing images is more convenient than adding original images to the game. This approach requires Valen v0.3.3 or higher (see above). Image replacement should be sufficient for the majority of texture mods.

First, use Valen to browse the game files for the images you want to replace. Export your images. You'll notice that the names of the exported images have the format: name#<16-character-code>.png

The #<code> is important! Atlan detects that code and uses it to determine the correct asset path for your image. This way you don't need to recreate the entire original image path, which is often very long and complicated!

In your mod's folder, your image should have the path image/<...>#<code>.png 

The actual path or name before the #code does not matter. All that matters is the path start with image/ and the name ends with #<code>. Remember: do not modify the code

// Some Examples: Both of these paths refer to the same image with code #1234567812345678
image/art/models/characters/doomslayer/torso/1001/doomslayer_torso_1011#1234567812345678.png
image/my_cool_slayer_mod#1234567812345678.png

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:

// Remember: The modloader converts '@' symbols into '/' symbols
image/my_awesome_image.png$streamed$mtlkind=albedo
image@your_username_here@your_modname_here@image_1.png$streamed$mtlkind=albedo
image/cool_skin/helmet/helmet_albedo.png$streamed$mtlkind=albedo

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 extension properties vary 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 won't need to worry about this. Atlan analyzes the extension properties discussed above to deduce these values. 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. The following snippet shows the formats with examples

// Version 1: ~FORMAT_CODE~MATERIAL_TYPE_CODE
"image/my_blendmask.tga$streamed$mtlkind=blendmask~FMT_BC7~TMK_BLENDMASK"

// Version 2: Uses the optional third parameter: ~FORMAT_CODE~MATERIAL_TYPE_CODE~REAL_FORMAT_CODE
"image/my_blendmask.tga$streamed$mtlkind=blendmask~FMT_BC7~TMK_BLENDMASK~FMT_BC7_SRGB"

As you can see, there are two formats:

  1. ~FORMAT_CODE~MATERIAL_TYPE_CODE
  2. ~FORMAT_CODE~MATERIAL_TYPE_CODE~REAL_FORMAT_CODE

Format #2 is for very rare circumstances. There are times where the game encodes an image one way, while the extension properties and image metadata both claim it's encoded in another way! If your image does not render correctly in-game and you've exhausted all other possibilities, try format #2. Otherwise, Format #1 will be enough.

Aliasing System

When adding new image files, their extension data quickly grows long and complicated. You may choose to use the mod config file's aliasing system to alleviate this problem. This way, instead of including the extension information in the filename itself, you may specify it in the config file. 

// Example of using the aliasing system on a new image file
aliasing = {
    "image/helmet_doodles.png" = "image/helmet_doodles.png$streamed$mtlkind=albedo~FMT_BC1_SRGB~TMK_ALBEDO"
}

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.

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,
};

No comments to display