GuideAPI

GuideAPI

GuideAPI – мод-библиотека, предоставляющая большие возможности для создания игровых документаций.
ModAPI.addAPICallback("GuideAPI", function(api) {
    const GuideAPI = api.GuideAPI;
    const GuideHelper = api.GuideHelper;
    const PageControllers = api.PageControllers;

    IDRegistry.genItemID("testGuide");
    Item.createItem("testGuide", "Test Guide", {
        name: "stick"
    });

    GuideAPI.registerGuide("guideTest", {
        item: ItemID.testGuide,
        debug: false,
        textures: {
            background: "your_texture",
            nextLink: "your_texture",
            preLink: "your_texture",
            close: "your_texture",
        },
        pages: {
            "default": {
                nextLink: "test",
                left: {
                    controller: PageControllers.BASIC_PAGE,
                    elements: []
                },

                right: {
                    controller: PageControllers.BASIC_PAGE,
                    elements: []
                }
            }
        }
    });
});

Регистрация происходит через метод GuideAPI.registerGuide(unique, params), где unique – уникальный идентификатор, params – объект с параметрами.
Параметры:

  • Объект textures задаёт текстуры для интерфейса. Если не объявлен, будет использоваться стандартное оформление
    • background – текстура заднего фона
    • nextLink– текстура для кнопки “вперёд”
    • preLink – текстура для кнопки “назад”
    • сlose – текстура для кнопки закрытия интерфейса
  • Объект item задаёт ид предмета, при клике которым происходит открытие интерфейса. Является необязательным параметром
  • Если debug объявлен и равен true, у интерфейса вызывается метод setDebugEnabled(true)
  • Объект pages содержит страницы. Каждая имеет правую(right) и левую(left) секции, для которых задаются контроллеры(controller). Любую из них можно пропустить. nextLink содержит идентификатор страницы, на которую происходит переход при нажатии кнопки “вперёд”, preLinkпри нажатии кнопки “назад”. При открытии интерфейса происходит загрузка страницы с идентификатором default.
 

Контроллеры

Контроллер – функция, указанная под идентификатором controller в объекте секции. GuideAPI предоставляет стандартные контроллеры, находящиеся в объекте PageControllers, которые позволяют решить большинство задач.

BASIC_PAGE

Контроллер BASIC_PAGE позволяет создавать простые страницы с текстом.
{
    controller: PageControllers.BASIC_PAGE,
    elements: [
        {text: "I'm simple text!" },
        { text: "I'm big text!", size: 20 },
        { text: "I'm red text!", color: android.graphics.Color.RED },
        { text: "I'm underlined bold text!", underline: true, bold: true },
        { text: "I'm link. Click me, please!", color: android.graphics.Color.BLUE, link: "page2" }
    ]
}

Объект elements доступен для использования во всех стандартных контроллерах. Он содержит массив строк, каждая из которых отображается на новой строке. Если текст не влезает в границы секции, он будет перенесён.
Параметры текста:

  • size – размер шрифта
  • color – цвет текста(android.graphics.Color.RED, android.graphics.Color.BLUE и тд)
  • underline – подчёркнутый ли текст
  • bold – жирный ли текст
  • link – идентификатор страница, на которую будет осуществлён переход при клике на текст

ITEM_PAGE

Котроллер ITEM_PAGE позволяет создавать страницы с группой предметов и текстом.

{
    controller: PageControllers.ITEM_PAGE,
    items: [
        { id: 1, data: 1 },
        { id: 264 },
        { id: 266 },
    ],
    elements: [
        { text: "I'm text", size: 20 },
        { text: "And I'm text too" }
    ]
}

items – массив из отображаемых предметов. Первый из них будет помещён в большой слот.

ITEM_GRID_PAGE

Контроллер ITEM_GRID_PAGE позволяет располагать предметы сеткой.

{
    controller: PageControllers.ITEM_GRID_PAGE,
    columns: 8,
    item_size: 30,
    items: [
        { id: 1, data: 1, count: 34 },
        { id: 264, link: "test" },
        {
            id: 265,
            clicker: {
                onClick: function() {
                    alert("CLICK!!!!!!!!!!!!!!!!!!11");
                }
            }
        },
        { id: 4 },
        { id: 5 },
        { id: 6 },
        { id: 7 },
        { id: 8 },
        { id: 9 },
        { id: 10 },
    ],
    elements: [
        { text: "HELLO", size: 15, underline: true, bold: true }
    ]
}

items – массив из отображаемых предметов
сolumns – количество колонок. По умолчанию 6
item_size – размер предмета. По умолчанию 60
Параметры для предметов:

  • link – идентификатор страница, на которую будет осуществлён переход при клике на текст
  • clicker – объект клика.
    • onClick – короткий клик
    • onLongClick - длинный

OTO_RECIPE_PAGE

Котроллер OTO_RECIPE_PAGE позволяет создавать страницы с рецептами “Один к одному”.

{
    controller: PageControllers.OTO_RECIPE_PAGE,
    title: "Furnace Recipe",
    type: 0,
    bar_texture: "furnace_bar_guide",
    recipes: [
        {
            input: { id: 4, data: 1, count: 10 },
            output: { id: 264 }
        },
        {
            input: { id: 264 },
            output: { id: 265 }
        }
    ],
    elements: [
        { text: "Text" },
        { text: "And Text" },
    ]
}

Если type равен 0, recipes – массив из объектов, в которых содержится предмет на вход(input) и предмет на выход(output).

{
    controller: PageControllers.OTO_RECIPE_PAGE,
    title: "Furnace Recipe",
    type: 1,
    bar_texture: "furnace_bar_guide",
    recipes: [
        { id: 1 },
        { id: 17, data: 1 }
    ],
    elements: [
        { text: "This is type 1" }
    ]
}

Если type равен 1, recipes – массив из объектов, которые содержат информацию о предмет на вход. В выходной слот будет помещаться результат обработки указанного предмета в печи.
Остальные параметры:

  • title – заголовок страницы
  • bar_texture – текстура для индикатора прогресса

GRID_3x3_PAGE

Котроллер GRID_3x3_PAGE позволяет создавать страницы рецептов с сеткой 3x3.

{
    controller: PageControllers.GRID_3x3_PAGE,
    title: "Workbench Recipe",
    recipes: [{
        grid: [
            ["b", "b", "b"],
            ["b", "g", "b"],
            ["b", "8", "b"]
        ],
        materials: {
            "b": { id: 4, data: 0 },
            "g": { id: 1, data: 0 },
        },
        result: { id: 61, count: 3 }
    }],
    elements: [
        { text: "Text"}
    ],
}

Создание собственных контроллеров

Для создания собственных контроллеров необходимо в поле controller передать функцию, которая будет рисовать элементы на странице.

PageControllers["MY_TEST_PAGE"] = function(params, elements, container, section) {
    let x = section === "left" ? 50 : 550;
    elements["text_" + section + "_" + i] = {
        type: "text",
        x: section,
        y: 40,
        text: params.title
    };

    if (params.elements)
        GuideHelper.drawTextArray(params.elements, x, 55, globalSize, elements, section);
};
//...
{
    controller: PageControllers.MY_TEST_PAGE,
    title: "I'm title",
    elements: [
        { text: "Text" }
    ],
}
//...

Передаваемые аргументы:

  • params – объект секции, для которой вызывается функция
  • elements – элементы интерфейса
  • container – контейнер интерфейса
  • section – название секции(left, right)