summer-store is a skill from the Summer skill library: a guide your AI agent reads when the task matches, so it builds the good version on the first try. Sell Summer items for Sparks: shop, checkout, slugs, bundles, sales, owned items, summer.items.json sync.
When your agent uses it
- 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, already_owned or unavailable, or bought items don’t appear
- Recognizing items in game code by slug (item key) so one build works in staging and production
- Defining items in summer.items.json and syncing them to the store for the owner’s approval
- Store bundles, Save %, timed sales, bundle-only items, or Owned instead of Buy
Install
summer setup installs every skill for your agent. To add only this one:
claude-code for your agent, such as codex or cursor. See Skills for every option.
The skill
Overview
Players pay with Sparks, Summer’s currency. Your game never touches money, balances or approval:- The client lists your published offers with
Summer.client.store.list_items(). - The player presses Buy. The client asks for a checkout with offer ids and quantities, never prices.
- The Summer app shows its own purchase sheet. The player approves or declines there.
- Summer charges the Sparks and issues the item into the player’s inventory.
- The game sees the item in
Summer.client.items(client) andSummer.authority.items(authority).
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:
This skill extends the Courtyard game from
multiplayer-project and
multiplayer-state.
Where items come from
Game code never creates or grants items at runtime. The creator defines them, Summer reviews each one, and the owner activates it. Two ways in:
An agent never writes an item or a price itself. Bundles and sales (step 5)
are not in the file; they belong to the store page draft, which the owner
publishes.
How an item becomes buyable
Today an item goes on sale only after all of these:- Defined. In Studio, or from a sync plan the owner approved (Studio applies it). Approving the plan does not put anything on sale.
- Reviewed. Each item is submitted for Summer’s review. Its page shows the state; “Check verification status” reads the result.
- Activated, one item at a time. Once Summer approves an item, the owner presses Review activation on that item’s page in Studio and confirms. Nothing activates it for them: not the sync, not an agent.
- The Game is live. An active item is buyable only while its Game’s store page is live. It stops selling while the Game is unlisted and resumes when the Game is listed again. An item can be activated before the Game goes live; it sells from the moment the Game is live.
update with "revision": "new_draft".
Players keep buying the live revision while the new one is reviewed, and
the new one replaces it only after the owner’s Review activation of it.
Coming: Summer has decided that items will go on sale without waiting for
Summer’s review. Staff will review an item after it goes live and can take
it down. The store change that does this is being built and has not shipped.
Until it ships, follow the four steps above. When it ships, steps 2 and 3
no longer hold up the sale; a live Game is still required.
summer.items.json
Sync it
- Plan (dry run).
summer_sync_items {"gameId": "game_..."}reads the file and the Game’s items by slug, and changes nothing. It answers create, update (with the changed fields), unchanged, blocked (with the reason), and the Game’s items the file does not name (listed, never changed). - Show the plan to the user and ask before sending it.
- Confirm.
summer_sync_items {"gameId": "game_...", "confirm": true}uploads the changed images and sends the plan to the owner. The answer isawaiting_owner_approvalwith an approval link: give it to the owner. Nothing changes until they approve in Studio. Then each item is created or revised, priced and submitted for Summer’s review. Each one still needs Summer’s approval and the owner’s Review activation before players can buy it (“How an item becomes buyable”). - One approval takes at most 50 items. A larger plan lists
batches; confirm each one with"slugs": [...]and pass on each approval link.
gameId from that environment’s game list.
The machine holds one store sign-in. To switch, set SUMMER_GATEWAY_URL and
SUMMER_MCP_RESOURCE_URL for the other environment, then run
summer login --store --force. Until then the sync stops with
store_login_other_environment.
Slugs
- Set in Studio (“Item key”, on create or on the item page) or from the file.
- Unique within the Game, and the same in staging and production.
- Frozen once the item’s first publication is claimed, even if that publication fails or the item is retired. Before that it can change, and an item without a slug can get one at any time.
- Never reused by another item of the Game, so game code and the authority can safely name items by slug.
StoreItem.slug and the inventory InventoryItem.definition_slug.
Game code reads them with SummerStoreItem.get_slug(),
SummerInventoryItem.get_slug(), SummerClientItems.has_owned_slug() and
SummerItemSelection.allowed_slugs. Those getters are not in Summer 0.7.3;
they come with the next Summer Engine release that carries them (0.7.4, in
progress). Check the version the game runs on before relying on them. Local
Play fixtures carry slugs too (step 7).
Without the getters, use the definition-id variants in steps 1–3, with each
environment’s definition ids.
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:
"slug" from the rows, pass the
item’s per-environment definition id, and use:
checkouts_changed to the Buy buttons: disable them while busy is
true, and for rows with owned true. Update rows by id; a status can be
delivered again after a crash, so rendering must be idempotent. Show each
checkout state:
2. Unlock from the inventory only
Unlock cosmetics in menus withowns(slug), 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”. Match by slug, never by item name, and never hard-code one
environment’s definition ids.
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:
await command({"c": "equip", "hat": slug}) and every client
draws hats from match_doc.hats. Other players see the hat only because the
authority published it.
Without slugs (Summer versions without the getters, or an item with no Item key):
keep each environment’s definition ids, send the definition id, and compare
item.get_definition_id() == definition_id instead of item.get_slug() == slug.
For an equipment slot, SummerItemSelection does this check for you: set
selection.allowed_slugs = PackedStringArray(["party_hat"]), then call
configure_slot with an empty definition allowlist. An item whose inventory
carries no slug never matches, so the slot fails closed until it has one.
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. Owned items and maxOwned
Summer counts owned copies plus purchases still settling. A checkout with no
room left is refused with
409 already_owned before anything is charged,
and of two simultaneous purchases of the last copy, one is accepted. In game
code that is a submission_failure whose reason is already_owned (step 1):
show “Owned”, not an error. The Summer apps’ shops already show Owned
instead of Buy; in your own shop, set owned from the inventory and disable Buy.
5. Bundles and timed sales
They live on the store page draft; saving never publishes. Players see them once the owner publishes the store page again (store.publish, owner-approved).
In Studio (studio.open target /studio/store/:gameId, the Store page tab):
- Bundles card: Add bundle, name it (the key comes from the name and is fixed once published), pick the Items (one without a price can’t be picked; a stackable takes a quantity), set the Sparks price. The line under the price shows the Items total and “Save N%”. Optional: a minimum price, and “On sale from” / “Until” dates. Save bundles. Removing a bundle removes its sales too.
- Sales card: Add sale, pick an Item or a bundle, the percent off and the start and end dates; it shows the result (“400 → 280 Sparks”). Save sales. A sale that has ended is dropped on save.
- Sold only in bundles: the checkbox on an Item’s row in a bundle, or the toggle on the Item’s page. A refusal shows at the field to fix.
store.set_bundles and store.set_sales.
store.get_listing returns itemStore: the bundles with itemsTotalSparks and savePercent, the sales with listSparks and saleSparks, bundleOnlyItemIds, and the Game’s Items with ids and Sparks prices.
Each call replaces the whole list, so send every bundle or sale to keep; [] clears it. A bundle without a key keeps the saved key of the same name; bundleOnlyItemIds on store.set_bundles sets the bundle-only Items. A refusal names the field, e.g. storeBundles[0].priceSparks.
A player who owns some of a bundle’s unique items gets those left out,
and the price drops by their share of the regular base prices:
bundle price × base of the items not owned ÷ base of all its items. It is
computed exactly, held at least at the minimum and at 1 Spark per unit, then
rounded up once, and never costs more than buying the remaining items
separately. Stackable and consumable items always count. Owning everything
shows Owned. Only the bundle total is promised; each item’s share on the
receipt just splits it.
Where players see them: the Game shop in the Summer apps (website,
desktop, iPhone, Android) shows a Bundles row, “Save N%”, “You own 2 of 5”,
“Ends in …”, and “This offer ended” (nothing charged) when a sale or bundle
window closes before the purchase.
In your in-game shop: list_items shows a running sale’s price as the
item’s price (no crossed-out price) and leaves bundle-only items out. Bundles
are not sold in game yet; point players to the Game shop in the Summer app.
6. Rules and why
- Offer ids and quantities only. Never send a price, an amount or a buyer. The platform prices everything, sales and bundles included, and a client-side price is what a cheater edits.
- One
request_checkoutis 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_changednormally, before reading statuses. A synchronous handler is how the SDK knows the result was delivered; a deferred-only handler leaves it undelivered. pendingandmanual_revieware 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()andcheck_checkout_readiness()return aSummerResult; show the shop only when they’reok.
7. Test
Local Play. The store and checkout reportunavailable, 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. Give them slugs with
catalog_item_slugs, only on a Summer version with slug getters; older ones
refuse the field.
- Every persona owns one item per template.
- Each item has the slug you gave its template: Bob’s hat is
party_hat, so slug code behaves as it will once slugs are delivered. - Other ids are local stand-ins: owned item id
local-item:bob:0, definition idlocal-definition:courtyard:0,item_template_version_id"hat". Without slugs, equip with the local definition id the client reads fromitems.get_owned_items().
summer.items.json still serves both). Your
production account and Games are not in it; if you have no staging account,
ask Summer for access. Purchases there use test payments: Sparks bought in
staging are sandbox Sparks, nothing real is charged, and they earn the
creator nothing. Test a purchase with a staging account that bought Sparks
in the staging Summer app.
Before testing, the item must be buyable in staging: reviewed, activated by
the owner, and the staging Game live (“How an item becomes buyable”).
Walk through every outcome:
- decline the sheet;
- buy with too few Sparks;
- buy a unique item you already own:
already_owned, nothing charged; - 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,equipis accepted for it and refused withnot_ownedfor anything else. - Game code names items by slug, or by each environment’s definition ids where slugs are not available.
- No code path creates an item, sends a price, or grants an item from a checkout status.
- Buy is disabled while
has_pending_checkouts()is true, and for owned unique items. -
manual_reviewshows “confirming”, andalready_ownedshows “Owned”. - Every
summer.items.jsonsync: the dry-run plan was shown, then confirmed, then the owner got the approval link. - Every new or changed item: Summer approved it, the owner pressed Review activation, and the Game is live.
- Staging: a purchase shows up in the inventory, and the equipped item appears for every player.
Common mistakes
See also
multiplayer-state: Commands and the match document used for equipped itemsmultiplayer-testing: Local Play fixtures and personassummer-player-data: saving a player’s loadout between matchessummer-analytics: measuring the shop
From a shell
No Summer MCP tools in this session? Run each one as a command; whensummer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.
Related skills
in-game-purchases: Sell items for Sparks via the Summer purchase sheet: checkout, not enough Sparks, unlocks, grants.multiplayer: Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next.multiplayer-state: Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events.multiplayer-testing: Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run.summer-player-data: Save a player’s progress so it follows them to every match: authority load and commit, autosave, safe retries.summer-analytics: Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay.
Source:
library/skills/summer-store/SKILL.md, rendered from summer-engine@4.9.2 on npm.
