> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# In-game Summer API (GDScript)

> The Summer singleton your game code calls: Summer.client for the player's game (analytics, store, friends, party, chat, matchmaking, leaderboards, player data) and Summer.authority for your server (match results, world saves, ratings). Generated from the engine's class reference.

**Class:** `SummerRuntime` · **Inherits:** Object

Engine-owned Summer context and service singleton registered as `Summer`.

Publishes immutable Game, Build, Player, World, and Session projections and owns [`multiplayer`](/api-reference/gdscript/overview#multiplayer). [`initialize()`](/api-reference/gdscript/overview#initialize) and [`shutdown()`](/api-reference/gdscript/overview#shutdown) are main-thread, concurrent-idempotent operations; internal state and atomic context changes happen before operation completion. Tickets, credentials, raw launch state, peers, admission verdicts, hosted ports, and runtime-role selection are not exposed. Ordinary gameplay should use runtime-routed behavior callbacks rather than server/client role queries.

## Properties

| Property | Type | Access | Description |
| - | - | - | - |
| <a id="authority" />`authority` | [`SummerAuthority`](/api-reference/gdscript/authority) | read-only, `get_authority()` | Authority root, or `null` when structurally absent. |
| <a id="client" />`client` | [`SummerClient`](/api-reference/gdscript/client) | read-only, `get_client()` | Client root, or `null` when structurally absent. |
| <a id="context" />`context` | [`SummerExecutionContext`](/api-reference/gdscript/types/execution-context) | read-only, `get_context()` | The one active immutable role context, or `null` before readiness. |
| <a id="debug" />`debug` | `SummerDebug` | read-only, `get_debug()` | Debug root, or `null` when structurally absent. |
| <a id="multiplayer" />`multiplayer` | [`SummerMultiplayerService`](/api-reference/gdscript/multiplayer) | read-only, `get_multiplayer()` | Engine-owned World and Session operation service. Always present; availability depends on runtime state. |

## Methods

### get\_build

```gdscript theme={null}
func get_build() -> SummerBuildIdentity const
```

Returns the immutable current Build identity after successful initialization, or `null`. Signed launch v1 supplies the Build ID and artifact digest; compatibility fields remain empty until a verified manifest/handshake supplies them.

**Returns:** [`SummerBuildIdentity`](/api-reference/gdscript/types/build-identity)

### get\_export\_info

```gdscript theme={null}
func get_export_info() -> Dictionary const
```

Returns the Summer export stamp of the running export: `engineSha`, `schema` (`"summer.export.v1"`) and `summerVersion`. Returns an empty `Dictionary` in the editor and when the project is not running from an exported pack.

**Returns:** Dictionary

### get\_game

```gdscript theme={null}
func get_game() -> SummerGameIdentity const
```

Returns the immutable current Game identity after successful initialization, or `null`. Use this getter rather than a setterless singleton property: GDScript may constant-fold read-only Engine-singleton properties before initialization.

**Returns:** [`SummerGameIdentity`](/api-reference/gdscript/types/game-identity)

### get\_managed\_binding\_identity

```gdscript theme={null}
func get_managed_binding_identity() -> String const
```

Returns the immutable ABI identity shared by the native Summer bindings and bundled managed adapter. This is a compatibility diagnostic; it does not grant a capability or reveal launch credentials.

**Returns:** String

### get\_player

```gdscript theme={null}
func get_player() -> SummerPlayer const
```

Returns the current local Player projection, or `null` for an authority process and before a join.

**Returns:** [`SummerPlayer`](/api-reference/gdscript/types/player)

### get\_session

```gdscript theme={null}
func get_session() -> SummerSession const
```

Returns the current immutable Session projection, or `null`.

**Returns:** [`SummerSession`](/api-reference/gdscript/types/session)

### get\_state

```gdscript theme={null}
func get_state() -> SummerRuntime.RuntimeState const
```

Returns the current lifecycle state.

**Returns:** [`SummerRuntime.RuntimeState`](/api-reference/gdscript/overview#runtimestate)

### get\_world

```gdscript theme={null}
func get_world() -> SummerWorld const
```

Returns the current immutable World projection, or `null`.

**Returns:** [`SummerWorld`](/api-reference/gdscript/types/world)

### initialize

```gdscript theme={null}
func initialize(game_id: String = "") -> SummerOperation
```

Starts initialization using the trusted Game identity supplied by the Summer Host or hosted authority launch. Omit `game_id` for a portable build. When supplied, it asserts the expected identity and never grants authorization or overrides the launch context. With no online launch or Host, an omitted ID creates a project-scoped synthetic local identity; a supplied ID preserves that explicit local namespace. Read the resolved identity with [`get_game()`](/api-reference/gdscript/overview#get_game).
A mismatch returns `&"game_identity_mismatch"` without publishing partial context. An incomplete/refused trusted context returns `&"trusted_launch_unavailable"` and never falls back to local play. Successful hosted authority initialization atomically publishes immutable Game, Build, and World projections without inventing a Player or Session.
Concurrent callers that omit the ID or assert the same resolved ID share one pending operation. Ready replay preserves the current context. A conflicting in-flight or ready ID returns `&"identity_conflict"`. Successful completion publishes [`STATE_READY`](/api-reference/gdscript/overview#state_ready). Cancellation restores the stable lifecycle state that preceded this initialization attempt.

| Parameter | Type | Default |
| - | - | - |
| `game_id` | String | `""` |

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

### is\_local

```gdscript theme={null}
func is_local() -> bool const
```

Returns whether the runtime is locally ready.

**Returns:** bool

### shutdown

```gdscript theme={null}
func shutdown() -> SummerOperation
```

Starts shutdown or returns the same pending shutdown operation. Success publishes [`STATE_UNINITIALIZED`](/api-reference/gdscript/overview#state_uninitialized); cancellation restores the pre-shutdown stable state.

**Returns:** [`SummerOperation`](/api-reference/gdscript/types/operation)

Returns at once. Wait for the result with `var result: SummerResult = await op.get_result_or_completed_signal()`; see [SummerOperation](/api-reference/gdscript/types/operation).

## Signals

### session\_changed

```gdscript theme={null}
signal session_changed(session: SummerSession)
```

Emitted after Player, World, and Session have been atomically replaced. `session` may be `null`.

### state\_changed

```gdscript theme={null}
signal state_changed(state: SummerRuntime.RuntimeState, previous_state: SummerRuntime.RuntimeState)
```

Emitted after the state changes, with the new and previous [`RuntimeState`](/api-reference/gdscript/overview#runtimestate) values.

### world\_changed

```gdscript theme={null}
signal world_changed(world: SummerWorld)
```

Emitted after Player, World, and Session have been atomically replaced. `world` may be `null`.

## Enums and constants

### RuntimeState

| Name | Value | Description |
| - | - | - |
| `STATE_UNINITIALIZED` | `0` | No initialization or shutdown is active. |
| `STATE_INITIALIZING` | `1` | Initialization is pending. |
| `STATE_READY` | `2` | One immutable execution context is active. Inspect `context` or `is_local` to distinguish local and online capabilities; readiness alone grants no authority. |
| `STATE_FAILED` | `3` | Initialization or shutdown failed with a structured failure result. |
| `STATE_SHUTTING_DOWN` | `4` | Shutdown is pending. |

***

What is live on the platform today: [platform capability status](/knowledge-base/source-status). Check availability at runtime before you offer a feature.

## The whole API

Generated from the engine's class reference: `modules/1summer_engine/doc_classes/*.xml`, `modules/summer_sdk_core/doc_classes/*.xml`, `modules/summer_multiplayer/doc_classes/SummerMultiplayerService.xml` in SummerEngine at commit `2c223081cd`. The generator checks the XML against the engine's C++ bindings and fails on any difference. If something here is wrong, the engine's class reference is wrong.

### How calls work

Every call that talks to Summer returns a [`SummerOperation`](/api-reference/gdscript/types/operation) at once and finishes later on the main thread. Await its result:

```gdscript theme={null}
var op := Summer.client.analytics.capture("level_completed", {"level": 3})
var result: SummerResult = await op.get_result_or_completed_signal()
if not result.ok:
    push_warning(result.message)
```

`Summer.client` exists only in the player's game and `Summer.authority` only on your game's server. The other one is `null`. Check readiness before you offer a feature: many services have `is_available()` or a `check_*_readiness()` method.

### Summer.client: in the player's game

| Service | What it does |
| - | - |
| [`Summer.client`](/api-reference/gdscript/client) | Role-scoped client SDK root. |
| [`Summer.client.channels`](/api-reference/gdscript/client/channels) | Player chat channels bound to the current admitted World. |
| [`Summer.client.analytics`](/api-reference/gdscript/client/analytics) | Captures creator game events through the private Player Host. |
| [`Summer.client.context`](/api-reference/gdscript/client/context) | Immutable client projection context. |
| [`Summer.client.friends`](/api-reference/gdscript/client/friends) | The player's Summer friends as this Game may see them. |
| [`Summer.client.items`](/api-reference/gdscript/client/items) | Read-only revisioned inventory projection for the current player. |
| [`Summer.client.matchmaking`](/api-reference/gdscript/client/matchmaking) | Hosted placement availability. |
| [`Summer.client.messages`](/api-reference/gdscript/client/messages) | The player's Summer direct messages, behind the player's per-Game consent. |
| [`Summer.client.party`](/api-reference/gdscript/client/party) | The player's Summer party as this Game sees it. |
| [`Summer.client.player_data`](/api-reference/gdscript/client/player-data) | Read-only view of this player's own public player data. |
| [`Summer.client.ratings`](/api-reference/gdscript/client/ratings) | This player's own match results and committed account ratings. |
| [`Summer.client.rankings`](/api-reference/gdscript/client/rankings) | This player's Game-scoped ranking scores. |
| [`Summer.client.store`](/api-reference/gdscript/client/store) | Browse the current Game store and request trusted checkout. |

### Summer.authority: on your game's server

| Service | What it does |
| - | - |
| [`Summer.authority`](/api-reference/gdscript/authority) | Role-scoped authoritative SDK root. |
| [`Summer.authority.analytics`](/api-reference/gdscript/authority/analytics) | Captures creator events through the private Supervisor. |
| [`Summer.authority.context`](/api-reference/gdscript/authority/context) | Immutable authority projection context. |
| [`Summer.authority.items`](/api-reference/gdscript/authority/items) | Authority items facade for verified-Session projections. |
| [`Summer.authority.match`](/api-reference/gdscript/authority/match) | Typed authoritative Match operations. |
| [`Summer.authority.player_data`](/api-reference/gdscript/authority/player-data) | Authority-written, per-player private game data. |
| [`Summer.authority.ratings`](/api-reference/gdscript/authority/ratings) | Authority read of each player's queue rating. |
| [`Summer.authority.rankings`](/api-reference/gdscript/authority/rankings) | Trusted reads and versioned writes for Game-scoped rankings. |
| [`Summer.authority.world`](/api-reference/gdscript/authority/world) | Typed authoritative World lifecycle operations. |

### Summer.multiplayer

[`Summer.multiplayer`](/api-reference/gdscript/multiplayer): Operation-based Summer World and Session service.

### Types

Results, operations and values the services return.

| Class | What it is |
| - | - |
| [`SummerAuthorityComponent`](/api-reference/gdscript/types/authority-component) | Immutable authority component identity and role. |
| [`SummerAuthorityInventoryOperation`](/api-reference/gdscript/types/authority-inventory-operation) | One allowlisted authority inventory read for one verified Session. |
| [`SummerAuthorityLeaseStatus`](/api-reference/gdscript/types/authority-lease-status) | Read-only projection of authority lease health. |
| [`SummerAuthorityRuntime`](/api-reference/gdscript/types/authority-runtime) | Immutable authority runtime, epoch, component, and lease projection. |
| [`SummerAvailability`](/api-reference/gdscript/types/availability) | Immutable truthful multiplayer capability report. |
| [`SummerBuildIdentity`](/api-reference/gdscript/types/build-identity) | Immutable Build and compatibility identity selected by Summer. |
| [`SummerCapabilityGrant`](/api-reference/gdscript/types/capability-grant) | Immutable negotiated Summer capability and version. |
| [`SummerChannelMessage`](/api-reference/gdscript/types/channel-message) | An authorized World channel message. |
| [`SummerChannelMessagePage`](/api-reference/gdscript/types/channel-message-page) | A bounded page of authorized World channel messages. |
| [`SummerChannelMessagesOperation`](/api-reference/gdscript/types/channel-messages-operation) | A typed asynchronous World channel operation. |
| [`SummerChannelReceipt`](/api-reference/gdscript/types/channel-receipt) | Immutable acceptance receipt for a World channel message. |
| [`SummerChannelSendOperation`](/api-reference/gdscript/types/channel-send-operation) | A typed asynchronous World channel operation. |
| [`SummerCheckoutLine`](/api-reference/gdscript/types/checkout-line) | One caller-selected offer and quantity for trusted checkout. |
| [`SummerCheckoutOperation`](/api-reference/gdscript/types/checkout-operation) | Observes one trusted checkout through its durable outcome. |
| [`SummerCheckoutReceipt`](/api-reference/gdscript/types/checkout-receipt) | Immutable authoritative receipt for an atomic checkout. |
| [`SummerCheckoutReceiptItem`](/api-reference/gdscript/types/checkout-receipt-item) | Immutable ownership targets from one purchased offer. |
| [`SummerCheckoutStatus`](/api-reference/gdscript/types/checkout-status) | Immutable versioned trusted checkout state. |
| [`SummerConversation`](/api-reference/gdscript/types/conversation) | The player's direct-message conversation with one other player. |
| [`SummerConversationsOperation`](/api-reference/gdscript/types/conversations-operation) | One page of the player's direct-message conversations. |
| [`SummerDirectMessage`](/api-reference/gdscript/types/direct-message) | One accepted Summer direct message. |
| [`SummerDirectMessageSendOperation`](/api-reference/gdscript/types/direct-message-send-operation) | One direct message sent through `SummerClientMessages.send`. |
| [`SummerDirectMessagesOperation`](/api-reference/gdscript/types/direct-messages-operation) | One page of a direct-message conversation. |
| [`SummerExecutionContext`](/api-reference/gdscript/types/execution-context) | Immutable base identity and capability context. |
| [`SummerExecutionDescriptor`](/api-reference/gdscript/types/execution-descriptor) | Immutable role, topology, artifact profile, and capabilities selected before execution. |
| [`SummerFriend`](/api-reference/gdscript/types/friend) | One of the player's Summer friends, as this Game may see them. |
| [`SummerGameIdentity`](/api-reference/gdscript/types/game-identity) | Immutable Game identity selected by Summer. |
| [`SummerInventoryChange`](/api-reference/gdscript/types/inventory-change) | One immutable inventory projection change. |
| [`SummerInventoryItem`](/api-reference/gdscript/types/inventory-item) | One immutable revisioned platform item projection. |
| [`SummerInventoryRefreshOperation`](/api-reference/gdscript/types/inventory-refresh-operation) | One engine-owned inventory projection refresh. |
| [`SummerItemMedia`](/api-reference/gdscript/types/item-media) | Immutable presentation media for an owned item. |
| [`SummerItemRights`](/api-reference/gdscript/types/item-rights) | Immutable platform-owned item rights projection. |
| [`SummerJoinOperation`](/api-reference/gdscript/types/join-operation) | The one operation every way into a World returns. |
| [`SummerJoinProgress`](/api-reference/gdscript/types/join-progress) | Immutable sanitized join progress, identical for every placement provider. |
| [`SummerJoinTarget`](/api-reference/gdscript/types/join-target) | Which placement provider brings this player into a World. |
| [`SummerLeaderboardEntry`](/api-reference/gdscript/types/leaderboard-entry) | One ranked player on a queue's leaderboard. |
| [`SummerLeaderboardOperation`](/api-reference/gdscript/types/leaderboard-operation) | Reads a rated queue's top-50 leaderboard. |
| [`SummerMatch`](/api-reference/gdscript/types/match) | Immutable Match identity and verified participant roster. |
| [`SummerMatchConclusionOperation`](/api-reference/gdscript/types/match-conclusion-operation) | Typed operation that commits a match and returns its settlement. |
| [`SummerMatchDeliveryCompletionOperation`](/api-reference/gdscript/types/match-delivery-completion-operation) | Typed completion of one persistent World's Match delivery phase. |
| [`SummerMatchResult`](/api-reference/gdscript/types/match-result) | This player's own view of one concluded Match. |
| [`SummerMatchSettlement`](/api-reference/gdscript/types/match-settlement) | Immutable, complete server-visible match settlement. |
| [`SummerMatchmakingProposal`](/api-reference/gdscript/types/matchmaking-proposal) | Opaque handle for one pending matchmaking proposal that requires an explicit decision. |
| [`SummerMatchmakingRequest`](/api-reference/gdscript/types/matchmaking-request) | Bounded creator preferences for hosted matchmaking. |
| [`SummerOperation`](/api-reference/gdscript/types/operation) | Single-terminal asynchronous operation for the Summer runtime. |
| [`SummerParticipant`](/api-reference/gdscript/types/participant) | Verified Session role, outcome eligibility and team in one Match. |
| [`SummerPartyMember`](/api-reference/gdscript/types/party-member) | One member of the player's Summer party, as this Game sees them. |
| [`SummerPlayer`](/api-reference/gdscript/types/player) | Immutable sanitized Player projection. |
| [`SummerPlayerDataCommitOperation`](/api-reference/gdscript/types/player-data-commit-operation) | Writes one slot of a player's data. |
| [`SummerPlayerDataLoadOperation`](/api-reference/gdscript/types/player-data-load-operation) | Reads a player's data. |
| [`SummerPlayerDataRecord`](/api-reference/gdscript/types/player-data-record) | One slot of one player's data. |
| [`SummerPlayerSettlement`](/api-reference/gdscript/types/player-settlement) | Immutable settlement projection for one verified participant Session. |
| [`SummerRankingLeaderboardOperation`](/api-reference/gdscript/types/ranking-leaderboard-operation) | The first 50 public rows of a Game-scoped ranking. |
| [`SummerRankingOperation`](/api-reference/gdscript/types/ranking-operation) | One player's Game-scoped ranking score after a successful read or write. |
| [`SummerRankingStandingOperation`](/api-reference/gdscript/types/ranking-standing-operation) | The caller's full place in a Game-scoped ranking. |
| [`SummerRatingChange`](/api-reference/gdscript/types/rating-change) | Immutable before-and-after rating projection. |
| [`SummerRatingLoadOperation`](/api-reference/gdscript/types/rating-load-operation) | Reads one player's queue rating for the authority. |
| [`SummerRatingSnapshot`](/api-reference/gdscript/types/rating-snapshot) | Immutable committed rating state. |
| [`SummerResult`](/api-reference/gdscript/types/result) | Immutable structured result returned by Summer runtime operations. |
| [`SummerServiceError`](/api-reference/gdscript/types/service-error) | Immutable versioned failure identity shared by Summer services. |
| [`SummerSession`](/api-reference/gdscript/types/session) | Immutable Player association with a Summer World. |
| [`SummerShutdownNotice`](/api-reference/gdscript/types/shutdown-notice) | Immutable platform advance notice for a World shutdown. |
| [`SummerStandingOperation`](/api-reference/gdscript/types/standing-operation) | Reads the caller's own place in a rated queue. |
| [`SummerStoreItem`](/api-reference/gdscript/types/store-item) | Immutable item listed in the current Game store. |
| [`SummerStoreItemsOperation`](/api-reference/gdscript/types/store-items-operation) | Resolves one page of the current Game store. |
| [`SummerStoreMedia`](/api-reference/gdscript/types/store-media) | Immutable expiring storefront media. |
| [`SummerStorePrice`](/api-reference/gdscript/types/store-price) | Immutable display price from the platform. |
| [`SummerWorld`](/api-reference/gdscript/types/world) | Immutable projection of the active Summer World. |
| [`SummerWorldChannel`](/api-reference/gdscript/types/world-channel) | An admitted participant's private handle to a World channel. |
| [`SummerWorldChannelOpenOperation`](/api-reference/gdscript/types/world-channel-open-operation) | A typed asynchronous World channel operation. |
| [`SummerWorldDefinitionIdentity`](/api-reference/gdscript/types/world-definition-identity) | Immutable selected WorldDefinition projection. |
| [`SummerWorldLoadOperation`](/api-reference/gdscript/types/world-load-operation) | Loads the current World save through its trusted owner. |
| [`SummerWorldSave`](/api-reference/gdscript/types/world-save) | A validated saved World or explicit pristine World. |
| [`SummerWorldSaveOperation`](/api-reference/gdscript/types/world-save-operation) | Commits one coherent game-defined save. |
| [`SummerWorldSaveReceipt`](/api-reference/gdscript/types/world-save-receipt) | Immutable accepted save revision. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.