summer-engine 1.3.1 → 1.3.2

package/skills/level-design/design-level/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: design-level
+description: Use when designing a single level — layout, pacing, encounters, secrets, reward gating. Outputs a level design doc and a concrete node-tree skeleton for `summer_create_scene`. Trigger on "design a level", "design level 1", "tutorial level", "boss arena", "design the encounter", "make a level layout".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: level-design
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_scene_tree summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_save_scene summer_get_script_errors
+paths: ["**/*.tscn", "**/*.gd", ".summer/**", "levels/**"]
+---
+
+# /design-level — Design One Level
+
+## Overview
+
+A level is a controlled sequence of player experiences in physical space. Layout, pacing, encounters, secrets, and reward gating must work together — a "fun layout" with a flat pacing curve still feels boring. This skill walks the six design beats of a single level and drops a node-tree skeleton ready for `summer_create_scene`.
+
+**Core principle:** A level has a *pacing curve* and a *teaching arc*. If you can't draw the tension graph and name what the player learned by the end, the level isn't designed yet.
+
+## Steps
+
+### 1. Pin the level type
+
+Ask exactly one question:
+
+> What kind of level? Pick one: tutorial / hub / combat encounter / boss / exploration / puzzle / stealth / platforming-challenge / mixed.
+
+Each type has different beats. Don't blend types in v1 — a "boss room with stealth and puzzles" is three levels poorly squeezed into one.
+
+### 2. Read context
+
+If `.summer/GameSoul.md` exists, read it. The level must serve the brief's core loop and the three mechanics.
+
+```
+Read .summer/GameSoul.md
+```
+
+If `.summer/mechanics/` exists, list the mechanics. Quote them back:
+
+> Brief says mechanics are: dash, parry, double-jump. This level should *exercise* at least one and ideally combine two.
+
+### 3. Define the teaching / experience goal
+
+Ask plain:
+
+> What does the player know by the end of this level that they didn't at the start?
+
+Tutorial-level answer: "How to dash." Combat-encounter answer: "That parrying converts damage to mana, and that big enemies need parry, not dodge." Exploration answer: "That this region's secrets are hidden behind double-jumpable gaps."
+
+If the user can't answer, the level has no purpose. Say it:
+
+> If there's no answer to that question, the level is filler. Either give it a teaching goal, give it a *failure-state* goal (the player must die here to progress), or merge it into the next level.
+
+### 4. Sketch the pacing curve
+
+Draw it as text. Five beats, intensity 0-10:
+
+```
+Intro    Build    Peak    Release    Hook
+ 2  →    5    →   8   →    3      →   6
+```
+
+For a 5-minute encounter level:
+
+| Beat | Duration | Intensity | Player feels | Designer plants |
+|---|---|---|---|---|
+| Intro | 30s | 2 | Calm, oriented | Visual landmark for the goal direction |
+| Build | 90s | 5 | Tension rising, small pressure | First weak enemy / first puzzle clue |
+| Peak | 60s | 8 | Stakes high, mistakes hurt | Main encounter / hardest fight |
+| Release | 60s | 3 | Catharsis, loot | Reward + breath room |
+| Hook | 30s | 6 | Curiosity for next | Visible-but-locked secret or path |
+
+Show the curve. Ask:
+
+> Pacing above. Does the peak land where you want, or does the level need a second wave?
+
+### 5. List encounters and secrets
+
+Encounters = explicit player tests (combat, puzzle, platforming). Secrets = optional rewards that respect the pacing curve.
+
+State them flat. For a combat encounter level:
+
+```
+Encounters (in player-traversal order):
+1. E1 — Tutorial enemy (1 weak grunt) at 0:30, in the open atrium. Teaches the basic attack.
+2. E2 — Forced parry (mid-tier enemy with telegraphed wind-up) at 1:30, in a corridor with no dodge room. Teaches parry.
+3. E3 — Mixed wave (2 grunts + 1 parry-required) at 3:00, in the peak arena. Tests both.
+4. E4 — Mini-boss at 4:00 in the chamber. Combines.
+
+Secrets (3 total — one per beat after intro):
+- S1 (build beat): Behind a breakable wall in the corridor, holds 50 currency. Teaches "walls can break".
+- S2 (peak beat): Visible from the arena, accessible only via parrying off an enemy. Rewards mastery.
+- S3 (hook beat): Locked door, key in a future level. Plants curiosity for next level.
+```
+
+### 6. Define reward gating
+
+What's behind which gate? Levels feel cheap when they hand out rewards without respecting the difficulty curve.
+
+| Reward | Gate | Why |
+|---|---|---|
+| Heal pickup | After E2 | Player just learned parry; reward + safety net before the peak |
+| New ability unlock | After mini-boss | Mastery-pinned; player demonstrates parry before getting upgrade |
+| Currency cache | Behind S1 (breakable wall) | Optional; rewards observation |
+| Story note | At the calm intro | Free; orients the player to the level's narrative |
+
+Ask:
+
+> Reward gating above. Anything missing or mis-placed?
+
+### 7. Define the layout primitives
+
+Every level is built from a small vocabulary of spaces. Name them. Most levels need 4-6 distinct spaces, no more.
+
+For a combat-encounter level:
+
+```
+Spaces (node-tree skeleton):
+World (Node3D)
+├── Geometry (Node3D)
+│   ├── IntroAtrium (Node3D)         # open, calm, well-lit
+│   ├── Corridor (Node3D)            # tight, forces parry
+│   ├── PeakArena (Node3D)           # large, multiple cover, exit visible
+│   └── BossChamber (Node3D)         # contained, single exit, dramatic lighting
+├── Spawns (Node3D)
+│   ├── PlayerSpawn (Node3D)         # marker
+│   ├── E1_Spawn (Node3D)
+│   ├── E2_Spawn (Node3D)
+│   ├── E3_Wave_Spawns (Node3D)
+│   └── MiniBoss_Spawn (Node3D)
+├── Triggers (Node3D)
+│   ├── E2_GateTrigger (Area3D)      # locks door behind player on entry
+│   ├── PeakWaveTrigger (Area3D)
+│   └── BossDoorTrigger (Area3D)
+├── Pickups (Node3D)
+│   ├── HealAfterE2 (Node3D)
+│   └── CurrencyS1 (Node3D)
+├── Secrets (Node3D)
+│   ├── S1_BreakableWall (StaticBody3D)
+│   ├── S2_ParryLedge (StaticBody3D)
+│   └── S3_LockedDoor (StaticBody3D)
+└── Lighting (Node3D)                # WorldEnvironment + DirectionalLight3D
+```
+
+Show the skeleton. Ask:
+
+> Tree above. May I create the level scene `levels/<level-name>.tscn` with this skeleton?
+
+### 8. Scaffold via MCP
+
+**Preferred (Summer MCP):**
+
+```
+summer_create_scene(path="res://levels/level_01.tscn", root_type="Node3D", root_name="World")
+summer_add_node(parent="./World", type="Node3D", name="Geometry")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="IntroAtrium")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="Corridor")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="PeakArena")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="BossChamber")
+summer_add_node(parent="./World", type="Node3D", name="Spawns")
+summer_add_node(parent="./World/Spawns", type="Node3D", name="PlayerSpawn")
+summer_add_node(parent="./World/Spawns", type="Node3D", name="E1_Spawn")
+# ... and so on
+summer_add_node(parent="./World", type="Node3D", name="Triggers")
+summer_add_node(parent="./World/Triggers", type="Area3D", name="E2_GateTrigger")
+# ... etc.
+summer_add_node(parent="./World", type="Node3D", name="Lighting")
+summer_add_node(parent="./World/Lighting", type="WorldEnvironment", name="WorldEnvironment")
+summer_add_node(parent="./World/Lighting", type="DirectionalLight3D", name="Sun")
+summer_save_scene
+```
+
+This is a **skeleton, not playable geometry**. Markers and Area3Ds, no meshes, no enemy scripts. Implementation in subsequent sessions / templates.
+
+**Fallback (no MCP):** Print the `.tscn` file contents for the user to save manually.
+
+### 9. Save the level design doc
+
+Always write the design doc — it's the artifact that drives implementation. Path: `.summer/levels/<level-name>.md`.
+
+```markdown
+# Level: <Name>
+
+**Type:** combat encounter
+**Duration target:** 5 min
+**Teaching goal:** Player learns parry and that parrying mid-tier enemies is required, not optional.
+
+**Pacing curve:** 2 → 5 → 8 → 3 → 6
+**Beats:** Intro (30s) | Build (90s) | Peak (60s) | Release (60s) | Hook (30s)
+
+## Encounters
+- E1 — Tutorial grunt @ 0:30 (IntroAtrium)
+- E2 — Forced parry @ 1:30 (Corridor)
+- E3 — Mixed wave @ 3:00 (PeakArena)
+- E4 — Mini-boss @ 4:00 (BossChamber)
+
+## Secrets
+- S1 — Breakable wall (Corridor) → 50 currency
+- S2 — Parry-ledge (PeakArena) → cosmetic
+- S3 — Locked door (BossChamber) → next level
+
+## Reward Gating
+- Heal pickup after E2
+- Ability unlock after mini-boss
+
+## Spaces
+1. IntroAtrium — open, calm
+2. Corridor — tight, forces parry
+3. PeakArena — large with cover
+4. BossChamber — contained, dramatic
+
+## Open questions
+<list anything the user couldn't answer>
+```
+
+Ask:
+
+> May I create `.summer/levels/<level-name>.md` with this design doc?
+
+### 10. Route to the next step
+
+End with:
+
+> Skeleton + design doc saved. Next:
+> - `/summer:design-mechanic` to design any mechanics this level requires that aren't designed yet.
+> - `/summer:design-npc` to design the enemies (E1-E4) in detail.
+> - `/summer:art-direction` if the visual style isn't pinned yet.
+> - Or open `levels/<level-name>.tscn` and start blocking out geometry.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| No teaching goal | Every level teaches something or fails. State it explicitly. |
+| Flat pacing curve | If intensity stays at 5 the whole time, you have a hallway, not a level. |
+| Too many spaces | 4-6 distinct spaces max. More fragments the player's mental map. |
+| Encounters not tied to mechanics | E2 should *require* parry, not just allow it. Forced use teaches; optional use doesn't. |
+| Secrets ignore the pacing curve | Don't put a major secret in the calm intro — players aren't curious yet. |
+| Reward gating too generous | Free heals before the peak deflate the peak. Gate them after the test. |
+| Blending level types | Stealth + puzzle + boss in one level = three half-baked levels. Pick one. |
+| Building geometry before the skeleton | Skeleton-first lets you iterate on layout cheaply. Geometry comes after the design is locked. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+
+## Collaborative protocol
+
+This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+This is a workflow that produces a skeleton scene. For runnable level examples, see:
+
+- `template-id: template-3d-fps` (https://github.com/SummerEngine/FPS-template-Summer-Engine) ships a sample arena.
+- `template-id: template-3d-platformer` (TBD) for jump-based level samples.
+
+The skeleton this skill produces is meant to be filled in via `/summer:design-mechanic`, gridmap blockout, or a template merge.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
+- `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
+- `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference
+- `rendering-and-lighting/3d-lighting/SKILL.md` — sets the lighting in `WorldEnvironment` + lights
+- `rendering-and-lighting/art-direction/SKILL.md` — defines the visual style the level expresses

package/skills/multiplayer-and-networking/setup-multiplayer/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: setup-multiplayer
+description: Use when the user wants to add multiplayer to an existing single-player game — co-op LAN, co-op online, competitive PvP, or lobbies/matchmaking. Strong opinion that you start with Godot's high-level MultiplayerAPI plus MultiplayerSpawner and MultiplayerSynchronizer; only roll custom networking with a justified reason. Walks peer authority, RPC patterns, replication graph, and irreversible architecture decisions. Trigger on "multiplayer", "co-op", "PvP", "online", "netcode", "rollback", "MultiplayerAPI", "host migration", "matchmaking".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_add_node summer_set_prop summer_connect_signal summer_save_scene summer_get_script_errors summer_project_setting summer_play summer_stop
+paths: ["**/*.gd", "**/*.tscn", "**/*.tres", "project.godot"]
+---
+
+# /setup-multiplayer — Add Multiplayer Without Repainting the Project
+
+## Overview
+
+Multiplayer is a one-way door. Pick the wrong authority model and refactoring later is brutal. This skill enforces an opinionated path: **start with Godot's high-level MultiplayerAPI + MultiplayerSpawner + MultiplayerSynchronizer + ENet**. Don't roll custom networking unless you have a measured reason. Make the irreversible decisions up front, in writing.
+
+**Core principle:** the architecture decision (peer authority vs server authority) is harder than the code. Lock it before touching a single RPC.
+
+## Steps
+
+### 1. Ask the four blocking questions
+
+Before any code:
+
+> 1. What kind of multiplayer? co-op LAN / co-op online / competitive PvP / lobbies + matchmaking
+> 2. How many players? 2 / 2–4 / 8+
+> 3. Who runs the simulation? host (one of the players) / dedicated server / authoritative peer-to-peer
+> 4. What's the network you're targeting? same Wi-Fi / public internet with ~80ms RTT / mobile
+
+Wait. Each answer flips an irreversible knob.
+
+### 2. Pick the authority model — irreversible decision
+
+**Lock it now.** Refactoring authority is a project-killer.
+
+| Model | Best for | Pros | Cons |
+|---|---|---|---|
+| **Host authority** (one player runs the sim) | Co-op (2–4 players), casual PvP, friends-only | Cheapest. No server bill. Host migration possible. | Host advantage (no lag for them). Cheating possible. |
+| **Dedicated server authority** | Competitive PvP, matchmaking, > 4 players | Fair. Anti-cheat possible. Stable. | Server bill. Need a deploy story. Higher complexity. |
+| **Peer-to-peer with shared authority** | Lock-step strategy / RTS, fighting games (rollback) | Symmetric latency. No "host advantage". | Determinism is a project on its own. Hard to debug. |
+
+**Default recommendation:** host authority for co-op (2–4 players), dedicated server for everything else. If user says "competitive PvP" + "lobbies": dedicated.
+
+State the choice explicitly:
+
+> Going with **host authority** for 2–4 player co-op. The first player to start a game is the host. Their scene tree is the source of truth; clients receive replicated state and send input RPCs. Host migration is hard with this model — if the host quits, the game ends. Confirm?
+
+### 3. Pick the transport
+
+Almost always: **ENetMultiplayerPeer**. It's UDP with reliability layers, ships with Godot, and just works for < 32 peers.
+
+When to switch:
+- **WebSocketMultiplayerPeer**: if you need the game to run in the browser (HTML5 export). ENet doesn't work in browsers.
+- **WebRTCMultiplayerPeer**: if you need browser AND P2P (no central server). Higher complexity.
+- **Custom transport**: never, unless you've shipped multiplayer before.
+
+### 4. Pick what to replicate — the replication graph
+
+Replicate the *minimum*. Every replicated field is bandwidth + bug surface.
+
+For a typical co-op shooter:
+
+| Object | Replicated state | Replication frequency | Authority |
+|---|---|---|---|
+| Player position / rotation | x, y, z, yaw | 20 Hz | Owner peer |
+| Player health | int | On change | Server/host |
+| Player input intent | move_dir, jump, fire | 30 Hz | Owner peer (sends to host) |
+| Enemy state | position, hp, FSM state | 10 Hz | Host only |
+| World items (pickups) | spawn / despawn events | On change | Host only |
+| UI / menus | nothing | nothing | Local only |
+| Particles, decorative VFX | nothing | nothing | Local only (each peer plays its own) |
+
+**Don't replicate:**
+- Local UI state.
+- Cosmetic-only VFX (each peer simulates locally).
+- Camera / view position (each peer has their own camera).
+- Audio (use 3D audio with replicated positions, not replicate the AudioStreamPlayer).
+
+### 5. Read the scene to find what changes
+
+```
+summer_get_scene_tree
+summer_inspect_node "./World/Player"
+```
+
+Note: the existing single-player Player needs to become a per-peer Player. The path is to spawn one Player per connected peer.
+
+### 6. Propose the change set
+
+> I'm about to:
+> - Add a `Network` autoload (`scripts/network.gd`) that owns peer setup + spawn lifecycle.
+> - Convert `./World/Player` from a static scene node into a `MultiplayerSpawner`-managed instance, spawned per peer on join.
+> - Add a `MultiplayerSynchronizer` to the player scene replicating `position`, `rotation.y`, `health`.
+> - Convert player input from local → input intent RPC sent to the authority.
+> - Add a basic host/join UI on the main menu.
+>
+> Authority model: host. Transport: ENet. Tick: 30 Hz input, 20 Hz position. Confirm before I touch anything?
+
+### 7. Build it
+
+#### a) Network autoload
+
+`scripts/network.gd`:
+
+```gdscript
+class_name Network
+extends Node
+
+const PORT := 7000
+const MAX_PLAYERS := 4
+
+signal player_joined(peer_id: int)
+signal player_left(peer_id: int)
+
+@export var player_scene: PackedScene
+
+var _peer: MultiplayerPeer
+
+func host_game() -> Error:
+    var enet := ENetMultiplayerPeer.new()
+    var err := enet.create_server(PORT, MAX_PLAYERS - 1)
+    if err != OK:
+        return err
+    _peer = enet
+    multiplayer.multiplayer_peer = _peer
+    multiplayer.peer_connected.connect(_on_peer_connected)
+    multiplayer.peer_disconnected.connect(_on_peer_disconnected)
+    # Host spawns its own player at id=1 (server id)
+    _spawn_player(1)
+    return OK
+
+func join_game(address: String) -> Error:
+    var enet := ENetMultiplayerPeer.new()
+    var err := enet.create_client(address, PORT)
+    if err != OK:
+        return err
+    _peer = enet
+    multiplayer.multiplayer_peer = _peer
+    return OK
+
+func _on_peer_connected(peer_id: int) -> void:
+    # Only the host spawns players. Clients receive via MultiplayerSpawner.
+    if multiplayer.is_server():
+        _spawn_player(peer_id)
+    player_joined.emit(peer_id)
+
+func _on_peer_disconnected(peer_id: int) -> void:
+    var node_name := str(peer_id)
+    var players := get_tree().get_first_node_in_group("players_root")
+    if players != null and players.has_node(node_name):
+        players.get_node(node_name).queue_free()
+    player_left.emit(peer_id)
+
+func _spawn_player(peer_id: int) -> void:
+    var player: Node = player_scene.instantiate()
+    player.name = str(peer_id)        # name = peer id; sync by name
+    player.set_multiplayer_authority(peer_id)
+    var players_root := get_tree().get_first_node_in_group("players_root")
+    players_root.add_child(player, true)
+```
+
+Register as autoload in `project.godot`:
+
+```
+summer_project_setting(name="autoload/Network", value="*res://scripts/network.gd")
+```
+
+#### b) Player scene with MultiplayerSynchronizer
+
+In the player scene, add:
+
+```
+Player (CharacterBody3D)
+├── CollisionShape3D
+├── Camera3D                         # local-only, attach in script if peer is local
+├── MeshInstance3D
+└── MultiplayerSynchronizer
+```
+
+```
+summer_add_node(parent="./World/Players/Player", type="MultiplayerSynchronizer", name="Sync")
+```
+
+Configure the synchronizer to replicate `position`, `rotation.y`, `health`. Save as a `SceneReplicationConfig.tres` (NOT inline sub_resource — silent-fail trap):
+
+```gdscript
+# scripts/player_net.gd
+extends CharacterBody3D
+
+@export var move_speed: float = 5.0
+@export var max_health: int = 100
+
+@onready var camera: Camera3D = $Camera3D
+@onready var sync: MultiplayerSynchronizer = $Sync
+
+var health: int = 100
+
+func _ready() -> void:
+    health = max_health
+    var auth := get_multiplayer_authority()
+    var is_local := auth == multiplayer.get_unique_id()
+    camera.current = is_local
+    set_physics_process(is_local)        # only the owner runs movement
+    set_process_input(is_local)
+
+func _physics_process(delta: float) -> void:
+    var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+    var direction := (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
+    if direction:
+        velocity.x = direction.x * move_speed
+        velocity.z = direction.z * move_speed
+    else:
+        velocity.x = move_toward(velocity.x, 0, move_speed)
+        velocity.z = move_toward(velocity.z, 0, move_speed)
+    if not is_on_floor():
+        velocity.y -= 9.8 * delta
+    move_and_slide()
+    # position is replicated automatically via MultiplayerSynchronizer
+
+@rpc("any_peer", "call_local", "reliable")
+func take_damage(amount: int) -> void:
+    if not multiplayer.is_server():
+        return                                          # only host applies damage
+    health = max(0, health - amount)
+    if health == 0:
+        rpc("on_died")
+
+@rpc("authority", "call_local", "reliable")
+func on_died() -> void:
+    queue_free()
+```
+
+#### c) RPC patterns — the four flavors
+
+Lock the conventions:
+
+| RPC config | Use case |
+|---|---|
+| `@rpc("authority", "call_local", "reliable")` | Host tells everyone something happened (health change result, death) |
+| `@rpc("any_peer", "call_remote", "unreliable")` | Frequent input intent (movement, look) — drop is OK |
+| `@rpc("any_peer", "call_remote", "reliable")` | Rare input event (fire weapon, pick up item) — drop NOT OK |
+| `@rpc("any_peer", "call_local", "reliable")` | Player asks host to do something (request damage) |
+
+**Authority validation is mandatory.** Inside any `any_peer` RPC, check `multiplayer.get_remote_sender_id()` and validate the sender owns the action.
+
+```gdscript
+@rpc("any_peer", "call_local", "reliable")
+func request_fire() -> void:
+    var sender := multiplayer.get_remote_sender_id()
+    if sender != get_multiplayer_authority():
+        return                       # someone else is trying to control this player; drop
+    # ... actually fire
+```
+
+#### d) Lag compensation outline
+
+Defer to a specialist skill, but flag the basics:
+
+- For projectiles: spawn locally on owner's machine at fire time, replicate the spawn event with a timestamp. Other peers fast-forward the projectile by their RTT.
+- For hit detection: server-authoritative + simple latency tolerance (host accepts hits within ~100ms past server time).
+- For movement: client-side prediction + server reconciliation is the standard model. Godot doesn't ship this — you write it. If users ask for "competitive PvP shooter", say: this is a deeper specialist topic and link `multiplayer-and-networking/lag-compensation/SKILL.md` when it ships.
+
+### 8. Save and verify
+
+```
+summer_save_scene
+summer_get_script_errors
+summer_play
+# user tests by running two instances locally (Project → Run Multiple Instances → 2)
+summer_stop
+```
+
+Test checklist:
+- [ ] Two instances connect (one hosts, one joins).
+- [ ] Each instance sees its own player as local (camera attached, can move).
+- [ ] Each instance sees the other player move smoothly (sync at 20 Hz).
+- [ ] Damage RPC routes through host (not double-applied on each peer).
+- [ ] Disconnect cleans up the disconnected player's node.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Decide authority model halfway through | Lock it in step 2 before touching code | Refactoring authority is a project-killer |
+| Replicate every property | Replicate position, rotation, health, that's it | Bandwidth + bug surface |
+| Run physics on every peer for every player | Physics on owner only, others receive transform | Otherwise jitter and divergence |
+| Trust the client | Validate `get_remote_sender_id()` in every `any_peer` RPC | Cheaters route through the wrong RPC |
+| Inline `SceneReplicationConfig` sub_resource | Save as standalone `.tres` | Silent-fail trap (see `_shared/mcp-tools-reference.md`) |
+| Roll custom transport | ENet (or WebSocket for browser) | You will hit edge cases ENet already solved |
+| Skip authority check in damage RPC | `if not multiplayer.is_server(): return` at the top of damage handlers | Otherwise damage applied N times |
+| Spawn players on every peer | MultiplayerSpawner — host spawns, clients receive | Otherwise N copies of each player |
+| `@rpc("any_peer")` everything | Use `authority` for server→clients, `any_peer` only for client→server | Mismatched flow = exploits |
+| Camera replicated | Camera is local-only, set `current = is_local` on spawn | Each peer needs their own camera |
+
+## Anti-patterns
+
+- **"Let's also have rollback netcode for our co-op shooter."** Rollback is a 6-month project on its own. Use it for fighting games and lock-step RTS, not co-op.
+- **NAT punchthrough on day one.** Use Steam Networking or a relay; don't write punchthrough yourself for v1.
+- **Dedicated servers without a deploy story.** If you can't redeploy in < 5 min, the dedicated path isn't ready.
+- **Custom serialization.** Godot's variant serialization is fine. Don't write your own packing until you measure bandwidth.
+- **Host migration in v1.** It's a feature, not a primitive. Ship without it; add later if churn data demands.
+
+## Collaborative protocol
+
+This skill rewires the project at the architectural level. Always ask before each block of changes. Group writes — "I'm about to add the autoload + 2 scenes + 3 scripts + InputMap entries. OK?". See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+For a known-good multiplayer scaffold (host + join UI, ENet transport, MultiplayerSpawner, replicated player), point users at:
+
+→ **template-id**: TBD (`template-co-op-online` planned, see `_shared/template-registry.md`)
+
+For now: this skill produces the scaffold inline. When the template lands, link from here.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list (project-setting, autoload registration)
+- `_shared/godot-version.md` — `MultiplayerAPI` is medium-churn; `SceneReplicationConfig` settled in 4.0+
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — typed GDScript conventions
+- `multiplayer-and-networking/multiplayerapi-basics/SKILL.md` — deeper MultiplayerAPI patterns
+- `multiplayer-and-networking/client-server-pattern/SKILL.md` — dedicated server architecture
+- `multiplayer-and-networking/peer-replication/SKILL.md` — synchronizer config patterns
+- `multiplayer-and-networking/enet-vs-websocket/SKILL.md` — transport choice
+- `multiplayer-and-networking/lag-compensation/SKILL.md` — deeper netcode for competitive (when shipped)
+- `multiplayer-and-networking/state-sync/SKILL.md` — selective replication patterns
+- `multiplayer-and-networking/lobby-and-matchmaking/SKILL.md` — lobby UI + Steam matchmaking