UI Image Atlases

UI Image Atlases (uimg) are what the game uses to store multiple UI assets, they reference a single texture asset, known as the atlas and have an array of textures which defines the different usable UI assets.

Examples:

1. Basic UI Image Atlas with 2 Textures

{
    "$type":"uimg",
    "path":"rui/atlas/example1",
    "atlas":"rui/example1",
    "textures":
    [
        {
            "path":"rui/example1/texture1",
            "width":128,
            "height":128,
            "posX":0,
            "posY":0
        },
        {
            "path":"rui/example1/texture2",
            "width":128,
            "height":128,
            "posX":128,
            "posY":0
        }
    ]
}

Note

This UI Image Atlas expects a texture with the path of rui/example1 which is at least 256x128

2. Full Map File With a UI Image Atlas

{
    "name":"blue_fire",
    "assetsDir":"../depot",
    "outputDir":"../rpaks",
    "version": 7,
    "files":[
        {
            "$type":"txtr",
            "path":"rui/blue_fire"
        },
        {
            "$type":"uimg",
            "path":"rui/atlas/blue_fire",
            "atlas":"rui/blue_fire",
            "textures":[
                {
                    "path":"blue_fire/hud/flame_wall",
                    "width":128,
                    "height":128,
                    "posX":0,
                    "posY":0
                },
                {
                    "path":"blue_fire/menu/flame_wall",
                    "width":128,
                    "height":128,
                    "posX":128,
                    "posY":0
                },
                {
                    "path":"blue_fire/hud/flame_shield",
                    "width":128,
                    "height":128,
                    "posX":0,
                    "posY":128
                },
                {
                    "path":"blue_fire/menu/flame_shield",
                    "width":128,
                    "height":128,
                    "posX":128,
                    "posY":128
                }
            ]
        }
    ]
}

Note

This map file is a shortened version of the one used in EXRILL's Blue Fire mod

Asset Structure:

$type

For an asset to be a UI Image Atlas asset, the $type field must be "uimg".

path

The path field for a UI Image Atlas asset is mostly unused, and as such can be set to almost any value. It is used when logging information about the asset.

atlas

The atlas field for a UI Image Atlas asset determines which texture asset it will use.

Error

If the uimg asset doesn't contain a valid atlas field, RePak will output one of the following errors to the console:

Required field 'atlas' not found for uimg asset '%s'. Exiting...

'atlas' field is not of required type 'string' for uimg asset '%s'. Exiting...

where %s is the path field of the UI Image Atlas

Error

If the texture asset cannot be found, RePak will output the following message to the console before exiting:

Atlas asset was not found when trying to add uimg asset '%s'. Make sure that the txtr is above the uimg in your map file. Exiting..."

where %s is the path field of the UI Image Atlas

textures

The textures array in a UI Image Atlas asset defines the different UI textures that the atlas contains. Any number of UI textures may be contained within one UI Image Atlas.

path

An entry in the textures array must have a path field, as the game must use it to identify and show the texture.

Error

If the entry in the textures array doesn't contain a valid path field, RePak will output one of the following errors to the console:

Required field 'path' not found for a texture in uimg asset '%s'. Exiting...

'path' field is not of required type 'string' for a texture in uimg asset '%s'. Exiting...

where %s is the path field of the UI Image Atlas

width and height

An entry in the textures array must have both a width and a height field, these values should both be integers.

Error

If the entry in the textures array doesn't contain a valid width or a valid height field, RePak will output one of the following errors to the console:

Required field 'width' not found for texture '%s' in uimg asset '%s'. Exiting...

Required field 'height' not found for texture '%s' in uimg asset '%s'. Exiting...

'width' field is not of required type 'number' for texture '%s' in uimg asset '%s'. Exiting...

'height' field is not of required type 'number' for texture '%s' in uimg asset '%s'. Exiting...

where the first %s is the path field of the texture, and the second %s is the path field of the UI Image Atlas

posX and posY

An entry in the textures array must have both a posX and a posY field, these values should both be integers. These fields determine the location of the top-left pixel in the UI texture.

Error

If the entry in the textures array doesn't contain a valid posX or a valid posY field, RePak will output one of the following errors to the console:

Required field 'posX' not found for texture '%s' in uimg asset '%s'. Exiting...

Required field 'posY' not found for texture '%s' in uimg asset '%s'. Exiting...

'posX' field is not of required type 'number' for texture '%s' in uimg asset '%s'. Exiting...

'posY' field is not of required type 'number' for texture '%s' in uimg asset '%s'. Exiting...

where the first %s is the path field of the texture, and the second %s is the path field of the UI Image Atlas