summer-engine 3.1.0 → 3.2.0

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

@@ -0,0 +1,30 @@
+id: skill/summer-leaderboards
+kind: skill
+version: 1.0.0
+summary: "Leaderboards in a Summer game: queue ratings from matches, and Game rankings your authority scores."
+use_when:
+  - "the user wants a leaderboard, high scores, ranks, MMR, Elo or a 'top 50' screen in a Summer game"
+  - "a rated queue should show each player's rating, standing or percentile"
+  - "the authority should write a score, such as total coins or best time, to a Game-wide ranking"
+  - "a co-op mode should rate players against the content with authority_v1 rating deltas"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - ui
+  modalities:
+    - scripts
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/summer-matchmaking
+    - skill/summer-match-results
+    - skill/summer-player-data
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/summer-match-results/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: summer-match-results
+description: "End a Summer match: report each player's win, loss or draw, show results on clients, then close the World."
+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_project_setting summer_play summer_stop summer_get_diagnostics
+paths: ["authority/**/*.gd", "client/**/*.gd", "world.json"]
+---
+
+# /summer-match-results — who won, and closing the match
+
+## Overview
+
+A match ends when **the authority** says so. It decides the outcome for every
+player, then:
+
+1. **Concludes** the match: `Summer.authority.match.conclude(outcomes, reason)`.
+   Summer settles it once and returns a settlement, including each player's
+   rating change on a rated queue.
+2. Summer delivers each player **their own** result on the client
+   (`Summer.client.ratings.match_result`), and later their committed rating
+   (`rating_committed`). The authority never relays results or ratings.
+3. **Completes** the World: `Summer.authority.world.complete()` for a
+   match-scoped World. Clients are disconnected and go back to your menu.
+
+Where it works: all of this runs under Local Play with a deterministic
+settlement, so the whole flow is testable locally. Rating values are real only
+when hosted.
+
+This skill extends the Courtyard game (`skill/multiplayer-project` and
+`skill/multiplayer-state`): the first player to collect `WIN_COINS` coins wins.
+With a team queue (`skill/summer-matchmaking`), their whole team wins.
+
+## Steps
+
+### 1. Track who is in the match
+
+In `authority/main.gd`, keep every Session the engine admitted, and the
+players who left. Add these variables:
+
+```gdscript
+const WIN_COINS := 1    # coins that win the match
+var ended := false
+var departed := {}      # session_id of players who left before the end
+var sessions := {}      # session_id -> SummerSession
+```
+
+In `_ready()`, next to the other World signals (skip this line if
+`skill/summer-player-data` already connected it):
+
+```gdscript
+	world.session_joined.connect(_on_session_joined)
+```
+
+```gdscript
+## Every player admitted into this match, kept as the exact Session object
+## the engine handed over: conclude accepts only these.
+func _on_session_joined(session: SummerSession) -> void:
+	sessions[session.session_id] = session
+```
+
+If the game already has `_on_session_joined` (`skill/summer-player-data`
+adds one), put the line at its start instead of defining it twice.
+
+At the top of `_on_session_left`:
+
+```gdscript
+	departed[session.session_id] = true
+```
+
+Keep a Session in `sessions` after it leaves: it stays on the match roster
+until the match is delivered, and it still needs an outcome.
+
+Presence signals on the authority's `SummerNetworkWorld`:
+
+| Signal | Meaning | Typical response |
+|---|---|---|
+| `session_joined(session)` | First admission into this World | Nothing extra: clients send `join` when their network is ready |
+| `session_disconnected(session)` | Transport lost; the seat is kept | Pause or freeze that player; don't end the match yet |
+| `session_reconnected(session)` | Same Session is back | Resume them |
+| `session_left(session, reason)` | The Session ended, exactly once | Count them as departed; retire their groups |
+
+Hosted, a seat waits `lifecycle.reconnect_seconds` (`world.json`) before
+Summer ends the Session. Under Local Play a quitting player only
+disconnects; `session_left` arrives when the World ends.
+
+### 2. Decide the outcome and conclude
+
+At the end of `_collect`, after `request.accept(...)`:
+
+```gdscript
+	if wallets[session.session_id] >= WIN_COINS:
+		_end_match(session)
+```
+
+Then add:
+
+```gdscript
+## Ends the match once: every player gets an outcome, Summer settles it, and
+## the World closes after a short results screen.
+func _end_match(winner: SummerSession) -> void:
+	if ended:
+		return
+	ended = true
+	var winner_team := Summer.authority.match.get_participant(winner).team
+	var outcomes: Dictionary[SummerSession, SummerAuthorityMatch.MatchOutcome] = {}
+	for id: String in sessions:
+		var session: SummerSession = sessions[id]
+		var participant := Summer.authority.match.get_participant(session)
+		if participant == null or not participant.outcome_eligible:
+			continue   # spectators get no outcome
+		if departed.has(id):
+			outcomes[session] = SummerAuthorityMatch.MATCH_OUTCOME_ABANDON
+		elif (participant.team == winner_team) if winner_team >= 0 else (id == winner.session_id):
+			outcomes[session] = SummerAuthorityMatch.MATCH_OUTCOME_WIN
+		else:
+			outcomes[session] = SummerAuthorityMatch.MATCH_OUTCOME_LOSS
+	match_doc.winner = winner.player.display_name
+	match_group.reset(Game.pack(match_doc))
+	var settled := await _conclude(outcomes)
+	# Let players read the results screen, then end the World.
+	await get_tree().create_timer(3.0).timeout
+	await Summer.authority.world.complete("match_complete").get_result_or_completed_signal()
+
+
+## Commits the outcomes. A retryable failure is retried with the same
+## arguments: Summer settles a match at most once.
+func _conclude(outcomes: Dictionary[SummerSession, SummerAuthorityMatch.MatchOutcome]) -> SummerMatchSettlement:
+	for attempt in 3:
+		var concluding := Summer.authority.match.conclude(outcomes, "coins_collected")
+		var concluded: SummerResult = await concluding.get_result_or_completed_signal()
+		if concluded.ok:
+			return concluding.settlement
+		if not concluded.retryable:
+			push_error("conclude: %s %s" % [concluded.code, concluded.message])
+			return null
+		await get_tree().create_timer(1.0 + attempt).timeout
+	return null
+```
+
+Give `match_doc` a `"winner": ""` entry so clients can show the winner's name.
+
+The rules `conclude` enforces:
+
+- **One outcome for every outcome-eligible player admitted into the match**,
+  including players who already left (`MATCH_OUTCOME_ABANDON`). A missing or
+  extra player fails with `invalid_roster`; spectators are skipped.
+- **Keys must be the exact `SummerSession` objects the engine delivered**
+  (`session_joined`, or `request.get_session()` in a Command). Copies, such as
+  the Sessions in `Summer.authority.context.participants`, fail with
+  `invalid_roster`.
+- Outcomes are `MATCH_OUTCOME_WIN`, `MATCH_OUTCOME_LOSS`, `MATCH_OUTCOME_DRAW`
+  and `MATCH_OUTCOME_ABANDON`. On a team queue give every member of a team the
+  same outcome; Summer scores the sides it formed.
+- **It settles once.** Retrying with identical arguments replays the same
+  settlement (`concluding.replayed` is true); different arguments are
+  refused. A rejected conclusion (`invalid_request`) commits nothing, so you
+  may conclude again with corrected arguments.
+- `rating_deltas`, the third argument, is only for `authority_v1` queues
+  (`skill/summer-leaderboards`).
+
+The settlement lists each player's committed rating changes:
+
+```gdscript
+	if settled != null:
+		for player: SummerPlayerSettlement in settled.players:
+			for change: SummerRatingChange in player.ratings:
+				print("%s %s %d -> %d" % [player.session.player.display_name, change.system, change.before.value, change.after.value])
+```
+
+Use it for authority logic (logs, rewards). Players get their own numbers
+directly from Summer, step 3.
+
+### 3. Show the result on each client
+
+In `client/main.gd`'s `_ready()`, connect the result signals right after
+`Summer.initialize` succeeds and before joining (`Summer.client` is null
+until then), and handle the end of the World:
+
+```gdscript
+	Summer.client.ratings.match_result.connect(_on_match_result)
+	Summer.client.ratings.rating_committed.connect(_on_rating_committed)
+	$World.server_disconnected.connect(_on_server_disconnected)
+```
+
+```gdscript
+func _on_match_result(result: SummerMatchResult) -> void:
+	var words := {
+		SummerMatchResult.OUTCOME_WIN: "You win!",
+		SummerMatchResult.OUTCOME_LOSS: "You lose.",
+		SummerMatchResult.OUTCOME_DRAW: "Draw.",
+	}
+	show_status(words.get(result.outcome, "Match over."))
+
+
+## Arrives later, privately, once Summer committed this player's rating.
+func _on_rating_committed(result: SummerMatchResult) -> void:
+	var change := result.rating
+	show_status("Rating %d (%+d)" % [change.after.value, change.delta])
+
+
+func _on_server_disconnected(code: String, _detail: String) -> void:
+	show_status("The match has ended.")
+```
+
+`show_status` and the `Hud/Status` label come from `skill/summer-matchmaking`.
+
+- `match_result` arrives when the authority concludes. Its `rating_state` is
+  `RATING_STATE_PENDING` on a rated queue, or `RATING_STATE_NONE`.
+- `rating_committed` follows when Summer committed the rating, with
+  `result.rating.before`, `after` and `delta`. Hosted only.
+- `Summer.client.ratings.last_result` and `results` keep recent results, so a
+  results screen opened later can read them.
+- Drive the results screen from `match_result`, not from a disconnect. Give
+  it a "Back to menu" button that awaits `Summer.client.leave()`, then offers
+  "Play again" (`find_match` again).
+- Hosted, completing the World ends every Session and Summer stops the server,
+  so clients get `server_disconnected`. Under Local Play the World completes
+  but clients stay connected until they leave or Local Play stops.
+
+### 4. Close the World
+
+- **Match-scoped World** (`"lifetime": "match_scoped"`, the project skill's
+  default): conclude, then `Summer.authority.world.complete(reason)`. This
+  permanently ends the World; Summer stops the server. Completing before a
+  successful conclusion fails with `settlement_required`.
+- **Persistent or multi-match World**: conclude, then
+  `Summer.authority.match.complete_delivery()`. Match-bound Sessions end,
+  World-bound Sessions stay, and the World keeps serving. Never call
+  `world.complete()` on a World that should keep running.
+- `draining(deadline_unix)` on the World means Summer is shutting the server
+  down (maintenance). Conclude or save before the deadline
+  (`skill/summer-world-saves`).
+
+A match that never concludes holds its players until the World is stopped;
+every match needs an ending, including "everyone else left".
+
+### 5. Test it with Local Play
+
+```
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+Make one player win. Expect, in order: the authority's conclusion succeeds,
+with a settlement of deterministic test ratings (system `deterministic-v1`);
+every client receives `match_result` with its own outcome and `rating_state`
+`RATING_STATE_PENDING` on a rated queue; about 3 seconds later the authority
+logs `session_left` with reason `match_complete` for each player and
+`world.complete()` succeeds. `rating_committed` does not fire locally, and
+clients stay connected until they leave.
+
+## Checklist
+
+- [ ] There is exactly one place that ends the match, guarded so it runs once.
+- [ ] Outcomes cover every outcome-eligible participant, including those who left (`MATCH_OUTCOME_ABANDON`).
+- [ ] Team queues give a whole team the same outcome.
+- [ ] A retryable conclusion failure is retried with identical arguments.
+- [ ] Clients show `match_result`, and `rating_committed` when it arrives.
+- [ ] Match-scoped Worlds call `world.complete()` after concluding; persistent Worlds call `match.complete_delivery()`.
+- [ ] Local Play shows the result on every client, and "Back to menu" leaves cleanly.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Decide the winner on a client | Decide on the authority and conclude there | Only the authority's outcome is settled |
+| Build outcomes from players still connected | Every Session from `session_joined`, leavers as `MATCH_OUTCOME_ABANDON` | Leavers stay on the roster; a missing one fails `invalid_roster` |
+| Key outcomes by `Summer.authority.context.participants` sessions or copied ids | The exact Session objects from `session_joined` | Copies are rejected with `invalid_roster` |
+| Wait for `server_disconnected` to show results | Show results on `match_result` | Local Play keeps clients connected after completion |
+| Send results or ratings to clients yourself | Let `Summer.client.ratings` deliver them | Each player gets their own result privately; the authority never relays account data |
+| Retry a conclusion with changed outcomes | Retry with identical arguments | A match settles once; divergent retries are refused |
+| `world.complete()` in a persistent World | `match.complete_delivery()` | `complete()` ends the World for good |
+| Call `world.complete()` before concluding | Conclude, show results, then complete | Completion ends every Session |
+| End the match when one player disconnects | Wait for `session_left` | A disconnect keeps the seat for the reconnect window |
+
+## See also
+
+- `skill/summer-matchmaking` — queues and teams that the outcome refers to
+- `skill/summer-leaderboards` — ratings and `authority_v1` rating moves
+- `skill/summer-world-saves` — persistent Worlds that outlive a match
+- `skill/multiplayer-testing` — running bots through a whole match

package/library/skills/summer-match-results/resource.yaml

@@ -0,0 +1,32 @@
+id: skill/summer-match-results
+kind: skill
+version: 1.0.0
+summary: "End a Summer match: report each player's win, loss or draw, show results on clients, then close the World."
+use_when:
+  - "a multiplayer Summer game needs a winner, a game-over screen or a match that ends"
+  - "reporting match outcomes, abandons or rating changes from the authority"
+  - "players disconnect, reconnect or leave mid-match and the authority must handle it"
+  - "the World should shut down after a match, or a persistent World runs several matches"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - gameplay
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-state
+    - skill/summer-matchmaking
+    - skill/summer-leaderboards
+    - skill/summer-world-saves
+    - skill/multiplayer-testing
+    - skill/summer-analytics
+source: official
+license: MIT
+status: stable
+recommended: false

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

@@ -0,0 +1,301 @@
+---
+name: summer-matchmaking
+description: "Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures."
+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_project_setting summer_play summer_stop summer_get_diagnostics
+paths: ["summer.build.json", "client/**/*.gd", "authority/**/*.gd", "client/**/*.tscn"]
+---
+
+# /summer-matchmaking — queues, teams and the way into a match
+
+## Overview
+
+A **queue** is a game mode players search in: "casual 2–8", "duel 1v1",
+"ranked 2v2". You declare queues in `summer.build.json`; Summer matchmaking
+groups searching players, reserves a server for them, and every player's
+`Summer.client.join(SummerJoinTarget.queue(...))` completes in the same World.
+The authority then reads each player's team from the verified Session.
+
+There is no lobby object, invite code or server browser. Friends who want to
+play together use a party (`skill/summer-parties`), which enters a queue as one group.
+
+Where it works:
+
+| Piece | Local Play | Hosted |
+|---|---|---|
+| Joining a queue, progress, failures | Yes: players are placed at once | Yes |
+| Teams (`get_participant(session).team`) | Yes: round-robin in roster order | Yes: balanced by rating, parties kept together |
+| Accept/Decline prompt | No: no proposal happens | Yes, when the queue declares `acceptance` |
+| Rating-based grouping | No | Yes |
+
+This skill extends the Courtyard game from `skill/multiplayer-project` and
+`skill/multiplayer-state`. Its client already joins `Game.QUEUE` and sends a
+`join` Command; its authority publishes `match_doc`.
+
+## Steps
+
+### 1. Declare the queues
+
+Each queue in `runtime.queues` of `summer.build.json` names the
+WorldDefinition its matches run. A casual mode and a 1v1 rated duel:
+
+```json
+"queues": [
+  { "name": "courtyard", "minPlayers": 2, "maxPlayers": 8, "worldDefinition": "courtyard", "policy": "fifo", "transport": "enet" },
+  {
+    "name": "duel", "minPlayers": 2, "maxPlayers": 2, "worldDefinition": "courtyard",
+    "policy": "rating", "ratingSystemRef": "elo_v1",
+    "teams": { "count": 2, "size": 1 },
+    "acceptance": { "mode": "all", "ttl": "20s" },
+    "searchTtl": { "min": "30s", "default": "2m", "max": "5m" },
+    "transport": "enet"
+  }
+]
+```
+
+The fields Summer accepts, and their rules:
+
+| Field | Meaning | Rules |
+|---|---|---|
+| `name` | The id clients join | Unique; ASCII letters, digits, `_ . : -` |
+| `minPlayers` / `maxPlayers` | Players per match | `minPlayers` ≥ 1, `maxPlayers` ≥ `minPlayers`. Measured support is up to 16 per match |
+| `worldDefinition` | The WorldDefinition's `definition_id` | Required; every WorldDefinition must be used by a queue |
+| `policy` | `fifo` (first come) or `rating` (group by skill) | `rating` needs `ratingSystemRef`; `fifo` must not declare one |
+| `ratingSystemRef` | `elo_v1` (Summer rates two sides) or `authority_v1` (your authority reports rating moves) | See `skill/summer-leaderboards` |
+| `teams` | `{count, size}`: fixed sides, such as 2v2 = `{2, 2}` | `count` 2..64, `size` 1..16, `minPlayers` = `maxPlayers` = count × size; `elo_v1` needs exactly 2 teams |
+| `acceptance` | `{"mode": "all", "ttl": "20s"}` asks every player to accept; `{"mode": "none"}` skips it | `ttl` required with `all`, forbidden with `none` |
+| `searchTtl` | `{min, default, max}` search lifetime | Go durations (`30s`, `2m`); min ≤ default ≤ max |
+| `regions` | Regions this queue may use | Omit to allow all |
+| `transport` | `enet` (UDP, default) or `ws` (WebSocket) | |
+
+Don't add `lobby` fields or `backfill`: Summer rejects both when you publish.
+Teams and acceptance need `runtime.interfaces.multiplayer` 5 or higher; the
+project skill's `summer.build.json` declares 6.
+
+### 2. Search, with progress the player can see
+
+Add a status label and two hidden buttons to the client scene,
+`client/main.tscn` (position them in the editor as you like):
+
+```
+[node name="Hud" type="CanvasLayer" parent="."]
+
+[node name="Status" type="Label" parent="Hud"]
+
+[node name="Accept" type="Button" parent="Hud"]
+visible = false
+text = "Accept"
+
+[node name="Decline" type="Button" parent="Hud"]
+visible = false
+text = "Decline"
+
+[connection signal="pressed" from="Hud/Accept" to="." method="_on_accept_pressed"]
+[connection signal="pressed" from="Hud/Decline" to="." method="_on_decline_pressed"]
+```
+
+In `client/main.gd`, replace the join in `_ready()`, from `var join :=`
+through the `if not joined.ok:` block, with a call to `find_match`:
+
+```gdscript
+	var joined := await find_match(Game.QUEUE)
+	if not joined.ok:
+		return
+```
+
+and add the matchmaking functions:
+
+```gdscript
+var proposal: SummerMatchmakingProposal   # a found match waiting for Accept/Decline
+
+
+## Searches `queue` until the player is in a match, showing progress.
+func find_match(queue: StringName) -> SummerResult:
+	var join := Summer.client.join(SummerJoinTarget.queue(queue))
+	join.progress_changed.connect(_on_progress)
+	join.acceptance_required.connect(_on_match_found)
+	var joined: SummerResult = await join.get_result_or_completed_signal()
+	proposal = null
+	$Hud/Accept.hide()
+	$Hud/Decline.hide()
+	show_status("" if joined.ok else join_failure_text(joined))
+	return joined
+
+
+## Stages carry no tickets or addresses, so they are safe to show.
+func _on_progress(progress: SummerJoinProgress) -> void:
+	match progress.stage:
+		SummerJoinProgress.STAGE_RESOLVING:
+			show_status("Searching for players… %ds" % (progress.elapsed_msec / 1000))
+		SummerJoinProgress.STAGE_RESERVED, SummerJoinProgress.STAGE_PROPOSED:
+			show_status("Match found")
+		SummerJoinProgress.STAGE_LAUNCHING, SummerJoinProgress.STAGE_CONNECTING, SummerJoinProgress.STAGE_ADMITTING:
+			show_status("Joining the match…")
+		SummerJoinProgress.STAGE_RECONNECTING:
+			show_status("Reconnecting…")
+
+
+func show_status(text: String) -> void:
+	$Hud/Status.text = text
+```
+
+### 3. Accept or decline a found match
+
+With `"acceptance": {"mode": "all"}`, Summer reserves a server first, then asks
+every player. The match starts only when all accept before the deadline. The
+engine never decides for the player: connect `acceptance_required`, or the
+join waits until the proposal expires.
+
+```gdscript
+## Summer reserved a server for these players. The match starts only when
+## everyone accepts before the deadline.
+func _on_match_found(found: SummerMatchmakingProposal) -> void:
+	proposal = found
+	var seconds_left := maxi(0, (found.accept_by_unix_msec - int(Time.get_unix_time_from_system() * 1000.0)) / 1000)
+	show_status("Match found! Accept within %ds" % seconds_left)
+	$Hud/Accept.show()
+	$Hud/Decline.show()
+
+
+func _on_accept_pressed() -> void: _decide(true)
+func _on_decline_pressed() -> void: _decide(false)
+
+
+func _decide(accept: bool) -> void:
+	if proposal == null or proposal.is_decided():
+		return
+	var decided: SummerResult = proposal.accept() if accept else proposal.decline()
+	if not decided.ok:
+		show_status(join_failure_text(decided))
+	$Hud/Accept.hide()
+	$Hud/Decline.hide()
+```
+
+After an accept, `find_match` keeps waiting until everyone accepted. A
+decline ends it with `proposal_declined`. A game that always accepts (one
+"Play" button) connects `acceptance_required` straight to `proposal.accept()`.
+
+### 4. Tell players what went wrong
+
+Every failure is a `SummerResult` with a stable `code` and `retryable`:
+
+```gdscript
+## Turns a typed failure into words for the player. `retryable` says whether
+## offering "Try again" makes sense.
+func join_failure_text(result: SummerResult) -> String:
+	match String(result.code):
+		"proposal_declined":
+			return "You declined the match."
+		"proposal_expired":
+			return "The match wasn't accepted in time."
+		"queue_not_found", "queue_closed":
+			return "This mode isn't available right now."
+		"capacity_exhausted", "world_full", "world_start_timeout", "region_unavailable":
+			return "Servers are busy. Try again in a moment."
+		"rate_limited":
+			return "Too many tries. Wait a moment."
+		"cancelled":
+			return ""
+	return "Couldn't join. Try again." if result.retryable else "Couldn't join: %s" % result.message
+```
+
+Other codes: `proposal_stale` and `proposal_already_decided` (a second
+decision), `world_waking` (a persistent World is restoring), `qos_stale`,
+`platform_error`, and `unavailable` (Local Play hosts a different queue).
+
+### 5. Cancel the search, or leave
+
+`Summer.client.leave()` cancels a search in flight, or leaves the current
+match. Await it before quitting the game, so the platform knows the player is
+gone and doesn't hold a seat for them:
+
+```gdscript
+## Stops searching, or leaves the current match. Await it before quitting.
+func leave_match() -> void:
+	var left: SummerResult = await Summer.client.leave().get_result_or_completed_signal()
+	if not left.ok:
+		push_warning("leave: %s" % left.code)
+```
+
+To offer "Play online" only when it can work, read
+`Summer.client.matchmaking.availability.hosted_sessions_available` (and
+`hosted_unavailable_reason`) before showing the button.
+
+### 6. Read teams and the queue on the authority
+
+The authority learns each player's team from the verified Session. In
+`authority/main.gd`, give `match_doc` a `"teams": {}` entry and add this to
+`_join` just before `request.accept(...)`:
+
+```gdscript
+	# The team matchmaking seated this player on: 0..count-1, or -1 without teams.
+	var participant := Summer.authority.match.get_participant(session)
+	var team := participant.team if participant != null else -1
+	match_doc.teams[session.player.display_name] = team
+	match_group.reset(Game.pack(match_doc))
+```
+
+Players learn teams only from what the authority publishes, here the shared
+match document. `Summer.get_world().queue` on the authority names the queue
+this match came from, so one authority scene can serve several modes.
+
+### 7. Test it with Local Play
+
+Local Play stands in for one queue at a time: the first one declared, or the
+one you name. In the editor and with `summer_play`, name it with the
+`summer/local_play/queue` project setting:
+
+```
+summer_project_setting name="summer/local_play/queue" value="duel"
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+A terminal run ignores that setting; pass the queue instead:
+`<summer> --path . --summer-local-play 2 --summer-local-play-queue duel --summer-local-play-smoke`.
+
+- The client must join the queue Local Play stands in for. Another queue
+  fails with `unavailable`: "Local Play is hosting queue 'courtyard'. Start
+  Local Play with queue 'duel' to test that queue."
+- Players are placed at once: progress goes straight to `STAGE_CONNECTED`,
+  with no search and no Accept/Decline.
+- A team queue seats players round-robin in roster order (player-1 on team 0,
+  player-2 on team 1, and so on), whatever order they connect in.
+- `Summer.client.matchmaking.availability` reports hosted sessions as
+  available.
+
+Test the accept prompt and rating-based grouping on a hosted staging build.
+
+## Checklist
+
+- [ ] Every queue names a WorldDefinition; teams queues have `minPlayers` = `maxPlayers` = count × size.
+- [ ] The client shows search progress and a readable message for each failure code.
+- [ ] Queues with `acceptance` show Accept/Decline with the deadline; nothing auto-accepts unless the game means to.
+- [ ] Cancel and quit both await `Summer.client.leave()`.
+- [ ] The authority reads `get_participant(session).team` and publishes teams to players.
+- [ ] Local Play with `summer/local_play/queue` set runs each queue you declared.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Build a lobby, invite codes or join-by-IP | Queues, plus parties for friends | Summer has no lobby object; invite, follow, portal and resume joins return `unsupported_placement` |
+| Ignore `acceptance_required` on a queue with `acceptance` | Show Accept/Decline, or connect it to `proposal.accept()` | The engine never accepts for the player; the join waits until `proposal_expired` |
+| `teams` with `minPlayers` ≠ count × size | Equal sizes: 2v2 is 4 and 4 | Summer rejects the queue when you publish |
+| Read the team on the client from matchmaking | Publish it from the authority | Clients only learn teams through the game's own state |
+| Join `courtyard` while Local Play stands in for `duel` | Set `summer/local_play/queue` to the queue the client joins | Local Play hosts one queue per run; the other fails `unavailable` |
+| Quit right after "Cancel" | Await `Summer.client.leave()` first | The search may keep holding a ticket for the player |
+| Show raw `result.message` for known codes | Map codes to your own words | Codes are stable; messages are diagnostics |
+
+## See also
+
+- `skill/multiplayer` — how Summer multiplayer fits together
+- `skill/summer-match-results` — ending a match and reporting who won
+- `skill/summer-leaderboards` — ratings and leaderboards for rated queues
+- `skill/summer-parties` — friends entering a queue together
+- `skill/multiplayer-testing` — Local Play options and bots

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

@@ -0,0 +1,32 @@
+id: skill/summer-matchmaking
+kind: skill
+version: 1.0.0
+summary: "Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures."
+use_when:
+  - "the user wants matchmaking, a lobby, a play button, quick play, ranked or casual modes in a multiplayer Summer game"
+  - "declaring queues, player counts, teams (2v2, 5v5), rated queues or a ready check in summer.build.json"
+  - "showing search progress, an Accept/Decline prompt, cancel search or join errors to players"
+  - "the authority needs to know which team or queue each player is on"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - ux
+  modalities:
+    - scripts
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-project
+    - skill/multiplayer-testing
+    - skill/summer-match-results
+    - skill/summer-leaderboards
+    - skill/summer-parties
+source: official
+license: MIT
+status: preview
+recommended: false