2D
精灵图集
概述
SpriteAtlas 是用于优化2D渲染性能的图集资源，通过合并多个精灵纹理实现批量绘制，核心优势包括：
✅ 性能提升：减少DrawCall数量，提升渲染效率
✅ 资源优化：合并碎片化纹理，降低网络请求次数
✅ 内存管理：减少纹理切换带来的GPU内存开销
编辑器使用
创建图集资源
- 路径：资产面板 > 右键菜单 >
创建>精灵图集 - 操作：创建后生成空白图集资产，可在检查器配置属性
管理精灵成员
添加精灵
| 操作方式 | 步骤说明 |
|---|---|
| 通过精灵资产添加 | 1. 选择目标精灵 2. 检查器面板 > 从属关系 > 选择目标图集 |
| 通过图集资产批量添加 | 1. 选择目标图集 2. 检查器面板 > 点击添加精灵（支持文件夹批量操作） |
移除精灵
| 操作方式 | 步骤说明 |
|---|---|
| 通过精灵资产移除 | 检查器面板 > 从属关系 > 点击移除图标 |
| 通过图集资产移除 | 检查器面板 > 精灵列表 > 定位目标精灵 > 点击移除图标 |
图集配置参数
打包设置
| 参数 | 说明 | 取值范围 |
|---|---|---|
| 纹理最大宽度 | 输出纹理宽度限制 | (1, 2048] |
| 纹理最大高度 | 输出纹理高度限制 | (1, 2048] |
| 边缘填充 | 打包精灵的边缘填充宽度 | ≥0 |
| 允许旋转 | 启用精灵旋转提升空间利用率（实验性功能，暂未开放） | true/false |
| 空白裁减 | 自动移除透明区域优化空间利用（实验性功能，暂未开放） | true/false |
超限警告：若打包后尺寸超过限制，需调整最大宽高或重新编排精灵。
纹理参数设置
| 参数 | 可选值 |
|---|---|
| Wrap Mode U/V | Clamp（截取）/ Repeat（重复）/ Mirror（镜像） |
| Filter Mode | Point（点过滤）/ Bilinear（双线性）/ Trilinear（三线性） |
| Aniso Level | 各向异性过滤等级（1-16） |
| Generate Mipmaps | 是否生成Mipmap链 |
脚本开发指南
命令行打包工具
# 全局安装工具包
npm i @galacean/tools-atlas -g
# 执行打包（示例：输入目录为assets，输出名为ui_atlas）
galacean-tool-atlas p assets -o ui_atlas| 属性 | 解释 |
|---|---|
| f/format | 打包输出的精灵图集格式 (默认: "galacean") |
| o/output | 打包输出的精灵图集文件名 (默认: "galacean") |
| a/algorithm | 打包精灵图集的算法 (默认: "maxrects") |
| ar/allowRotate | 打包精灵图集是否支持旋转 (默认: false) |
| p/padding | 图集中每个精灵和这个精灵边框的距离 (默认: 1) |
| mw/maxWidth | 最后打包出的精灵图集的最大宽度 (默认: 1024) |
| mh/maxHeight | 最后打包出的精灵图集的最大高度 (默认: 1024) |
| s/square | 强制打包成正方形 (默认: false) |
| pot | 宽高强制打包成 2 的幂 (默认: false) |
📘 完整参数文档
运行时加载使用
// 加载图集资源
engine.resourceManager.load<SpriteAtlas>({
url: "https://cdn.com/ui_atlas.atlas",
type: AssetType.SpriteAtlas
}).then((atlas) => {
// 获取全部精灵
const allSprites = atlas.sprites;
// 按名称精确查询
const heroSprite = atlas.getSprite("hero_idle");
// 批量查询同名精灵
const duplicateSprites = atlas.getSprites("coin", []);
});上传图集图片和图集文件至 CDN 同一目录下，例如文件和图片的地址应分别为
https://*cdnDir*/*atlasName*.atlas 和 https://*cdnDir*/*atlasName*.png。最佳实践
图集优化技巧
- 尺寸规划：控制打包资源尺寸，预设合理最大宽高（推荐1024x1024），避免纹理尺寸超标
- 预览调整：通过
打包并预览功能查看利用率（建议≥80%）
API参考
| 核心类 | 关键方法/属性 | 说明 |
|---|---|---|
SpriteAtlas | sprites: Sprite[] | 获取图集内全部精灵 |
getSprite(name: string) | 按名称获取单个精灵（若存在同名，返回第一个） | |
getSprites(name: string) | 按名称获取所有同名精灵 |