summer-engine 3.0.0 → 3.2.0

package/library/skills/sprite-sheet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sprite-sheet
-description: Use when generating animated 2D character sprites laid out as a sprite sheet (grid of frames) — walk cycle, attack frames, idle bob, death sequence. Wires into AnimatedSprite2D / SpriteFrames. Trigger on "sprite sheet", "walk cycle", "attack frames", "animated sprite", "frame-by-frame animation", "2D character animation".
+description: "Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/summer-analytics/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: summer-analytics
+description: "Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_script_errors summer_play summer_stop summer_get_diagnostics summer_open
+paths: ["**/*.gd"]
+---
+
+# /summer-analytics — game events you can chart later
+
+## Overview
+
+Summer analytics stores named events, such as `level_completed` or
+`coin_collected`, for the creator to query in Studio. There are two ways in:
+
+| Captured from | Call | What it means |
+|---|---|---|
+| The player's client | `Summer.client.analytics.capture(name, properties)` | An **untrusted** observation from that player's device. Summer attaches the player, game and build; you never pass ids. |
+| The authority | `Summer.authority.analytics.capture(name, properties)` | An observation about this World's runtime. It describes the server, not a player or a match. |
+
+Analytics is for **looking at** your game, never for running it:
+
+- Capture returns immediately.
+- Gameplay never waits for capture and never depends on its result.
+- **Capture is never retried.** An `unavailable` result may already have stored the event, and capturing again records a second event.
+
+**Where it works:** hosted only. Under Local Play both calls complete with
+`ok == false` and code `unavailable`, and nothing is stored. Also print each
+event while testing, so you can check it in the logs.
+
+## Steps
+
+### 1. Choose a small set of events
+
+Name events after things that happened, in the past tense:
+`match_started`, `coin_collected`, `tutorial_step_completed`.
+
+- **Names**:
+  - 1 to 64 characters, matching `^[A-Za-z][A-Za-z0-9_.:-]{0,63}$`.
+  - Case-sensitive, and never starting with `summer.`.
+- **Never put changing values in names** (`coin_7_collected`). Put them in properties: `{"coin": 7}`.
+  - New event names are rate-limited per player and per game per day.
+  - Known names keep working after that limit.
+- **Properties** are a JSON `Dictionary`:
+  - at most 64 scalar values;
+  - nesting at most 4 deep;
+  - property names up to 128 bytes;
+  - one event at most 16 KiB.
+- **Never send personal data or secrets.** Names such as `email`, `password`, `phone`, `address`, `ip_address` and `*_token` are rejected at any depth, as is anything starting with `$summer_`.
+
+Capture authoritative facts on the authority, where the game decided them.
+Capture interface facts on the client: menu opened, tutorial step shown,
+settings changed.
+
+### 2. Add a fire-and-forget helper
+
+Authority, in `authority/main.gd`:
+
+```gdscript
+## Fire-and-forget: gameplay never waits on analytics, and a failure is
+## logged once, never retried (a retry would count the event twice).
+var _analytics_warned := false
+
+func _track(event: String, properties: Dictionary = {}) -> void:
+	print("ANALYTICS ", event, " ", JSON.stringify(properties))
+	var capture := Summer.authority.analytics.capture(event, properties)
+	var result: SummerResult = await capture.get_result_or_completed_signal()
+	if not result.ok and not _analytics_warned:
+		_analytics_warned = true
+		push_warning("analytics unavailable: %s" % result.code)
+```
+
+Client, in `client/main.gd`, the same shape with the client facade:
+
+```gdscript
+var _analytics_warned := false
+
+func _track(event: String, properties: Dictionary = {}) -> void:
+	print("ANALYTICS ", event, " ", JSON.stringify(properties))
+	var capture := Summer.client.analytics.capture(event, properties)
+	var result: SummerResult = await capture.get_result_or_completed_signal()
+	if not result.ok and not _analytics_warned:
+		_analytics_warned = true
+		push_warning("analytics unavailable: %s" % result.code)
+```
+
+### 3. Call it without awaiting
+
+Call `_track(...)` as a statement and do **not** `await` it, so the caller
+continues immediately. For example, in the authority's `_collect`, after the
+coin is applied:
+
+```gdscript
+	_track("coin_collected", {"coin": coin, "players": seat_of.size()})
+```
+
+On the client, after a menu choice:
+
+```gdscript
+	_track("menu_opened", {"from": "pause"})
+```
+
+### 4. Read the results
+
+Open the game's analytics in Studio: `summer_open` with target `game` and
+params `gameId` (your game's id) and `section: "analytics"`. Events show up
+there after a short delay.
+
+## Result codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `unavailable` | No analytics service here (Local Play, an old Host), or a lost answer | Nothing. Do not capture again. |
+| `capacity_exceeded` | More than 32 captures are pending | Capture less often; batch counts into one event |
+| `analytics_storage_limit_exceeded` | The game's analytics quota is used up | Stop capturing this event type; final for now |
+| `not_configured` | An older Supervisor without authority analytics | Nothing |
+
+Every failure is final: none of them asks you to capture again.
+
+## Checklist
+
+- [ ] Every capture is a plain `_track(...)` call; no gameplay code awaits it.
+- [ ] Event names are fixed strings; values live in properties.
+- [ ] No personal data, tokens or free-typed player text in properties.
+- [ ] Authority-decided facts (won, collected, bought) are captured on the authority.
+- [ ] Under Local Play the game plays normally while captures report `unavailable`.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| `await _track(...)` in gameplay code | Call it and move on | A slow or failing capture would stall the game |
+| Capture again after `unavailable` | Log once and drop it | It may already be stored; a second capture double-counts |
+| `coin_%d_collected` names | `coin_collected` with `{"coin": 7}` | New names are rate-limited; values belong in properties |
+| Trust client events for rewards or rankings | Decide on the authority; capture there too | Client events are untrusted observations |
+| Put emails, ids or tokens in properties | Summer attaches player and game identity itself | Blocked names are rejected; personal data must not be collected |
+| Make gameplay depend on analytics working | Treat it as optional | It is unavailable locally and may be unavailable hosted |
+| Start names with `summer.` | Your own names | That namespace is reserved |
+
+## See also
+
+- `skill/multiplayer` — where the client and the authority run
+- `skill/multiplayer-state` — the authority's Command handlers, where most events happen
+- `skill/summer-match-results` — results and ratings, which Summer records itself

package/library/skills/summer-analytics/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/summer-analytics
+kind: skill
+version: 1.0.0
+summary: "Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay."
+use_when:
+  - "adding analytics, telemetry or event tracking to a Summer game: level completed, coin collected, tutorial funnel"
+  - "deciding what to track on the client versus the authority, and how to name analytics events and properties"
+  - "analytics capture fails with unavailable, capacity_exceeded or analytics_storage_limit_exceeded"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - scripting
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-state
+    - skill/summer-match-results
+    - skill/summer-store
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/summer-friends/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: summer-friends
+description: "Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_script_errors summer_project_setting summer_play summer_stop summer_get_diagnostics
+paths: ["**/*.gd", "summer.build.json"]
+---
+
+# /summer-friends — friends, profiles and direct messages
+
+## Overview
+
+Friendships belong to the player's Summer account. The Summer app owns the
+social graph itself:
+
+- friend requests;
+- blocking;
+- the friends list screen;
+- profiles;
+- chat.
+
+Your game gets two client-only facades.
+
+**`Summer.client.friends`**
+- Two screens need **no consent**: `show_friends()` and `show_chat(user_id)`. They ask the Summer app to show its own screen over the game.
+- `show_profile(user_id)` is the same. The profile includes add friend, message, invite to party and report, so it is the social feature most games need.
+- **With consent**, it reads the list: each friend's name, handle and whether they are `offline`, `online`, `in_this_game` or `in_other_game`. Another game is never named.
+
+**`Summer.client.messages`**
+- Reads and sends the player's direct messages, with a separate consent for each kind of access.
+- Prefer `show_chat(user_id)` unless chat is central to your game.
+
+Reading friends or messages needs two things:
+
+1. **The Build declares the permission** in `summer.build.json`.
+2. **The player grants it** in the Summer app's consent sheet, which your game asks for with `request_access`.
+
+Declining never blocks play. A game must work without these permissions.
+
+**Availability:**
+
+- **Engine release.** This needs an engine that includes Summer Engine PR #508. On engines without it, `Summer.client.friends` does not exist and scripts that use it fail to parse. Check the class reference for `SummerClientFriends` before using this skill.
+- **Hosted only.** `is_available()` is `false` in Local Play and editor runs, for guests, for accounts the platform keeps out of social features (`age_restricted`, under 13), and in Summer apps without `player.friends@1` (friends) or `player.messaging@1` (messages).
+- **Overlays.** The screens need the Summer app to offer friends and parties; otherwise they fail with `capability_unavailable` or `ui_unavailable`.
+
+## Steps
+
+### 1. Declare the permissions you use
+
+Add a top-level `permissions` array to `summer.build.json`, next to `schema`
+and `gameId`. List only what the game uses; each entry is an upper bound on
+what you may ask for.
+
+```json
+  "permissions": ["social.friends.read"],
+```
+
+| Permission | Allows |
+| --- | --- |
+| `social.friends.read` | `get_friends()`, statuses, the `changed` signal |
+| `social.messages.read` | `list_conversations`, `list_messages`, `list_messages_after` |
+| `social.messages.send` | `send` |
+| `social.messages.read_state.write` | `mark_read` |
+
+Unknown or duplicate entries are rejected when you publish. Without a
+declaration, `get_access()` reports `undeclared`, and `request_access()` fails
+at once with `permission_undeclared`.
+
+### 2. The friends node
+
+`client/friends.gd`, a child `Friends` of `Main`. In `client/main.gd`'s `_ready()`, call
+`$Friends.start()` right after `Summer.initialize` succeeds:
+
+```gdscript
+extends Node
+## The player's Summer friends, with their consent, and the Summer app's
+## friend screens over the game.
+
+signal friends_changed(rows: Array)   # [{user_id, name, status}]
+signal status(text: String)
+
+var friends: SummerClientFriends
+
+
+## Main calls this right after Summer.initialize succeeds: a child's _ready
+## runs before that, while Summer.client is still null.
+func start() -> void:
+	friends = Summer.client.friends
+	friends.changed.connect(_render)
+	friends.access_changed.connect(func(_state: StringName) -> void: _render())
+	_render()
+
+
+## The Friends button: asks for consent once, then shows the list.
+func open() -> void:
+	if not friends.is_available():
+		status.emit("Friends are not available here.")
+		return
+	if friends.get_access() != &"granted":
+		var decision: SummerResult = await friends.request_access().get_result_or_completed_signal()
+		if not decision.ok:
+			status.emit("Your friends list stays private.")
+			return
+	_render()
+
+
+func _render() -> void:
+	var rows := []
+	for friend in friends.get_friends():
+		rows.append({"user_id": friend.user_id, "name": friend.display_name, "status": friend.status})
+	friends_changed.emit(rows)
+
+
+## The Summer app's profile for any other player this game knows. No consent needed.
+func show_profile(user_id: String) -> void:
+	var shown: SummerResult = await friends.show_profile(user_id).get_result_or_completed_signal()
+	if not shown.ok:
+		status.emit("That screen is not available right now.")
+
+
+## The Summer app's direct-message thread with a friend, over the game.
+func show_chat(user_id: String) -> void:
+	var shown: SummerResult = await friends.show_chat(user_id).get_result_or_completed_signal()
+	if not shown.ok:
+		status.emit("That screen is not available right now.")
+```
+
+How it behaves:
+
+- **When the list is read again.** With a handler on `changed`, the engine re-reads the list on every change hint, after a consent decision, on `refresh()`, and about every 60 seconds while the game is in front. Never poll yourself.
+- **Statuses.** Show `in_this_game` friends first. `unknown` means presence couldn't be read; it is not `offline`.
+- **Rows.** Key them by `user_id`; each read replaces the `SummerFriend` objects.
+- **Profiles of other players.** For the people in the current match, use the user ids your authority publishes (the `players` map in `skill/summer-world-chat`, step 1) and call `show_profile(user_id)`. Your own id fails with `invalid_argument`.
+- **Inviting a friend into a match.** Use the party invite sheet (`skill/summer-parties`).
+
+### 3. Direct messages (only if chat is central)
+
+```gdscript
+## Sends one direct message, asking for the send permission once.
+func send_message(user_id: String, text: String) -> void:
+	var messages := Summer.client.messages
+	if not messages.is_available():
+		return
+	if messages.get_access(&"social.messages.send") != &"granted":
+		var decision: SummerResult = await messages.request_access(PackedStringArray(["social.messages.send"])).get_result_or_completed_signal()
+		if not decision.ok:
+			return
+	var sent := messages.send(user_id, text)
+	var result: SummerResult = await sent.get_result_or_completed_signal()
+	if result.ok:
+		print("sent #%d" % sent.message.sequence)
+	elif result.code == &"text_not_allowed":
+		status.emit("That message was not sent.")
+	elif result.code == &"target_unavailable":
+		status.emit("You can't message this player.")
+```
+
+Reading a thread works the same way:
+
+- **Read a page.** Ask for `social.messages.read`, then `messages.list_messages(user_id)`. Read `op.messages`, newest page first; pass `op.next_cursor` for older pages.
+- **Catch up.** After `messages_changed`, call `list_messages_after(user_id, last_sequence)`. Today `messages_changed` fires only after a stream resync, so also reload when the chat screen opens.
+- **Mark read.** `mark_read(user_id, sequence)` needs `social.messages.read_state.write`. It marks the thread read on every device.
+- **Send rules.** `send` takes 1–4000 characters and no control characters except newline and tab. Each call is one message; the engine never sends it twice.
+
+### 4. Failure codes
+
+| Code | Meaning | Show |
+| --- | --- | --- |
+| `permission_not_requested`, `permission_declined`, `permission_revoked` | The player hasn't granted it | A "Show friends" button that calls `request_access()` again later |
+| `permission_undeclared` | `summer.build.json` lacks it | Fix the declaration (step 1) |
+| `capability_unavailable` | Local Play, guest or older Summer app | Hide the feature |
+| `age_restricted` | Under-13 account | Hide the feature |
+| `ui_unavailable` | The app can't show a sheet now | "Try again" |
+| `operation_in_progress` (retryable) | Another Summer sheet (party or friends) is open | Wait |
+| `text_not_allowed` | Filtered; nothing stored | "Not sent" |
+| `target_unavailable` | Not a friend, blocked, or gone | "You can't message this player" |
+| `rate_limited`, `unavailable` (retryable) | Busy, or the Player Host is unreachable | Retry later, never in a loop |
+
+### 5. Test
+
+Local Play has no accounts, so check the hidden path locally:
+
+- `is_available()` is `false`;
+- buttons are hidden;
+- there are no script errors.
+
+```
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+Then test on Summer staging with two accounts that are friends: grant, decline
+and revoke access in the Summer app, and watch `access_changed`.
+
+## Checklist
+
+- [ ] The engine's class reference lists `SummerClientFriends` (Summer Engine PR #508 or later).
+- [ ] `summer.build.json` declares exactly the permissions the code asks for.
+- [ ] Local Play: friends features are hidden, with no script errors.
+- [ ] Declining consent leaves the game fully playable, and the button can ask again later.
+- [ ] Hosted: a friend playing the game shows `in_this_game`; `show_profile` opens for another player in the match.
+- [ ] No polling timer: updates come from `changed`.
+
+## Common mistakes
+
+| Don't | Do | Why |
+| --- | --- | --- |
+| Ask for consent at startup | Ask when the player opens a friends feature | A consent sheet without context gets declined |
+| Gate play on friends access | Treat it as optional | Declining must never block the game |
+| Build friend requests, blocking or a profile screen | `show_friends()`, `show_profile()`, `show_chat()` | The Summer app owns them, with no consent needed |
+| Treat `unknown` as `offline` | Show it as unknown | It means presence couldn't be read |
+| Poll `refresh()` on a timer | Connect `changed` | The engine already re-reads while a handler is connected |
+| Declare every permission "just in case" | Declare only what you use | The consent sheet lists each declared permission |
+| Use friends to put players in one match | `skill/summer-parties` | Parties are how players play together |
+
+## See also
+
+- `skill/summer-parties`: playing together, the invite sheet
+- `skill/summer-world-chat`: chat inside a match
+- `skill/multiplayer-publish`: `summer.build.json` and publishing a Build
+- `skill/multiplayer-testing`: what Local Play can and can't test

package/library/skills/summer-friends/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/summer-friends
+kind: skill
+version: 1.0.0
+summary: "Summer friends in a game: a consented friends list, profile and chat screens, direct messages. Hosted only."
+use_when:
+  - "showing a friends list, who is online or which friends are playing this Summer game"
+  - "opening a player's Summer profile, friends list or chat screen from inside a game"
+  - "reading or writing a player's direct messages, or a friends call fails with permission_undeclared or permission_declined"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - ui
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-testing
+    - skill/summer-parties
+    - skill/summer-world-chat
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/summer-leaderboards/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: summer-leaderboards
+description: "Leaderboards in a Summer game: queue ratings from matches, and Game rankings your authority scores."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_read_file summer_replace_text summer_write_file summer_get_script_errors summer_play summer_stop summer_get_diagnostics
+paths: ["summer.build.json", "client/**/*.gd", "authority/**/*.gd"]
+---
+
+# /summer-leaderboards — ratings, rankings and the top 50
+
+## Overview
+
+Summer keeps two kinds of score board. Pick by where the number comes from:
+
+| Board | The number is | Declared as | Written by | Read with |
+|---|---|---|---|---|
+| **Queue rating** | A skill rating (Elo, MMR) that moves with every match in a rated queue | A queue with `"policy": "rating"` | Summer, when the authority concludes a match | `Summer.client.ratings`, `Summer.authority.ratings` |
+| **Game ranking** | Any score your game defines: total coins, best time, levels cleared | `runtime.rankings` | Your authority, with compare-and-set | `Summer.client.rankings`, `Summer.authority.rankings` |
+
+Players only ever read their **own** rating and score, plus the public top 50,
+which shows display names, never account ids. Nobody can write a score from a
+client.
+
+Where it works: leaderboards, standings and rankings are read through the
+Summer app that hosts the player, so they work in **hosted** games only.
+Under Local Play they fail with a typed code (step 5); the authority's
+`ratings.load` returns a deterministic test value. Build the screens so they
+degrade gracefully, and check the real numbers on a hosted staging build.
+
+This skill extends the Courtyard game: its authority concludes matches as in
+`skill/summer-match-results`.
+
+## Steps
+
+### 1. Declare the boards
+
+In `summer.build.json`, a rated queue gets a rating, and `runtime.rankings`
+declares Game rankings:
+
+```json
+"queues": [
+  {
+    "name": "duel",
+    "minPlayers": 2,
+    "maxPlayers": 2,
+    "worldDefinition": "courtyard",
+    "policy": "rating",
+    "ratingSystemRef": "elo_v1",
+    "teams": { "count": 2, "size": 1 },
+    "transport": "enet"
+  }
+],
+"rankings": [
+  { "name": "coins", "initialRating": 0 }
+]
+```
+
+- `ratingSystemRef`: `elo_v1` lets Summer compute rating moves from win, loss
+  and draw. `authority_v1` makes your authority report each player's move
+  (step 4). Optional `initialRating` is a newcomer's rating (default 1200).
+- A ranking `name` is lower-case letters and digits separated by single `.`,
+  `_` or `-`, at most 64 characters; at most 32 rankings. `initialRating`
+  defaults to 0.
+- To make a rated queue and a ranking one board, give the queue
+  `"rankingRef": "<ranking name>"` and drop the queue's `initialRating`. A
+  queue and a ranking may not share a name without `rankingRef`.
+
+### 2. Show a queue's top 50 and the player's standing
+
+On a client, after Summer is initialized (no match needed):
+
+```gdscript
+## Fills a leaderboard screen for a rated queue. Hosted games only.
+func show_queue_board(queue: StringName) -> void:
+	var board := Summer.client.ratings.leaderboard(queue)
+	var read: SummerResult = await board.get_result_or_completed_signal()
+	if not read.ok:
+		show_board_unavailable(read)
+		return
+	for entry: SummerLeaderboardEntry in board.entries:
+		add_board_row(entry.rank, entry.display_name, entry.value, entry.you)
+	var standing := Summer.client.ratings.standing(queue)
+	if (await standing.get_result_or_completed_signal()).ok:
+		if standing.rank > 0:
+			show_place("#%d of %d" % [standing.rank, standing.players])
+		elif standing.rated:
+			show_place("Top %.1f%%" % (100.0 - standing.percentile))
+		else:
+			show_place("Play a rated match to get a rank")
+```
+
+- `entries` holds up to 50 rows, best first; `you` marks the player's own row.
+- `standing.rank` is set only inside the top 1000; otherwise show the
+  percentile. Before the first rated match `rated` is false and `value` is the
+  queue's `initialRating`.
+- `Summer.client.ratings.get_current(queue)` returns the last known
+  `SummerRatingSnapshot` (`value`, `games`, `version`) without a network read,
+  or `null`. `refresh(queue)` reads it again; `rating_changed(queue)` fires
+  when it moves.
+- One read of each kind is in flight at a time; calling again while one is
+  pending returns the same operation.
+
+After a match, `Summer.client.ratings.rating_committed` delivers the
+player's own before-and-after rating (see `skill/summer-match-results`).
+
+### 3. Write a Game ranking from the authority
+
+Only the authority writes rankings, by the player's stable id, with
+**compare-and-set**: read the score and its version, write the new absolute
+value against that version, and read again if someone else wrote first. In
+`authority/main.gd`, after the match concluded:
+
+```gdscript
+## Adds this match's coins to each player's Game ranking "coins".
+## Compare-and-set: read the version, write against it, re-read on conflict.
+func _record_coins() -> void:
+	for session_id: String in wallets:
+		var player: SummerPlayer = sessions[session_id].player
+		await _add_score(&"coins", player.user_id, int(wallets[session_id]))
+
+
+func _add_score(ranking: StringName, player_id: String, points: int) -> void:
+	for attempt in 3:
+		var before := Summer.authority.rankings.get_score(ranking, player_id)
+		var read: SummerResult = await before.get_result_or_completed_signal()
+		if not read.ok:
+			return   # hosted only: Local Play has no ranking service
+		var write := Summer.authority.rankings.set_score(ranking, player_id, before.rating.version, before.rating.value + points, before.rating.games + 1)
+		var wrote: SummerResult = await write.get_result_or_completed_signal()
+		if wrote.ok or wrote.code != &"ranking_version_conflict":
+			return
+		# Someone else wrote first: read again and recompute.
+```
+
+`sessions` maps each `session_id` to the `SummerSession` the authority keeps
+in `_on_session_joined` (`skill/summer-match-results`, step 1). The engine never
+retries a write. After a failure other than a conflict, read the score before
+deciding to write again: the first write may have committed.
+
+Clients read their own ranking with `Summer.client.rankings.get_score("coins")`,
+`standing("coins")` (full rank and player count; rank 0 before the first
+score) and `leaderboard("coins")` (top 50, zero-score players included). These
+work in a standalone game too, before any match.
+
+### 4. Own a co-op queue's rating (`authority_v1`)
+
+Elo rates two sides against each other. A co-op mode, where a group plays
+against the content, declares `"ratingSystemRef": "authority_v1"` and reports
+every player's move when the match concludes:
+
+```gdscript
+## A co-op run against content rated `content_rating`; `cleared` says whether
+## the group made it. Moves each player's rating like Elo against the content.
+func conclude_run(players: Array[SummerSession], content_rating: int, cleared: bool) -> void:
+	var outcomes: Dictionary[SummerSession, SummerAuthorityMatch.MatchOutcome] = {}
+	var deltas: Dictionary[SummerSession, int] = {}
+	for session in players:
+		var read := Summer.authority.ratings.load(session)
+		if not (await read.get_result_or_completed_signal()).ok:
+			return   # rating_unavailable: this queue keeps no rating
+		var expected := 1.0 / (1.0 + pow(10.0, (content_rating - read.rating.value) / 400.0))
+		deltas[session] = roundi(32 * ((1.0 if cleared else 0.0) - expected))
+		outcomes[session] = SummerAuthorityMatch.MATCH_OUTCOME_WIN if cleared else SummerAuthorityMatch.MATCH_OUTCOME_LOSS
+	var concluded: SummerResult = await Summer.authority.match.conclude(outcomes, "run_complete", deltas).get_result_or_completed_signal()
+```
+
+- Each delta is an `int` within ±1000, one for **every** participant.
+  Deltas on a non-`authority_v1` queue, or a missing one, fail the
+  conclusion with `invalid_request` and commit nothing; conclude again with
+  corrected arguments.
+- `Summer.authority.ratings.load(session)` is for the authority's own logic.
+  Never show one player's rating to other players; the leaderboard is the
+  public view.
+- `Summer.authority.ratings.leaderboard("dungeon")` reads the same top 50,
+  unmarked, for an in-World trophy wall.
+
+### 5. Degrade gracefully where boards aren't available
+
+```gdscript
+func show_board_unavailable(result: SummerResult) -> void:
+	match String(result.code):
+		"rating_unavailable":
+			show_place("This mode has no ranking")
+		_:
+			show_place("Leaderboard unavailable right now" if result.retryable else "Leaderboards appear in the Summer app")
+```
+
+Under Local Play these calls fail without a Summer account behind them:
+
+| Call | Under Local Play |
+|---|---|
+| `Summer.client.ratings.leaderboard`, `standing`, `refresh` | Fails with `unavailable` (retryable) |
+| `Summer.client.ratings.get_current` | `null` |
+| `Summer.client.rankings.get_score`, `standing`, `leaderboard` | Fails with `unavailable` (not retryable) |
+| `Summer.authority.rankings.get_score`, `set_score` | Fails with `service_error` |
+| `Summer.authority.ratings.load` | Works: a deterministic test rating (system `deterministic-v1`) |
+| `Summer.authority.ratings.leaderboard` | Works: an empty list |
+| `Summer.authority.match.conclude` | Works: a deterministic settlement with test rating changes |
+
+Hide or grey out leaderboard buttons when a read fails; never block the game
+on them.
+
+## Checklist
+
+- [ ] Every board is declared: rated queues with `ratingSystemRef`, rankings under `runtime.rankings`.
+- [ ] The leaderboard screen marks the player's own row and shows rank or percentile.
+- [ ] Ranking writes happen only on the authority, by `player.user_id`, with compare-and-set and a conflict re-read.
+- [ ] `authority_v1` queues conclude with a delta for every participant; other queues send none.
+- [ ] Every read handles failure, and the game stays playable without boards.
+- [ ] Real numbers checked on a hosted staging build.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Write scores from the client | `Summer.authority.rankings.set_score` | Clients can only read their own score; the authority is trusted |
+| `set_score` without the version you read | Read with `get_score`, pass `before.rating.version` | It is compare-and-set; a stale version fails `ranking_version_conflict` |
+| Blindly retry a failed write | Read again, then decide | The first write may have committed; the engine doesn't replay it |
+| Send rating deltas on an `elo_v1` or `fifo` queue | Deltas only on `authority_v1`, one per participant | Otherwise the conclusion fails `invalid_request` |
+| Show other players' ratings from `authority.ratings.load` | Show the leaderboard | Ratings are private to each player |
+| Name a ranking like a queue without `rankingRef` | Distinct names, or `rankingRef` to share one board | Summer rejects the manifest |
+| Treat a Local Play failure as a bug | Expect `unavailable` or `service_error` locally; test boards hosted | Boards are read through the hosting Summer app |
+
+## See also
+
+- `skill/summer-match-results` — concluding matches, which moves ratings
+- `skill/summer-matchmaking` — declaring rated queues and teams
+- `skill/summer-player-data` — saving per-player progress that isn't a ranking