Этот туториал — часть серии Начало работы — День 4, Неделя 3.
Проблема: корректные данные в непригодном формате
Хотя коллекция Карты представляет собой исходную базовую модель игрового баланса, отфильтрованную и сохранённую в удобных представлениях, ни один конечный потребитель не может использовать эти данные в их первозданном виде. Игровой движок рассчитывает получить строго определённую структуру JSON — например, прямые поля card.damage и card.owner без избыточной обёртки вроде values.props.damage. В то же время команда геймдизайна предпочитает анализировать баланс в привычных электронных таблицах Excel или Google Sheets, для чего требуются чистые строки формата CSV.
Поскольку ни разработчики движка, ни геймдизайнеры не нуждаются в самом интерфейсе редактора, обоим потребителям требуется лишь специфическая проекция исходных данных, адаптированная под их рабочие инструменты. Если формировать подобные представления вручную при каждой итерации баланса, неизбежно возникнет рутинный процесс копирования чисел, приводящий к рассинхронизации данных, — той самой проблемы, для устранения которой и создана эта серия материалов.
Пользовательский формат экспорта как сохранённый алгоритм
Для решения этой задачи в IMS Creators предусмотрены пользовательские форматы экспорта, представляющие собой готовые шаблоны настройки. Они разово определяют, какие именно элементы коллекции (с возможностью фильтрации по типу), в каком формате, с какими конкретно полями и какими скриптами постобработки должны преобразовываться в итоговые файлы. Единожды настроив такой формат, вы сможете использовать его для регулярного экспорта коллекций.
Настройка JSON для игрового движка: выбор полей и объединение в один файл
Чтобы сформировать нужный экспорт для движка, создайте новый формат со следующими параметрами:
- Заголовок —
Карты для движка. - Тип — Игровая карта — чтобы ограничить выборку только картами.
- Формат — JSON.
При экспорте в JSON доступны три базовых шаблона структуры:
- Полный — выгружает абсолютно все именованные неслужебные атрибуты элемента.
- Только значения — сохраняет структурированные значения, оставляя их сгруппированными по блокам.
- Выбранные поля — экспортирует исключительно отмеченные свойства без избыточной служебной информации.
Для игрового движка оптимально подходит вариант Выбранные поля, позволяющий передать строго необходимые атрибуты — Имя, Стоимость, Урон и Легендарная. При этом вы можете переименовать вывод полей непосредственно в списке экспорта: благодаря этому исходное поле Урон получит то наименование, которое ожидает движок, и станет соответствующим ключом в JSON-объекте.
Настройка CSV для команды: плоская таблица вместо сложной структуры
Второй формат — CSV — предназначен для преобразования тех же данных баланса в удобные строки, предназначенные для совместного ревью. При настройке этого формата вы выбираете необходимые колонки, задаёте подходящий разделитель (например, точку с запятой для корректного открытия в локальных версиях Excel) и добавляете строку заголовков, после чего каждая карта преобразуется в отдельную строку таблицы.
Таким образом, два независимых алгоритма экспорта (для движка и для команды) работают параллельно, ссылаясь на одну и ту же коллекцию Карты и используя единый источник данных.
Постобработка: кастомная сборка элементов с помощью скриптов
Если встроенные шаблоны позволяют ограничить список экспортируемых полей, то для изменения самой структуры вложенности данных используется скрипт постобработки, прикрепляемый к формату экспорта. В процессе обработки каждый элемент пропускается через JavaScript-функцию, где входной объект передаётся в переменную asset_data, а возвращаемое значение записывается в итоговый файл. По умолчанию стандартный скрипт возвращает данные без изменений:
return asset_data;Однако если движку требуется словарь с вычисленными характеристиками и переименованными флагами, скрипт постобработки позволяет сформировать готовые вычисляемые значения на ходу:
return {
name: asset_data.name,
damage: asset_data.damage,
cost: asset_data.cost,
legendary: asset_data.legendary,
power_budget: asset_data.damage + asset_data.cost,
overtuned: asset_data.damage / asset_data.cost > 1.5,
};В данном примере ключи name, damage, cost и legendary — это имена вывода, заданные ранее в настройках формата Выбранные поля: именно под этими именами выбранные поля попадают в подготовленный элемент asset_data, и именно так они читаются в скрипте. В то же время поле power_budget суммирует показатели урона и стоимости, а overtuned вычисляет логический флаг превышения баланса через их отношение. Благодаря этому итоговый файл содержит готовые производные параметры, устраняя необходимость в их повторном расчёте на стороне игрового движка или ручном сопоставлении данных.
Встроенный редактор позволяет писать скрипты с возможностью интерактивного предпросмотра на реальных элементах коллекции: благодаря этому вы можете убедиться в корректности структуры данных ещё до момента сохранения файлов на диск.
Фоновое выполнение скриптов и интеграция с системой контроля версий
Поскольку скрипт обрабатывает каждый элемент колоды независимо, итоговая структура остаётся гарантированно единообразной для всех карт. Сгенерированные текстовые файлы легко интегрируются в систему контроля версий Git, позволяя отслеживать любые изменения баланса в виде читаемых diff-сравнений.
Итоговая концепция
Пока геймдизайнеры работают с удобным интерфейсом редактора, игровой движок получает его актуальную и точно настраиваемую проекцию. Эта проекция формируется автоматически и не превращается во второй источник истины, поскольку при каждом экспорте она заново пересобирается из эталонных данных без риска появления опечаток или рассинхронизации.
Процесс выгрузки и следующий шаг: автоэкспорт
Для запуска выгрузки достаточно вызвать контекстное меню коллекции Карты, выбрать нужный формат и указать целевую директорию. В зависимости от выбранных настроек вы получите либо единый файл .csv, либо общую JSON-структуру с массивом элементов, либо набор отдельных файлов формата <element-id>.json для каждого объекта.
Несмотря на то что использование готовых форматов сводит выгрузку к одному действию, необходимость вручную запускать экспорт после каждой правки создаёт риски в условиях сжатых сроков. В следующей части серии будет рассмотрен автоэкспорт, позволяющий автоматизировать обновление файлов при сохранении в редакторе: благодаря этому движок Godot сможет подхватывать свежий баланс без дополнительного вмешательства.
Готовы придать форму своему экспорту? Скачайте IMS Creators, откройте ims.cr5.space/desktop, создайте JSON-формат для движка с Выбранными полями и CSV-формат для команды и просмотрите оба на реальной карте сегодня.
Готовы? Измените характеристику карты, и Godot перезагрузит её — следующий пост в этой серии.
FAQ
Что представляет собой пользовательский формат экспорта?
Это сохранённый алгоритм создания файлов из набора элементов, задающий правила фильтрации по типам, выбор формата (JSON или CSV), список выгружаемых полей и опциональные скрипты постобработки.
В чём заключаются различия между шаблонами JSON?
Шаблон Полный выгружает абсолютно все неслужебные атрибуты, Только значения сохраняет структурированные данные по блокам, а Выбранные поля оставляет исключительно явно указанные свойства, гарантируя чистоту проекции для игрового движка.
Для чего нужен CSV, если доступен JSON?
Формат CSV необходим для членов команды, анализирующих баланс через Excel или Google Sheets, в то время как JSON оптимизирован для считывания непосредственно игровым движком.
Зачем использовать параметр «Сгруппировать в одном файле»?
Данная опция определяет структуру вывода: при объединении все элементы формируют единый массив в одном файле, а без объединения создаются отдельные файлы для каждого элемента.
Допустимо ли сохранять экспортированные файлы в Git?
Да — выгружаемые текстовые файлы прекрасно отслеживаются в сис, выгружаемые текстовые файлы прекрасно отслеживаются в системе контроля версий Git, сохраняя прозрачную историю изменений игрового баланса с помощью понятных diff-сравнений.