diff --git a/tutorials/platform/ios/plugins_for_ios.rst b/tutorials/platform/ios/plugins_for_ios.rst index fdf9960bd..df0d63095 100644 --- a/tutorials/platform/ios/plugins_for_ios.rst +++ b/tutorials/platform/ios/plugins_for_ios.rst @@ -8,7 +8,7 @@ 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 `_ +Latest updates, documentation and source code can be found at `Godot iOS plugins repository `_ Accessing plugin singletons --------------------------- @@ -38,7 +38,7 @@ this: :: - Error purchase(Variant p_params); + Error purchase(Variant params); The parameter will usually be a Dictionary, with the information necessary to make the request, and the call will have two phases. First, @@ -51,7 +51,7 @@ the 'pending events' queue. Example: :: func on_purchase_pressed(): - var result = in_app_store.purchase({ "product_id": "my_product" }) + var result = InAppStore.purchase({ "product_id": "my_product" }) if result == OK: animation.play("busy") # show the "waiting for response" animation else: @@ -86,34 +86,42 @@ Store Kit Implemented in `Godot iOS InAppStore plugin `_. -The Store Kit API is accessible through the ``InAppStore`` singleton. -It is initialized automatically. +The Store Kit API is accessible through the ``InAppStore`` singleton (will +always be available from GDScript on iOS). It is initialized automatically. -- ``Error purchase(Variant p_params);`` -- ``Error request_product_info(Variant p_params);`` -- ``Error restore_purchases();`` - -and the pending_event interface +The following methods are available and documented below: :: - int get_pending_event_count(); - Variant pop_pending_event(); + 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) -purchase -~~~~~~~~ + and the pending events interface: -Purchases a product id through the Store Kit API. + :: + + 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 +Takes a dictionary as a parameter, with one field, ``product_id``, a string with your product id. Example: :: - var result = InAppStore.purchase( { "product_id": "my_product" } ) + var result = InAppStore.purchase({ "product_id": "my_product" }) Response event ^^^^^^^^^^^^^^ @@ -127,7 +135,7 @@ On error: { "type": "purchase", "result": "error", - "product_id": "the product id requested" + "product_id": "the product id requested", } On success: @@ -137,23 +145,23 @@ On success: { "type": "purchase", "result": "ok", - "product_id": "the product id requested" + "product_id": "the product id requested", } -request_product_info -~~~~~~~~~~~~~~~~~~~~ +``request_product_info`` +~~~~~~~~~~~~~~~~~~~~~~~~ Requests the product info on a list of product IDs. Parameters ^^^^^^^^^^ -Takes a Dictionary as a parameter, with one field, ``product_ids``, a -string array with a list of product ids. Example: +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 = InAppStore.request_product_info( { "product_ids": ["my_product1", "my_product2"] } ) + var result = InAppStore.request_product_info({ "product_ids": ["my_product1", "my_product2"] }) Response event ^^^^^^^^^^^^^^ @@ -173,8 +181,8 @@ The response event will be a dictionary with the following fields: "localized_prices": [ list of valid product localized prices ], } -restore_purchases -~~~~~~~~~~~~~~~~~ +``restore_purchases`` +~~~~~~~~~~~~~~~~~~~~~ Restores previously made purchases on user's account. This will create response events for each previously purchased product id. @@ -189,31 +197,71 @@ The response events will be dictionaries with the following fields: { "type": "restore", "result": "ok", - "product id": "product id of restored purchase" + "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: + +:: + + InAppStore.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: + +:: + + InAppStore.finish_transaction("my_product1") + Game Center ----------- Implemented in `Godot iOS GameCenter plugin `_. -The Game Center API is available through the ``GameCenter`` singleton. It +The Game Center API is available through the "GameCenter" singleton. It has the following methods: -- ``Error authenticate();`` -- ``bool is_authenticated();`` -- ``Error post_score(Variant p_score);`` -- ``Error award_achievement(Variant p_params);`` -- ``void reset_achievements();`` -- ``void request_achievements();`` -- ``void request_achievement_descriptions();`` -- ``Error show_game_center(Variant p_params);`` -- ``Error request_identity_verification_signature();`` +:: -plus the standard pending event interface. + 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() -authenticate -~~~~~~~~~~~~ +and the pending events interface: + +:: + + int get_pending_event_count() + Variant pop_pending_event() + +``authenticate`` +~~~~~~~~~~~~~~~~ Authenticates a user in Game Center. @@ -243,15 +291,15 @@ On success: "player_id": the value from GKLocalPlayer::playerID, } -post_score -~~~~~~~~~~ +``post_score`` +~~~~~~~~~~~~~ Posts a score to a Game Center leaderboard. Parameters ^^^^^^^^^^ -Takes a Dictionary as a parameter, with two fields: +Takes a dictionary as a parameter, with two fields: - ``score`` a float number - ``category`` a string with the category name @@ -260,7 +308,7 @@ Example: :: - var result = GameCenter.post_score( { "score": 100, "category": "my_leaderboard", } ) + var result = GameCenter.post_score({ "score": 100, "category": "my_leaderboard", }) Response event ^^^^^^^^^^^^^^ @@ -287,8 +335,8 @@ On success: "result": "ok", } -award_achievement -~~~~~~~~~~~~~~~~~ +``award_achievement`` +~~~~~~~~~~~~~~~~~~~~~ Modifies the progress of a Game Center achievement. @@ -307,7 +355,7 @@ Example: :: - var result = award_achievement( { "name": "hard_mode_completed", "progress": 6.1 } ) + var result = award_achievement({ "name": "hard_mode_completed", "progress": 6.1 }) Response event ^^^^^^^^^^^^^^ @@ -333,8 +381,8 @@ On success: "result": "ok", } -reset_achievements -~~~~~~~~~~~~~~~~~~ +``reset_achievements`` +~~~~~~~~~~~~~~~~~~~~~~ Clears all Game Center achievements. The function takes no parameters. @@ -350,7 +398,7 @@ On error: { "type": "reset_achievements", "result": "error", - "error_code": the value from NSError::code + "error_code": the value from NSError::code, } On success: @@ -362,8 +410,8 @@ On success: "result": "ok", } -request_achievements -~~~~~~~~~~~~~~~~~~~~ +``request_achievements`` +~~~~~~~~~~~~~~~~~~~~~~~~ Request all the Game Center achievements the player has made progress on. The function takes no parameters. @@ -380,7 +428,7 @@ On error: { "type": "achievements", "result": "error", - "error_code": the value from NSError::code + "error_code": the value from NSError::code, } On success: @@ -391,11 +439,11 @@ On success: "type": "achievements", "result": "ok", "names": [ list of the name of each achievement ], - "progress": [ list of the progress made on each achievement ] + "progress": [ list of the progress made on each achievement ], } -request_achievement_descriptions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``request_achievement_descriptions`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Request the descriptions of all existing Game Center achievements regardless of progress. The function takes no parameters. @@ -412,7 +460,7 @@ On error: { "type": "achievement_descriptions", "result": "error", - "error_code": the value from NSError::code + "error_code": the value from NSError::code, } On success: @@ -423,16 +471,16 @@ On success: "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 ] + "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 -~~~~~~~~~~~~~~~~ +``show_game_center`` +~~~~~~~~~~~~~~~~~~~~ Displays the built in Game Center overlay showing leaderboards, achievements, and challenges. @@ -454,8 +502,8 @@ Examples: :: - var result = show_game_center( { "view": "leaderboards", "leaderboard_name": "best_time_leaderboard" } ) - var result = show_game_center( { "view": "achievements" } ) + var result = show_game_center({ "view": "leaderboards", "leaderboard_name": "best_time_leaderboard" }) + var result = show_game_center({ "view": "achievements" }) Response event ^^^^^^^^^^^^^^ @@ -470,3 +518,34 @@ On close: "type": "show_game_center", "result": "ok", } + +Multi-platform games +-------------------- + +When working on a multi-platform game, you won't always have the +"GameCenter" singleton available (for example when running on PC or +Android). Because the gdscript compiler looks up the singletons at +compile time, you can't just query the singletons to see and use what +you need inside a conditional block, you need to also define them as +valid identifiers (local variable or class member). This is an example +of how to work around this in a class: + +:: + + 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