Sprite Atlas

SpriteAtlas is a collection of sprite resources that combines multiple sprite textures into a single sprite atlas to merge draw calls during rendering. It has the following advantages:

• Better performance (merged draw calls);
• Less video memory (packing algorithm reduces texture size);
• Fewer requests (reduces the number of load requests by reducing fragmented files);

In the example of the sprite atlas below, only one draw call is made per frame:

Editor Usage

Creating a Sprite Atlas

Right-click in the Assets Panel, select Create from the Function List, and choose Sprite Atlas. At this point, a blank sprite atlas asset is successfully created.

Select the Sprite Atlas asset to view detailed information about the asset in the Inspector Panel.

Adding Sprites

After determining the inclusion relationship between the Sprite Atlas and the Sprite, you need to add the Sprite to the corresponding Sprite Atlas. This step can be achieved by operating the Sprite asset or by operating the Sprite Atlas asset. Next, we will practice both methods.

Method 1: Operating the Sprite

Left-click to select the Sprite asset to be added. In the Inspector Panel, find the sprite's Affiliation, and select Pack into Atlas to choose the Sprite Atlas asset you want to pack into.

Method 2: Operating the Sprite Atlas

Left-click to select the target Sprite Atlas asset. In the Inspector Panel, find the sprite list of the atlas, and select Add Sprite to choose the Sprite asset you want to pack. (If you select a folder, all sprites in the folder directory will be added)

Removing Sprites

Method 1: Operating the Sprite

Left-click to select the Sprite asset to be removed from the atlas. In the Inspector Panel, find the sprite's Affiliation (make sure the target atlas path matches), and click the remove button to remove the sprite from the target atlas.

Method 2: Operating the Sprite Atlas

Left-click to select the Sprite Atlas asset to be operated on. In the Inspector Panel, find the sprite list of the atlas, find the sprite object to be removed, and click the remove button.

Quick Operations on Sprites

After the Sprite asset is added to the Sprite Atlas, you can quickly operate the sprite in the Inspector Panel of the Sprite Atlas. Its properties will be synchronously modified in the Sprite asset.

Settings

Packaging Settings

If you encounter the following warning during packaging, it means that the size of the atlas exceeds the maximum width and height of the texture. You can solve this by adjusting the Max Texture Width and Max Texture Height or rearranging the scattered images for packaging.

Export Settings

Best Practices

Click on the Sprite Atlas asset, adjust the Max Texture Width and Max Texture Height in the Packaging Settings, and then call Pack and Preview in the Packaging Object to ensure a high level of atlas utilization.

The left side of the preview image shows the size information of the exported image, and the right side shows the atlas utilization information (representing the percentage of the total area of all scattered images occupying the final large image). You can adjust the packing settings based on this value to achieve better results.

Script Usage

Atlas Generation

Galacean provides a command-line tool for sprite atlas generation. Developers can generate an atlas by following these steps:

1. Install the package

npm i @galacean/tools-atlas -g

2. Execute the packing command

galacean-tool-atlas p inputPath -o outputName

Here, inputPath represents the path of the folder to be packed, and outputName represents the name of the output sprite atlas file. If you get the result shown in the image below, it means the packing was successful.

For more details, refer to Atlas Packing Tool.

Usage

1. Upload the atlas image and atlas file to the same directory on the CDN. For example, the addresses of the file and image should be https://*cdnDir*/*atlasName*.atlas and https://*cdnDir*/*atlasName*.png, respectively.

2. Load and use

engine.resourceManager
  .load<SpriteAtlas>({
    url: "https://*cdnDir*/*atlasName*.atlas",
    type: AssetType.SpriteAtlas
  })
  .then((atlas) => {
    // Get all sprites.
    const allSprites = atlas.sprites;
    // Get sprite by spriteName.
    atlas.getSprite("spriteName");
    // If multiple sprites have the same name, we can get all like this.
    const allSpritesWithSameName = atlas.getSprites("spriteName", []);
  });

Notes

1. Please pack sprites with connected drawing sequences into the same atlas to significantly improve performance (reduce the number of draw calls);
2. When cleaning up the sprite atlas, ensure that all sprites in the atlas are no longer in use;
3. When packing the sprite atlas, it is necessary to coordinate the number and size of sprites to avoid generating multiple sprite atlases in one packing session;