README.ru.md

Godot 4 Aseprite Importers

Это плагин для игрового движка Godot 4.x, добавляющий несколько плагинов импорта для файлов графического пиксел-арт редактора Aseprite 1.3+.

Этот плагин в настоящее время ещё работоспособен, но попробуйте вместо него Importality - более полный м функциональный набор импортеров графики и анимации самых разных форматов!

godot_aseprite_importers_preview.mp4

💽 Установка

Просто скачайте этот плагин из Библиотеки Ассетов Godot

Другой способ - скачайте или клонируйте этот репозиторий и скопируйте содержимое его папки addons в папку addons вашего проекта.

После этого:

• Откройте Настройки проекта (Project Settings)
• Переключитесь на вкладку Плагины (Plugins)
• Включите плагин, установив флажок напротив его названия
• Переключитесь на вкладку Основное (General)
• Включите переключатель "Расширенные настройки" (Advanced Settings)
• Промотайте вниз дерево настроек и выберите секцию Aseprite Importers
• Укажите в настройках этой секции путь к исполняемому файлу Aseprite

👷‍♀️ Как использовать

После установки плагина в проекте появится поддержка .ase- и .aseprite-файлов.

1. Поместите Aseprite-файлы в проект
2. Выберите один или несколько Aseprite-файлов в дереве файловой системы проекта
3. В панели импорта выберите один из плагинов импорта
4. Установите настройки импорта
5. Опционально установите настроеннуюю конфигурацию настроек по умолчанию для выбранного плагина импорта
6. Нажмите кнопку Reimport

🛠 Настройки импорта

• Spritesheet - настройки листа спрайтов
  • Embed Image (пока не реализовано) - включить полученное изображение в ресурс или разместить рядом с исходным файлом
  • Layout - вариант раскладки листа спрайтов
    • Packed - упакованный - все спрайты обрезаны и максимально плотно прилегают друг к другу
    • By Rows (с параметром Fixed Columns Count) - по строкам - все спрайты имеют одинаковый размер и располагаются по строкам фиксированной ширины
    • By Columns (с параметром Fixed Columns Count) - по колонкам - все спрайты имеют одинаковый размер и располагаются по колонкам фиксированной высоты
  • Border Type - тип рамки вокруг каждого спрайта
    • None - спрайты в листе примыкают друг к другу без зазоров
    • Transparent - вокруг каждого спрайта создается прозрачная рамка шириной в 1 пиксел
    • Extruded - вокруг каждого спрайта создается рамка шириной в 1 пиксел, дублирующая цвета прилежащих пикселов спрайта
  • Trim - (only for grid-based layouts) - одинаково уменьшает все ячейки спрайтов так, чтобы анимация была вписана в новый размер ячейки
  • Ignore Empty - не включает в лист спрайты, на которых все пикселы прозрачные
  • Merge Duplicates - объединяет одинаковые спрайты в одни и те же участки на листе
• Animation - настройки анимации
  • Default - анимация по умолчанию
    • Name - имя анимации, которым будет названа анимация, если в исходном файле нет ни одного тэга
    • Direction - направление анимации, созданной по умолчанию
      • Forward - анимация проигрывается от первого до последнего кадров
      • Reverse - анимация проигрывается от последнего до первого кадров
      • Ping-pong - анимация проигрывается от первого до последнего кадров, а потом обратно до первого, без дублирования последнего кадра
      • Ping-pong reverse - анимация проигрывается от последнего до первого кадров, а потом обратно до последнего, без дублирования первого кадра
    • Repeat Count - количество повторений для анимации, созданной по умолчанию (0 - для бесконечного повторения). Крайние кадры не дублируются, когда анимация меняет направление.
  • Autoplay - имя анимации, которая будет помечена, как запускающаяся автоматически
  • Strategy... (только для анимаций, основанных на AnimationPlayer) - набор свойств узла, которые будет использовать AnimationPlayer для анимирования
• Layers (пока не реализовано) - настройки слоев Aseprite
  • Include Reg Ex (пока не реализовано) - регулярное выражение для белого списка включаемых слоев
  • Exclude Reg Ex (пока не реализовано) - регулярное выражение для черного списка включаемых слоев
• Tags (пока не реализовано) - настройки тэгов Aseprite
  • Include Reg Ex (пока не реализовано) - регулярное выражение для белого списка включаемых тэгов
  • Exclude Reg Ex (пока не реализовано) - регулярное выражение для черного списка включаемых тэгов

🧱 Типы импортируемых ресурсов

🖼️ Текстура (ресурс Texture)

Вы можете импортировать ваши *.aseprite или *.ase файлы как обычные текстуры из файлов изображений. К несчастью, нет возможности выбирать слои и кадры анимации. В этом режиме текстура создается из всех видимых слоев на самом первом кадре анимации.

🎞 Анимации, основанные на ресурсе SpriteFrames

• SpriteFrames - создает ресурс SpriteFrames для дальнейшего его использования в анимированных спрайтах
• AnimatedSprite2D - готовый анимированный спрайт для плоских сцен
• AnimatedSprite3D - готовый анимированный спрайт для объемных сцен

📽 Анимации, основанные на узле AnimationPlayer

Создает ресурс PackedScene с дочерним узлом AnimationPlayer, с помощью которого происходит анимация. Вы можете увидеть этот узел в родительской сцене, если установите в контекстном меню флажок Editable Children

• Sprite2D - создает ресурс PackedScene с узлом Sprite2D и дочерним узлом AnimationPlayer
• Sprite3D - создает ресурс PackedScene с узлом Sprite3D и дочерним узлом AnimationPlayer
• TextureRect - создает ресурс PackedScene с узлом TextureRect и дочерним узлом AnimationPlayer

Стратегии анимации с помощью AnimationPlayer:

При раскладке спрайтов, основанной на сетке:

• Animate sprite's region - анимирует свойство спрайта region
• Animate sprite's frame index - анимирует свойство спрайта frame
• Animate sprite's frame coords - анимирует свойство спрайта frame_coords
• Animate single atlas texture's region - анимирует свойство атлас-текстуры спрайта region
• Animate multiple atlas texture instances - создает по экземпляру атлас-текстуры на каждый уникальный фрейм и анимирует свойство спрайта texture, подставляя их в него одну за одной

При упакованной раскладке тайлов:

• Animate sprite's region and offset - анимирует свойства спрайта region и offset
• Animate single atlas texture's region and margin - анимирует свойства атлас-текстуры спрайта region и margin
• Animate multiple atlas texture instances - создает по экземпляру атлас-текстуры на каждый уникальный фрейм и анимирует свойство спрайта texture, подставляя их в него одну за одной

🤖 Планы на будущее:

Подавить возникающие при импорте сообщения об ошибках в консоли

Во время выполнения импорта могут появляться некоторые ошибки в консоли. Большинство из них - внутренние ошибки движка Godot версии 4.x, пока в нем еще не исправлены все недочёты.

Если там будут возникать сообщения об ошибках, связанные непосредственно с работой скрипта импорта - пожалуйста, создайте тикет с их описанием и алгоритмом воспроизведения.

Добавить настройки импорта

Флажок для включения изображения в ресурс Spritesheet/Embed Image: bool

Пока что возможности движка Godot 4 не позволяют сохранить CompressedTexture в папку импортированных файлов. Этот ресурс создается автоматически только для изображений, поддерживаемых движком. По этому чтобы получить CompressedTexture нужно создать файл изображения в дереве ресурсов проекта и указать движку импортировать его.

Если же встраивать изображение в ресурс формата .res (бинарный), то оно будет запаковано не самым оптимальным образом, и будет занимать в несколько раз больше места на диске.

Если использовать формат ресурса .tres (текстовый), то встроенное изображение будет кодироваться в Base64, и займет еще в несколько раз больше места.

Полный список планируемых функций:

• Опция включения полученного изображения листа тайлов в ресурс: Spritesheet/Embed Image: bool
• Регулярные выражения для включения/исключения слоёв и тэгов: Layers/Include, Layers/Exclude, Tags/Exclude and Tags/Exclude
• Импорт обычных ресурсов текстур: (TileSetAtlasSource, ImageTexture, CompressedTexture, PortableCompressedTexture, и AtlasTexture)
• Импорт обычных спрайтов (Sprite2D и Sprite3D без анимации)
• Импорт ресурса TileSetAtlasSource
• Импорт ресурса NinePatchRect
• И еще чего-нибудь, если будут интересные предложения от вас)))