Textures

esx makes a Fallout 4 DDS file from a PNG or TGA image, with each mip level. It needs no external tool. esx does not show a texture. Examine the result in the game.

Each command that writes a file needs -o with a .dds path. An output file that exists needs --overwrite.

Read a DDS file

esx texture info Textures/Weapons/Pistol/Pistol_d.dds

{"file": "Textures/Weapons/Pistol/Pistol_d.dds", "bytes": 699192, "format": "BC1_UNORM", "dxgi": 71,
 "width": 1024, "height": 1024, "mip_levels": 11, "cube_map": false, "header": "legacy",
 "alpha_below_255": false}

alpha_below_255 is for the first mip level. A format with no alpha channel gives false. The value is null when esx cannot decode the format, for example an Xbox texture. To read a texture of the game, extract it first with esx resource extract.

Convert an image

esx texture convert Pistol_d.png -o Textures/Weapons/Pistol/Pistol_d.dds --role diffuse
esx texture convert Pistol_n.png -o Textures/Weapons/Pistol/Pistol_n.dds --role normal --flip-green

The role selects the format. These are the formats of the 173 vanilla weapon textures.

Role	File name	Format
diffuse	_d	BC1 (DXGI 71). BC3 (DXGI 77) when the image has alpha below 255.
normal	_n	BC5 (DXGI 83) with the red and green channels of the image.
specular	_s	BC5 (DXGI 83). Red is specular, green is glossiness.
raw	No rule	--texture-format is necessary.

Option	Function
--texture-format F	Use bc1, bc3, bc5, bc7 or bgra8 and not the format of the role. Each format is UNORM.
--mips auto	Write each level down to 1 pixel. This is the default.
--mips N	Write N levels. --mips 1 writes no smaller level.
--flip-green	Invert the green channel. Only for the role normal.
--half	Write half the width and half the height of the image.

The option is --texture-format, because --format is the output format of esx.

A normal map must have the DirectX convention. A map with the OpenGL convention needs --flip-green.

A mip level comes from the full image with a triangle filter on the stored values.

esx texture convert Pistol_d.png -o Pistol_bc7.dds --role diffuse --texture-format bc7 --half
esx texture convert Pistol_d.png -o Mask.dds --role raw --texture-format bgra8 --mips 1

The first command makes a BC7 file of 512 by 512 pixels with 10 mip levels from an image of 1024 by 1024 pixels.

Pack channels

A _s file has specular in the red channel and glossiness in the green channel. pack-channels makes it from one gray image for each channel:

esx texture pack-channels --red Specular.png --green Gloss.png -o Textures/Weapons/Pistol/Pistol_s.dds

The format is BC5. Each image must have the same size. A color image gives its luminance. Alpha is 255. BC5 has no blue channel, so --blue needs another format:

esx texture pack-channels --red Specular.png --green Gloss.png --blue Gloss.png -o Mask2.dds --texture-format bc7

Make a cube map

esx texture cubemap px.png nx.png py.png ny.png pz.png nz.png -o Textures/Shared/Cubemaps/Pistol_e.dds

The six images are the faces +X, -X, +Y, -Y, +Z and -Z, in this order. Each image must be square. Each face gets --size by --size pixels and each mip level. The default is the form of 44 of the 71 vanilla cube maps: B8G8R8A8 (DXGI 87), 128 pixels, 8 mip levels. Most of the other vanilla cube maps are BC1 with 32 pixels:

esx texture cubemap px.png nx.png py.png ny.png pz.png nz.png -o Small_e.dds --size 32 --texture-format bc1

Warnings

Code	Condition
TEXTURE_NOT_POWER_OF_TWO	The width or the height is not a power of two.
TEXTURE_SIZE_ODD	The format is BC1, BC3, BC5 or BC7, and the width or the height is not a multiple of 4.
TEXTURE_ALPHA_DROPPED	The format is bc1 and the image has alpha below 255. The file has no transparent pixel. Use bc3 or bc7 to keep the alpha.

esx writes the file with each of these warnings.

Pack the files

Put each file below Textures/ in the asset folder. esx build packs the DDS files into the Textures archive. By hand:

esx archive pack stage -o 'Pistol - Textures.ba2' --archive-format fo4-dds
esx archive check 'Pistol - Textures.ba2'

BC1, BC3, BC5 and B8G8R8A8 files get the 128 byte header, and BC7 files get the DX10 header. These are the headers that archive extract writes. A file is thus the same before archive pack and after archive extract.

See Archives and Meshes and materials.