VoxelEngine/doc/ru/content-packs.md

Контент-паки

Для создания контент-пака сначала нужно придумать ему название (id) соответствующее следующим требованиям:

• название может состоять только из букв латиницы, цифр и символа подчёркивания '_'
• название не может начинаться с цифры
• длина названия должна находиться в пределах от 2 до 24 включительно

Далее в res/content создаётся папка с выбранным названием контент-пака.

В созданной папке создаётся файл package.json с следующим содержимым:

{
    "id": "выбранное_имя_пака",
    "title": "имя контент-пака для отображения в меню контента",
    "version": "версия контент-пака в формате major.minor",
    "creator": "создатель контент-пака",
    "description": "краткое описание",
    "dependencies": [
        "зависимости",
        "пакета"
    ]
}

Вместо creator можно указать массив creators

Уровни зависимостей указываются с помощью префиксов в имени:

• '!' - обязательная зависимость
• '?' - опциональная зависимость
• '~' - слабая зависимость Отсутствие префикса интерпретируется как '!'.

Пример: '~randutil' - слабая зависимость 'randutil'.

Версии зависимостей указываются после '@' и имеют операторы для ограничения допустимых версий. Отсутствие версии зависимости интерпретируется как '*', т.е. любая версия.

Пример: 'randutil@>=1.0' - зависимость 'randutil' версии 1.0 и старше.

Пример:

{
    "id": "doors",
    "title": "DOORS",
    "creator": "MihailRis",
    "version": "1.0",
    "description": "doors test"
}

Изображение контент-пака добавляется в виде файла icon.png в папку пака (не в textures). Рекомендованный размер изображения: 128x128

Файловая система

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

Это значит, что для доступа к файлам пака не требуется использование дополнительных функций:

print(file.read("пак:package.json")) -- выведет содержимое package.json пака

Также это является одной из причин того, что некоторые id зарезервированы от использования.

Точки входа монтируются как read-only. Для получения доступа к записи существует функция pack.request_writeable.

Подробнее про библиотеку file.

Структура контент-пака

Пусть вас не пугает следующий текст, ведь минимальный пак содержит только package.json.

• Контент:
  • block_materials/ - определения материалов блоков
  • blocks/ - определения блоков
  • items/ - определения предметов
  • generators/ - генераторы мира
  • entities/ - определения сущностей
  • skeletons/ - определения скелетов сущностей
  • presets/ - пресеты (может использоваться и паками в своих целях)
    • text3d/ - 3D текст
    • weather/ - погода
• Код:
  • modules/ - скриптовые модули
  • scripts/ - скрипты контента, мира
    • components/ - компоненты сущностей
• Ассеты (ресурсы клиентской стороны):
  • fonts/ - шрифты
  • models/ - 3D модели
  • textures/ - текстуры
  • shaders/ - шейдеры
    • effects/ - эффекты пост-обработки
  • sounds/ - звуки и музыка
  • texts/ - файлы локализации
• GUI:
  • layouts/ - макеты UI
    • pages/ - макеты страниц меню (элемент pagebox)
• Конфигурация:
  • config/ - файлы конфигурации
    • defaults.toml - переопределения стандартных привязок к контенту, такие как сущность игрока, генератор по-умолчанию и т.д.
    • bindings.toml - привязки к клавишам / мыши
    • user-props.toml - пользовательские свойства определений контента
  • devtools/ - вспомогательные файлы внутренних инструментов отладки
  • content.json - генерируемые автоматически списки контента, используемое для проверки корректности индексов в мире и конвертации при несовпадении
  • icon.png - иконка пака
  • package.json - файл опеределения пака
  • preload.json - списки предзагрузки ассетов, которые не загружаются автоматически, не следует указывать ассеты без надобности
  • resources.json - списки определений ресурсов (не путать с ассетами)
  • resource-aliases.json - файлы объявления псевдонимов для ресурсов

Warning

Ручное редактирование content.json противопоказано и скорее всего приведёт к необратимой поломке миров.

Источники контента

Поиск контент-паков производится среди источников контента, являющихся путями в файловой системе движка.

Приоритет источника определяет порядок сканирования: если один и тот же пак найден в нескольких источниках, будет выбран тот, что принадлежит источнику с наивысшим приоритетом.

Источники контента в порядке убывания приоритета:

• world:content - контент папке с миром (мир/content/)
• user:content - контент в папке пользователя ($HOME/.voxeng/content/)
• project:content - контент в папке с проектом (проект/content/)
• res:content - встроенный контент, поставляемый вместе с ядром движка (res/content/)

Т.е. если в world:content и в user:content есть один и тот же пак, будет выбрана версия из world:content.

Версия пака, при этом, на данный момент, не учитывается.