summer-engine 3.1.0 → 3.2.0

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

package/library/skills/make-game/references/2d-platformer-polish.md

@@ -0,0 +1,93 @@
+# 2D Platformer - Enemies, Hazards, Juice, Progression
+
+Add these only after the core loop (run/jump/goal/death) from `2d-platformer.md`
+feels good. Combat mechanics reuse the `combat-basics` skill.
+
+## Patrol enemy
+
+A `CharacterBody2D` that walks, turns at ledges/walls, and hurts on contact. Ledge
+detection via a downward `RayCast2D` at the front foot.
+
+```gdscript
+extends CharacterBody2D
+@export var speed: float = 60.0
+var dir: float = 1.0
+var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")
+@onready var ledge: RayCast2D = $LedgeCheck   # points down, ahead of feet
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y += gravity * delta
+	if is_on_wall() or (is_on_floor() and not ledge.is_colliding()):
+		dir *= -1.0
+		ledge.position.x *= -1.0
+		$Sprite2D.flip_h = dir < 0.0
+	velocity.x = dir * speed
+	move_and_slide()
+```
+
+Give it a hurtbox (masks PlayerHurtbox) and a Health node from `combat-basics`.
+
+## Stomp-to-kill
+
+The classic platformer verb. A separate Area2D under the player masking only the
+Enemies layer; on overlap, kill the enemy and bounce the player.
+
+```gdscript
+# in player, StompArea (Area2D) child
+func _on_stomp_body_entered(enemy: Node) -> void:
+	if velocity.y > 0.0 and enemy.has_method("die"):
+		enemy.die()
+		velocity.y = jump_velocity * 0.7   # bounce
+```
+
+Falling (`velocity.y > 0`) distinguishes a stomp from a side hit that should damage
+the player instead.
+
+## Hazards
+
+- Spikes/lava: an Area2D on the Triggers layer that calls `player.die()`.
+- Bounce pad: Area2D that sets `player.velocity.y = -launch_force` on enter.
+- Bottomless pit: one wide killzone under the level.
+
+## Juice (the difference between prototype and game)
+
+Route through a small helper so every hit feels alive:
+
+- Hit flash: `modulate` to white, tween back over 0.06s.
+- Screen shake: offset the Camera2D by decaying random noise for ~0.2s.
+- Hitstop: `Engine.time_scale = 0.05` for one frame on a kill, then back to 1.0.
+- Floating text: spawn a Label that rises and fades on coin/hit.
+- Squash/stretch: tween the sprite `scale` to (1.2, 0.8) on land, back over 0.1s.
+- Dust particles on land and on turn.
+
+A silent, still platformer fails the 30-second bar even if every system works.
+
+## Progression: coins, gems, and a level goal
+
+- Coins increment `GameManager.score`; emit `score_changed` for the HUD.
+- A `level_end` Area2D (flag/door) triggers the level-complete screen with time and
+  coin count, then advances to the next room `.tscn`.
+- Save unlocked rooms + best times via the `save-load` skill.
+
+## Metroidvania gating (optional)
+
+For an interconnected map with ability gates:
+
+- `AbilityManager` autoload: `unlocked: Dictionary`, `has(name)`, `unlock(name)`.
+- Ability pickup: Area2D that calls `AbilityManager.unlock("double_jump")`.
+- Ability gate: a wall/door that only opens if `AbilityManager.has("dash")`, or a
+  ledge only reachable with double jump.
+- The player controller checks `AbilityManager.has("double_jump")` before allowing
+  a second air jump, `has("dash")` before a dash, etc.
+
+Keep gating data-driven: one place lists what each ability unlocks, so designers
+tune it without touching the controller.
+
+## Traps
+
+- Enemies as RigidBody2D fight the player physically; use CharacterBody2D or Area2D.
+- Stomp check without a `velocity.y > 0` guard kills enemies on any touch.
+- Ledge raycast that does not flip with direction walks enemies off cliffs.
+- Piling on juice at once (shake + hitstop + flash on every coin) reads as noise;
+  reserve the big feedback for kills and damage, keep coins light.

package/library/skills/make-game/references/2d-platformer.md

@@ -0,0 +1,117 @@
+# 2D Platformer - Core
+
+Side-scrolling platformer blueprint: architecture, the level, and the core loop.
+Movement itself lives in the `character-movement` skill (base controller) and its
+`../../character-movement/references/platformer-feel.md` (coyote time, jump buffer, variable height) - do
+not rewrite it here; wire it in. For Celeste-grade precision movement (dash, wall
+jump, climb) use `celeste-momentum-platforming` instead.
+
+## Minimum playable base (build this first)
+
+Scene first (the make-game Scaffold phase): `main.tscn` with a Node2D root, a ground `StaticBody2D`
+with a `CollisionShape2D`, the player, and a `Camera2D` child of the player. Prove
+run + jump + land before anything else. Placeholder art is a colored
+`ColorRect`/`Sprite2D`.
+
+## Architecture (grows into a full game)
+
+```
+res://
+  scenes/
+    player/player.tscn
+    rooms/room_01.tscn        # one .tscn per room/level
+    enemies/patrol_enemy.tscn
+    ui/{hud,pause_menu,main_menu,game_over}.tscn
+  scripts/
+    autoloads/
+      event_bus.gd            # global signals, decouples systems
+      game_manager.gd         # score, lives, current room, checkpoint
+      audio_manager.gd        # pooled SFX + music
+      save_manager.gd
+    player/player_controller.gd
+    systems/{coin,checkpoint,killzone,moving_platform,one_way_platform,
+             crumbling_platform,bounce_pad,door,level_end}.gd
+```
+
+Add autoloads only once the base loop works. Register in Project Settings in
+dependency order: EventBus first (others reference it), then GameManager, then the
+rest. All autoloads `process_mode = ALWAYS` so they survive pause.
+
+## Collision layers (set names in Project Settings)
+
+| Layer | Name | Used by |
+|-------|------|---------|
+| 1 | World | TileMap, static platforms |
+| 2 | Player | Player body |
+| 3 | Enemies | Enemy bodies |
+| 4 | PlayerHitbox | Sword/stomp hit area |
+| 5 | EnemyHitbox | Enemy hit area |
+| 6 | PlayerHurtbox | Player hurt area |
+| 7 | EnemyHurtbox | Enemy hurt area |
+| 8 | Collectibles | Coins, gems |
+| 9 | Triggers | Doors, killzones, checkpoints |
+
+Hitboxes mask the OPPOSING hurtbox (see the `combat-basics` skill). The stomp detector is a
+separate Area under the player masking only the Enemies layer.
+
+## Building the level with a TileMap
+
+Use a `TileMapLayer` (Godot 4.3+) for the solid world. Create a `TileSet`, paint
+the collision polygon on the solid tiles, put the layer on the World collision
+layer. The player collides with it for free - no per-tile StaticBody.
+
+- One `TileMapLayer` for collidable terrain, a second (no collision, lower
+  z-index) for background decoration.
+- For large levels, split into room `.tscn`s and load the current room via a
+  RoomManager; connect doors to `change_scene_to_file` or swap room instances.
+- Parallax background: `Parallax2D` (or ParallaxBackground) layers with
+  `motion_scale` < 1 so distant layers move slower.
+
+## Moving, one-way, and crumbling platforms
+
+These three cover most platformer level tech.
+
+```gdscript
+# moving_platform.gd - AnimatableBody2D so riders move with it
+extends AnimatableBody2D
+@export var offset: Vector2 = Vector2(200, 0)
+@export var duration: float = 2.0
+func _ready() -> void:
+	var t := create_tween().set_loops().set_trans(Tween.TRANS_SINE)
+	t.tween_property(self, "position", position + offset, duration)
+	t.tween_property(self, "position", position, duration)
+```
+
+Use `AnimatableBody2D` (not StaticBody2D) for movers - it carries the player. For
+one-way platforms, enable `one_way_collision` on the platform's CollisionShape2D
+so the player jumps up through and lands on top. Crumbling platform: on
+`body_entered`, start a short timer, shake, then disable collision and fade out;
+re-enable after a respawn delay.
+
+## Checkpoints and death
+
+```gdscript
+# checkpoint.gd
+extends Area2D
+func _ready() -> void:
+	body_entered.connect(func(b):
+		if b.is_in_group("player"):
+			GameManager.checkpoint = global_position)
+
+# killzone.gd - fall/spike death
+extends Area2D
+func _ready() -> void:
+	body_entered.connect(func(b):
+		if b.is_in_group("player"):
+			b.die())   # player respawns at GameManager.checkpoint
+```
+
+## Core loop checklist (the 30-second bar)
+
+- Run + jump feels good (tuned gravity/fall multiplier, coyote + buffer).
+- Coins/goal give immediate feedback: sound + pop tween + counter tick.
+- Death is instant and respawns at the last checkpoint, no long reload.
+- A visible goal (flag/door) ends the level with a clear result.
+
+Enemies, hazards, juice, and metroidvania progression are in
+`2d-platformer-polish.md`.