Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

iOS 的插件

Godot 提供了 StoreKit、GameCenter、iCloud 服务等插件。它们使用下面解释的相同异步调用模型。

ARKit和Camera访问也作为插件提供.

最新的更新、文档和源代码可以在Godot iOS插件库找到 Godot iOS plugins repository

访问插件单例

要访问插件功能, 首先需要通过调用 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()

请记住,当一个调用返回 OK 时,API 将始终通过 pending_event 接口产生一个事件,即使它是一个错误,或网络超时等。您应该能够,例如,安全地阻止等待的接口来自服务器的回复。如果任何 API 不以这种方式运行,则应将其视为错误。

挂起事件接口包含两个方法:

  • get_pending_event_count() 返回队列中挂起事件的数量。

  • Variant pop_pending_event() 弹出队列中的第一个事件并返回它。

Store Kit

实现在 Godot iOS InAppStore 插件 .

Store Kit API 可通过 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

通过 Store Kit API 购买一个产品 ID。你需要在收到成功响应后调用 finish_transaction(product_id),或者在调用 purchase() 之前调用 set_auto_finish_transaction(true)。这两个方法确保事务完成。

参数

参数是一个字典,包含一个 product_id 字段,是你的商品的字符串 ID。例子:

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

响应事件

响应事件将是包含以下字段的字典:

出错时:

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

成功时:

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

request_product_info

在产品ID列表中请求产品信息.

参数

参数为字典,只有一个字段 product_ids,是产品 ID 字符串的数组。例如:

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

响应事件

响应事件将是包含以下字段的字典:

{
  "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

恢复用户账户之前完成的购买。会为每一个之前购买过的产品 ID 创建响应事件。

响应事件

响应事件将是包含以下字段的字典:

{
  "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 插件中实现。

The Game Center API is available through the GameCenter singleton. It has the following methods:

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

在游戏中心对用户进行身份验证.

响应事件

响应事件将是包含以下字段的字典:

出错时:

{
  "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

将分数发布到游戏中心排行榜.

参数

参数为一个字典,有两个字段:

  • score 浮点数

  • category 表示类别名称的字符串

示例:

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

响应事件

响应事件将是包含以下字段的字典:

出错时:

{
  "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

修改游戏中心成就的进度.

参数

将Dictionary作为参数, 包含3个字段:

  • name(字符串)成就名称

  • progress(float)成就进度从 0.0 到 100.0(传递给 GKAchievement :: percentComplete

  • show_completion_banner(bool)游戏中心是否应该在屏幕顶部显示成就横幅

示例:

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

响应事件

响应事件将是包含以下字段的字典:

出错时:

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

成功时:

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

reset_achievements

清除所有 Game Center 成就。该函数不带参数。

响应事件

响应事件将是包含以下字段的字典:

出错时:

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

成功时:

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

request_achievements

请求游戏角色取得进步的所有游戏中心成就. 该函数不带参数.

响应事件

响应事件将是包含以下字段的字典:

出错时:

{
  "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成就. 该函数不带参数.

响应事件

响应事件将是包含以下字段的字典:

出错时:

{
  "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

显示内置的游戏中心叠加层, 显示排行榜, 成就和挑战.

参数

将Dictionary作为参数, 包含两个字段:

  • 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" })

响应事件

响应事件将是包含以下字段的字典:

关闭时:

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