Modding:Texture Atlas

Each texture is a relatively small image. Multiple of those small images are combined together into a large image called a texture atlas (called a sprite sheet in some games).

Benefits

A MeshData is mostly a list of triangles to draw on the screen. When the triangles are rendered on the screen, they are filled in with parts of a texture image. If two MeshDatas for different objects use the same texture, then they can be appended together with MeshData.AddMeshData such that the resulting mesh draws both objects. This reduces the number of meshes that need to be sent to the video card, and the number of times the video card has to switch textures.

If all of the block textures fit into a single texture atlas, then the meshes for all of the tessellated blocks in the chunk can be combined into a single MeshData for the chunk. More generally, if n texture atlases are used for the block textures, then each block produces n meshes, which are appended to the corresponding n meshes for the chunk.

Texture atlas types

Block

Holds the textures used by all blocks. Accessed through ICoreClientAPI.BlockTextureAtlas.

Item

Holds the textures used by all items. Accessed through ICoreClientAPI.ItemTextureAtlas.

Entity

Holds the textures used by all items. Accessed through ICoreClientAPI.EntityTextureAtlas.

Texture atlas size

The texture atlas size is configured with the "maxTextureAtlasWidth" and "maxTextureAtlasHeight" settings in VintagestoryData/clientsettings.json. As of 1.19.0-pre.2, the default texture atlas size is 4096x2048. The size can also be set to 8192x8192 by installing the Bigger Texture Atlas mod.

If the size is set too large, some video cards will be unable to process the textures.

Exporting the texture atlas

Each texture atlas type can be exported to png images using the .debug exptexatlas [block|item|entity] command. The command will make 1 or more png images in the vintagestory directory.

Support for multiple texture atlases

Only allowing a single texture atlas for each of the 3 types, with a limited size for that atlas, limits the number of block textures that can be added by mods. A solution would be to support multiple texture atlases for each type.

As of 1.18.15, there is a lot of code for that, but it does not work properly. When the texture atlas fills up, a new one is created. However, it does not render properly. The rendered textures seem to come from the first texture atlas. Also, if there are multiple atlases for the same type, then the .debug exptexatlas command will dump multiple copies of the first atlas, instead of dumping each one.