Вы когда-нибудь заполняли json-конфигов на 20 000 - 25 0000 строк вручную перед выпуском релиза? А боль в глазах геймдизайнеров от этого процесса видели?
Вы TechLead/Менеджер и к вам часто подходят дизайнеры с просьбой написать парсер данных, а свободных рук нет? А после изменений в фиче приходится выделять человека для правок схемы парсинга под новую разметку?
Возможно, пора начать использовать тулзу по экспорту данных, которую смогут настроить сами геймдизайнеры? Нам этот инструмент сократил время настройки игровых конфигов с 4 дней до 15 минут, после предварительной настройки.
Привет! Меня зовут Игорь, я занимаюсь разработкой на Unity c 2018 года. В статье рассказываю о тулзе, с помощью которой можно выгружать данные из Google Sheets и Excel в json без привлечения программистов.
P.S. в конце статьи есть видосик с процессом настройки и экспорта одной фичи.
Оглавление
Контекст и требования к инструменту
Имеется мультиплеерный F2P проект. Релизы раз в две недели.
Практически каждый релиз выпускаются новые фичи.
Иногда могут происходить ребалансы уже существующих фич.
Несколько раз был глобальный ребаланс (баланс менялся практически в каждой фиче).
Так вот к чему это?
Представьте сколько человеко-часов на то, чтобы данные просто перенести из таблиц в конфиги.
Представьте кол-во итераций изменений конфигов для внутреннего теста баланса.
Представьте сколько времени нужно, чтобы тестировщики проверили итоговый результат. Представьте кол-во ошибок при переносе.
Эта рутинная работа занимает много времени людей, вместо того чтобы заниматься более важными задачами. Такие длительные процедуры создают риски срыва даты релиза.
Меня, как техлида, это не устраивало, хотелось как-то помочь ребятам.
Так появились мысли о том, что нужен инструмент экспорта\парсинга, который упростит жизнь и сделает это дело более надёжным. Но не хотелось создавать инструмент слишком частным, чтобы его постоянно приходилось допиливать и постоянно выделять под это дело программистов.
К инструменту появились следующие требования:
Геймдизайнеры должны самостоятельно настраивать и перенастраивать инструмент по мере необходимости
Инструмент не должен требовать знаний программирования (актуально для геймдизов)
Инструмент не должен требовать привлечения программистов (Вообще. Это было самое важное условие для меня)
В json конфигах может быть большая вложенность уровней. Инструмент должен быть универсальным, поддерживать неограниченное кол-во уровней вложенности.
Инструмент должен поддерживать возможность использовать ячейки из таблиц гибко, а не требовать таблицу MxN (данные могут быть разбросаны на разных страницах и т.д.)
Инструмент должен иметь возможность заполнять объекты json с плавающим кол-вом полей (например, массив объектов, где один элемент будет иметь 2 поля, а другой 4 поля)
Инструмент, там где это возможно, не должен прекращать парсинг, если что-то неправильно введено. Ошибки должны подсвечиваться как предупреждение.
Открытый исходный код. В компании достаточно строгие правила по безопасности.
Левый софт особо не поиспользуешь (NDA, потенциальные утечки и т.д.).Инструмент должен предоставлять возможность выносить повторяющуюся структуру json‑объектов в аналог математической функции, которая принимает параметры на вход
func(level, amount), и преобразует это в блок текста json
Позднее добавились пожелания от геймдизайнеров:
Каждый новый уровень json - это отдельный Google Sheets лист
Все фичи можно размещать вперемешку на Google Sheets листах с уровнями семантики парсинга (не создавать под каждую фичу свои листы с уровнями, разделять фичи за счёт группировки строк через сворачивание в “+”)
Изначально искали решение на просторах интернета. К сожалению ничего полезного найти не удалось, всё что попадалось решало очень частные задачи.
Решил написать самостоятельно, как пет-проект.
Немного теории о структуре json
Json можно представлять в виде иерархической (древовидной) структуру, где есть верхнее звено и от него расходятся ветви, которые имеют свои звенья. Мы можем обходить это дерево. Каждый раз когда мы переходим по ветви глубже, мы спускаемся на следующий уровень. На следующем уровне может быть как звено, которое ведёт к следующему уровню, любо содержать конечное значение (строку, число, логическое значение).
Идея парсера в том, чтобы описать эти звенья как промежуточные узлы в таком формате, чтобы Google Sheets и Excel возможности могли относительно легко подставлять значения в промежуточные части, если придерживаться определённой семантической структуры.
О парсере
Исходя из идеи парсера и требований к этому парсеру, было получено решение, которое описывает узлы как структуру название(name) - тип данных(type) - значение (value). Т.к. следующий уровень может быть узлом, а не значением, то значение может быть ссылающиеся на другой узел (reference type - ref).
Так получился парсер, который поддерживает следующие типы данных-полей:
str – текстовое поле
num – числовое поле
bool – логическое поле
null – поле со значением null
object – вложенный json объект (именуется как ref)
arr - массив других типов
alias функции – аббревиатура формата математической функции
func(level, amount)для повторяющихся элементов, принимающая изменяющиеся данные как параметр.
Видео с примером использования для Google Sheets
Ниже на видео пример использования парсера с применением формулы FILTER для экспорта данных из Google Sheets.
Что на видео:
В начале видео показана таблица данных, которую нужно экспортировать в json. Показан примерный формат json, который используется для фичи (пример данных для конфига).
Подготовка парсера (настройка alias функций).
Это не полная процедура настройки парсера, а только основной фрагмент.
Остальная часть — это добавление в конфиг парсинга нескольких строк с описанием фичи.Заполнение семантики парсинга в Google Sheets документе
Подготовка исходных данных, для применения формулы FILTER
Заполнение оставшейся семантики с использованием формулы FILTER
Процесс экспорта данных
Если видео не загрузится: Youtube
P.S. В Excel формулы немного другие из-за разной работы формул.
Итог: за 13 минут (видео ускорил, чтобы не смотреть рутинные действия) сделал частичную предварительную настройку парсера и экспортировал 400 строк данных в json файл. На продакшен проекте такая фича является ротируемой(каждые 2 недели смена), обычно имеет 30 stages, около 15 вариантов alias функций, что в среднем даёт 2 000 json-строк.
Дисклеймер
Первичная настройка парсера и семантики может быть долгой. Зависит от Ваших навыков владения Google Sheets/Excel и фантазии как по удобнее располагать данные для скорости интеграции.
Что инструмент умеет?
Поддерживает Excel и Google Sheets источники данных
Гибкая настройка схемы парсинга json с неограниченной вложенностью объектов. Схема переопределяется непосредственно в источнике с данными. Не требует привлечения программистов и не требует изменения исходного кода.
Предварительно нужно понять простою идею как заполняются данные и как происходит разделение на слои.
Добавлены два типа Alias функций (функции которые сокращают повторяющиеся структуры за счёт параметров)
TableAliasFunc - настраивается в Google Sheets на отдельных Google Sheets листах (по тем же правилам, что и обычная семантика)
JsonAliasFunc - настраиваются в отдельных json-файлах.Alias-функции поддерживают как именованные параметры (человеко читаемые: amount, level и т.д.), так и анонимные (arg1, arg2, arg3). Читайте инструкцию как какие параметры использовать.
TableAlias-функции могут использовать другие alias функции, включая JsonAlias-функции.
Параметры Alias-функций можно пробрасывать во вложенные Alias-функции
Можно настроить место парсинга фичей, каждая фича в свой файл, по своему пути.
Открытый исходный код. Если нужно сканируйте/изучайте исходники, можно вносить изменения под свой проект.
Mit-лицензия. Можно использовать бесплатно, включая коммерческое использование.
Где найти парсер?
В репозитории с исходным кодом на GitHub написана подробная инструкция, как настроить и использовать. Так же написана и инструкция как подключить Google Sheets. В репозитории Вы найдёте больше примеров семантики парсинга в разных вариации в Excel-файле и по ссылке на такой Google Sheets файл.
GitHub репозиторий: Тык
Кому хочется побыстрее посмотреть семантику парсинга в Google Sheets: Тык
P.S. Документ доступен как пример в режиме только для чтения. Если хотите что-то потыкать, то копируйте на свой диск.
Как рекомендую действовать:
Сделать настройку по инструкции из репозитория
Рекомендую почитать инструкцию, хотя бы по диагонали (инструкция должна снять большинство вопросов)
Потыкать файлы в папке Example (Config.json, JsonAliasFuncs)
Отключить лишние тестовые фичи для парсинга из тестового конфига парсинга и включать их по одной, попутно экспериментируя с редактированием и добавлением полей.
Дополнительно
Если вас тоже интересует улучшение рабочих процессов, то возможно вас заинтересуют другие мои статьи:
Как при помощи ведения дневника событий искать точки роста, оценивать свой результат, проводить ретроспективу и давать конкретную обратную связь:
Статья «Activity Journal. Самоорганизация и анализ рабочего времени. На что уходят рабочие часы?»Как с помощью код-анализа можно ускорить изучение\понимание кодовой базы:
Статья: «Unity, Roslyn и code analysis. Прикладная задача визуализации графа состояний»