Формат уровня

Что лежит в папке уровня, какие файлы едут вместе с ним, какие остаются на устройстве и как устроен JSON внутри

Папка уровня

Уровень - это папка. Каждое имя файла в ней зафиксировано в FileNames:

Расширение и есть формат. Внутри файлов оно нигде не записано. Читатель смотрит, какой из файлов существует: level.json или level.blob

Уровень и метаданные выбирают формат независимо. Например, встроенный уровень new-zero-demo хранит level.blob рядом с metadata.json

metadata.json - отдельный файл специально. Каталог показывает тысячу уровней по тысяче маленьких файлов метаданных. Ни один уровень при этом не открывается

Ресурсы

Ресурс адресуется парой uri и uri_type (ResourceUriType):

AbsolutePath получается, когда уровень создают вокруг песни. Экспорт архива копирует такой файл внутрь. Подробнее - Архивы и защита

Обложка доступна через LevelMeta.LevelLogo, как любой другой ресурс. logo.png или logo.jpg - решают байты самого файла, а не имя исходной картинки

Что не едет вместе с уровнем

Эти файлы лежат рядом с папкой levels, никогда не внутри папки уровня. Архивирование, отправка или удаление уровня их не трогают:

Ключи JSON

JSON всегда пишется компактно, без отступов. Чтобы читать глазами, отформатируйте его в текстовом редакторе

Длина ключа зависит от того, сколько раз он встречается в уровне:

• ключ, который встречается раз на файл, пишется полными словами в snake_case: level_id, min_generation
• ключ, который повторяется тысячи раз, сокращается до нескольких букв: objs, f, e, v

Ключи занимают 52% байтов файла уровня, поэтому это правило, а не вкусовщина. Все ключи объявлены в Names.cs

Полиморфное значение пишется как [тег, данные]. Простая строка - [0,{"v":"Author"}], локализованная - [1,{"strs":[...]}]

Обёртки идентификаторов вроде ObjectId пишутся голым числом или строкой

Идентификаторы

Знак целочисленного идентификатора имеет смысл. 0 всегда значит "не задан":

pid, равный 0, значит, что у объекта нет родителя. Числа меньше -3 существуют только во время работы игры и в файл не попадают

У Marker, Checkpoint и BeatSegment нет идентификатора. Их адрес - место во времени: у маркера и чекпоинта это кадр f, у сегмента ритма - первый кадр его промежутка sp (сегменты не пересекаются). Если такой объект сдвинуть, его адрес изменится

Переопределение префаба называет поле номером, а не ключом JSON. Установка хранит свои переопределения в списке mod. Ключ key каждого переопределения держит три числа:

• id - объект внутри шаблона, а не его копия в уровне
• f - постоянный номер поля
• i - элемент поля-списка или -1 для поля целиком

Номер закреплён за полем навсегда. Переименование ключа JSON этого поля не ломает переопределения, уже сохранённые в уровнях

Внешний "g"

Каждый корень сериализации завёрнут в конверт с двумя ключами:

{"g":1,"v":{"level_id":"18df5f61-3aa4-4812-bf69-d357f2201bc3","vrs":"1.0", ... }}

g - поколение модели (Names.Generation), v - данные

Конверты вкладываются. Внутри Level свой конверт есть у LevelSettings, GameLevel, AudioLevel, LevelResources и LevelHints. Как работают поколения - Версии и миграции