Work in progress

The content of this page was not yet updated for Godot 4.4 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 與相機存取也以外掛程式方式提供。

最新動態、說明文件與原始碼可於 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);

參數通常為 Dictionary，內含請求所需資訊。呼叫後會有兩個階段：首先，方法會立即回傳一個錯誤碼（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 介面產生一個事件，不論後續結果為錯誤、網路逾時等。這樣你可以安心讓 UI 等待伺服器回應。如果 API 沒有這樣設計，請回報為錯誤。

待處理事件介面（pending event interface）包含兩個方法：

get_pending_event_count()：回傳佇列中的待處理事件數量。
Variant pop_pending_event()：取出佇列中的第一個事件並回傳。

StoreKit

實作於 Godot iOS InAppStore plugin。

StoreKit 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`

藉由 StoreKit API 購買指定商品 ID。收到成功回應時需呼叫 finish_transaction(product_id)，或於購買前先呼叫 set_auto_finish_transaction(true)。這兩種方式都可確保交易被完成。

參數

參數為 Dictionary，需含 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 的商品資訊。

參數

參數為 Dictionary，需含 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`

恢復使用者帳號過去的購買紀錄。每個以前購買過的商品都會產生一個回應事件。

回應事件

回應事件為包含下列欄位的字典：

{
  "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。用以指定要完成購買的商品。例如：

in_app_store.finish_transaction("my_product1")

Game Center

實作於 Godot iOS GameCenter plugin。

Game Center API 可經由 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 驗證使用者身份。

回應事件

回應事件會是一個包含下列欄位的字典：

發生錯誤時：

{
  "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 排行榜。

參數

參數為 Dictionary，包含兩個欄位：

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`

修改 Game Center 成就的進度。

參數

參數為 Dictionary，包含 3 個欄位：

name （字串，成就名稱）
progress``（浮點數，成就進度，0.0~100.0，傳遞給 ``GKAchievement::percentComplete）
show_completion_banner （布林值，是否顯示成就完成橫幅於畫面頂端）

範例：

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`

查詢玩家所有已取得進度的 Game Center 成就。此函式不帶參數。

回應事件

回應事件會是一個包含下列欄位的字典：

發生錯誤時：

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

顯示內建 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",
}

iOS 外掛程式

存取外掛單例

非同步方法

StoreKit

purchase

參數

回應事件

request_product_info

參數

回應事件

restore_purchases

回應事件

set_auto_finish_transaction

參數

finish_transaction

參數

Game Center

authenticate

回應事件

post_score

參數

回應事件

award_achievement

參數

回應事件

reset_achievements

回應事件

request_achievements

回應事件

request_achievement_descriptions

回應事件

show_game_center

參數

回應事件

`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`