summer-engine 3.1.0 → 3.2.0

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