iOS用プラグイン

Godot provides StoreKit, GameCenter, iCloud services and other plugins. They are using same model of asynchronous calls explained below.

ARKit and Camera access are also provided as plugins.

Latest updates, documentation and source code can be found at Godot iOS plugins repository

Accessing plugin singletons

To access plugin functionality, you first need to check that the plugin is exported and available by calling the Engine.has_singleton() function, which returns a registered singleton.

Here's an example of how to do this in 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であり、呼び出しには2つのフェーズがあります。 まず、メソッドはすぐにエラー値を返します。 エラーが OK でない場合、コール操作は終了しますが、おそらく、ローカルで発生したエラー(インターネット接続がない、APIが正しく構成されていないなど)です。 エラー値が OK の場合、応答イベントが生成され、'pending events' キューに追加されます。 例:

func on_purchase_pressed():
    var result = InAppStore.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のいずれかがこのように動作しない場合は、バグとして扱う必要があります。

保留中のイベント(pending event)インターフェイスは、2つのメソッドで構成されています:

  • get_pending_event_count() キュー上の保留中のイベントの数を返します。

  • Variant pop_pending_event() キューから最初のイベントをポップし、それを返します。

Store Kit

Implemented in Godot iOS InAppStore plugin.

The Store Kit API is accessible through the InAppStore singleton. It is initialized automatically.

The following methods are available and documented below:

   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

Purchases a product ID through the Store Kit API. You have to call finish_transaction(product_id) once you receive a successful response or call set_auto_finish_transaction(true) prior to calling purchase(). These two methods ensure the transaction is completed.

Parameters

Takes a dictionary as a parameter, with one field, product_id, a string with your product ID. Example:

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

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

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

成功時:

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

request_product_info

製品IDのリストで製品情報を要求します。

Parameters

Takes a dictionary as a parameter, with a single product_ids key to which a string array of product IDs is assigned. Example:

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

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

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

Restores previously made purchases on user's account. This will create response events for each previously purchased product ID.

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

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

set_auto_finish_transaction

If set to true, once a purchase is successful, your purchase will be finalized automatically. Call this method prior to calling purchase().

Parameters

Takes a boolean as a parameter which specifies if purchases should be automatically finalized. Example:

in_app_store.set_auto_finish_transaction(true)

finish_transaction

If you don't want transactions to be automatically finalized, call this method after you receive a successful purchase response.

Parameters

Takes a string product_id as an argument. product_id specifies what product to finalize the purchase on. Example:

in_app_store.finish_transaction("my_product1")

Game Center

Implemented in Godot iOS GameCenter plugin.

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()

and the pending events interface:

int get_pending_event_count()
Variant pop_pending_event()

authenticate

Authenticates a user in Game Center.

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

{
  "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リーダーボードにスコアを投稿します。

Parameters

Takes a dictionary as a parameter, with two fields:

  • score 浮動小数点数

  • category カテゴリー名の文字列

例:

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

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

{
  "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アチーブメント(実績)の進捗を変更します。

Parameters

3つのフィールドを持つ Dictionary をパラメーターとして受け取ります:

  • name (string) 実績名

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

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

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

成功時:

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

reset_achievements

Game Centerのすべての実績をクリアします。 この関数はパラメーターを受け取りません。

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

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

成功時:

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

request_achievements

プレイヤーが進捗したGame Centerのすべての実績を要求します。この関数はパラメーターを受け取りません。

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

{
  "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の実績の説明を要求します。この関数はパラメーターを受け取りません。

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

エラー時:

{
  "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オーバーレイを表示し、リーダーボード、実績、課題を示します。

Parameters

次の2つのフィールドを使用した、Dictionaryをパラメーターとして受け取ります。

  • view (string) (オプション) 表示するビューの名前。"default"、"leaderboards"、 "achievements"、または "challenges" を受け入れます。 デフォルトは "default" です。

  • leaderboard_name (string) (オプション) 提示するリーダーボードの名前。"view" が "leaderboards" (または "default" がリーダーボードを表示するように設定されている)の場合にのみ使用されます。指定しない場合、Game Centerは集計リーダーボードを表示します。

例:

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

応答イベント

応答イベントは、次のフィールドを持つ Dictionary になります:

クローズ時:

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

マルチプラットフォームゲーム

マルチプラットフォームゲームで作業する場合、"GameCenter"シングルトンを常に使用できるとは限りません(たとえば、PCまたはAndroidで実行している場合)。 gdscriptコンパイラはコンパイル時にシングルトンを検索するため、シングルトンにクエリを実行して条件ブロック内で必要なものを確認して使用することはできません。また、シングルトンを有効な識別子(ローカル変数またはクラスメンバー)として定義する必要があります。これは、クラスでこれを回避する方法の例です:

var GameCenter = null # define it as a class member

func post_score(score):
    if GameCenter == null:
        return
    GameCenter.post_score({ "value": score, "category": "my_leaderboard" })

func check_events():
    while GameCenter.get_pending_event_count() > 0:
        # do something with events here
        pass

func _ready():
    # check if the singleton exists
    if Globals.has_singleton("GameCenter"):
        GameCenter = Globals.get_singleton("GameCenter")
        # connect your timer here to the "check_events" function