Добавление плагина в проект Defold

Установка

Вы можете использовать его в своем собственном проекте, добавив github проект в качестве зависимости библиотеки Defold.

Инициализация

В файл game.project необходимо добавить раздел gamepush и указать id и token игры, остальные параметры можно опустить:

[gamepush]
id = идентификатор игры
token = токен
description = There are not enough words to describe the awesomeness of the game
image = /img/ogimage.png

Дополнительные параметры: (doc)

Для начала необходимо инициализировать SDK с помощью метода init:

local gamepush = require("gamepush.gamepush")

gamepush.init(function(success)
    if success then
        -- инициализация прошла успешно
    else
        -- ошибка инициализации
    end
end)

Для подписки на событие необходимо определить соответсвующий метод таблицы callbacks:

local gamepush = require("gamepush.gamepush")

local function ads_start()
    -- выключаем звук
end

local function ads_close(success)
    -- включаем звук
end

local function ads_reward()
    -- подкидываем золотишка игроку
end

-- функции событий можно назначить до инициализации SDK
gamepush.ads.callbacks.start = ads_start
gamepush.ads.callbacks.close = ads_close
gamepush.ads.callbacks.rewarded_reward = ads_reward
-- инициализация SDK
gamepush.init(function(success)
    if success then
        -- показываем прелоадер
        gamepush.ads.show_preloader(function(result)
            -- реклама закрыта, можно что-то делать
        end)
        -- что то делаем еще

        -- показываем рекламу за вознаграждение
        gamepush.ads.show_rewarded_video()

        -- показываем рекламу за вознаграждение с использованием колбека
        gamepush.ads.show_rewarded_video(function(result)
            if result then
                -- подкидываем игроку кристаллов
            end
        end)
    else
        -- ошибка инициализации
    end
end)

Список всех методов

Подробнее со списком всех методов можно ознакомиться по ссылке.

Вызов нативных методов платформы

Для вызова нативного метода, получения объекта или поля предназначена функция call_native_sdk(method, parameters, callback).

method: строка, путь до метода, объекта или поля разделенного точками. Если указан путь до объекта или поля объекта, то parameters и callback будет проигнорирован.
parameters: параметр вызываемого метода (string, number, boolean, table). Если необходимо передать несколько параметров, то параметры необходимо поместить в массив (таблицу). Порядок параметров определяется индексом массива. Не поддерживается передача функций в качестве параметров!
callback: функция обратного вызова, необходимо указывать, если нативный метод возвращает промис. Если callback == nil, то функция возвращает результат, иначе nil.

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

Параметр method ссылается на объект или поле объекта:

Если результат string, number, boolean или объект, то возвращаются полученные данные.
В случае если произошло исключение, то данные об ошибке возвращаются в виде таблицы {error = "error description"}.

Параметр method ссылается на функцию:

Если результат string, number, boolean или объект, то возвращаются полученные данные.
В случае если произошло исключение, или промис завершился ошибкой, то данные об ошибке возвращаются в виде таблицы {error = "error description"}.

callback(result): result - результат выполнения промиса, если промис завершился ошибкой, то result = {error = "error description"}.

Расширенные действия с промисами

Бывают ситуации, когда промис возвращает объект с функциями, которые может потребоваться выполнить позже. Для этих ситуаций предусмотрен механизм сохранения объекта на уровне JS и дальнейшего его использования при следующих вызовах API.

В этих случаях формат параметра method для функции call_native_sdk может принимать вид:

var=path1.path2.path3: объект path1.path2.path3 будет сохранен в переменную var
var:method: вызов метода из ранее сохраненного объекта
var2=var:method2: вызов метода (необходимо что-бы он был промисом) из ранее сохраненного объекта и сохранение результата в переменной var2

Примеры различных вариантов вызова

Запрос к СДК	Тип	Вызов функции и результат
environment	object	call_native_sdk("environment") table
environment.i18n.lang	string	call_native_sdk("environment.i18n.lang") string
env	undefined	call_native_sdk("env") {error = 'Field or function "env" not found!'}
player.getUniqueID()	function	call_native_sdk("player.getUniqueID") string
feedback.canReview()	function	call_native_sdk("feedback.canReview", nil, callback) nil После завершения промиса будет вызван callback.
getLeaderboards().then(lb => {})	function	call_native_sdk("lb=getLeaderboards", nil, callback) nil После завершения промиса будет вызван callback. Результат будет сохранен в переменной JS.
lb.setLeaderboardScore()	function	call_native_sdk("lb:setLeaderboardScore") После завершения промиса будет вызван callback. При вызове функции будет обращение к ранее сохраненной переменной JS, если она не найдена функция вернет {error = "The 'lb' object has not been previously saved!"}

Пример нативной работы с платформой Yandex:

local gamepush = require("gamepush.gamepush")

gamepush.init(function(result)
    if result then
        -- Получить переменные окружения Яндекса, эквивалент ysdk.environment
        local environment = gamepush.platform.call_native_sdk("environment")

        -- Получить язык интерфейса Яндекс.Игр в формате ISO 639-1, эквивалент ysdk.environment.i18n.lang
        local language = gamepush.platform.call_native_sdk("environment.i18n.lang")

        -- Получить таблицы лидеров, эквивалент ysdk.getLeaderboards()
        -- промис возвращает объект, сохраним его в переменную lb
        gamepush.platform.call_native_sdk("lb=getLeaderboards", nil, function(leaderboards)
            pprint(leaderboards)
            -- Запись нового рекорда, эквивалент lb.setLeaderboardScore('leaderboard2021', 120);
            -- будем обращаться к переменной lb
            gamepush.platform.call_native_sdk("lb:setLeaderboardScore", { "leaderboard2021", 120 })
            -- Получить данные таблицы лидеров, эквивалент lb.getLeaderboardEntries('leaderboard2021')
            gamepush.platform.call_native_sdk("lb:getLeaderboardEntries", "leaderboard2021", nil, function(result)
                pprint(result)
            end)

            -- Получить данные таблицы лидеров с параметрами
            -- эквивалент lb.getLeaderboardEntries('leaderboard2021', {quantityTop: 10, includeUser: true, quantityAround: 3})
            local parameters = {
                "leaderboard2021",
                { quantityTop = 10, includeUser = true, quantityAround = 3 }
            }
            gamepush.platform.call_native_sdk("lb:getLeaderboardEntries", parameters, function(result)
                pprint(result)
            end)
        end)
    end
end)

Представленный выше код эквивалентен коду JS:

YaGames.init().then((ysdk) => {
    // Получить переменные окружения Яндекса
    let environment = ysdk.environment;

    // Получить язык интерфейса Яндекс.Игр в формате ISO 639-1
    let language = ysdk.environment.i18n.lang;

    // Получить таблицы лидеров
    ysdk.getLeaderboards().then(function (lb) {
        console.log(lb);
        // Запись нового рекорда
        lb.setLeaderboardScore('leaderboard2021', 120);
        // Получить данные таблицы лидеров
        lb.getLeaderboardEntries('leaderboard2021').then(function (result) {
            console.log(result);
        });

        // Получить данные таблицы лидеров с параметрами
        let parameters = { quantityTop: 10, includeUser: true, quantityAround: 3 };
        lb.getLeaderboardEntries('leaderboard2021', parameters).then(function (result) {
            console.log(result);
        });
    });
});

Заглушка для других платформ, отличных от html

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

При использовании функций:

player.get(key)
player.set(key, value)
player.add(key, value)
player.toggle(key)
player.has(key)
player.to_json()
player.from_json(player)

данные будут сохраняться/считываться с помощью sys.save()/sys.load() локально в/из файла "gamepush.dat" (можно поменять)

local mock_api = require("gamepush.mock_api")

-- установим имя для файла локального хранилища данных
mock_api.file_storage = "my_storage.dat"

-- установка параметров "заглушек"
mock_api["player.name"] = "my player name"
mock_api["player.id"] = 625
mock_api["player.score"] = 500

Каждая функция-заглушка GamePush API может быть представлена данными или функцией выполняющее действие и/или возвращающая данные. Любые функции/данные можно переопределять для удобства работы/отладки.

Заглушка для нативных вызовов

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

--native_api.lua
local M = {}

M["environment"] = {
    app = {
        id = "app_id"
    },
    browser = {
        lang = "ru"
    },
    i18n = {
        lang = "ru",
        tld = "ru"
    }
}

return M

local mock = require("gamepush.mock")
local native_api = require("native_api")
local gamepush = require("gamepush.gamepush")

-- Устанавливаем заглушку для нативных функций
mock.set_native_api(native_api)
-- Обращаемся к нативной функции
local result = gamepush.platform.call_native_sdk("environment")
pprint(result)

Автор: Megalanthus

Оставайтесь на связи

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

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!

Добавление плагина в проект Defold

Установка​

Инициализация​

Список всех методов​

Вызов нативных методов платформы​

Расширенные действия с промисами​

Примеры различных вариантов вызова​

Пример нативной работы с платформой Yandex:​

Заглушка для других платформ, отличных от html​

Заглушка для нативных вызовов​

Оставайтесь на связи​