summer-engine 3.0.0 → 3.2.0

package/library/skills/make-game/references/3d-third-person-systems.md

@@ -0,0 +1,220 @@
+# 3D Third-Person - Systems
+
+The combat and content layer on top of `3d-third-person.md`: melee, bullets,
+grenade with arc preview, two enemy archetypes, coins, destructible boxes,
+and the HUD.
+
+## Shared damage interface
+
+Everything hittable (player, enemies, boxes) implements:
+
+```gdscript
+func damage(impact_point: Vector3, force: Vector3) -> void
+```
+
+and joins the "damageables" group. `impact_point` is
+`global_position - body.global_position` (direction from body to impact),
+`force` is the knockback vector. Enemies additionally join "targeteables"
+for grenade lock-on. One interface, three weapons, all content - keep it.
+
+## Weapons
+
+Tab toggles DEFAULT and GRENADE (a `weapon_switched` signal drives the HUD
+icons). DEFAULT: left-click = melee from the hip, aim (RMB) + left-click =
+ranged shot with over-shoulder camera + crosshair. GRENADE: left-click
+throws with a live arc preview.
+
+### Melee (animation-gated hitbox)
+
+The MeleeAttackArea's CollisionShape3D starts disabled. The "Attack"
+animation (0.3-0.5s) has method-call tracks: `activate()` at the impact
+frame (~0.15s), `deactivate()` at the end. The area's `body_entered` damages
+"damageables" with force pointing away from the player. Player side:
+`attack()` plays the animation, fires the skin's punch OneShot, and sets
+`velocity = rotation_root.basis * Vector3.BACK * attack_impulse` (forward
+lunge). Movement is locked while the attack animation plays.
+
+Animation-gated hitboxes beat timer-gated ones: the active window is
+authored visually next to the swing frames.
+
+### Bullet (shared by player AND enemies)
+
+Node3D moved manually in `_process` - no physics body:
+
+```gdscript
+func _ready() -> void:
+	_area.body_entered.connect(_on_body_entered)
+	look_at(global_position + velocity)
+	_alive_limit = distance_limit / velocity.length()
+
+func _process(delta: float) -> void:
+	global_position += velocity * delta
+	_time_alive += delta
+	_bullet_visuals.scale = Vector3.ONE * scale_decay.sample(_time_alive / _alive_limit)
+	if _time_alive > _alive_limit:
+		queue_free()
+
+func _on_body_entered(body: Node3D) -> void:
+	if body == shooter:
+		return
+	if body.is_in_group("damageables"):
+		body.damage(global_position - body.global_position, velocity)
+	queue_free()
+```
+
+The `shooter` reference prevents self-hits, which is what lets one bullet
+scene serve both sides. Distance limit expressed as time
+(`distance / speed`); visual scale decays via an exported Curve so bullets
+fade with range. Player shots originate at `global_position + Vector3.UP`
+and fly toward `camera_controller.get_aim_target()`.
+
+Fast projectiles tunnel through thin walls: keep speeds moderate (player
+10, enemies 6) or fatten the Area3D shape.
+
+### Grenade launcher (arc preview + lock-on)
+
+While GRENADE is equipped the launcher is visible and every physics frame:
+camera tilt lerps throw distance between min 7 and max 16; a ShapeCast3D
+finds the landing point; if the cast hits a "targeteables" body, the landing
+snaps to that enemy (lock-on, SnapMesh indicator); initial velocity
+decomposes into vertical `sqrt(2 * gravity * peak_height)` and horizontal
+`distance / time_to_land`; the preview trail is a triangle-strip mesh built
+with SurfaceTool sampling the parabola at 0.05s steps.
+
+The grenade itself is a CharacterBody3D using `move_and_collide` (NOT
+move_and_slide) so it can bounce:
+
+```gdscript
+func _physics_process(delta) -> void:
+	_velocity += Vector3.DOWN * gravity * delta
+	var collision := move_and_collide(_velocity * delta)
+	if collision:
+		_velocity = _velocity.bounce(collision.get_normal(0)) * 0.7
+		if _explosion_start_timer.is_stopped():
+			_explosion_start_timer.start()
+```
+
+First bounce arms the fuse timer. Explosion: damage all overlapping
+"damageables" in the ExplosionArea EXCEPT the Player (`not body is Player` -
+self-immunity), spawn explosion visuals, hide, await the sound, free. On
+throw, add a collision exception between grenade and thrower via
+`PhysicsServer3D.body_add_collision_exception`.
+
+## Enemies
+
+Both are RigidBody3D with a PlayerDetectionArea (big sphere Area3D), a
+reaction label ("!" / "?" animations on detect/lose), and the same death
+choreography: play defeat sound, set `_alive = false`, DISCONNECT the
+detection signals (dead enemies must not react), enable the death collider,
+enable gravity so the body drops, wait 2s, spawn a smoke puff, `await
+puff.full`, burst coins out of the smoke, `queue_free()`.
+
+The smoke puff emits `full` from an animation keyframe at peak opacity -
+awaiting it makes coins appear to burst out of the cloud instead of
+clipping through a half-formed puff.
+
+### Bee bot (flying turret)
+
+RigidBody3D with `gravity_scale = 0` (floats). While a target is set:
+
+```gdscript
+var target_transform := transform.looking_at(_target.global_position)
+transform = transform.interpolate_with(target_transform, 0.1)
+```
+
+Fires the SAME bullet scene as the player every 1.5s at speed 6, aimed at
+`target.global_position + Vector3.UP`. `damage()` applies an impulse
+(clamped length 3) then runs the death choreography; gravity_scale flips to
+1.0 so it falls out of the air.
+
+### Beetle bot (NavigationAgent3D chaser)
+
+RigidBody3D with rotation axes locked (rigid until death). Chase loop:
+
+```gdscript
+_navigation_agent.target_position = _target.global_position
+var next := _navigation_agent.get_next_path_position()
+if not _navigation_agent.is_target_reached():
+	var direction := (next - global_position)
+	direction.y = 0                      # never dive/fly
+	direction = direction.normalized()
+	var collision := move_and_collide(direction * delta * 3)
+	if collision and collision.get_collider() is Player:
+		var force := -(global_position - collider.global_position)
+		force.y = 0.5
+		collider.damage(impact_point, force * 10.0)
+		_beetle_skin.attack()
+```
+
+`look_at` the target with Y flattened to its own height. On death, unlock
+all angular axes so the corpse tumbles.
+
+Navigation requirements: the level MUST have a baked NavigationRegion3D or
+the beetle stands still forever; the target must be reachable on the
+navmesh; always zero the Y of path directions.
+
+Enemy skins: AnimationTree state machines (Idle/Walk/Attack/Shake/PowerOff)
+with a secondary-action timer firing random idle shakes every 3-8s;
+`power_off()` stops that timer.
+
+## Coins
+
+RigidBody3D collectible, either placed in the level or scattered by
+`spawn()` (random impulse: direction rotated randomly around UP, range 2-4,
+height 1-3). Collection is DELAYED: layer 3 collision is off for
+`coin_delay` (0.5s default, 1.5s when the player drops them) so coins from
+a kill do not vacuum back instantly.
+
+Magnet: when the player enters the coin's detection area (mask = Player
+layer 4), freeze physics and tween to the player:
+
+```gdscript
+func set_target(new_target: PhysicsBody3D) -> void:
+	PhysicsServer3D.body_add_collision_exception(get_rid(), new_target.get_rid())
+	if _target == null:
+		sleeping = true
+		freeze = true
+		_initial_tween_position = global_position
+		_target = new_target
+		var tween := create_tween()
+		tween.tween_method(_follow, 0.0, 1.0, 0.5)   # lerp start -> player
+		tween.tween_callback(_collect)
+```
+
+`_follow` lerps from the captured start to the LIVE player position, so the
+coin homes even while the player runs. Collect: random-pitch sound,
+`player.collect_coin()`, hide, await audio, free. Coin model: spin
+`rotation.y += 1.5 * delta`, bob `sin(t) * 0.04`.
+
+## Destructible boxes
+
+`damage()` on the box: spawn 5 coins with `spawn()`, instantiate a
+pre-fractured debris scene, disable own collision (deferred), play sound,
+await it, free. Debris scene = 6 hidden frozen RigidBody3D pieces; on ready,
+shuffle and launch 3 random ones with `apply_force(rand_vector * 500)`,
+leave the rest hidden. Half-count random debris looks as good as full
+simulation at a fraction of the cost.
+
+## HUD
+
+```
+UI (CanvasLayer)
+  AimRecticle (%unique, ColorRect centered)   # visible only while aiming
+  CoinsContainer (%unique, HBoxContainer)     # slides in on change
+    CoinIcon + CoinsLabel + Timer
+  WeaponUI (PanelContainer)                   # Flash / Grenade icons
+```
+
+Coin counter: slides from y -100 to y 20 on `update_coins_amount`, restarts
+its display timer per change, slides back out on timeout. Weapon icons:
+inactive at alpha 0.2, tween to full white on select; `switch_to()` guards
+against reselecting the current one. Use unique names (%) so the deep
+player script reaches UI without brittle paths.
+
+## Order of work
+
+1. Melee: attack animation + gated hitbox + a destructible box to punch.
+2. Coins with magnet + HUD counter (the reward loop).
+3. Aim mode: over-shoulder pivot + crosshair + bullet.
+4. Bee bot (reuses your bullet), then beetle bot (navmesh required).
+5. Grenade launcher last - arc preview, lock-on, explosion.

package/library/skills/make-game/references/3d-third-person.md

@@ -0,0 +1,215 @@
+# 3D Third-Person - Core
+
+Third-person action blueprint: camera-relative movement, orbit camera with
+SpringArm3D and over-shoulder aim pivot, animation-driven character skin, and
+level assembly. Combat, enemies, collectibles, and HUD live in
+`3d-third-person-systems.md`.
+
+## Minimum playable base (build this first)
+
+Level (CSG floor + light + WorldEnvironment) + player capsule with
+camera-relative WASD, orbit camera on a SpringArm3D, and jump. Prove "run
+around, camera orbits, no wall clipping" before combat exists.
+
+## Player scene tree
+
+```
+Player (CharacterBody3D)
+  CharacterRotationRoot (Node3D)      # model rotation lives here, not on body
+    CharacterSkin (Node3D)            # mesh + AnimationTree
+    MeleeAnchor (Node3D)
+      AnimationPlayer                 # "Attack" anim toggles hitbox
+      MeleeAttackArea (Area3D + CollisionShape3D, disabled)
+  CameraController (Node3D)           # follows via code, NOT rigid parenting
+    CameraSpringArm (SpringArm3D)
+      CameraThirdPersonPivot (Node3D)
+    CameraOverShoulderPivot (Node3D)  # right + closer, for aiming
+    PlayerCamera (Camera3D)
+      CameraRayCast (RayCast3D, target (0,0,-100))  # aim target
+  GrenadeLauncher (Node3D)            # LaunchPoint, ShapeCast3D, TrailMesh
+  GroundShapeCast (ShapeCast3D, down) # ground height for camera
+  StepSound / LandingSound (AudioStreamPlayer3D)
+  UI (CanvasLayer)                    # %AimRecticle, %CoinsContainer, WeaponUI
+```
+
+Physics layers: 1 Entities, 2 Level, 3 Coins, 4 Player. Groups: "damageables"
+(anything with `damage()`), "targeteables" (grenade lock-on).
+
+Input: move_up/down/left/right, jump (Space, hold for air boost), attack
+(LMB / RT), aim (RMB / LT), swap_weapons (Tab), pause, camera_left/right/up/
+down (QERF keyboard fallback + right stick). The player script can
+auto-register missing actions at runtime via `InputMap.add_action` so the
+scene works when dropped into a bare project.
+
+## Controller: the decisions that matter
+
+Tuning baseline: move_speed 8.0, acceleration 4.0, rotation_speed 12.0,
+jump_initial_impulse 12.0, jump_additional_force 4.5 (held-jump air boost),
+attack_impulse 10.0, gravity -30.0 (deliberately NOT project default;
+project gravity 16 is too floaty for 3D platforming - tune independently).
+
+Camera-relative input with diagonal correction:
+
+```gdscript
+func _get_camera_oriented_input() -> Vector3:
+	if _attack_animation_player.is_playing():
+		return Vector3.ZERO                # attacking locks movement
+	var raw := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+	var input := Vector3.ZERO
+	input.x = -raw.x * sqrt(1.0 - raw.y * raw.y / 2.0)   # no faster diagonals
+	input.z = -raw.y * sqrt(1.0 - raw.x * raw.x / 2.0)
+	input = _camera_controller.global_transform.basis * input
+	input.y = 0.0
+	return input
+```
+
+Last strong direction - the model holds its facing when input stops instead
+of snapping to zero; while aiming it faces camera-forward:
+
+```gdscript
+if _move_direction.length() > 0.2:
+	_last_strong_direction = _move_direction.normalized()
+if is_aiming:
+	_last_strong_direction = (_camera_controller.global_transform.basis * Vector3.BACK).normalized()
+```
+
+Orientation slerps `CharacterRotationRoot` (never the body) toward that
+direction at rotation_speed, preserving model scale.
+
+Velocity: split Y off before lerping so gravity is never interpolated:
+
+```gdscript
+var y_velocity := velocity.y
+velocity.y = 0.0
+velocity = velocity.lerp(_move_direction * move_speed, acceleration * delta)
+if _move_direction.length() == 0 and velocity.length() < stopping_speed:
+	velocity = Vector3.ZERO
+velocity.y = y_velocity
+```
+
+Jump: impulse on press, plus `jump_additional_force * delta` while jump is
+held and still rising (variable height). Track `_is_on_floor_buffer` to
+detect the landing frame for the landing sound.
+
+Unstick hack after `move_and_slide()`: if velocity is nonzero but position
+did not change (wedged in geometry), nudge
+`global_position += get_wall_normal() * 0.1`.
+
+`damage(impact_point, force)` on the player: force.y forced positive (always
+tossed upward), clamped by max_throwback_force 15, drops up to 5 coins that
+scatter for re-collection.
+
+## Camera system
+
+Two pivots, one camera. `CameraThirdPersonPivot` sits at the end of the
+SpringArm3D (behind and above). `CameraOverShoulderPivot` is a plain Node3D
+offset right and closer (about x 1.0, y 0.5, z -2.0). Aiming switches pivots
+via `set_pivot()`; each `_process` the camera copies the active pivot's
+global transform and zeroes `rotation.z`.
+
+- Orbit uses accumulated euler angles from mouse (`_unhandled_input`, only
+  while mouse captured) plus joystick strength added in `_process`; inputs
+  are consumed and zeroed every frame. Tilt clamped -60..60 deg. Never
+  `look_at()` per frame - it jitters.
+- SpringArm3D handles wall avoidance for free, but MUST exclude the player:
+  `_camera_spring_arm.add_excluded_object(anchor.get_rid())` and
+  `_camera_raycast.add_exception_rid(anchor.get_rid())` in `setup()`.
+- Ground-height tracking: camera Y lerps toward the player's
+  `_ground_height` (from GroundShapeCast), not the player's Y - so jumps do
+  not bounce the camera. The player computes `_ground_height` as the max
+  collision point of the downward ShapeCast, clamped to its own Y when
+  falling below it.
+- Aim target: CameraRayCast collision point (or the ray end if no hit) is
+  what bullets fly toward and what the grenade locks onto -
+  `get_aim_target()` / `get_aim_collider()`.
+
+## Character skin (AnimationTree)
+
+If the visual is a Summer humanoid package, do not use the generic setup below.
+Instantiate its `character.tscn` under `CharacterRotationRoot`, preserve the package's
+normalized `-Z` forward axis, then install the `character-movement` skill's
+`../../character-movement/references/default-third-person-controller.gd` unchanged for the standard
+playable controller (that skill has the byte-exact install steps and the
+verification probe). Do not hand-write an equivalent controller. Never rebuild package clips
+into a second AnimationTree.
+
+The generic setup below is only for non-package character skins that already expose
+compatible animations.
+
+BlendTree root: a StateMachine (idle / move / jump / fall, where move is a
+BlendSpace1D walk-run blended by normalized speed) plus a PunchOneShot
+(AnimationNodeOneShot) layered on top so punches play over any state.
+
+```gdscript
+func set_moving(value: bool):      # SETTER - travel only on change
+	moving = value
+	state_machine.travel("move" if moving else "idle")
+
+func punch():
+	animation_tree["parameters/PunchOneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
+```
+
+Driving rules from the player: `jump()` on jump press, `fall()` when
+`not is_on_floor() and velocity.y < 0`, `set_moving(xz_speed > stopping_speed)`
+plus `set_moving_speed(inverse_lerp(0, move_speed, xz_speed))` on the floor.
+
+Footsteps: a `stepped` signal emitted from method-call keyframes in the
+walk/run animations; player plays the step sound with `randfn(1.2, 0.2)`
+pitch. Free audio sync, no timers.
+
+`animation_tree.active = true` in `_ready()` or nothing plays. Imported
+animations often default to non-looping: keep a `_force_loop` export array
+and set `loop_mode = Animation.LOOP_LINEAR` on those at runtime.
+
+## Level assembly
+
+Check for real assets first (`asset-strategy`: `summer_search_assets`, then
+`summer_import_asset`): a ready location or kit beats CSG. Keep CSG for the
+first-motion blockout, invisible glue (death planes, triggers) and pieces no
+asset covers — do not ship a grey-box level when a real one is available.
+
+- WorldEnvironment: sky background (ProceduralSkyMaterial), ACES tonemap
+  (`tonemap_mode = 2`), glow enabled. Without WorldEnvironment everything
+  is flat and dark.
+- DirectionalLight3D angled ~45 deg, `shadow_enabled = true` (off by
+  default; without shadows objects float).
+- Geometry: CSGCombiner3D with `use_collision = true`, CSGBox3D/
+  CSGCylinder3D children; boolean subtraction (operation 2) for tunnels.
+  Materials with `uv1_triplanar = true` so textures map on any face.
+- DeathPlane: big Area3D at y -20; `body_entered` on the Player calls
+  `reset_position()` (respawn at `_start_position` captured in `_ready`).
+- Jump pad: Area3D setting
+  `body.velocity = Vector3.UP * body.jump_initial_impulse + transform.basis * Vector3.UP * impulse_strength`
+  (basis-relative so rotated pads launch at angles) + squash-and-elastic
+  rebound tween on the mesh.
+- Project: 1920x1080, stretch canvas_items / keep_height.
+- Pause menu node needs `process_mode = ALWAYS` and must flip mouse mode
+  between CAPTURED (gameplay) and VISIBLE (menu).
+
+## Build order
+
+1. Project settings + input actions + layer names.
+2. Player scene tree above; movement + jump with a placeholder capsule.
+3. CameraController: spring arm orbit, then over-shoulder aim pivot.
+4. CharacterSkin AnimationTree once movement feels right.
+5. Level: imported location/props (`asset-strategy`) where they fit;
+   CSG floor/platforms only as blockout or for missing pieces; light,
+   environment, death plane, jump pad.
+6. Combat + enemies + coins (`3d-third-person-systems.md`).
+
+## Traps
+
+- Parenting the camera rigidly to the player - it inherits every rotation
+  and nauseates. Follow via code with offset + lerp.
+- Skipping SpringArm3D (camera clips walls) or forgetting to exclude the
+  player's RID from it (camera collides with the player).
+- `look_at()` every frame for camera or `state_machine.travel()` every
+  frame for animation - both jitter/reset; only act on change.
+- Scaling the CharacterBody3D itself - scale the mesh under
+  CharacterRotationRoot. Physics on scaled bodies misbehaves.
+- 1 unit = 1 meter. Characters are 1-2 units tall; extreme scales break
+  physics and lighting.
+- Toggling CollisionShape3D `disabled` directly inside physics callbacks -
+  always `set_deferred("disabled", ...)`.
+- Low gravity. -30 for the player feels right; project-default 16 is
+  floaty. Tune player gravity independently of the physics setting.

package/library/skills/make-game/resource.yaml

@@ -1,10 +1,11 @@
 id: skill/make-game
 kind: skill
-version: 1.0.3
+version: 1.1.0
 summary: "Orchestration spine for 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship — delegates to specialist skills."
 use_when:
   - the user says 'make me a game', 'build me a game', 'I want to make a [genre] game', or 'let's build something' — running the full game-dev pipeline
   - the user wants a complete playable game end to end, from brainstorm through shipping
+  - the user names a genre — platformer, survivors, top-down RPG, FPS, third-person, horror — and the build needs its architecture and build order
 facets:
   lifecycle:
     - build
@@ -27,6 +28,10 @@ related:
     - skill/new-project
     - skill/play
     - skill/scene-composition
+    - skill/character-movement
+    - skill/camera-rigs
+    - skill/combat-basics
+    - skill/save-load
 source: official
 license: MIT
 status: stable

package/library/skills/multiplayer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: multiplayer
+description: "Start here for Summer multiplayer: how the authority, clients, Worlds and Sessions fit, and which skill comes next."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Glob summer_get_scene_tree summer_get_script_errors summer_project_setting
+paths: ["**/*.gd", "**/*.tscn", "project.godot", "summer.build.json", "world.json"]
+---
+
+# /multiplayer — how Summer multiplayer works
+
+Read this first, whatever the user asked for: "multiplayer", "co-op", "PvP",
+"online", "play with friends", "lobby", "peer-to-peer", "host a game",
+"netcode", "sync players". It explains the model in one page and sends you to
+the skill that builds the next piece.
+
+## The picture
+
+A Summer multiplayer game is **one project with two entry scenes**:
+
+- the **client** scene, which every player runs: input, camera, visuals, UI;
+- the **authority** scene, which runs headless as the match server and owns
+  the rules.
+
+```text
+   each player's device                   Summer hosting (or Local Play)
+  ┌──────────────────────┐  my pose       ┌──────────────────────────────┐
+  │ client scene         │ ─────────────► │ authority scene = one World  │
+  │ moves its own player │  "collect"     │ checks every pose and request│
+  │ draws everyone else  │ ─────────────► │ owns score, doors, items...  │
+  │                      │ ◄───────────── │                              │
+  └──────────────────────┘  state, events └──────────────────────────────┘
+```
+
+- A running match is a **World**. Summer starts one authority for it; the game
+  declares what a World is in `world.json` (a **WorldDefinition**).
+- A player joins with `Summer.client.join(...)` and gets a verified
+  **Session**: their seat in that World, with a verified player identity.
+- Players find a World through a **queue** in `summer.build.json`. Hosted,
+  Summer's matchmaking fills it; locally, **Local Play** starts the authority
+  and N clients on your machine.
+- The same code runs locally and hosted. No `if server`, no local-only
+  branches, no IP addresses.
+
+There is no player-hosted server, so there is no host migration, and a player
+quitting never ends the match for the others.
+
+## How data moves
+
+Both sides load one **network composition** (`network/composition.tres`). It
+declares every stream the game uses, and a **Spawner** node attaches it to the
+World:
+
+| You want | Use | Who writes it | Skill |
+|---|---|---|---|
+| My character moves | Owner-written State group, one per player | that player's client; the authority checks each pose | `multiplayer-movement` |
+| Everyone sees the score, a door, the round timer | Authority-written State group, World audience | the authority | `multiplayer-state` |
+| Only I see my wallet, hand, inventory | Authority-written State group, target-Session audience | the authority | `multiplayer-state` |
+| A player wants to buy, open, collect, ready up | Command | client asks, authority accepts or refuses | `multiplayer-state` |
+| A one-off effect (sparkle, sound, hit flash) | Event | the authority | `multiplayer-state` |
+
+State is retained, so a late joiner gets the current value. Commands carry
+the sender's verified Session. Events are fire-and-forget.
+
+## The rules
+
+1. **Each client moves its own character.** Movement feels instant on every
+   connection. The authority accepts or refuses each pose, and a refused pose
+   snaps the player back.
+2. **The authority owns every other fact.** Clients never change shared
+   state; they send a Command and show the result.
+3. **Identity comes from the Session**, never from a field a client sent.
+4. **Never use the stock high-level multiplayer API in a Summer game:** no
+   `@rpc`, `MultiplayerSynchronizer`, `MultiplayerSpawner`,
+   `ENetMultiplayerPeer`, `multiplayer.is_server()` or peer-ID branches. Their
+   sender ids are transport peers, not verified players. Late joiners miss
+   state, and the game cannot use Summer hosting, matchmaking or identity.
+5. **Test under a bad network before calling anything done:** Local Play
+   with latency, jitter and loss (`multiplayer-testing`).
+
+## Words
+
+| Word | Meaning |
+|---|---|
+| Game | Your game on Summer; its id is `gameId` in `summer.build.json` and the argument to `Summer.initialize` |
+| World | One running match or shared place, simulated by one authority |
+| WorldDefinition | `world.json`: which scenes run the client and the authority, lifetime, persistence |
+| Queue | How players find a World; declared in `summer.build.json` |
+| Session | One player's verified seat in a World |
+| Composition | The network contract both sides load: State streams, Command and Event streams |
+| State group | One retained value (a pose, a scoreboard); one writer, an audience |
+| Command | A request from a client, answered by the authority |
+| Event | A one-off message from the authority |
+| Local Play | Runs the authority and N clients locally, with optional network emulation |
+
+## Build it in this order
+
+Each skill continues the same small game, so their code fits together:
+
+1. **`multiplayer-project`**: the files, both entry scenes, joining, and a
+   first Local Play run.
+2. **`multiplayer-movement`**: each player moves their own character; others
+   see it smoothly; the authority checks every pose.
+3. **`multiplayer-state`**: score, doors, private inventories, Commands and
+   Events.
+4. **`multiplayer-testing`**: Local Play under latency and loss, bots, and
+   what a passing run must show.
+5. **`multiplayer-publish`**: export the summer.games bundle and upload it as
+   a Build.
+
+## Add Summer services
+
+| Skill | What it adds | Works in Local Play? |
+|---|---|---|
+| `summer-matchmaking` | Queues, match sizes, teams, the accept prompt, join failures | Yes, without the accept prompt |
+| `summer-match-results` | Ending a match: winners, losers, rating changes | Yes |
+| `summer-leaderboards` | Ratings and Game-wide leaderboards | Partly; reading boards needs hosting |
+| `summer-parties` | Friends queue together as a party | No, hosted only |
+| `summer-friends` | The player's Summer friends and direct messages | No, hosted only |
+| `summer-player-data` | Progress that follows the player to any World | Yes, stored on disk |
+| `summer-world-saves` | Worlds that persist between sessions | Yes, in memory |
+| `summer-world-chat` | Text chat inside a World | No, hosted only |
+| `summer-store` | Selling items for Sparks, owned items | Items yes; the store is hosted only |
+| `summer-analytics` | Game events for your analytics dashboard | No, hosted only |
+
+## What people ask for, and what Summer does
+
+| They ask for | On Summer |
+|---|---|
+| "One player hosts", peer-to-peer | A headless authority per match, started by Summer or by Local Play |
+| Host migration | Not needed: no player is the authority |
+| Join by IP, invite code, server browser | Not available. Players join a queue; friends join as a party (`summer-parties`) |
+| A lobby | A queue with `minPlayers`/`maxPlayers` and an accept prompt (`summer-matchmaking`) |
+| "Sync the player's position" | An owner-written pose group (`multiplayer-movement`) |
+| "Tell everyone the door opened" | An authority-written State group (`multiplayer-state`) |
+| "The client asks the host to buy something" | A Command validated with the verified Session (`multiplayer-state`) |
+| Save progress | Player data for the player, World saves for the place (`summer-player-data`, `summer-world-saves`) |
+
+## Start
+
+Check what exists: `summer.build.json`, `world.json`, `network/`,
+`authority/`, `client/`.
+
+- **None of them:** start with `multiplayer-project`.
+- **They exist:** pick the skill for the piece you need from the tables above.
+- **The game already uses `@rpc` or `MultiplayerSynchronizer`:** tell the user
+  it needs moving to Summer's networking. Then follow `multiplayer-project`
+  and port one system at a time: movement first, then state.

package/library/skills/multiplayer/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/multiplayer
+kind: skill
+version: 1.0.0
+summary: "Start here for Summer multiplayer: how the authority, clients, Worlds and Sessions fit, and which skill comes next."
+use_when:
+  - "the user wants multiplayer, co-op, PvP, online play over the internet, or to play with friends in a Summer game"
+  - "the user asks for peer-to-peer, a player-hosted server, host migration, join-by-IP or a lobby"
+  - "deciding how a multiplayer Summer game is structured before writing networking code"
+  - "a multiplayer game was built with @rpc or MultiplayerSynchronizer and needs moving to Summer's networking"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - project
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/multiplayer-project
+    - skill/multiplayer-movement
+    - skill/multiplayer-state
+    - skill/multiplayer-testing
+    - skill/multiplayer-publish
+    - skill/summer-matchmaking
+    - skill/summer-player-data
+source: official
+license: MIT
+status: stable
+recommended: true