Use of atlases

July 4, 2022

Use of atlases

Usually, when we use images in UI, it is more convenient to use separate images, but the rendering efficiency of a single image is low. To improve runtime performance, we also support the use of atlases in the UI.

An atlas usually refers to combining multiple pictures into a large picture, and generating a description file, which is used to describe the name, size, position, etc. of the sub-pictures.

Package Atlas

Currently, the editor supports creating new atlases, and supports the use of images in atlases. Open the editor, import the image resources that need to be packaged into the editor, find the new atlas in the editor resource manager, or right-click the blank space under the atlas directory to be packaged


Select the image resources that need to be packaged into an atlas, adjust the appropriate atlas packaging method, and click OK


At present, the editor supports creating new atlases and packaging atlases. You need to use the third-party tool “TexturePacker” to pack atlases. The following operations take “TexturePacker” as an example:

  1. Open the TexturePacker software and choose the free version or the professional version according to your personal situation.
  2. Drag the pictures to be packaged or the folder where the pictures are located into the TexturePacker software.
  3. In the settings panel on the right, set the data format of the output file to “JSON (Hash)”.
  4. Set Border Fill and Shape Fill to 2.
  5. Click “Publish Sprite Sheet” to export the merged image and json data file.


1.Modifying the atlas file will render the atlas invalid.

2. The naming of atlas files is limited to English, numbers and underscores.

Atlas format conversion

The json file exported by TexturePacker cannot be directly read by the engine, and the json file needs to be converted into an imageset file.

clickhereDownload the atlas conversion tool, unzip it after downloading, and then follow the steps below to convert the file:

  1. Put the json file exported by TexturePacker into the import folder.
  2. Click run.bat and wait a moment.
  3. When it prompts “Please press any key to continue”, it means that the conversion is successful, just close the cmd window.
  4. After the conversion is completed, an imageset format file with the same name as the json file will be generated in the export folder. The imageset file is the atlas description file we need to use.

import atlas

Similar to importing other resources, you can import the atlas in the resource management panel.Note that you need to import images (.png files) and description files (.imageset files) at the same time


Note: Please do not modify the names of the pictures and description files after importing, otherwise the pictures in the atlas will not be read.

Use the atlas

Selecting an atlas is similar to selecting a picture. Next, take selecting a picture for the picture control as an example:

  1. Click the Image Selection button in the Properties panel:
  2. In the window for selecting resources, select the atlas to be used. You need to select the imageset file, not the png image:
  3. After clicking the OK button, the sub-picture selection window of the atlas will pop up, and this window will only list all the sub-pictures contained in the current atlas:
  4. Just select the image you want to use.