Автоматическая сборка текстурных атласов с помощью Ant’a

Для того, чтобы упростить себе работу и не заглядывать в постоянно в GUI-инструмент при обновлении ресурсов приложения я воспользовался инструментом для командной строки Texture Packer‘a от Code And Web GmbH.

Для настройки автоматической сборки атласов нам понадобится сам Texture Packer (с лицензией, так как инструмент для коммандной строки не работает в триальной версии), Apache Ant и набор тасков для него ant-contrib.

Подготовка

Будем считать, что у вас уже есть Texture Packer и вы располагаете лицензией к нему.

  • Первым делом вам потребуется установить Ant, если он ещё не установлен.
    Для этого вам потребуется скачать бинарники (.zip archive), распаковать в любую удобную вам папку, желательно чтобы путь не содержал пробелов и кириллицы.

  • Следом обновляем переменную среды PATH и добавляем в неё полный путь к папке место_установки_ant\bin, например:
  • Также создаём новую переменную среды с именем ANT_HOME и добавляем в неё путь к папке место_установки_ant, например:
  • Далее нам нужны таски ant-contrib. Скачиваем и устанавливаем:
    Извлекаем файл ant-contrib/lib/ant-contrib.jar из архива и копируем его в в папку место_установки_ant\lib.

Всё должно быть готово к работе. Чтобы убедиться в том, что Ant установлен верно из командной строки в любом запустите команду “ant”, в случае если все пути и переменные среды прописаны верно, то Ant скажет вам, что билд-файл отсутствует. В ином случае он сообщит об ошибке – скорее всего переменная ANT_HOME прописана неверно или отсутствует. Если же команда не запустится вообще – то значит путь к папке bin Ant’a прописан неверно в переменной PATH

Автоматизация сборки атласов

Когда все приготовления закончены, можем приступать к написанию билд-файла.

Пример:

В проекте у нас имеется есть папка ассетов, со следующей структурой:

Свойства проекта сборки

Следовательно нам необходимо создавать и обновлять автоматически атласы для каждой из папок верхнего уровня, в данном примере board и ui.
В первую очередь необходимо создать файл со свойствами сборки build.properties

  • Каждая строка является парой ключ=значение.
  • Строки начинающиеся с “#” являются комментариями и не имеют особой ценности.
  • Переменные в Ant’е указываются в формате ${property}

Давайте рассмотрим каждую из строк с переменными:

В данной строке мы объявляем переменную packer, которая указывает на путь к утилите командой строки TexturePacker’a. Обратите внимание на то, что для путей используются обратные слэши.
В объявлении пути мы используем переменную среду %ProgramFiles% (которая определена по умолчанию в любой версии Windows) через использование переменной Ant’a ${env.ProgramFiles}. Мы можем отказаться от её использовать и использовать полный путь

Как можно догадаться в данных строках мы определяем переменные с путями для ассетов и ресурсов. Папка с ресурсами – это место куда будут складываться готовые атласы и их конфигурации.
Переменная ${basedir} содержит путь к базовой директории относительно которой будут производиться все действия. Данная переменная определяется Ant’ом по умолчанию как текущая (из которой запущен ant), если в билд-файле не указан другой путь.

Файл сборки

Если вы уже хорошо знакомы с Ant’ом, то пролистайте в конец статьи для того, чтобы просмотреть финальную версию build.xml.

Мы определили все необходимые нам свойства и можем приступить к написанию билд-файла. Он представляет собой обычный XML-файл с определенной семантикой.
Обычно он называется build.xml (именно этот файл ищет ant при запуске, если не указан другой через параметр -buildfile ), давайте создадим его.

Я не буду подробно останавливаться на синтаксисе задач Ant’a, лишь опишу кратко, что означают те или иные конструкции. Чтобы получить больше информации – воспользуйтесь очень подробной и интересной документацией. Также с помощью любого из поисковиков вы найдёте невероятное количество готовых решений от сообщества и ответы на любые свои вопросы.

Пока всё просто? Если нет, то давайте быстренько разберемся:

  • Определяем название проекта и задачу (default), которая будет выполняться если ant запущен без параметров
  • Подключаем таски из ant-contrib
  • В переменную “env” мы просим Ant’a записать все переменные среды, так чтобы можно было в процессе получать к ним доступ. Например, уже знакомые вам ${env.PATH} или ${env.ANT_HOME}
  • Загружаем дополнительные переменные, которые мы определили раньше, из файла build.properties
  • Создаем новую задачу под названием update_resources

Теперь нам необходимо каким-то образом получить весь список директорий из assets. Что ж давайте добавим в нашу задачу update_resources следующие строки:

  • Для каждой директории (исключая вложенные) в ${assets.path} мы будем выполнять задачу -update-atlas, при том полный путь текущей директории для обработки будет записан в переменную ${atlas.src.path}.

Что ж, теперь нам надо определить эту загадочную задачу -update-atlas:

  • Определяем задачу
  • Записываем в переменную atlas.name только название основной директории из всего пути. Например, полный путь к текущей директории для обработки выглядит как:
    Следовательно в переменную ${atlas.name} запишется “board”
  • Выводим в консоль текст Updating atlas for directiory: board
  • Запускаем командную утилиту с аргументами. Здесь нас интересуют следующие аргументы:

    В первой строке указывается файл, в который будет записана конфигурация атласа. Финальный вид:

    Во второй файл, в который будет записан сам атлас.

    В третьей же указывается место поиска изображений для упаковки в атлас.

    Остальные параметры отвечают за конфигурацию упаковки, подробнее об них вы можете прочесть в официальной документации.

В конечном итоге мы получаем следующий build-файл:

Теперь если мы сохраним его и запустим ant без параметров, или с параметром “ant update_resources”, то в папке resources появятся атласы готовые к использованию.
После изменении файлов в директориях ассетов вам потребуется всего лишь ещё раз запустить ant, и имеющиеся атласы автоматически обновятся, при условии если будут найдены изменения в ассетах.

Бонус

Возможно вы ещё не успели заметить, но текстуры в конфигурации атласов, имеют названия начинающиеся НЕ с базовой директории. То есть вместо ожидаемых

вы увидите

что не совсем отвечает удобству использования (по крайней мере в моём случае).

GUI версия Texture Packer’a имеет чудесную опцию Prepend Smart Folder’s Name, которая добавляет эту волшебную фичу и на выходе вы получаете ожидаемое имя для текстур.

К сожалению по какой-то причине версия для командной строки лишена этой опции, но я нашел простой и удобный выход из этой ситуации. Чтобы получить имя текстуры, которое вы и ожидаете, добавьте в билд-файл в качестве ещё одного аргумента следующую конструкцию:

Она добавит к началу названия текстуры имя атласа который мы создаём.

В одной из новых версий Texture Packer’a появится данная опция, автор уже написал мне об этом. А пока можете воспользоваться моим решением.

Исходники

Пример проекта для данной статьи вы можете скачать на github.

О чем забыл сказать

В случае если у вас поменяется верхняя структура папок ассетов, и исчезнет например board, то из resources boad.xml и board.png никуда не денутся, а останутся лежать мертвым грузом.

Чтобы разрешить эту ситуацию необходимо написать ещё одну задачу, которая будет следить за актуальностью текстурных атласов. Данный вопрос я оставлю на ваше усмотрение, либо напишу в отдельной статье, если потребуется.


Comments are closed.