2D
Sprite Atlas
SpriteAtlas is a texture atlas resource designed to optimize 2D rendering performance by merging multiple sprite textures for batch rendering. Key benefits include:
✅ Performance Boost: Reduce Draw Calls and improve rendering efficiency
✅ Resource Optimization: Consolidate fragmented textures to minimize network requests
✅ Memory Management: Decrease GPU memory overhead caused by frequent texture switching
- Path: Assets Panel > Right-click Context Menu >
Create > Sprite Atlas
- Action: A blank atlas asset will be created and can be configured in the Inspector.
| Method | Steps |
|---|
| Via Sprite Asset | 1. Select target sprite 2. Inspector > Packaging > Choose atlas |
| Via Atlas Asset (Batch) | 1. Select target atlas 2. Inspector > Click Add Sprites (Supports folder batch operations) |
| Method | Steps |
|---|
| Via Sprite Asset | Inspector > Packaging > Click remove icon |
| Via Atlas Asset | Inspector > Sprite List > Locate target sprite > Click remove icon |
| Parameter | Description | Valid Range |
|---|
| Max Texture Width | Output texture width constraint (Must be power of 2) | (1, 2048] |
| Max Texture Height | Output texture height constraint (Must be power of 2) | (1, 2048] |
| Padding | Empty pixels between sprites to prevent edge bleeding | ≥0 |
| Allow Rotation | Rotate sprites to improve space utilization (Experimental, disabled) | true/false |
| Trim Transparency | Automatically remove transparent areas (Experimental, disabled) | true/false |
Oversize Warning: If packed size exceeds limits, adjust max width/height or reorganize sprites.
| Parameter | Options |
|---|
| Wrap Mode U/V | Clamp / Repeat / Mirror |
| Filter Mode | Point / Bilinear / Trilinear |
| Anisotropic Level | Anisotropic filtering level (1-16) |
| Generate Mipmaps | Enable Mipmap chain generation |
# Install globally
npm i @galacean/tools-atlas -g
# Package assets (Example: input dir=assets, output name=ui_atlas)
galacean-tool-atlas p assets -o ui_atlas
| Parameter | Description | Default |
|---|
-f/--format | Output format (galacean only) | galacean |
-mw/--maxWidth | Max texture width | 1024 |
-mh/--maxHeight | Max texture height | 1024 |
-p/--padding | Pixel padding between sprites | 1 |
📘 Full Parameter Docs
// Load atlas
engine.resourceManager.load<SpriteAtlas>({
url: "https://cdn.com/ui_atlas.atlas",
type: AssetType.SpriteAtlas
}).then((atlas) => {
// Get all sprites
const allSprites = atlas.sprites;
// Retrieve by exact name
const heroSprite = atlas.getSprite("hero_idle");
// Batch retrieve duplicates
const coinSprites = atlas.getSprites("coin", []);
});
Ensure atlas files (.atlas and .png) reside in the same CDN directory, e.g., https://cdnDir/atlasName.atlas and https://cdnDir/atlasName.png.
- Size Planning: Set reasonable max dimensions (e.g., 1024x1024) to avoid oversizing.
- Preview Utilization: Use
Pack & Preview to check space efficiency (Aim ≥80%).
| Core Class | Key Methods/Properties | Description |
|---|
SpriteAtlas | sprites: Sprite[] | All sprites in the atlas |
| getSprite(name: string) | Get first sprite by name |
| getSprites(name: string) | Get all sprites with matching name |
