@qspkp @NoHaijeSo1o @shonestew

Script API(то, что используется для создания скриптов);
JavaScript(язык программирования, на котором пишутся скрипты);
bedrock.dev(документация к аддонам),
wiki.bedrock.dev(некий учебник и документация к аддонам, также там есть туториалы по скриптам).

Доброго дня, в этой публикации будет расказываться об структуре аддонов, как они устроены и т.д. Погнали!

Аддоны внутренне устроены следующим образом - в директории(папка) аддона есть две другие директории - это ресурспак, там лежат текстуры предметов, мобов, настройки интерфейса и т.п., и набор параметров - там лежит файлы, которые обьявляют новый предмет, мобов и т.п. а также описывают им свойства(к примеру, у предметов это прочность, текстура и т.д.).

Каждый пак(набор параметров и ресурспаки обобщено) обьявляют главным файлом manifest.json, которые идентифицируют пак, его название, описание а также подключенные внутри него модули. К примеру, чтобы идентифицировать ресурспак, надо написать в манифест(manifest.json) следующее:

{
    "format_version": 2,
    "header": {
        "name": "Пример манифеста ресурспака",
        "description": "Ресурспак",
        "uuid": "b603f596-e272-40df-ae7c-05a1dcc610d6",
        "version": [1, 0, 0],
        "min_engine_version": [1, 20, 0]
    },
    "modules": [
        {
            "description": "Модуль для ресурспака",
            "type": "resources",
            "uuid": "4b71209a-6927-4e29-b297-f8e551cb8ea2",
            "version": [1, 0, 0]
        }
    ]
}

Давайте же разберём этот код, и поймем какие опции за что отвечают:
format_version - версия формата, для скин-паков - это 1, для ресурспаков и набором параметров - 2.
header - секция заголовка аддона, куда указывается его название, описание, uuid(дальше разберем что это), версия аддона и минимальная версия клиента/сервера, при котором можно ещё установить пак. Его опции:
name - название аддона,
description - его описание,
uuid - 16-байтный идентификатор аддона, позволяет отличать паки. Сгенерировать его можно тут.
version - версия аддона, и кстати - при импорте того же аддона, но с версией, указанной выше заменяется сам аддон и его файлы на версию новее.
min_engine_version - минимальная версия клиента/сервера, при котором можно ещё установить пак.
modules - секция для подключения модулей. В неё можно подключать модули для работы клиентских скриптов, ресурспаков и наборов параметров. Строение подключенного модуля:
description - описание модуля,
type - тип подключаемого модуля, для ресурспаков - resources, для наборов параметров - data,
uuid - идентификатор модуля,
version - версия модуля.

Все эти опции являются обязательными, и без них манифест, и соответственно сам пак, не импортируется в игру. Также есть и другие, необязательные опции, которые можно тоже применять в манифесте, для дополнительной идентификации пака. Для того, чтобы сделать манифест для набора параметров, надо изменить тип подключаемого модуля на data. Подробнее читать про это здесь.

Теперь, когда мы разобрались в строении манифест, можно начать разбираться, как составлять директории в паках.
Для ресурспаков лучшее всего делать расположение директории так:

my_resource_pack/
├── textures/
│    ├── items/
│    │    ├── item1.png
│    │    ├── item2.png
│    │    └── item3.png
│    └── blocks/
│    │    ├── block1.png
│    │    ├── block2.png
│    │    └── block3.png
├── manifest.json
└── pack_icon.png

Это одна из распространенных видов структурирования директории и файлов аддона. В наборе параметров в основном всё так:

my_behavior_pack/
├── items/
│    └── item1.json
│    └── item2.json
│    └── item3.json
├── blocks/
│    └── block1.json
│    └── block2.json
│    └── block3.json
├── manifest.json
└── pack_icon.png

Такие виды структурирования паков очень распространены. Они более удобны для ориентировки по исходникам аддона, и позволяют удобнее делать обновление аддонам в будущем. Но как структурировать аддон остается во многом за вами, но один момент который является обязательным - manifest должен быть в самой главной по иерархии директорией(то есть, в примере это my_resource_pack или my_behavior_pack).

Как вы знаете, для разработки аддонов требуются некоторые приложения(если у вас смартфон) или программы(если у вас ПК/ноутбук).
В этой публикации будет 2 группы приложении/программ для разработки аддонов и 1 дополнение. Поехали!

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

Файловый менеджер - замечательный файловый менеджер, подходит для управлениями файлов.
Cx проводник - тоже, замечательный файловый менеджер, более популярный.
RAR - для архивации файлов аддонов, но можно использовать его как файловый менеджер.
7-zip - древний архиватор на Windows, с открытым исходным кодом.

Надо же как-то редактировать файл, дабы туда записать код. Так вот, редакторы кода с этим вам помогут. Администраторы канала советуют вам несколько приложении и программ для редактирования кода, а именно:

QuickEdit - простой редактор кода, подойдет для написания мелких аддонов, прост и понятен.
Acode - более продвинутый, подойдет для написания более крупных аддонов, поддерживаем плагины и выводит подсказки.
Visual Studio Code - очень популярный редактор кода на Windows, Linux и macOS , плагинов уйма и подходит не только для написания аддонов, а и для программ, чат ботов и так далее.
Subline Text - очень легкий редактор кода на Windows, Linux и macOS, тоже подходит для написания аддонов.

JaylyBot - бот для дебаггинга кода, можно не заходя в игру проверять работоспособность кода, на сайте бота написано и показано как его использовать.

События, к примеру это может быть разрушение блока, использование чего либо, вход игрока, спавн игрока, и т.д.

AfterEvents (после)
Это происходит после их выполнения, к примеру после ломания блока, после сообщения в чате, и т.д, событие которое произойдёт «после» нельзя отменить.
BeforeEvents (до)
Это происходит до их выполнения, к примеру сообщение в чате, ломание блока, и т.д, событие которое происходит «до» можно отменить.

world.beforeEvents.chatSend.subscribe((event) => {
    const player = event.sender; // Игрок который отправил сообщение
    const message = event.message; // Сообщение которое отправил игрок

    if (message === "#rtp") { // Если сообщение равно #rtp
        event.cancel = true; // Отменяем отправку сообщения в чат
        player.sendMessage("Подождите, происходит телепортация..."); // Отправляем сообщение игроку
        RTP(player); // Функция для ртп
    }
});

Для начала стоит понять что такое вообще API.
API - это набор способов и правил, по которым различные программы общаются между собой и обмениваются данными. В нашем же случае, между собой общаются не скорее программы, а скриптом и мир/сервер (дальше будет просто мир).
Сам же Script API (ранее назывался как GameTest Framework) - это такой же набор способов и правил (или функции), с которым происходит общение скрипта с миром, позволяя создавать сценарии действии при определенных событии. Про события и их прослушивания было в прошлой статье.

В Script API есть модули, которые импортируются через манифест (в публикации про один из модулей разберем подробнее), которые отвечают за свои функции. Все основные модули:
@minecraft/server - основной модуль для написания скриптов, нужен в 99% случаях,
@minecraft/server-ui - необходим для создания форм(см. фото), которые можно использовать для взаимодействия с игроком через удобные формы,
@minecraft/server-net - модуль для отправки HTTP-запросов методами GET, POST, DELETE, HEAD и PUT,
Также есть и доп. модули, но разбирать их не требуется, пригодяться они очень редко.

Для написания скриптов требуется базовое знание JavaScript. В частности: переменные, циклы for/while, условия if else, базовые математические операторы, функции, стрелочные функции, switch/case и др. Кроме этого, нужен инструментарии в лице любого редактора кода. Какой выбрать - мы уже расписывали в этом посту. А изучить JavaScript можно на прекрасном сайте learn.javascript.ru.

В прошлой публикации мы обьясняли про модули в Script API. И при разборе основных модулей был упомянут основной модуль - @minecraft/server. Оно является самым главным при написании скрипта и нужен в 90% случаях. Сам модуль состоит из 5 классов для взаимодействия с игрой - World, Block, Entity, Dimension и ItemStack. Они все состоят из разных функции, нужные для взаимодействии. В этой же публикации мы будем разбирать классы World и Entity. Если вы хотите публикацию про другие классы - пишите комментарии в качестве обратной связи. Итак, начнём

Ключевой класс в основном модуле, содержит в себе функции для взаимодействия с миром, к примеру исполнения команд, выдачи эффектов и прослушивания событии. К примеру, если мы хотим чтобы каждые 20 тиков(1 секунда) отправлялось сообщение в чат, то делаем это так:

import { world, system } from "@minecraft/server";

system.runInterval(() => {
    world.sendMessage("Привет, мир!");
});

Здесь мы сначало импортируем класс world и system, после через system задаем интервал срабатывания кода в 20 тиков(1 секунду). Внутри функции интервала находиться функция отправки сообщения sendMessage, в который аргументом вписываем строку с текстом "Привет, мир!", всё.
Также обратившись к классу world можно прослушивать события 2 функциями - afterEvents и beforeEvents. Их отличия заключается в том, что первая нужна для прописания логики после события (к примеру, игрок нанес урон и ему за это выдается яблоко), а второе нужна для прописывания логики до выполнения события (к примеру, игрок нанес урон, но событие было отменено). К примеру, используем функцию beforeEvents:

import { world } from "@minecraft/server";

world.beforeEvents.chatSend.subscribe((ev) => {
    let player = ev.sender;
    let msg = ev.message;
    if (msg == "!test") {
        ev.cancel = true;
        player.runCommandAsync("give @s apple");
        player.sendMessage("Вы получили яблоко!");
    };
});

В этом примере мы прослушиваем событие отправки сообщение, и если игрок отправил сообщение "!test" - отменяем событие отправки сообщения, после игроку выдается яблоко и пишется ему что ему было выдано яблоко. Также в классе world есть и другие функции, которые можно посмотреть здесь. В дальнейшем мы снова вернемся к слушателям событии и будем разбирать исходники некоторых аддонов.

Этот класс представляет из себя сборник функции, с которым можно получить информацию об сущности(игрока тоже), к примеру его координаты и т.д. Давайте же напишем скрипт, который при вписывании команды "!health" будет выводить здоровье игрока в чат:

import { world, EntityComponentTypes } from "@minecraft/server";

world.beforeEvents.chatSend.subscribe((ev) => {
    let player = ev.sender;
    let msg = ev.message;
    if (msg == "!health") {
        ev.cancel = true;
        let healthCount = player.getComponent(EntityComponentTypes.Health);
        player.sendMessage(`У вас ${healthCount} здоровья!`);
    };
});

Тут как выше - при отправке сообщении, если это была команда health - через доп. класс EntityComponentTypes извлекаем количество здоровья и выводим в чат. Подробнее про другие функции можно почитать здесь.
На этом всё. В следующих публикациях будет разбор модуля @minecraft/server-ui. Когда оно будет - я незнаю, так что ждите.

https://jaylydev.github.io/scriptapi-docs/

{
    "format_version": 2,
    "header": {
        "name": "Bedrock Add-ons",
        "description": "Script API Template",
        "uuid": "<UUID>",
        "version": [0, 1, 0],
        "min_engine_version": [1, 20, 0]
    },
    "modules": [
        {
            "type": "script",
            "language": "javascript",
            "uuid": "<UUID>",
            "entry": "scripts/main.js",
            "version": [0, 1, 0]
        }
    ],
    "dependencies": [
        {
            "module_name": "@minecraft/server",
            "version": "1.8.0-beta"
        },
        {
            "module_name": "@minecraft/server-ui",
            "version": "1.3.0"
        }
    ]
}

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

Такую форму к примеру можно наблюдать при регистрации или входе на сайт. В Майнкрафте же оно выглядет примерно так.

В самом модуле существуют 8 форм, но мы разберем 3 основных класса для вывода 3 видов формы - ActionFormData (обычная форма, можно выводить только текст и кнопки), MessageFormData (форма, который содержит заголовок, основной текст и 2 кнопки), ModalFormData (форма с текстовыми полями, ползунками и т.д.)

Это форма в большинстве подходит для интерфейсов магазина, выбора мини-игр и т.д. Для его использования логично надо сначало импортировать, после создать экземпляр. А дальше все в коде:

import { world } from "@minecraft/server";
import { ActionFormData } from "@minecraft/server-ui";

world.beforeEvents.itemUse.subscribe((ev) => {
    const player = ev.source;

    let form = new ActionFormData();
    form.title("Заголовок формы");
    form.body("Тело формы, тоесть текст в форме");
    form.button("Кнопка 1");
    form.button("Кнопка 2", "textures/items/stick.png");

    form.show(player).then((res) => {
        if (res.canceled) return;

        if (res.selection === 0) {
            player.sendMessage("Это кнопка 1 вывело сообщение");
            return;
        } else if (res.selection === 1) {
             player.sendMessage("Это кнопка 2 с текстуркой палочки вывело сообщение");
            return;
        };
    });
});

Тут мы слушаем событие использование любого предмета, если используют предмет - создается экземпляр формы, в котором мы можем ввести 3 параметра - параметры заголовка, тела формы и их кнопок. В нашем случае мы изменили заголовок, тело формы и создали 2 кнопок. У второй кнопки же мы вводим в доп. параметры текстурки палки. И да - вместо палки можно вставить любую текстурку, и даже свою. Главное укажите путь до файла.

После создания экземпляра и ввода параметров мы его выводим через функцию show, указывая игрока, дабы ему вывести форму. После через then получаем результаты отправки форума, и если игрок нажал на крестик(находиться сверху справа), то форма закрывается посредством возвратной функции return, или же выполняем в нём инструкцию отправки сообщения если игрок не закрывал форму. И тут есть один момент - первая кнопка начинается по счету с 0, вторая - 1 и так далее.

Это класс для вывода формы, в экземпляр которого можно записать только заголовок, тело формы и 2 кнопки(без указания текстурки). Пример его использования:

import { world } from "@minecraft/server";
import { MessageFormData } from "@minecraft/server-ui";

world.beforeEvents.itemUse.subscribe((ev) => {
    const player = ev.source;

    let form = new MessageFormData();
    form.title("Заголовок формы");
    form.body("Вы хотите пиццу?");
    form.button1("Да");
    form.button2("Нет");

    form.show(player).then((res) => {
        if (res.canceled) return;

        if (res.selection === 0) {
            player.sendMessage("А нет, у меня так-то пиццы нету :3");
            return;
        } else if (res.selection === 1) {
             player.sendMessage("Ладно, у меня итак пиццы не было :3");
            return;
        };
    });
});

Здесь также, как и в прошлом коде, только стоит учитывать что тут не просто button, а только button1 и button2. Только выводимый текст немного другой.

Это форма, которую отличает от других разные виды ввода данных, а именно: текстовые поля, ползунки(слайдеры), выпадающий список и переключатель. В них можно также как и в других вводить заголовок формы, его тело, но вместо кнопок тут другие виды ввода данных, описанные выше. Пример кода ниже:

import { world } from "@minecraft/server";
import { ModalFormData } from "@minecraft/server-ui";

world.beforeEvents.itemUse.subscribe((ev) => {
    const player = ev.source;

    let form = new ModalFormData();
    form.title("Заголовок формы");
    form.textField("Введите сюда ваше имя для заказа", "Андрей");
    form.dropdown("Выберите пиццу:", ["Моцарелла", "Пеперонни", "Ещё я не придумал"]);
    form.slider("Выберите диаметр пиццы(в сантиметрах)", 25, 30, 40);
    form.toggle("Хотите в подарок стринги?");

    form.show(player).then((res) => {
        const [ textField, dropdown, slider, toggle ] = res.formValues;

        if (res.canceled) return;

        player.sendMessage(`Вы заказали пиццу "${dropdown}" на имя ${textField}, размер пиццы - ${slider} сантиметров, стринги в подарок - ${toggle}`);
    });
});

Тут мы вводим в параметры текстовое поля, выпадающий список, слайдер и переключитель, после выводим игроку в чат какую пиццу он заказал.