To build a tile set, lslib needs to know what textures to include in what layers. The tile set configuration XML is a descriptor that contains all information required to build and merge tile sets. (See below for a complete example)
The tile set needs a name; this can be any user-defined name. The generated GTS and GTP file names will take the form YOUR_TILESET_FILE_NAME.gts
and YOUR_TILESET_FILE_NAME_xxxx.gtp
.
<TileSet Version="2" Name="YOUR_TILESET_FILE_NAME">
The paths for where to read source textures from and where to put the generated virtual textures to needs to be defined in the tile set XML. These paths are relative to the root of your mod directory:
<Paths>
<SourceTextures>Public\YOUR_MOD_NAME\Assets\Textures</SourceTextures>
<VirtualTextures>Public\YOUR_MOD_NAME\Assets\VirtualTextures</VirtualTextures>
</Paths>
The tile set can contain an arbitrary number of textures. During tile set generation, the virtual texture is resized automatically to fit all source textures.
Each virtual texture has multiple source textures (layers), one source DDS file is required for each layer defined in the tile set.
For BG3, the number of layers is hardcoded to 3, called Albedo
, Normal
and Physical
. Note that character body textures still use the same layer names, despite not containing Albedo
and Physical
maps but rather HMVY
and CLEA
maps.
Source DDS files must satisfy following requirements:
- Mipmaps must be included in the .DDS file (make sure to check "Generate mipmaps" or the equivalent in your exporter)
- Texture must be at least 128x128
- Texture width and height must be a multiple of two (Note: width and height can differ, eg. a 1024x512 texture is allowed)
- Must use DXT5/BC3 format
DDS textures within the same virtual texture must have the same size ratio; eg. an Albedo
of 1024x1024 and a Normal
of 1024x512 is not allowed. However, their size can be a multiple of each other; eg. an Albedo
of 1024x1024 and a Normal
of 512x512 is allowed.
The texture name (Name="e05176c4ac30d5228d0c0452d938f699"
) is the GTex
name used in asset LSF files.
Layer name must be one of the 3 predefined names (Albedo
, Normal
or Physical
).
The Source path (Source="e05176c4ac30d5228d0c0452d938f699_0.dds"
) is relative to the SourceTextures
path defined above.
<Textures>
<Texture Name="e05176c4ac30d5228d0c0452d938f699"> <!-- GTex name -->
<Layer Name="Albedo" Source="e05176c4ac30d5228d0c0452d938f699_0.dds" />
<Layer Name="Normal" Source="e05176c4ac30d5228d0c0452d938f699_1.dds" />
<Layer Name="Physical" Source="e05176c4ac30d5228d0c0452d938f699_2.dds" />
</Texture>
In case a virtual texture only has two layers (eg. it has no Physical
map), the missing layer can be omitted and it will not be included in the generated tile set:
<Textures>
<Texture Name="e05176c4ac30d5228d0c0452d938f699">
<Layer Name="Albedo" Source="e05176c4ac30d5228d0c0452d938f699_0.dds" />
<Layer Name="Normal" Source="e05176c4ac30d5228d0c0452d938f699_1.dds" />
</Texture>
A complete sample XML:
<?xml version="1.0" encoding="utf-8"?>
<TileSet Version="2" Name="YOUR_TILESET_FILE_NAME">
<Paths>
<SourceTextures>Public\YOUR_MOD_NAME\Assets\Textures</SourceTextures>
<VirtualTextures>Public\YOUR_MOD_NAME\Assets\VirtualTextures</VirtualTextures>
</Paths>
<Textures>
<Texture Name="e05176c4ac30d5228d0c0452d938f699">
<Layer Name="Albedo" Source="e05176c4ac30d5228d0c0452d938f699_0.dds" />
<Layer Name="Normal" Source="e05176c4ac30d5228d0c0452d938f699_1.dds" />
<Layer Name="Physical" Source="e05176c4ac30d5228d0c0452d938f699_2.dds" />
</Texture>
<Texture Name="00fb1fe11e94bc9fad61170f5551017f">
<Layer Name="Albedo" Source="00fb1fe11e94bc9fad61170f5551017f_0.dds" />
<Layer Name="Normal" Source="00fb1fe11e94bc9fad61170f5551017f_1.dds" />
</Texture>
</Textures>
<Layers>
<Layer Name="Albedo" Type="R8G8B8A8_SRGB" />
<Layer Name="Normal" Type="X8Y8Z8W8" />
<Layer Name="Physical" Type="X8Y8Z8W8" />
</Layers>
<TileSetConfig>
<Compression>Best</Compression>
<OneFilePerGTex>false</OneFilePerGTex>
<BackfillPages>true</BackfillPages>
<DeduplicateTiles>true</DeduplicateTiles>
</TileSetConfig>
</TileSet>
After making the config XML, the tile set can be built either using the LSLib UI on the Virtual Textures tab, or by using the VTexTool.exe
cli using the parameters:
VTexTool.exe \<XML path\> \<Mod root path\>
(eg. VTexTool.exe "C:\Dev\MyMod\Mods\YOUR_MOD_NAME\VTexConfig.xml" "C:\Dev\MyMod"
)
To load custom .GTS files, Script Extender v12 or later is required (currently Devel
branch only).
The mod must include a configuration file at Mods\YOUR_MOD_NAME\ScriptExtender\VirtualTextures.json
that describes which GTex resource can be found in which .GTP file.
If you specify a GTexName that is already defined by the base game, the original GTex will be overridden by the new one. If you specify a GTexName that is defined by another mod, the mod that loads later will override the GTex of the one that loaded earlier.
{
"Mappings": [
{
"GTexName": "e05176c4ac30d5228d0c0452d938f699",
"GTS": "Public/YOUR_MOD_NAME/Assets/VirtualTextures/YOUR_TILESET_FILE_NAME.gts"
},
{
"GTexName": "00fb1fe11e94bc9fad61170f5551017f",
"GTS": "Public/YOUR_MOD_NAME/Assets/VirtualTextures/YOUR_TILESET_FILE_NAME.gts"
}
]
}
- Tile Set - A huge texture containing multiple sub-textures merged into one
- .GTS file - Graphine Tile Set file, containing a description of the tile set and the layout/position of all tiles and page files
- .GTP file - Graphine Tile Page file, containing the textures subdivided into equally sized chunks (tiles)
- GTex - A slice of the tile set containing only a specific source texture