Work in progress

The content of this page was not yet updated for Godot 4.6 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

Плагины для iOS

Godot предоставляет сервисы StoreKit, GameCenter, iCloud и другие плагины. Они используют ту же модель асинхронных вызовов, которая описана ниже.

ARKit и доступ к камере также предоставляются в виде плагинов.

Если вы собираетесь участвовать в работе над документацией, её репозиторий можно найти здесь

Доступ к одиночным (singletons) плагинам

Чтобы получить доступ к функционалу плагина, сначала необходимо проверить, что плагин экспортирован и доступен, вызвав функцию Engine.has_singleton(), которая возвращает зарегистрированный синглтон.

Вот простой пример того, как это сделать на GDScript:

var in_app_store
var game_center

func _ready():
    if Engine.has_singleton("InAppStore"):
        in_app_store = Engine.get_singleton("InAppStore")
    else:
        print("iOS IAP plugin is not available on this platform.")

    if Engine.has_singleton("GameCenter"):
        game_center = Engine.get_singleton("GameCenter")
    else:
        print("iOS Game Center plugin is not available on this platform.")

Асинхронные методы

При запросе асинхронной операции метод будет выглядеть так:

Error purchase(Variant params);

Параметром обычно является словарь, содержащий информацию, необходимую для выполнения запроса, а вызов будет состоять из двух фаз. Сначала метод немедленно возвращает значение Error. Если значение Error не равно 'OK', операция вызова завершается, при этом ошибка, вероятно, вызвана локально (отсутствие подключения к Интернету, неправильная настройка API и т.д.). Если значение ошибки равно 'OK', будет создано ответное событие и добавлено в очередь 'ожидающих событий'. Пример:

func on_purchase_pressed():
    var result = in_app_store.purchase({ "product_id": "my_product" })
    if result == OK:
        animation.play("busy") # show the "waiting for response" animation
    else:
        show_error()

# put this on a 1 second timer or something
func check_events():
    while in_app_store.get_pending_event_count() > 0:
        var event = in_app_store.pop_pending_event()
        if event.type == "purchase":
            if event.result == "ok":
                show_success(event.product_id)
            else:
                show_error()

Помните, что при успешном завершении вызова API всегда создаст событие через интерфейс pending_event, даже если это ошибка, тайм-аут сети и т. д. Вы должны иметь возможность, например, безопасно заблокировать интерфейс в ожидании ответа от сервера. Если какой-либо API работает не так, это следует рассматривать как ошибку.

Интерфейс ожидающего события состоит из двух методов:

get_pending_event_count() Возвращает количество ожидающих событий в очереди.
Variant pop_pending_event() Извлекает первое событие из очереди и возвращает его.

Store Kit (Комплект для магазина)

Реализовано в Godot iOS InAppStore plugin.

API Store Kit доступен через синглтон InAppStore. Он инициализируется автоматически.

Доступны и задокументированы следующие методы:

   Error purchase(Variant params)
   Error request_product_info(Variant params)
   Error restore_purchases()
   void set_auto_finish_transaction(bool enable)
   void finish_transaction(String product_id)

and the pending events interface:

::

   int get_pending_event_count()
   Variant pop_pending_event()

`purchase`

Покупает идентификатор товара через API Store Kit. Необходимо вызвать finish_transaction(product_id) после получения успешного ответа или set_auto_finish_transaction(true) перед вызовом purchase(). Эти два метода гарантируют завершение транзакции.

Параметры

Принимает словарь в качестве параметра с одним полем product_id, строкой с идентификатором вашего продукта. Пример:

var result = in_app_store.purchase({ "product_id": "my_product" })

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "purchase",
  "result": "error",
  "product_id": "the product ID requested",
}

В случае успеха:

{
  "type": "purchase",
  "result": "ok",
  "product_id": "the product ID requested",
}

`request_product_info`

Запрашивает информацию о продукте из списка идентификаторов продуктов.

Параметры

Принимает словарь в качестве параметра с одним ключом product_ids, которому назначается строковый массив идентификаторов продуктов. Пример:

var result = in_app_store.request_product_info({ "product_ids": ["my_product1", "my_product2"] })

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

{
  "type": "product_info",
  "result": "ok",
  "invalid_ids": [ list of requested IDs that were invalid ],
  "ids": [ list of IDs that were valid ],
  "titles": [ list of valid product titles (corresponds with list of valid IDs) ],
  "descriptions": [ list of valid product descriptions ],
  "prices": [ list of valid product prices ],
  "localized_prices": [ list of valid product localized prices ],
}

`restore_purchases`

Восстанавливает ранее совершённые покупки в учётной записи пользователя. Это создаст события ответа для каждого ранее приобретённого идентификатора продукта.

Response event (Событие ответа)

События ответа будут представлять собой словари со следующими полями:

{
  "type": "restore",
  "result": "ok",
  "product_id": "product ID of restored purchase",
}

`set_auto_finish_transaction`

Если установлено значение true, после успешной покупки она будет завершена автоматически. Вызовите этот метод перед вызовом purchase().

Параметры

Принимает логическое значение в качестве параметра, указывающего, следует ли автоматически завершать покупки. Пример:

in_app_store.set_auto_finish_transaction(true)

`finish_transaction`

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

Параметры

Принимает строку product_id в качестве аргумента. product_id указывает, какой продукт необходимо завершить покупку. Пример:

in_app_store.finish_transaction("my_product1")

Игровой центр

Реализовано в Godot iOS GameCenter plugin.

API Game Center доступен через синглтон GameCenter. Он содержит следующие методы:

Error authenticate()
bool is_authenticated()
Error post_score(Variant score)
Error award_achievement(Variant params)
void reset_achievements()
void request_achievements()
void request_achievement_descriptions()
Error show_game_center(Variant params)
Error request_identity_verification_signature()

и интерфейс ожидающих событий:

int get_pending_event_count()
Variant pop_pending_event()

`authenticate`

Аутентифицирует пользователя в Game Center.

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "authentication",
  "result": "error",
  "error_code": the value from NSError::code,
  "error_description": the value from NSError::localizedDescription,
}

В случае успеха:

{
  "type": "authentication",
  "result": "ok",
  "player_id": the value from GKLocalPlayer::playerID,
}

`post_score`

Публикует результаты в таблице лидеров Game Center.

Параметры

Принимает в качестве параметра словарь с двумя полями:

score число с плавающей точкой
category строка с названием категории

Пример:

var result = game_center.post_score({ "score": 100, "category": "my_leaderboard", })

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "post_score",
  "result": "error",
  "error_code": the value from NSError::code,
  "error_description": the value from NSError::localizedDescription,
}

В случае успеха:

{
  "type": "post_score",
  "result": "ok",
}

`award_achievement`

Изменяет ход выполнения достижения Game Center.

Параметры

Принимает в качестве параметра Словарь с 3 полями:

name (строка) название достижения
progress (float) прогресс достижения от 0,0 до 100,0 (передается в GKAchievement::percentComplete)
show_completion_banner (bool) должен ли Game Center отображать баннер достижения в верхней части экрана

Пример:

var result = award_achievement({ "name": "hard_mode_completed", "progress": 6.1 })

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "award_achievement",
  "result": "error",
  "error_code": the error code taken from NSError::code,
}

В случае успеха:

{
  "type": "award_achievement",
  "result": "ok",
}

`reset_achievements`

Удаляет все достижения Game Center. Функция не принимает параметров.

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "reset_achievements",
  "result": "error",
  "error_code": the value from NSError::code,
}

В случае успеха:

{
  "type": "reset_achievements",
  "result": "ok",
}

`request_achievements`

Запросить все достижения Game Center, в которых игрок продвинулся. Функция не принимает параметров.

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "achievements",
  "result": "error",
  "error_code": the value from NSError::code,
}

В случае успеха:

{
  "type": "achievements",
  "result": "ok",
  "names": [ list of the name of each achievement ],
  "progress": [ list of the progress made on each achievement ],
}

`request_achievement_descriptions`

Запросить описания всех существующих достижений Game Center, независимо от прогресса. Функция не принимает параметров.

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

В случае ошибки:

{
  "type": "achievement_descriptions",
  "result": "error",
  "error_code": the value from NSError::code,
}

В случае успеха:

{
  "type": "achievement_descriptions",
  "result": "ok",
  "names": [ list of the name of each achievement ],
  "titles": [ list of the title of each achievement ],
  "unachieved_descriptions": [ list of the description of each achievement when it is unachieved ],
  "achieved_descriptions": [ list of the description of each achievement when it is achieved ],
  "maximum_points": [ list of the points earned by completing each achievement ],
  "hidden": [ list of booleans indicating whether each achievement is initially visible ],
  "replayable": [ list of booleans indicating whether each achievement can be earned more than once ],
}

`show_game_center`

Отображает встроенный оверлей Game Center с таблицами лидеров (leaderboards), достижениями (achievements) и задачами (challenges).

Параметры

Принимает Словарь в качестве параметра с двумя полями:

view (строка) (необязательно) — имя представления для отображения. Допустимые значения: "default", "leaderboards", "achievements", или "challenges". Значение по умолчанию — "default".
leaderboard_name (строка) (необязательно) название отображаемой таблицы лидеров. Используется только если в качестве "view" выбрано "leaderboards" (или в качестве "default" настроено отображение таблиц лидеров). Если не указано, Game Center будет отображать общую таблицу лидеров.

Примеры:

var result = show_game_center({ "view": "leaderboards", "leaderboard_name": "best_time_leaderboard" })
var result = show_game_center({ "view": "achievements" })

Response event (Событие ответа)

Событием ответа будет словарь со следующими полями:

При закрытии:

{
  "type": "show_game_center",
  "result": "ok",
}

Плагины для iOS

Доступ к одиночным (singletons) плагинам

Асинхронные методы

Store Kit (Комплект для магазина)

purchase

Параметры

Response event (Событие ответа)

request_product_info

Параметры

Response event (Событие ответа)

restore_purchases

Response event (Событие ответа)

set_auto_finish_transaction

Параметры

finish_transaction

Параметры

Игровой центр

authenticate

Response event (Событие ответа)

post_score

Параметры

Response event (Событие ответа)

award_achievement

Параметры

Response event (Событие ответа)

reset_achievements

Response event (Событие ответа)

request_achievements

Response event (Событие ответа)

request_achievement_descriptions

Response event (Событие ответа)

show_game_center

Параметры

Response event (Событие ответа)

`purchase`

`request_product_info`

`restore_purchases`

`set_auto_finish_transaction`

`finish_transaction`

`authenticate`

`post_score`

`award_achievement`

`reset_achievements`

`request_achievements`

`request_achievement_descriptions`

`show_game_center`