====== Management ======

===== Управление Магазином =====

Для управления товарами в магазине используются JSON файлы, которые необходимо создавать вручную в папке ".minecraft/config/oxygen/data/server/store/offers/". Текстуры для виджетов и иконок должны быть размещены в папке ".minecraft/config/oxygen/data/server/store/offers/textures/". Для перезагрузки данных во время игры можно использовать команду "/oxygenop store -reload-offers" (доступна операторам и консоли, только при значении "enable_store_management_ingame: true" в файле конфигурации Store).

Товары (описание и текстуры) синхронизируются с игроками автоматически и кэшируются на клиенте для оптимизации работы магазина.

Пример конфигурации можно {{ :store:oxygen-store-info_1_.zip |взять тут}}. Вы можете скачать и поместить содержимое этой папки в корневую папку игры и протестировать всё самостоятельно.

Пример стуктуры JSON файла для описания товаров в магазине:

{{:store:store_offers_config_example.png|}}

Файл конфигурации товаров представляет собой массив JSON объектов, где каждый объект содержит информацию об одном товаре. Store попытается загрузить содержимое всех JSON файлов в папке ".minecraft/config/oxygen/data/server/store/offers/" (включая вложенные папки), так что предлагается для каждой категории товаров создавать отдельный файл для удобства.

Для перезагрузки данных во время игры можно использовать команду "/oxygenop store -reload-offers", убедитесь что вы обновили "version_id" отредактированной сделки.

Порядок сделок в магазине зависит от их порядка в конфиге

==== Описание товара ====

Каждый товар представлен отдельным JSON объектом.

  * "persistent_id" (число типа long) - уникальный идентификатор товара

Идентификатор служит для сохранения ссылки на товар в системе подарков, так что если товар можно преобрести в подарок, то этот идентификатор не должен изменяться. Число должно быть уникальным относительно "persistent_id" и "version_id" других товаров.

  * "version_id" (число типа long) - уникальный идентификатор версии товара

В случае необходимости отредактировать товар (изменить описание, цену и т.д) для товара, который может быть куплен в подарок используется этот параметр. После внесения изменений его необходимо обновить, сохранив при этом уникальность относительно "persistent_id" и "version_id" других товаров. Обновление этого значения обеспечивает синхронизацию изменений с игроками.

  * "type" (string) - тип товара

Существуют три типа товаров: ITEM (набор предметов), COMMAND (выполнение команды от имени консоли) и SCRIPT (выполнение скрипта).

  * "category" (string) - категория товара

Категория определяет заздел, в котором будет отображаться товар в интерфейсе магазина. В качестве значения можно использовать значение "как есть" (прим. "Оружие") или ключ локализации для lang файлов (прим. "oxygen.store.category.weapon", c дальнейшим добавлением локализации для ключа).

  * "name" (string) - название товара

Название будет отображаться в интерфейсе магазина.

  * "description" (string) - описание товара

Описание будет отображаться в интерфейсе магазина. Описание при отображении будет автоматически разделено на строки при необходимости, есть возможность вручную указать место переноса строки с помощью разделителя "\n".

  * "price" (long) - стоимость товара

Если указна стоимость "0", то товар можно получить бесплатно неограниченное количество раз. В этом случае рекомендуется настроить лимит "max_purchases" и/или "purchase_cooldown".

  * "sale_price" (long) - скидочная стоимость товара

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

  * "available" (boolean) - доступность товара

Если необходимо снять товар с продажи, установите значение "false". Это лишит игроков возможности видеть товар в магазине и покупать его, но сохранит его в системе подарков.

  * "can_be_gifted" (boolean) - возможость купить товар в подарок

Если товар можно купить в подарок другому игроку, установите "true".

  * "max_purchases" (число типа int) - максимальное количество операций по покупке товара для одного игрока

Значение "- 1" означает отсутствие ограничений. При исчерпании лимита покупок игрок не сможет покупать товар для себя, в подарок или получать товар в качестве подарка.

  * "purchase_cooldown" (число типа int) - кулдаун покупки товара в секундах

Значение "0" означает отсутствие кулдауна. Во время действия кулдауна игрок не сможет покупать товар для себя, в подарок или принимать товар в качестве подарка.

  * "widget_size" (string) - размер виджета товара в интерфейсе магазина

Виджет может быть двух размеров: "BIG" (большой, 170 на 56 пикселей) и "SMALL" (маленький, 84 на 56 пикселей). Размер виджета определяет размеры текстуры для него. Размер текстуры должен быть кратным размеру виджета.

  * "widget_texture" (string) - название текстуры виджета

Каждый товар может иметь уникальную текстуру виджета (фона). Текстура должна быть расположена в папке ".minecraft/config/oxygen/data/server/store/offers/textures/". Текстуры могут быть расположены во вложенных папках, тогда название дополнительно должно содержать каталог (прим. "weapon/weapon_pack_1.png"). При отсутствии файла будет использована стандартная текстура "MISSING_TEXTURE".

  * "goods_icons" (массив JSON объектов) - иконки с информацией о товаре

Опционально. Иконки могут быть двух типов: "ITEM" (стандартный предмет) и "TEXTURE" (текстура с тултипом). Иконки позволяют дополнить виджет товара важной информацией - показать предметы, входящие в набор или описать товар с несколькими услугами.

=== Иконка типа ITEM ===


Пример:

{{:store:icon_type_item.png|}}

Структура:

{{:store:icon_item_config.png|}}

Описание параметров:

  * "type" (string) - тип иконки

  * "x" (число типа int) - координата иконки по горизонтали (на виджете)

Координаты выставляются вручную, это позволяет размещать иконки на виджете в любом месте. Размеры виджетов: большой - 170 на 56 пикселей, маленький - 84 на 56 пикселей.

  * "y" (число типа int) - координата иконки по вертикали (на виджете)

  * "itemstack" (JSON объект) - объект с данными отображаемого предмета

Данные любого предмета могут быть получены в игре с помощью команды "/oxygenc core -item -to-json {название файла (в одно слово, без .json)}" (предмет должен быть в руке). Файл будет создан в папке ".minecraft/config/oxygen/data/client/core/itemstack/".

  * "amount" (число типа int) - отображаемое количество предмета
=== Иконка типа TEXTURE ===


Пример:

{{:store:icon_type_texture.png|}}

Структура:

{{:store:icon_texture_config.png|}}

Описание параметров:

  * "type" (string) - тип иконки

  * "x" (число типа int) - координата иконки по горизонтали (на виджете)

Координаты выставляются вручную, это позволяет размещать иконки на виджете в любом месте. Размеры виджетов: большой - 170 на 56 пикселей, маленький - 84 на 56 пикселей.

  * "y" (число типа int) - координата иконки по вертикали (на виджете)

  * "icon" (string) - название текстуры для иконки

Текстура должна быть расположена в папке ".minecraft/config/oxygen/data/server/store/offers/textures/". Текстуры могут быть расположены во вложенных папках, тогда название дополнительно должно содержать каталог (прим. "icons/icon_64x64.png"). При отсутствии файла будет использована стандартная текстура "MISSING_TEXTURE".

  * "tooltip" (string) - тултип или текст который отображается при наведении
Для переноса текста на следующую строку используйте разделитель "\n".

  * "goods" (JSON элемент) - иформация о предметах/"услугах", которые игрок получает при покупке товара

Существуют три типа товаров: ITEM (набор предметов), COMMAND (выполнение команды от имени консоли) и SCRIPT (выполнение скрипта). В зависимости от типа указанного в "type" этот объект должен содержать:

=== ITEM (набор предметов) ===


Набор предметов представляется в виде массива JSON объектов, содержащих данные предметов и количество каждого предмета.

Структура:

{{:store:goods_item.png|}}

Описание параметров:

  * "itemstack" (JSON объект) - объект с данными предмета
Данные любого предмета могут быть получены в игре с помощью команды "/oxygenc core -item -to-json {название файла (в одно слово, без .json)}" (предмет должен быть в руке). Файл будет создан в папке ".minecraft/config/oxygen/data/client/core/itemstack/".

  * "amount" (число типа int) - количество предмета
=== COMMAND (набор команд для исполнения консолью) ===


Набор команд представляется в виде массива строк. Команды должны начинаться со слэша "/". Указатели: "@p" - ник игрока, "@pX" - координата игрока по X, "@pY" - координата игрока по Y, "@pZ" - координата игрока по Z, "@dim" - идентификатор измерения (числа int).

Для работы некоторых команд требуется включить командные блоки

Структура:

{{:store:goods_command.png|}}

=== SCRIPT (исполняемый скрипт на JavaScript, TypeScript и Groovy) ===


Скрипт должен быть расположен в папке ".minecraft/config/oxygen/data/server/store/offers/scripts/". Скрипты могут быть расположены во вложенных папках, тогда название дополнительно должно содержать каталог (прим. "misc/misc_1.ts"). Скрипт должен возвращать boolean значение "true" при успешном выполнении для успешного завершения операции покупки.

Примечание: Поддержка скриптов обеспечивается аддонами Scripting Adapter (WIP), однако Core имеет встроенный адаптер для ECMAScript (TypeScript, JavaScript) и для его активации нужно установить значение "enable_ecmascript_adapter: true" в конфиге "core.json".

Структура:
{{:store:goods_script.png|}}