Задача сборщика grunt
, для упаковки спрайтов в атласы и вывода мета-данных результата. Для упаковки используется пакет ovcharik/sprite-builder
.
Так как пакет не размещен в npm
репозитории, можно его поставить прямо из гитхаба. Для этого выболните следующую команду:
npm install --save-dev github:ovcharik/grunt-sprite-builder
Далее необходимо добавить задачу в Ваш Gruntfile
:
grunt.loadNpmTasks('grunt-sprite-builder');
Задача называется sprite-builder
(можно использовать и spriteBuilder
). Параметры исходных данных, параметры результата и опции нужно задавать в соответствии с руководством конфигурации задач в grunt
.
Необходимо указывать путь до директории(ий), в которой(ых) лежат спрайты (параметр: src
). Все спрайты из одной директории будут упакованы в один атлас. Результатом будет файл, имя которого складывается из имени директории со спрайтами и md5
хэш-суммы, исходных файлов, если опция hashname == true
(<src-folder>-<md5-hash>.png
), иначе записывается просто имя дирректории. Файл будет сохранен в указанной директории (параметр: dest
).
Пример
/*
* Допустим у нас есть такое дерево файлов:
* path/
* └─ to/
* ├─ single-atlas/
* │ ├─ sprite-0.png
* │ ├─ sprite-1.png
* │ ├─ ...
* │ └─ sprite-n.png
* ├─ multi-atlases/
* │ ├─ multi-atlas-0/
* │ ├─ multi-atlas-1/
* │ ├─ ...
* │ └─ multi-atlas-n/
* └─ results/
*/
// Зададим параметры для задачи
grunt.initConfig({
'sprite-builder': {
'single-atlas': {
src : 'path/to/single-atlas/', // путь до директории со спрайтами
dest: 'path/to/results/' // путь до директории, куда сохранится результат
},
'multi-atlases': {
src : 'path/to/multi-atlases/*/', // шаблон пути до директорий со спрайтами
dest: 'path/to/results/' // путь до директории, куда сохранится результат
}
}
});
/*
* Результат выполнения обеих задач будет таким:
* path/
* └─ to/
* ├─ single-atlas/
* ├─ multi-atlases/
* └─ results/
* ├─ single-atlas-<md5-hash>.png
* ├─ multi-atlas-0-<md5-hash>.png
* ├─ multi-atlas-1-<md5-hash>.png
* ├─ ...
* └─ multi-atlas-n-<md5-hash>.png
*/
<tr>
<td><strong><code>padding</code></strong></td>
<td>
Type: <code>Number</code><br/>
Default: <code>0</code>
</td>
<td>Расстояние в пикселях между спрайтами в атласе.</td>
</tr>
<tr>
<td><strong><code>trim</code></strong></td>
<td>
Type: <code>Boolean</code><br/>
Default: <code>true</code>
</td>
<td>Обрезка пустых краев спрайтов.</td>
</tr>
<tr>
<td><strong><code>hashname</code></strong></td>
<td>
Type: <code>Boolean</code><br/>
Default: <code>true</code>
</td>
<td>Добавление к имени итогового атласа <code>md5</code> хэш-сумму.</td>
</tr>
<tr>
<td><strong><code>cache</code></strong></td>
<td>
Type: <code>Boolean</code><br/>
Default: <code>true</code>
</td>
<td>Кеширование промежуточного результата, позволяет ускорить выполнение задачи при повторных запусках.</td>
</tr>
<tr>
<td><strong><code>cacheFile</code></strong></td>
<td>
Type: <code>String</code><br/>
Default: <code>".sprite‑builder‑cache.json"</code>
</td>
<td>Файл для хранения кешированной информации.</td>
</tr>
<tr>
<td><strong><code>filter</code></strong></td>
<td>
Type: <code>RegExp</code><br/>
Default: <code>/\.png$/i</code>
</td>
<td>Фильтр для имени файлов спрайтов, которые будут упаковываться в атлас. Все файлы, что не соответсвуют фильтру будут игнорироваться.</td>
</tr>
<tr>
<td><strong><code>templates</code></strong></td>
<td>
Type: <code>Object</code><br/>
Default: <code>{}</code>
</td>
<td>
Шаблоны для записи мета-данных. Подробнее.
Имя | Свойства | Описание |
---|---|---|
method |
Type: ("growing"|"vertival"|"horizontal") Default: "growing"
|
Метод упаковки спрайтов в атласы, доступны следующие:
|
Шаблоны указываются в обычном объекте, где ключ -- это название шаблона или путь до файла с шаблоном, а значние - это путь до файла, куда запишется результат. Шаблоны компилируются с помощью библиотеки mustache
.
Данные, передаваемые в шаблон
{
"files": [
{
"sprites": [
{
"name" : "sprite-0", // имя образуется из базового имени файла
"file" : "path/to/atlas-0/sprite-0.png", // путь до файла спрайта
"dest" : "path/to/atlas-0-<md5-hash>.png", // путь до атласа с этим спрайтом
"width" : 92, // ширина обрезанного спрайта
"height" : 104, // высота обрезанного спрайта
"offsetX" : 2, // x-координата верхнего левого угла спрайта с учетом padding'а
"offsetY" : 126, // y-координата верхнего левого угла спрайта с учетом padding'а
"canvasX" : 0, // x-координата верхнего левого угла спрайта без учета padding'а
"canvasY" : 112, // y-координата верхнего левого угла спрайта без учета padding'а
"frameWidth" : 108, // оригинальная ширина спрайта
"frameHeight" : 140, // оригинальная высота спрайта
"frameRegX" : 2, // x-координата верхнего левого спрайта до обрезки
"frameRegY" : 14, // y-координата верхнего левого спрайта до обрезки
"isFirst" : true, // первый спрайт в списке
"isLastSprite" : false // последний спрайт в списке
}
// [, <sprite-1> [, ...]]
],
"basename" : "atlas-0", // базовое имя атласа
"src" : "path/to/atlas-0/", // путь до исходной директории со спрайтами
"ext" : ".png", // расширение спрайтов
"name" : "path/to/atlas-0-<md5-hash>.png", // путь до атласа
"dest" : "path/to/atlas-0-<md5-hash>.png", // путь до атласа
"hash" : "62c0ab3a9443ca64848438d4c7fd219e", // md5-hash исходных файлов
"width" : 432, // ширина атласа
"height" : 280, // высота атласа
"spritesLength" : 8, // количество спрайтов в атласе
"isLastFile" : false // последний файл в списке
}
// [, <atlas-1> [, ...]]
]
}
Заготовленные шаблоны
Шаблон anim
(код)
Создает файл формата less
, в котором указанны переменные, описывающие параметры спрайтов, в дальнейшем эти переменные можно использовать для создания спрайтовой анимации на less
используя mixins
. Тут нужно учитывать, что данный шаблон используется для описания спрайтов упакованных в одну строку (method = "horizontal"
), что бы в дальнейшем можно было написать миксин для "проматывания" итогового атласа, и создания тем самым спрайтовой анимации. Формат:
@sprite-0_url : "./path/to/atlas-0-<md5-hash>.png";
@sprite-0_w : 1024px; // ширина атласа
@sprite-0_h : 128px; // высота атласа
@sprite-0_frames : 8; // количество спрайтов в атласе
@sprite-0_frame_w : 128px; // ширина одного спрайта
@sprite-0_frame_h : 128px; // высота одного спрайта
// [<sprite-1> [...]]
Шаблон json
(код)
В json
шаблон записывается необходимая информация о спрайтах. Формат:
{
"./path/to/atlas-0-<md5-hash>.png": {
"sprite-0": { // имя спрайта (базовое имя файла)
"w" : 128, // ширина (px) спрайта
"h" : 128, // высота (px) спрайта
"x" : 0, // x-координата (px) верхнего левого угла спрайта в атласе
"y" : 0 // y-координата (px) верхнего левого угла спрайта в атласе
},
// [, <sprite-1> [, ...]]
},
// [, <atlas-1> [, ...]]
}
Шаблон less
(код)
В less
шаблон записывается необходимая информация о спрайтах в виде переменных. Формат:
// atlas-0
@sprite-0_f: "./path/to/atlas-0-<md5-hash>.png";
@sprite-0_w: 128px; // ширина спрайта
@sprite-0_h: 128px; // высота спрайта
@sprite-0_x: -0px; // -x-координата верхнего левого угла спрайта в атласе
@sprite-0_y: -0px; // -y-координата верхнего левого угла спрайта в атласе
// [<sprite-1> [...]]