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.
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_eventon a node that calledevents::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::identityfetches the url, signature, salt and timestamp a server needs to verify a Game Center player.apple::sign_inis 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_statesays whether a saved account is authorized, revoked or transferred.apple::show_dashboardandapple::access_pointare Game Center's own screens.- Purchases:
apple::products,purchase,entitlements,restore_purchasesandfinish_purchase. - Arrivals:
apple::request_notifications,notify,cancel_notification,register_for_pushandlisten_for_urls. A tapped notification, an opened URL, a push token or a purchase from another device reaches the nodes that calledevents::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_purchaseis a separate call, made after the server that checked thejwshas 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.