summer-engine 3.0.0 → 3.2.0

package/library/skills/environment-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: environment-kit
-description: Use when generating a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corner blocks that snap together to form a level. Multiple meshes that share a visual style. Trigger on "build a dungeon kit", "modular walls", "level kit", "tileset", "interior pieces", "snap-together pieces", "make a kit for the temple".
+description: "Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets

package/library/skills/export-and-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-and-ship
-description: Use when the user wants to assess or prepare a Summer game export. Inventories the templates and targets actually available in the installed Summer Engine build, validates release assets and configuration, and produces only locally supported builds after approval. It does not publish, upload, host, or submit a game. Trigger on "export", "ship", "release", "build", "Steam", "itch", "HTML5", "iOS", "Android", "submit", "publish".
+description: "Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment

package/library/skills/fabricating-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabricating-assets
-description: Use when an asset needs Blender's mesh tooling rather than generation or a library download — a modular kit with exact dimensions and snapping, VFX meshes (shatter fragments, curve sweeps, LOD chains), or decimating/UV-unwrapping/baking a generated model — and you are about to write a bpy script for summer_fabricate_3d. Covers the route decision (fabricate vs generate vs import), the bpy rules that survive glTF export, the script -> import -> snapshot -> screenshot loop, every failure_reason and what to do about it, and the licensing shape (the user's own Blender, never bundled).
+description: "Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models."
 ---
 
 # Fabricating Assets

package/library/skills/facial-and-lipsync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: facial-and-lipsync
-description: Use when the user has a voice-over (or wants one) and needs the character's mouth to actually move with the words — phoneme extraction from audio, mapping to viseme blendshapes, plus emotional facial expressions (smile, frown, surprise). Trigger on "lipsync", "lip sync", "talking head", "phonemes", "viseme", "facial animation", "blendshapes", "make him talk", "dialogue animation".
+description: "Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

package/library/skills/fps-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fps-controller
-description: Use when building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces — production-quality first-person controller with WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling. Trigger on "FPS", "first-person", "WASD", "character controller", "mouse look", "player movement", "jump".
+description: "Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
@@ -295,12 +295,14 @@ The skeleton doesn't change — only the `@export` defaults. That's the point of
 
 ## Networking Note
 
-For multiplayer, two viable patterns:
-
-1. **Server-authoritative (the open-source-friendly path):** gate physics with `if not multiplayer.is_server(): return` for non-local players, sync `global_position` + `velocity` via `MultiplayerSynchronizer`, send input via RPC. This skeleton is compatible — wrap the `_physics_process` body in a `is_local_player` check and add a separate `apply_remote_player_physics` that interpolates from network snapshots.
-2. **Custom action protocol (the shipped-game path):** the same skeleton runs on every client; one peer is "host" and broadcasts authoritative state at a fixed interval. Out of scope for this skill — see the multiplayer-and-networking category.
-
-The external-velocity accumulator pattern is a multiplayer-correctness gift either way: explosions and knockbacks happen on the host, the impulse is RPC'd to the affected player, and the client's controller absorbs it without fighting local input. That's why the subtract-previous-contribution trick at the top of `_physics_process` exists — it is the single fix that prevents knockback drift in netcode.
+In a Summer multiplayer game this controller stays on the player's own
+client: it moves the local body, and the client publishes the resulting pose
+for the authority to check (`multiplayer-movement`). Other players' bodies
+are drawn from their published poses, never simulated locally. Never sync it
+with `@rpc` or `MultiplayerSynchronizer`. Knockback, explosions and jump pads
+that the authority decides arrive as an authority `reset()` of the pose, or
+as State the owner applies to `external_velocity`; the external-velocity
+accumulator above absorbs them without fighting input.
 
 ## Beyond This Skeleton
 

package/library/skills/fps-controller/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/fps-controller
 kind: skill
-version: 1.0.3
+version: 1.0.4
 summary: Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling.
 use_when:
   - building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces
@@ -17,6 +17,9 @@ facets:
 compatibility:
   engine: ">=4.6"
 related:
+  skills:
+    - skill/character-movement
+    - skill/camera-rigs
   # Legacy frontmatter declared template-id: template-3d-fps (no such repo exists);
   # mapped to the real repo template-3d-fps-old-school.
   templates:

package/library/skills/game-feel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: game-feel
-description: Use when a Summer game "feels flat", "lacks impact", "needs juice", or "needs punch", or the user asks for hit feedback, screen shake, camera shake, audio ducking, or general game feel. Walks through Summer Engine's hit-flash, trauma camera shake, and audio-ducking stack, wired so one hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
+description: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/gameskill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gameskill
-description: Use when finishing a game-development session and you want to capture what you just learned as a reusable skill so the next session starts smarter. Trigger on "gameskill", "/gameskill", "capture learnings", "save to skills".
+description: "Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: workflow

package/library/skills/gdscript-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdscript-patterns
-description: Use when writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods (`_ready` vs `_process` vs `_physics_process`), `get_node` vs `$NodePath`, naming conventions. Trigger on "GDScript", "script", "signals", "exports", "onready", "_ready", "_process".
+description: "GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns

package/library/skills/generate-motion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-motion
-description: Use when the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library. Picks the right curated motion, attaches the resulting clip to an AnimationPlayer. Trigger on "animation", "animate", "idle", "walk", "run", "attack animation", "motion", "mocap", "dance", "death animation".
+description: "Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
@@ -15,10 +15,10 @@ Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-
 
 The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
 
-> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on
-> the roadmap but not shipped yet. For one-off signature moves not on the
-> curated list, fall back to hand-authoring in Summer Engine or importing from
-> Mixamo. See the Edge cases section.
+> **Custom or non-humanoid motion** (e.g. "drops to one knee, draws bow", a
+> nodding flower, a creature) goes to the `text-to-motion` skill
+> (`backend: "text-to-motion"`) when the server has it enabled; otherwise fall
+> back to hand-authoring in Summer Engine or importing from Mixamo.
 
 ## Web Chat / Public Orchestrator Equivalent
 
@@ -50,7 +50,7 @@ After animation jobs complete, import the rig plus child animation assets togeth
 - The user wants facial / lipsync animation — that's `facial-and-lipsync`.
 - The mesh isn't rigged. Rig first; never call `summer_generate_motion` on a static `.glb`.
 - The user wants procedural look-at, IK, foot placement — that's `procedural-animation`.
-- The user described a **custom signature move** that isn't on the curated list. Today, route to the manual-authoring fallback below.
+- The user described a **custom signature move** that isn't on the curated list — use `text-to-motion`; if the server answers `backend_unavailable`, use the manual-authoring fallback below.
 
 ## Steps
 
@@ -71,7 +71,7 @@ The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAsset
 ```
 summer_generate_motion(
   rigAssetId: "<id>",
-  backend: "meshy-library",   // only option today
+  backend: "meshy-library",   // curated library (default)
   motionName: "run"           // exact name from the curated list — see Reference card
 )
 ```
@@ -154,11 +154,11 @@ have actually seen, or route to the manual-authoring fallback.
 ## Edge cases
 
 - **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom
-  prompt-driven backend is on the roadmap but not shipped today. Workarounds:
+  prompt-driven route is `text-to-motion`. If it is unavailable, workarounds:
   hand-author the clip in Summer Engine's animation panel, import a licensed
   clip as an `AnimationLibrary`, or compose curated clips in an
   `AnimationTree` OneShot blend.
-- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds, hand-author or import a Mixamo-style external library (out of scope for this skill).
+- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds and other non-humanoid rigs use `text-to-motion`, or hand-author / import an external library.
 - **Character is < 1m tall (child / dwarf).** Library clips assume a ~1.8m humanoid. Apply the clip; the proportions retarget but stride length looks long. Either accept it or tune `playback_speed` on the AnimationPlayer track.
 - **Character has wings / tail.** The library ignores the extra bones — they sag. Hand-author additive overlays for the extra bones, or accept the visual hit.
 

package/library/skills/generate-motion/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/generate-motion
 kind: skill
-version: 1.0.3
+version: 1.0.4
 summary: Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer.
 use_when:
   - the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library
@@ -24,6 +24,7 @@ related:
     - skill/facial-and-lipsync
     - skill/procedural-animation
     - skill/retarget
+    - skill/text-to-motion
     - skill/asset-strategy
     - skill/fps-controller
 source: official

package/library/skills/godogen-visual-proof-game-generation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: godogen-visual-proof-game-generation
-description: "Use when adopting Godogen's thin-runtime autonomous game generation and its 'proof over claims' visual QC loop for SummerEngine: capture frames from the running engine, let the host agent self-verify against the brief, and drive bounded fix iterations until a proof recording closes the run."
+description: "Godogen-style game generation with a visual QC loop — capture frames from the running game, self-verify against the brief, bounded fix rounds, proof clip."
 license: MIT
 category: workflow
 tags:

package/library/skills/headless-scripting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: headless-scripting
-description: Use when a Summer project needs an operation no MCP tool exposes, such as baking a navmesh, generating collision shapes, authoring an Animation, building a TileSet, re-importing assets after file changes, or preparing a supported local export. Runs a GDScript file against Summer Engine from the shell. Also use when a plan involves "run it headless and screenshot it", which does not work and this skill explains why.
+description: "Run a GDScript file against Summer Engine from the shell for operations no MCP tool exposes — navmesh baking, collision shapes, TileSets, re-imports."
 ---
 
 # Headless Scripting

package/library/skills/in-game-purchases/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: in-game-purchases
+description: "Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: gameplay
+allowed-tools: Read Grep Write summer_get_script_errors summer_get_scene_tree
+paths: ["**/*.gd"]
+---
+
+# In-game purchases with Sparks
+
+Sparks are Summer's currency. A game never takes money, never holds a
+balance and never approves a payment. It asks Summer, Summer shows its own
+purchase sheet over the game, and the game reacts to the authoritative
+result. There are two calls and they follow the same shape:
+
+| The player wants to | Call | Validated by |
+| --- | --- | --- |
+| buy an item with Sparks they have | `Summer.client.store.request_checkout(lines)` | the Summer ledger (debit) |
+| buy Sparks because they are short | `Summer.client.store.request_sparks_purchase(minimum_sparks)` | the payment provider (Stripe or Apple), then the ledger credit |
+
+## When to sell with Sparks
+
+- Sell anything that persists across sessions or devices (cosmetics, unlocks,
+  passes) as a Summer item with a Sparks price. *Why:* the platform owns the
+  item, so ownership survives reinstalls and cannot be forged by editing the
+  game.
+- Do not invent your own currency that is bought with money. *Why:* Summer
+  can only refund, protect and pay you out for Sparks purchases.
+- Offer "Get Sparks" only when a purchase failed for lack of Sparks, or on an
+  explicit shop button. *Why:* the Summer sheet interrupts play; surprise
+  payment prompts read as pressure and get games reported.
+
+## Rules and the reason for each
+
+1. **Never grant an item from a button press or a receipt.** Unlock only when
+   `Summer.client.items` shows the player owns it. *Why:* the receipt proves
+   the debit; the inventory projection is what the platform guarantees the
+   player owns, including after a crash or on another device.
+2. **Never send prices, amounts or providers.** The game passes an offer ID
+   and a quantity, or a Sparks hint. *Why:* the platform prices everything; a
+   client-supplied price is exactly what a cheater edits.
+3. **One call is one purchase.** Every call creates a new identity. Never
+   call again to "retry" an unknown outcome. *Why:* the first request may
+   already be charged; the SDK and the Summer app recover it and deliver the
+   result on the signal.
+4. **Handle results only in the status signals, and deduplicate by
+   `request_id` plus `version`.** Connect normally (not deferred) before
+   requesting. *Why:* results can arrive after a restart or twice after a
+   crash; a synchronous handler is how the SDK knows the result was delivered.
+5. **Treat `manual_review` and pending as not done.** *Why:* the platform
+   has not decided yet; showing success or failure would be a guess.
+6. **Check readiness and hide what is unavailable.**
+   `check_checkout_readiness()` and `check_sparks_purchase_readiness()` return
+   a `SummerResult`. *Why:* editor play, guest sessions and older Summer apps
+   do not offer purchases; a dead button is worse than no button.
+
+## Result states
+
+Both signals deliver a status with `state`:
+
+| State | Meaning | What the game does |
+| --- | --- | --- |
+| `awaiting_approval` | the Summer sheet is open | nothing; optionally dim the shop |
+| `pending` | payment or debit in progress | show "processing" |
+| `purchased` | done; Sparks debited (checkout) or credited (Sparks) | checkout: refresh items and unlock from inventory. Sparks: say "Sparks added", let the player buy again |
+| `declined` | the player closed the sheet | return to the shop quietly |
+| `expired` | the sheet or payment timed out | same as declined |
+| `rejected` | refused; read `error_code` | checkout with `insufficient_funds`: offer "Get Sparks". Sparks: `provider_rejected`, say the payment did not go through |
+| `manual_review` | platform is checking it | "We are confirming this purchase" |
+| `refunded` | Sparks only: a credited purchase was refunded or charged back (`full_refund`, `dispute_lost`) | nothing to undo; Summer already took the Sparks back. Refresh any balance display |
+
+A Sparks request can also fail to start with `purchase_limit` (the player
+reached the daily in-game Sparks limit) or `age_required` / `adult_required`
+(only adults with a saved age can buy Sparks). Show a short message and no
+retry button. *Why:* both limits are platform policy; retrying changes nothing.
+
+The operation returned by each call also completes (`completed` signal) on
+`purchased` (ok) or a terminal failure with codes such as `checkout_declined`
+or `sparks_purchase_declined`. The status signal is the one to build UI on.
+
+## Minimal complete example
+
+```gdscript
+extends Node
+## A one-item shop. Buys `offer_id`; if the player is short, lets them buy
+## Sparks through the Summer sheet, then they press Buy again.
+
+@export var offer_id := "offer_sword"
+@export var definition_id := "item_sword"
+@export var price_sparks := 250 # display only; the platform charges its own price
+
+signal message(text: String)
+var _seen := {}
+
+func _ready() -> void:
+	var store := Summer.client.store
+	store.checkout_status_changed.connect(_on_checkout)
+	store.sparks_purchase_status_changed.connect(_on_sparks)
+	Summer.client.items.refreshed.connect(_sync_owned)
+	_sync_owned()
+
+func buy() -> void:
+	if not Summer.client.store.check_checkout_readiness().ok:
+		message.emit("The shop is not available here.")
+		return
+	var lines: Array[SummerCheckoutLine] = [SummerCheckoutLine.create(offer_id, 1)]
+	Summer.client.store.request_checkout(lines) # result arrives in _on_checkout
+
+func get_sparks() -> void:
+	if not Summer.client.store.check_sparks_purchase_readiness().ok:
+		message.emit("Get Sparks from the Summer app.")
+		return
+	Summer.client.store.request_sparks_purchase(price_sparks) # hint only
+
+func _first_time(status) -> bool:
+	var key := "%s:%d" % [status.request_id, status.version]
+	if _seen.has(key):
+		return false
+	_seen[key] = true
+	return true
+
+func _on_checkout(status: SummerCheckoutStatus) -> void:
+	if not _first_time(status):
+		return
+	match status.state:
+		&"purchased":
+			Summer.client.items.refresh() # ownership comes from inventory
+		&"rejected":
+			if status.error_code == &"insufficient_funds":
+				message.emit("Not enough Sparks.") # show a Get Sparks button -> get_sparks()
+			else:
+				message.emit("The purchase was not completed.")
+		&"manual_review":
+			message.emit("We are confirming this purchase.")
+		&"declined", &"expired":
+			pass
+
+func _on_sparks(status: SummerSparksPurchaseStatus) -> void:
+	if not _first_time(status):
+		return
+	match status.state:
+		&"purchased":
+			message.emit("%d Sparks added." % status.receipt.sparks_credited)
+		&"rejected":
+			message.emit("The payment did not go through.")
+		&"manual_review":
+			message.emit("We are confirming your payment.")
+
+func _sync_owned() -> void:
+	if Summer.client.items.has_owned_definition(definition_id):
+		message.emit("Sword unlocked.") # the only place the item is granted
+```
+
+After Sparks are added the player presses Buy again. That is a new checkout
+and Summer shows it again. *Why:* the player confirms each spend separately.
+
+## Multiplayer: granting an effect on a dedicated authority
+
+Buying Sparks only adds Sparks to the wallet. Anything the Sparks buy
+("Grow now", "Summon rain") is a separate checkout, and on a server the
+authority must never grant it because a client says it paid. *Why:* a client
+message is the one thing a cheater controls.
+
+Model the effect as a consumable catalog item with instance ownership (each
+purchase is a separate item, not a stack). *Why:* a stackable (quantity) item
+shares one owned item ID across purchases, so the ID could not tell two
+purchases apart. The client checks out; the receipt's `owned_item_ids` are item instances in
+the player's Summer inventory. The client sends the authority only that owned
+item ID. The authority consumes it with
+`Summer.authority.items.consume(session, owned_item_id, idempotency_key)` and
+applies the effect only after a successful receipt. *Why:* the platform ledger
+consumes an instance item once, so the same item cannot be redeemed twice, in
+this world or any other.
+
+```gdscript
+# On the dedicated authority. `redeemed` is saved with the world.
+func redeem(session: SummerSession, owned_item_id: String) -> void:
+	if redeemed.has(owned_item_id):
+		return # a repeated message grants once
+	var key := "redeem_" + owned_item_id.sha256_text().substr(0, 40)
+	var op := Summer.authority.items.consume(session, owned_item_id, key)
+	var result: SummerResult = await op.get_result_or_completed_signal()
+	if not result.ok:
+		# item_not_found: not owned or already used, never grant.
+		# unavailable: retry later with the same key.
+		return
+	redeemed[owned_item_id] = op.command_id # record, apply, then save the world
+	apply_grow_now(session)
+```
+
+- Derive the key from the owned item ID. *Why:* the same key returns the same
+  receipt (`op.replayed` is true), so a retry after a timeout never consumes
+  twice, and a different item with that key fails with `idempotency_conflict`.
+- Apply the effect when the receipt arrives even if `op.replayed` is true, as
+  long as `redeemed` does not have the item. *Why:* a replay means the item was
+  consumed earlier but your world may have crashed before saving the effect.
+- Save the world right after applying. *Why:* the receipt replay is tied to
+  the authority process; after a restart as a different process the same key
+  is a new consumption and the already-consumed item returns `item_not_found`.
+
+## Idempotency
+
+The SDK generates the request ID and replays it across transport failures and
+app restarts; the platform credits a Sparks purchase once per provider
+transaction and debits a checkout once per request. Your only job is the
+`request_id:version` dedupe above, so a replayed signal does not show a
+message or play an effect twice.
+
+## Per-surface behaviour
+
+- **Summer Games app on iOS:** a native Summer sheet over the game. Sparks are
+  bought with Apple In-App Purchase only.
+- **Summer desktop app:** an overlay sheet; Sparks are paid with Stripe in the
+  browser, and the result returns to the game on the signal.
+- **Web:** the same sheet in the page, paid with Stripe.
+- **Editor play and local runs:** readiness is `unavailable`. Build the
+  unavailable path first.
+
+The game code is identical on every surface.
+
+## Testing
+
+- Test against Summer staging, which runs payments in sandbox mode: Stripe
+  sandbox cards on web and desktop, an Apple Sandbox tester account on iOS test
+  builds. *Why:* no real money moves and results are identical to production.
+- Walk every state: decline the sheet, let it expire, buy with too few
+  Sparks, buy Sparks, then buy the item. Kill the game while a payment is
+  pending and relaunch; the result must still arrive once.
+- Verify the unlock comes from `items.refreshed`, not from the checkout
+  signal.
+
+## Store policy notes
+
+- Apple requires In-App Purchase for digital goods and currency sold inside
+  iOS apps. Summer's iOS sheet handles this; never add your own payment links,
+  web prices or "cheaper on the web" text inside the game. *Why:* it can get
+  the Summer app removed from the App Store for every game.
+- Randomized paid rewards must disclose their odds before purchase (Apple and
+  most regions require it).
+- Say what a purchase gives in plain words next to the price.
+
+## Availability
+
+`request_checkout` ships today. `request_sparks_purchase` needs a Summer
+Engine and Summer app release that advertise `player.store.sparks_purchase@1`;
+until then `check_sparks_purchase_readiness()` reports `unavailable` and the
+example above falls back to "Get Sparks from the Summer app".
+
+## See also
+
+- multiplayer-state
+- ui-basics

package/library/skills/in-game-purchases/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/in-game-purchases
+kind: skill
+version: 1.0.0
+summary: "Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy."
+use_when:
+  - "adding a shop, buy button or paid item to a Summer game and wiring request_checkout"
+  - "a checkout was rejected with insufficient_funds and the player should be able to buy Sparks without leaving the game"
+  - "deciding whether an item should be sold for Sparks, or handling pending, declined, expired, rejected or manual_review purchase results"
+do_not_use_when:
+  - "designing multiplayer state ownership unrelated to purchases (use multiplayer-state)"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - gameplay
+    - scripting
+    - game-design
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer-state
+    - skill/ui-basics
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/instantiate-asset-pack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: instantiate-asset-pack
-description: Use when the user wants to import or spawn an entire asset pack (the multi-slice ArtAsset produced by `create-asset-sheet`) into the current scene — not a single slice, the whole pack. Reads the pack's per-slice metadata (zOrder, isComposite, parentSliceIndex, widget, bbox), groups composites, sorts children by paint order, and emits the Sprite2D / Node2D / NinePatchRect ops to lay it out correctly. Trigger on "import the X pack", "spawn the UI from pack Y", "bring in that asset sheet", "add the panel from the pack".
+description: "Import a whole create-asset-sheet pack into the scene: groups composites, sorts paint order, emits Sprite2D/Node2D/NinePatchRect ops to lay it out."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/investigating-bugs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: investigating-bugs
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: "Systematic investigation of any bug, test failure, or unexpected behavior before proposing fixes."
 ---
 
 # Systematic Debugging

package/library/skills/lumera-single-image-scene-reconstruction/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lumera-single-image-scene-reconstruction
-description: "Use when building a Lumera-style single-image → editable-engine-scene pipeline in SummerEngine: VLM-parsed object boxes and parametric lights, per-object meshes, HDR environment probe, engine-native assembly, and a bounded dual-agent refinement loop."
+description: "Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop."
 license: MIT
 category: art-pipeline
 tags:

package/library/skills/make-game/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: make-game
-description: "Use when the user says \"make me a game\", \"build me a game\", \"I want to make a [genre] game\", \"let's build something\" \u2014 the orchestration spine that runs the full game-dev pipeline: brainstorm \u2192 plan \u2192 scaffold \u2192 build core mechanics \u2192 art direction \u2192 audio \u2192 polish/VFX \u2192 verify \u2192 ship. Delegates to specialist skills with explicit checkpoints between phases. Trigger on \"make a game\", \"build me a game\", \"create a new game\", \"make me a game\", \"let's build a game\", \"I want to build [game shape]\"."
+description: "Orchestration spine for 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship — delegates to specialist skills."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -27,6 +27,28 @@ This is the skill that runs end-to-end when a user says "make me a game." It doe
 - User already has a working scaffold and wants to iterate → start at the relevant phase below, don't re-run the whole pipeline.
 - User says "I want to use a template" → run `browse-templates` first; come back here only if they decide they want a custom build instead.
 
+## Genre playbooks (`references/`)
+
+Distilled blueprints for common genres live in this skill's `references/` folder: architecture, scene tree, collision layers, core-loop code, build order, traps. Each genre is two files — a core file and a systems/polish file. Read the core file during Phase 2 (Plan) so the build plan follows its architecture and build order; read the systems file only when Phase 4 reaches those mechanics. Never load more than the one genre you are building.
+
+| Game | Core | Systems | Root / player / camera |
+|---|---|---|---|
+| Side-scrolling platformer | `references/2d-platformer.md` | `references/2d-platformer-polish.md` | Node2D / CharacterBody2D / Camera2D follow |
+| Horde survivors / bullet heaven | `references/2d-survivors.md` | `references/2d-survivors-progression.md` | Node2D / CharacterBody2D / Camera2D on player |
+| Top-down action RPG (also the base for puzzle, grid, tower defense) | `references/2d-rpg.md` | `references/2d-rpg-content.md` | Node2D / CharacterBody2D / Camera2D |
+| First-person shooter | `references/3d-fps.md` | `references/3d-fps-systems.md` | Node3D / CharacterBody3D / Camera3D on Head |
+| Third-person action / 3D platformer | `references/3d-third-person.md` | `references/3d-third-person-systems.md` | Node3D / CharacterBody3D / SpringArm3D |
+| First-person horror | `references/3d-horror.md` | `references/3d-horror-systems.md` | Node3D / CharacterBody3D / Camera3D on Head |
+
+No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `setup-multiplayer`.
+
+Two rules from the playbooks apply to every genre:
+
+- **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
+- **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
+- **Fast first draft when someone is waiting.** The first playable version uses shapes, the palette and any template art, plus at most one or two generated assets the person specifically asked for; generation takes minutes, so it never blocks the first play. Say plainly that it is a first draft to get a feel for the game, that the art is not final, and ask if this is the direction they want. Generate the rest of the art in later passes.
+- **Text the default font can show.** No emoji or symbols (▲ ◀ ★ ♥ ✓) in UI text: they render as boxes with hex codes. Use words or icons; see `ui-basics`.
+
 ## The Pipeline
 
 ```
@@ -153,7 +175,7 @@ For each mechanic in the plan, **in order**:
 
 2. **Implement**:
    - Add the nodes via `summer_add_node` / `summer_set_prop`. Use `scene-composition` if the structure is non-trivial.
-   - For movement-class mechanics, prefer the matching pre-built skill: `fps-controller`, `peer-to-peer-multiplayer`, etc.
+   - For movement-class mechanics, prefer the matching pre-built skill: `character-movement`, `fps-controller`, `multiplayer-movement`, etc. Follow the genre playbook's build order when one applies.
    - Write GDScript with `gdscript-patterns` open.
 
 3. **Verify**:
@@ -176,7 +198,7 @@ Repeat until every mechanic in the plan is implemented OR the user calls cut.
 Skill: art-direction
 ```
 
-That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work.
+That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work. If the game plays in the browser or is exported for the web, it runs the Compatibility renderer only: follow `web-compatibility-look` instead of Forward+-only features (SDFGI, SSAO, SSR, volumetric fog), and keep `rendering/renderer/rendering_method` on `gl_compatibility`.
 
 ```
 Skill: audio-direction