summer-engine 3.1.0 → 3.2.0

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

@@ -0,0 +1,271 @@
+---
+name: summer-store
+description: "Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks."
+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/test-users.json"]
+---
+
+# /summer-store — sell items, check what players own
+
+## Overview
+
+Players pay with **Sparks**, Summer's currency. Your game never touches money,
+balances or approval:
+
+1. The client lists your published offers with `Summer.client.store.list_items()`.
+2. The player presses Buy. The client asks for a checkout with offer ids and quantities, never prices.
+3. The Summer app shows its own purchase sheet. The player approves or declines there.
+4. Summer charges the Sparks and issues the item into the player's **inventory**.
+5. The game sees the item in `Summer.client.items` (client) and `Summer.authority.items` (authority).
+
+Three ids, kept apart:
+
+| Id | Where it comes from | Use it for |
+| --- | --- | --- |
+| Offer id | `item.price.offer_id` in the store listing | `SummerCheckoutLine.create(offer_id, quantity)` |
+| Definition id | Your item definition in the Summer catalog | "Does this player own a hat?" |
+| Owned item id | One owned copy (`item.get_owned_item_id()`) | Pointing at a specific owned copy |
+
+The rule that makes it cheat-proof: **the authority decides what a player may
+use by reading that player's inventory itself.** A client saying "I bought it"
+proves nothing.
+
+**What runs where:**
+
+| Surface | Store and checkout | Inventory |
+| --- | --- | --- |
+| Hosted | Need the Summer app's `player.store.read@1` / `player.store.checkout@1` | Needs `player.items@1` |
+| Local Play | `unavailable` | Works from a fixture: empty unless `.summer/test-users.json` lists item templates (step 5) |
+| Guests, older Summer apps | Readiness reports `unavailable` | Readiness reports `unavailable` |
+
+Items and offers are created in your game's Studio pages (`summer_open` target
+`game`). Code never creates items.
+
+This skill extends the Courtyard game from `skill/multiplayer-project` and
+`skill/multiplayer-state`.
+
+## Steps
+
+### 1. The client shop
+
+`client/shop.gd`, a child `Shop` of `Main`. In `client/main.gd`'s `_ready()`, call
+`$Shop.start()` right after `Summer.initialize` succeeds:
+
+```gdscript
+extends Node
+## A shop for Summer items, paid in Sparks. Summer shows its own purchase
+## sheet; the game never sees money and never grants an item itself.
+
+signal shelf_changed(rows: Array)          # [{name, sparks, offer_id}]
+signal checkouts_changed(busy: bool, rows: Array)
+signal status(text: String)
+
+var store: SummerClientStore
+var items: SummerClientItems
+
+
+## Main calls this right after Summer.initialize succeeds: a child's _ready
+## runs before that, while Summer.client is still null.
+func start() -> void:
+	store = Summer.client.store
+	items = Summer.client.items
+	# Connect before reading retained statuses; a normal (not deferred)
+	# connection is how the SDK knows a result was delivered.
+	store.checkout_status_changed.connect(func(_status: SummerCheckoutStatus) -> void: _render_checkouts())
+	items.refreshed.connect(_on_items_changed)
+	items.item_replaced.connect(func(_change: SummerInventoryChange) -> void: _on_items_changed())
+	items.item_removed.connect(func(_change: SummerInventoryChange) -> void: _on_items_changed())
+	_render_checkouts()
+
+
+## Opening the shop screen.
+func open() -> void:
+	var readiness := store.check_browse_readiness()
+	if not readiness.ok:
+		status.emit("The shop is not available here.")   # hide the shop button
+		return
+	var page := store.list_items(50)
+	var listed: SummerResult = await page.get_result_or_completed_signal()
+	if not listed.ok:
+		status.emit("The shop could not load.")
+		return
+	var rows := []
+	for item in page.items:
+		if item.price != null and item.price.offer_id != "":
+			rows.append({"name": item.name, "sparks": item.price.sparks_amount, "offer_id": item.price.offer_id})
+	shelf_changed.emit(rows)
+	if items.check_refresh_readiness().ok:
+		items.refresh()
+
+
+## The Buy button. One call is one purchase: never call it again to retry.
+func buy(offer_id: String) -> void:
+	if not store.check_checkout_readiness().ok:
+		status.emit("Purchases are not available here.")
+		return
+	if store.has_pending_checkouts():
+		return
+	var lines: Array[SummerCheckoutLine] = [SummerCheckoutLine.create(offer_id, 1)]
+	var operation := store.request_checkout(lines)
+	_render_checkouts()
+	await operation.get_result_or_completed_signal()
+	_render_checkouts(operation)
+
+
+func _render_checkouts(operation: SummerCheckoutOperation = null) -> void:
+	var view := SummerCheckoutObservation.capture(store, operation)
+	var rows := []
+	for checkout in view.statuses:
+		rows.append({"id": checkout.request_id, "state": checkout.state, "error": checkout.error_code})
+	checkouts_changed.emit(view.has_pending_checkouts(), rows)
+	if view.submission_failure != null:
+		status.emit("The purchase did not start: %s" % view.submission_failure.code)
+
+
+## Ownership comes only from the inventory, never from a checkout result.
+func owns(definition_id: String) -> bool:
+	return items.is_projection_loaded() and items.has_owned_definition(definition_id)
+
+
+func _on_items_changed() -> void:
+	status.emit("Inventory updated.")
+```
+
+Bind `checkouts_changed` to the Buy buttons: disable them while `busy` is
+true. Update rows by `id`; a status can be delivered again after a crash, so
+rendering must be idempotent. Show each checkout state:
+
+| `state` | Show |
+| --- | --- |
+| `awaiting_approval`, `pending` | "Waiting for Summer…" |
+| `purchased` | "Bought!" The item arrives through the inventory signals, possibly a moment later |
+| `declined`, `expired` | Nothing, or "Cancelled" |
+| `rejected` with `error_code` `insufficient_funds` | "Not enough Sparks" (players get Sparks in the Summer app) |
+| `rejected`, other codes | "The purchase was not completed" |
+| `manual_review` | "We're confirming this purchase." Not done, not failed |
+
+### 2. Unlock from the inventory only
+
+Unlock cosmetics in menus with `owns(definition_id)`, and refresh the menu on
+`refreshed`, `item_replaced` and `item_removed`. Never unlock from a
+`purchased` status: the receipt proves the debit, the inventory proves
+ownership, including after a reinstall or on another device. An empty inventory
+before `is_projection_loaded()` is "still loading", not "owns nothing".
+
+### 3. The authority checks entitlement
+
+Anything that changes the match because of an item goes through a Command, and
+the authority reads that Session's inventory. Add `"equip"` to the `match` in
+`authority/main.gd`'s `_on_command`:
+
+```gdscript
+		"equip":
+			_equip(request, str(command.get("definition", "")))
+```
+
+```gdscript
+## A player asks to wear a hat. The authority reads that Session's inventory
+## itself; a client saying "I own it" proves nothing.
+func _equip(request: SummerNetworkCommandRequest, definition_id: String) -> void:
+	var session := request.get_session()
+	var read := Summer.authority.items.inventory_for_session(session)
+	var result: SummerResult = await read.get_result_or_completed_signal()
+	if not result.ok:
+		request.refuse(&"inventory_unavailable")   # retryable: try again later
+		return
+	for item in read.items:
+		if item.is_owned() and item.get_definition_id() == definition_id:
+			var hats: Dictionary = match_doc.get("hats", {})
+			hats[session.player.user_id] = definition_id
+			match_doc["hats"] = hats
+			match_group.reset(Game.pack(match_doc))
+			request.accept({}, Game.pack({"equipped": definition_id}))
+			return
+	request.refuse(&"not_owned")
+```
+
+The client sends `await command({"c": "equip", "definition": definition_id})`
+and every client draws hats from `match_doc.hats`. Other players see the hat
+only because the authority published it.
+
+`Summer.authority.items.inventory_changed(session, change)` hints that a
+player's inventory changed during the match. To drop an item that was
+refunded mid-match, re-read with `inventory_for_session` (or
+`refresh_inventory`) on that hint.
+
+### 4. Rules and why
+
+- **Offer ids and quantities only.** Never send a price, an amount or a buyer. The platform prices everything, and a client-side price is what a cheater edits.
+- **One `request_checkout` is one purchase.** Each call gets a new identity. Never call it again because a result is slow; `is_outcome_unknown()` means it may already be charged, and the status will still arrive.
+- **Connect `checkout_status_changed` normally, before reading statuses.** A synchronous handler is how the SDK knows the result was delivered; a deferred-only handler leaves it undelivered.
+- **`pending` and `manual_review` are not failures.** Don't show success or failure until a terminal state.
+- **Carts:** 1–16 different offers, at most 64 units, as one atomic purchase.
+- **Hide what's unavailable.** `check_browse_readiness()` and `check_checkout_readiness()` return a `SummerResult`; show the shop only when they're `ok`.
+
+### 5. Test
+
+**Local Play.** The store and checkout report `unavailable`, so the hidden-shop
+path is what you test. Inventory and the authority check work from a fixture:
+create `.summer/test-users.json` with item templates.
+
+```json
+{
+  "schema": "summer.local-fixture.v1",
+  "fixture_id": "courtyard",
+  "fixture_version": 1,
+  "seed": 1,
+  "world_definition": "world.json",
+  "service_outcomes": [],
+  "catalog_item_templates": ["hat"],
+  "personas": [
+    {"persona_id": "alice", "display_name": "Alice", "participant_role": "player", "eligible_for_outcome": true, "session_lifetime": "match_bound"},
+    {"persona_id": "bob", "display_name": "Bob", "participant_role": "player", "eligible_for_outcome": true, "session_lifetime": "match_bound"}
+  ]
+}
+```
+
+What the fixture gives you:
+
+- Every persona owns one item per template.
+- Ids are local stand-ins. Bob's hat has owned item id `local-item:bob:0`, definition id `local-definition:courtyard:0`, and `item_template_version_id` `"hat"`.
+- A check against your real catalog definition id is therefore `false` in Local Play. To exercise the authority path locally, equip with the local definition id the client reads from `items.get_owned_items()`.
+
+**Staging.** Test real purchases there; Summer staging uses sandbox payments.
+Walk through every outcome:
+
+- decline the sheet;
+- buy with too few Sparks;
+- buy, then kill the game while the purchase is pending and relaunch: the result must arrive exactly once.
+
+## Checklist
+
+- [ ] Local Play: the shop button is hidden, and there are no script errors.
+- [ ] Local Play with the fixture: `items.refresh()` succeeds, the owned item is listed, `equip` is accepted for it and refused with `not_owned` for anything else.
+- [ ] No code path sends a price or grants an item from a checkout status.
+- [ ] Buy is disabled while `has_pending_checkouts()` is true.
+- [ ] `manual_review` shows "confirming", not success or failure.
+- [ ] Staging: a purchase shows up in the inventory, and the equipped item appears for every player.
+
+## Common mistakes
+
+| Don't | Do | Why |
+| --- | --- | --- |
+| Unlock on `purchased` | Unlock from `Summer.client.items` | Ownership lives in the inventory; receipts can replay |
+| Let the client tell the authority what it owns | `Summer.authority.items.inventory_for_session(session)` | Client claims are what cheaters forge |
+| Send prices or amounts | Offer id + quantity only | The platform prices every purchase |
+| Call `request_checkout` again on a slow result | Wait for its status; check `is_outcome_unknown()` | The first request may already be charged |
+| Connect the status signal deferred or after reading statuses | Connect normally, first | Deferred handlers don't count as delivered; statuses can be missed |
+| Treat `manual_review` as failed | Show "confirming" | The platform hasn't decided yet |
+| Invent your own paid currency | Sell Summer items for Sparks | Summer can only protect, refund and pay out Sparks purchases |
+| Assume the shop exists everywhere | Check readiness, hide when unavailable | Local Play, guests and older Summer apps have no store |
+
+## See also
+
+- `skill/multiplayer-state`: Commands and the match document used for equipped items
+- `skill/multiplayer-testing`: Local Play fixtures and personas
+- `skill/summer-player-data`: saving a player's loadout between matches
+- `skill/summer-analytics`: measuring the shop

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

@@ -0,0 +1,29 @@
+id: skill/summer-store
+kind: skill
+version: 1.0.0
+summary: "Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks."
+use_when:
+  - "adding a shop, in-game purchases, cosmetics or skins sold for Sparks to a Summer game"
+  - "checking on the authority that a player really owns an item before letting them use or equip it"
+  - "checkout shows pending, manual_review, insufficient_funds or unavailable, or bought items don't appear"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - gameplay
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-state
+    - skill/multiplayer-testing
+    - skill/summer-player-data
+    - skill/summer-analytics
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/summer-world-chat/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: summer-world-chat
+description: "Add match chat to a Summer game: one World channel shared by everyone in the match. 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", "**/*.tscn"]
+---
+
+# /summer-world-chat — chat with everyone in the match
+
+## Overview
+
+A **World channel** is a text channel for the World (match) the player has
+joined. Every player in that World can open the same channel by key, such as
+`"match"`. The platform owns everything that matters about it:
+
+- who may read it;
+- the text filter;
+- rate limits;
+- 24-hour retention;
+- blocks between players.
+
+Your game owns only the chat UI. Messages never travel through your network
+composition, and the authority neither sees nor writes them.
+
+| Fact | Value |
+| --- | --- |
+| Text | Plain Unicode, 1 to 4000 characters. Always render it as plain text, never as markup |
+| Channel keys | 1–64 of `A-Z a-z 0-9 _ . -`, starting with a letter or digit; at most 64 channels per World |
+| History | Best effort, not a full log. A new handle shows the newest 2 messages; `load_older()` grows the window to at most 16 |
+| Lifetime | A handle belongs to one World admission. After leaving or joining another World, open a new one |
+| Not included | Direct messages (`skill/summer-friends`), party chat (the Summer app) and messages written by your server |
+
+**Hosted only.** Chat needs a joined hosted World and a Summer app whose Player
+Host offers `player.channels`. A queue reservation is not enough: open the
+channel after `enter()` succeeds. In Local Play and editor runs,
+`check_open_readiness()` and `open_world_channel()` fail with `unavailable`.
+Build the "chat hidden" path first.
+
+This skill extends the Courtyard game from `skill/multiplayer-project` and
+`skill/multiplayer-state`.
+
+## Steps
+
+### 1. Publish player names
+
+Messages carry the author's Summer user id (`player_id`), not a name. The
+authority already knows every verified name. Publish them in the shared match
+document (`skill/multiplayer-state`): in `authority/main.gd`'s `_join`, before
+accepting, add
+
+```gdscript
+	var players: Dictionary = match_doc.get("players", {})
+	players[session.player.user_id] = session.player.display_name
+	match_doc["players"] = players
+	match_group.reset(Game.pack(match_doc))
+```
+
+On the client, copy `match_doc.get("players", {})` into the chat node's
+`names` whenever the match document changes.
+
+### 2. Add the chat node
+
+`client/chat.gd`, added as a child `Chat` of `Main` in `client/main.tscn`:
+
+```gdscript
+extends Node
+## Match chat: one World channel that every player in this match shares.
+
+signal lines_changed(lines: PackedStringArray)
+signal status(text: String)
+
+var chat: SummerWorldChannel
+var names := {}   # player user id -> display name, from your match state
+
+
+## Call after the player has entered the match.
+func open() -> void:
+	var channels := Summer.client.channels
+	var ready := channels.check_open_readiness()
+	if not ready.ok:
+		status.emit("Chat is not available here.")   # hide the chat box
+		return
+	var opened := channels.open_world_channel("match")
+	var result: SummerResult = await opened.get_result_or_completed_signal()
+	if not result.ok:
+		status.emit("Chat is not available here.")
+		return
+	chat = opened.get_channel()
+	if chat == null:
+		return   # the player already left this World
+	chat.history_changed.connect(_render)
+	chat.history_failed.connect(func(_failure: SummerResult) -> void: status.emit("Chat history is unavailable. Tap to retry."))
+	chat.closed.connect(func(_reason: String) -> void:
+		chat = null
+		_render())
+	_render()   # the first history may already be here
+
+
+## The Retry tap after history_failed.
+func retry_history() -> void:
+	if chat != null:
+		chat.refresh()
+
+
+func send(text: String) -> void:
+	if chat == null or text.strip_edges().is_empty():
+		return
+	var sent := chat.send_message(text)
+	var result: SummerResult = await sent.get_result_or_completed_signal()
+	if not result.ok and result.retryable and result.code != &"rate_limited":
+		# An ambiguous failure may have been accepted. Retry the same send,
+		# never send_message again: that would be a second message.
+		sent = sent.retry()
+		result = await sent.get_result_or_completed_signal()
+	if result.ok:
+		return
+	match result.code:
+		&"text_not_allowed":
+			status.emit("That message was not sent.")
+		&"rate_limited":
+			status.emit("You are sending messages too fast.")
+		_:
+			status.emit("Message not sent.")
+
+
+## The visible window always comes from get_messages(), never from appending.
+func _render() -> void:
+	var lines := PackedStringArray()
+	if chat != null and chat.is_history_current():
+		for message in chat.get_messages():
+			var author := "Game" if message.author_kind == &"creator_system" else String(names.get(message.player_id, "Player"))
+			lines.append("%s: %s" % [author, message.text])
+	lines_changed.emit(lines)
+```
+
+Call `$Chat.open()` after `enter()` returns `true`. Wire it into the UI:
+
+- **Messages:** a `Label` or `RichTextLabel` with `bbcode_enabled = false`, refilled from `lines_changed`.
+- **Input:** a `LineEdit` whose `text_submitted` calls `$Chat.send(text)` and clears itself.
+- **Status:** `status` feeds a status line; hide the whole box when chat is unavailable.
+
+### 3. Rules the code above follows
+
+- **Render, don't append.** `history_changed` means "replace the view from `get_messages()`". It also fires when a block or expiry removes messages, which must disappear from the screen.
+- **`message_received` is for sounds and badges only.** It fires for newly seen messages, not for the initial or older history. Display still comes from `get_messages()`.
+- **One `send_message` call is one message.** For an ambiguous retryable failure, call `retry()` on the same operation; it reuses the original idempotency key. A second `send_message` would post twice.
+- **`text_not_allowed` stored nothing.** The filter refused it, and resending the same text fails again.
+- **`rate_limited`.** About 120 messages a minute per player; tell them to slow down, don't loop.
+- **Sequence gaps are normal.** Blocks, other recipients and expiry hide messages; never treat a gap as an error.
+- **`creator_system` messages are from the game**, never from a player or from Summer staff.
+
+### 4. Test
+
+Locally, check that the hidden path works and nothing errors:
+
+```
+summer_project_setting name="summer/local_play/players" value=2
+summer_play
+summer_get_diagnostics
+summer_stop
+```
+
+Then test real chat on Summer staging with two accounts in one match.
+
+## Checklist
+
+- [ ] Local Play: `open()` reports chat unavailable, the chat box is hidden, and there are no script errors.
+- [ ] The channel opens only after the player entered the World.
+- [ ] Hosted: a message from one player appears for the other, with the right name.
+- [ ] A filtered message shows "not sent" and never appears.
+- [ ] After leaving and joining another match, chat reopens on a new handle.
+- [ ] Text is shown as plain text: `[b]hi[/b]` appears literally.
+
+## Common mistakes
+
+| Don't | Do | Why |
+| --- | --- | --- |
+| Send chat through your own Commands or State | `Summer.client.channels` | Summer filters, rate-limits, applies blocks and expires text; your State does none of that |
+| Open the channel right after `Summer.initialize` | Open after `enter()` succeeds | Only a joined World admission can open it |
+| Append each message to a log | Re-render from `get_messages()` on `history_changed` | Blocked and expired text must disappear |
+| Call `send_message` again after a timeout | `operation.retry()` | A new call is a second message |
+| Render with BBCode enabled | Plain `Label`, or `bbcode_enabled = false` | Player text is never markup |
+| Keep a handle across matches | Open a new channel per World | Handles never follow the player to another World |
+| Show `player_id` | Map it to a name your authority publishes | Ids are not names |
+
+## See also
+
+- `skill/multiplayer-state`: the match document that carries player names
+- `skill/summer-friends`: direct messages with friends
+- `skill/summer-parties`: party chat lives in the Summer app
+- `skill/multiplayer-testing`: what Local Play can and can't test

package/library/skills/summer-world-chat/resource.yaml

@@ -0,0 +1,30 @@
+id: skill/summer-world-chat
+kind: skill
+version: 1.0.0
+summary: "Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only."
+use_when:
+  - "adding in-game text chat, match chat or a chat box to a multiplayer Summer game"
+  - "chat messages fail with text_not_allowed, rate_limited or unavailable, or chat history looks incomplete"
+  - "deciding where player chat should live instead of sending it through Commands or State"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - ui
+  modalities:
+    - scripts
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer
+    - skill/multiplayer-state
+    - skill/multiplayer-testing
+    - skill/summer-friends
+    - skill/summer-parties
+source: official
+license: MIT
+status: preview
+recommended: false