InnerCore/Mods/AchievementsAPI

AchievementsAPI – библиотека для создания достижений. В ней содержаться два модуля: AchievementsPopup и AcvievementsAPI. Здесь описаны основные их возможности. Больше информации вы можете узнать в виде комментариев в коде библиотеки.

AchievementPopup

Данный модуль позволяет создавать кастомные уведомления. Для этого существует метод show. Он добавляет уведомление в очередь на показ, из которой они последовательно показываются. Принимает объект со следующими полями: 
 

Название	Описание	Значение по умолчанию
title	Заголовок
color	Цвет заголовка	android.graphics.Color.YELLOW
description	Описание. Текст под заголовком
item	Иконка, задаваемая предметом	id – 0 data – 0 count – 1
delay	Кол-во тиков, которые уведомление будет находиться на экране	80

Пример использования:

ModAPI.addAPICallback("AchievementsAPI", function (api) {
    Callback.addCallback("ItemUse", function () {
        api.AchievementPopup.show({
            title: "Title",
            description: "And description",
            item: {
                id: 264,
                data: 0,
                count: 1
            }
        });
    });
});

AchievementAPI

В AchievementAPI представлен основной функционал мода - создание достижений.  Но для начала необходимо создать группу, в которой они будут находиться, используя registerGroup(obj),где obj – объект, описывающий группу. Все поля, которые он может содержать, описаны в таблице, приведённой далее.
 

Название	Описание	Значение по умолчанию
unique	Уникальный идентификатор группы	Обязательное поле
name	Название группы. Отображается в левом нижнем углу окна просмотра достижений
width	Размер области, в которой отображаются достижения по ширине и высоте соответственно	600
height		250
size	Размер достижений в области	100
bgTexture	Название текстуры в директориях ресурсов для гпи, которая используется в качестве фона области достижений. Данное изображение маштабируется до 50 пикселей и дублируется по ширине и высоте. Рекомендуемый размер – 16x16 пикселей
icon	Иконка группы, задаваемая предметом. Отображается в левом нижнем углу окна просмотра достижений	id – 0 data -0

Пример:

ModAPI.addAPICallback("AchievementsAPI", function (api) {  
    api.AchievementAPI.registerGroup({  
        unique: "vanilla",  
        name: "Vanilla",  
        width: 600,  
        height: 250,  
        size: 100,  
        bgTexture: "end",  
        icon: {  
            id: 1  
        }  
    });  
});  

Для регистрации самих достижений используется метод register(groupUnique,obj),где groupUnique – идентификатор группы, obj – объект, описывающий достижений. Для указания значения первого поля можно использовать как созданную вами, так и из сторонних модов.
ВНИМАНИЕ! Группа должна быть зарегистрирована до создания достижений для неё!

В таблице приведены возможные поля объекта.

Название	Описание	Значение по умолчанию
unique	Уникальный идентификатор достижения в текущей группе. В разных группах они могут повторяться.	Обязательное поле
name	Объект, задающий название/описание достижения, который может содержать поля translateи text. Первое указывает строку, которая будет локализована, если это не удалось или она не задана, будет использоваться text.
description
column	Один из способов размещения достижений – позиционирование по сетке.
row
x	Размещение достижений с явным указанием координат. Имеет больший приоритет, чем выравнивание по сетке, если заданы оба варианта.
y
parent	Задаёт родителя достижения. Данный объект может содержать unique, идентификатор родительского достижения, и groupUnique, группа, в которой оно находится. Если groupUnique не задано, поиск родителя будет осуществляться в пределах текущей группы и, если это завершилось успехом, они будут соединены линией. РОДИТЕЛЬСКОЕ ДОСТИЖЕНИЕ ДОЛЖНО БЫТЬ ЗАРЕГИСТРИРОВАНО РАНЬШЕ ДОЧЕРНЕГО!
strongDependence	Если значение – истина, достижение не будет отображаться, пока не выполнен родитель.	false
type	Тип достижения. Влияет на форму рамки и заголовок уведомления при выполнении. Существует три стандартных – default','challengeи goal. Для создания кастомной рамки необходимо в директории ресурсов для гпи создать папку achievement_bg и поместить в неё текстуры со следующими суффиксами: _completed', _'locked', _'unlocked. Для выполненных, заблокированных (родитель не выполнен),разблокированных достижений соответственно.	default
progressMax	Максимальный прогресс выполнения достижения. Предназначение поля будет описано ниже.
notCompletePopup	Если истина, уведомление о выполнении достижения показываться не будет.	false
item	Иконка достижения, задаваемая предметом.	id– 0 data– 0

Пример:

ModAPI.addAPICallback("AchievementsAPI", function (api) {
    api.AchievementAPI.register("somethingGroup", {
        unique: "one",
        name: {
        text: "Minecraft",
            translate: "achievements.story.root.title"
        },
        description: {
            text: "The heart and story of the game",
            translate: "achievements.story.root.description"
        },
        column: 1,
        row: 2,
        item: {
            id: 2
        }
    });
        
    api.AchievementAPI.register("somethingGroup", {
        unique: "two",
        name: {
            text: "Stone Age",
            translate: "achievements.story.mine_stone.title"
        },
        description: {
            text: "Mine stone with your new pickaxe",
            translate: "achievements.story.mine_stone.description"
        },
        parent: {
            unique: "one"
        },
        column: 2,
        row: 3,
        item: {
            id: 270
        }
    });
});

Для выдачи достижений используется метод give(groupUnique,unique). Если задано поле progressMax, то при вызове методы специальный счетчик будет увеличиваться на единицу, пока не будет равен значение максимального прогресса, после чего достижение будет выдано. В противном случае это произойдёт сразу.

Предусмотрена возможность сохранения информации о ходе выполнения достижения. Для этого необходимо вызвать метод getData(groupUnique,unique), который возвращает объект. В него вы можете сохранять какую-либо произвольную информацию. Пример, демонстрирующий эту функциональность:

Callback.addCallback("ItemUse", function (coords, item, block) {
    let data = AchievementAPI.getData("somethingGroup", "achievement");

    if (!data[item.id]) {
        data[item.id] = true;
        AchievementAPI.give("somethingGroup", "achievement")
    }
});

Нам необходимо использовать разные предметы progressMax раз, чтобы выполнить достижение.

Существует метод loadFrom(path), который загружает информацию из JSON файла. В нём могут находиться две секции – groups, achievements. Первая – массив для объектов, описывающих группы достижений, другая – объект, который хранит массивы из достижений. Ключом служит идентификатор группы. Пример такого файла:

{
    "groups": [
        {
            "unique": "vanilla",
            "name": "Vanilla",
            "width": 600,
            "height": 250,
            "size": 100,
            "bgTexture": "end",
            "icon": {
                "id": 1
            }
        },
        {
            "unique": "vanilla2",
            "name": "Vanilla2",
            "bgTexture": "nether",
                "icon": {
                "id": 264
            }
        }
    ],
    "achievements": {
        "vanilla": [
            {
                "unique": "one",
                "name": {
                    "text": "Minecraft",
                    "translate": "achievements.story.root.title"
                },
                "description": {
                    "text": "The heart and story of the game",
                    "translate": "achievements.story.root.description"
                },
                "column": 1,
                "row": 2,
                "item": {
                    "id": 2
                }
            }
        ],
        "vanilla2": [
            {
                "unique": "wwww23",
                "name": "test",
                "column": 1,
                "row": 2,
                "type": "challenge",
                "parent": {
                    "unique": "rrr23",
                    "groupUnique": "vanilla"
                },
                "item": {
                    "id": 4
                }
            }
        ]
    }
}