Skip to content

Search

Documentation

Stores

The platform module is one script API over every store: sign-in, achievements, leaderboards, cloud saves and in-app purchases, with StoreKit behind it.

On this page

The platform module is one script API over every store.

  • One call unlocks an achievement on Game Center, Play Games and Steam.
  • What only one platform has lives in that platform's module: apple.
  • With no store loaded (the editor, a desktop run, a replay) every call answers kind = "unsupported".
pub class Player {
    node: Node,
}

impl Player {
    pub async fn init() {
        events::listen(self.node, "platform_event");
        let me = await task::wait(platform::sign_in());
        log::info("playing as {me["alias"]}");
        platform::unlock("first_blood");
    }

    pub fn on_platform_event(e: any) {
        if e["kind"].as_str() == platform::EVENT_SIGNED_OUT {
            // The player signed out in the OS. A node that listens hears it.
        }
    }
}
  • Delivery is the networking and Gamend contract. A call returns an id at once. The store answers on a later tick, to whoever awaits the id.
  • A sign-in or a sign-out also reaches on_platform_event on a node that called events::listen(node, "platform_event").
  • Every answer carries a kind: signed_in, signed_out, done, scores, read, error, unsupported.

The portable module

Call What it does
sign_in, player, signed_in Who is playing. A node listening for platform_event hears a later sign-out
unlock, progress Award an achievement, or report progress on it
submit_score, scores Post to a leaderboard, and read it: scope, period, count and start in the options
cloud_read, cloud_write A value the store syncs between the player's devices
set_presence What the player is doing, where the store shows it

A store without one of these answers unsupported: Game Center has no presence.

Achievements and rollback

  • An achievement cannot be un-awarded. A rollback game can re-run a predicted tick with different inputs.
  • A call that changes the store waits until the tick that made it can no longer be re-run.
  • Reads never wait. Repeating one costs a round trip.
  • Without a rollback session every tick is final at once.

Apple

The apple feature puts Game Center behind the portable calls and adds the apple module.

Portable call On an Apple platform
platform::sign_in Game Center, including its sign-in sheet
platform::unlock, progress GKAchievement
platform::submit_score, scores GKLeaderboard
platform::cloud_read, cloud_write The iCloud key-value store

Apple only:

pub async fn init() {
    events::listen(self.node, "apple_event");                  // arrivals nobody asked for
    let proof = await task::wait(apple::identity());  // for the server to check
    apple::show_dashboard(apple::ShowDashboardOptions { state: "leaderboards" });
    apple::access_point(true, apple::AccessPointOptions { location: "top_trailing" });
}
  • apple::identity fetches the url, signature, salt and timestamp a server needs to verify a Game Center player.
  • apple::sign_in is Sign in with Apple, a separate account from Game Center's. It answers with an identity token and an authorization code. The player's name comes once, on the first authorization; save it then. apple::credential_state says whether a saved account is authorized, revoked or transferred.
  • apple::show_dashboard and apple::access_point are Game Center's own screens.
  • Purchases: apple::products, purchase, entitlements, restore_purchases and finish_purchase.
  • Arrivals: apple::request_notifications, notify, cancel_notification, register_for_push and listen_for_urls. A tapped notification, an opened URL, a push token or a purchase from another device reaches the nodes that called events::listen(node, "apple_event").

The engine never decides who a player is or whether a purchase counts. It carries the proof (an identity signature, an identity token, a transaction's signed jws) for a server such as Gamend to check.

Buying

pub class Shop {
    node: Node,
}

impl Shop {
    pub async fn init() {
        let found = await task::wait(apple::products(["com.studio.game.coins"]));
        let bought = await task::wait(apple::purchase("com.studio.game.coins"));
        if bought["kind"].as_str() == apple::EVENT_PURCHASED {
            // Send bought["jws"] to your server. Once it has granted the thing:
            apple::finish_purchase(bought["id"].as_str());
        }
    }
}
  • A purchase is not finished when it lands. StoreKit re-delivers an unfinished transaction on every launch.
  • finish_purchase is a separate call, made after the server that checked the jws has granted the purchase.
  • The engine carries a small Swift shim, compiled at build time: StoreKit 2 has no Objective-C interface.
  • A machine without a Swift toolchain still builds the engine. Purchases there answer unsupported.

Export declarations

Apple resolves each of these services against the bundle. A game declares them in project.toml; balaur export writes the Info.plist and the entitlements file from it. See Shipping.

The full function list is in the script modules reference.

Are you sure?