summer-engine 1.4.0 → 2.0.0

package/skills/debugging/debug/SKILL.md

@@ -1,137 +1,157 @@
 ---
 name: debug
-description: Use when the user reports their game is broken, crashing, behaving unexpectedly, or says "debug", "fix", "something's wrong", or "it's not working". Triages the bug end-to-end via Summer Engine's diagnostic tools (console, debugger errors, script errors), locates the offending code, proposes a fix, and verifies the fix.
+description: Use when the user reports a bug, crash, error, or unexpected behavior in a Godot/Summer project, before making any code or scene changes — runs a disciplined script-errors → console → debugger → hypothesis → fix → verify loop. Trigger on "debug", "crash", "error", "broken", "not working", "freezes", "wrong".
 license: MIT
-compatibility: [Cursor, Claude Code, Windsurf, Codex]
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
 user-invocable: true
-allowed-tools: Read Grep Glob Edit summer_get_console summer_get_debugger_errors summer_get_script_errors summer_get_diagnostics summer_clear_console summer_play summer_stop summer_is_running summer_get_scene_tree summer_inspect_node
-paths: ["**/*.gd", "**/*.tscn", "**/*.cs"]
+allowed-tools: Read Edit Grep summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
+paths: ["**/*.gd", "**/*.cs", "**/*.tscn", "**/*.tres", "project.godot"]
 ---
 
-# /debug — Triage and Fix a Bug
+# /debug — Triage and Fix a Bug End-to-End
 
-## Overview
+The disciplined debugging loop for Godot/Summer projects. Read the error before guessing. Form a hypothesis before editing. Verify the fix before declaring victory. Never grep the codebase before reading the actual error.
 
-A bug in a Godot/Summer game can hide in three places: scripts (GDScript/C# compile or runtime errors), the engine console (printed messages, warnings), or the scene/resource state (wrong property, missing collider, broken signal connection). This skill walks all three before guessing.
+**Core principle:** The debugger already knows what's wrong. Your job is to listen to it before doing anything else.
 
-**Core principle:** read what the engine actually saw, not what the code looks like it does.
+## When to use this skill
 
-## Steps
+- The user says "it crashes", "it broke", "throws an error", "doesn't work", "freezes", "wrong behavior".
+- The user pastes a stack trace.
+- A previous build or test step failed and the user wants to fix it.
 
-### 1. Get the user's description first
+## When NOT to use this skill
 
-Ask one short question:
+- The user is asking how to *prevent* a class of bug — that's a design question. Use the relevant discipline skill (`gdscript-patterns`, `scene-composition`).
+- The user is asking for a feature with a known unfinished spec — that's `make-game` territory.
+- The bug is in a non-Godot file the host agent can debug natively (CI config, npm scripts) — use the host's debugger.
 
-> What's happening? Briefly: when does it go wrong, and what do you expect vs. what you see?
+## The Loop
 
-Wait for the answer before doing anything else. Don't start grepping code yet — the user's words narrow the search 10x.
+```
+  Listen → Diagnose → Hypothesize → Propose → Fix → Verify
+```
 
-### 2. Read the engine's actual error state
+Do not skip steps. Do not loop back to "Hypothesize" without re-running the cheap diagnostic.
 
-Always do this in order. Each tool answers a different question.
+### 1. Listen
 
-**Preferred (Summer MCP):**
+Ask the user **one** focused question and wait for the answer:
 
-```
-summer_get_script_errors        # Compile errors? (cheapest, do first)
-summer_get_console              # Print() output, warnings, info
-summer_get_debugger_errors      # Runtime errors with stack traces
-summer_get_diagnostics          # Aggregated count + summary
-```
+> What's happening, and when does it happen?
 
-If the bug is reproducible only at runtime and the engine isn't currently playing:
+If they already gave a clear symptom in the request, skip the question.
+If they say "something's broken", that one question is your only call until they reply. Don't run tools yet.
 
-```
-summer_clear_console            # Clean slate
-summer_play                     # Run it
-                                # (let the user reproduce the bug)
-summer_get_debugger_errors      # Now read what blew up
-summer_stop                     # When done
-```
+### 2. Diagnose — cheapest tool first
 
-**Fallback (no MCP — engine isn't connected):**
+In strict order. Stop at the first one that returns useful signal.
 
-Ask the user to copy-paste the engine's Output panel and Debugger errors. Inspect manually.
+| Order | Tool | When |
+|---|---|---|
+| 1 | `summer_get_script_errors` | Always start here. Catches GDScript parse errors, missing identifiers, signature mismatches. Cheapest, no side effects. |
+| 2 | `summer_get_diagnostics` | Aggregate console + debugger error counts. One call, broad picture. |
+| 3 | `summer_get_console` | Read the editor Output panel — print statements, warnings, errors that didn't crash. |
+| 4 | `summer_get_debugger_errors` | Runtime errors caught by the debugger. Use AFTER `summer_play` for runtime-only bugs. |
 
-### 3. Locate the offending code
+**If `summer_get_script_errors` is clean and the user says it crashes only when running:** it's a runtime bug. Go to step 2b.
 
-For each error, follow the stack trace to the file + line. Use host file tools:
+### 2b. Runtime-only bugs
 
 ```
-Read <file>:<line-near-error>
+  summer_clear_console
+  summer_play
+  ─▶ ASK USER: "Reproduce the bug now."
+  (wait for confirmation)
+  summer_get_debugger_errors
+  summer_stop
 ```
 
-Read 20–40 lines around the error site. Don't open the whole file unless you need to — context budget matters.
+Do not skip the "reproduce now" prompt. Auto-running and grabbing whatever's in the buffer leads you to chase ghosts from previous sessions.
 
-If the error mentions a node path (e.g. `./World/Player/Camera`), inspect it:
+### 2c. MCP unavailable (engine not running, or no Summer install)
 
-```
-summer_inspect_node "./World/Player/Camera"
-```
+If `summer_get_script_errors` returns "Summer Engine is not running" or the tool isn't available:
 
-### 4. Form a hypothesis and propose the fix
+1. Ask the user to copy-paste the Output panel and the Debugger panel from the Godot editor.
+2. Reason over the pasted text exactly as you would over MCP output.
+3. Continue with the rest of the loop unchanged.
 
-State it in one sentence:
+Do NOT loop on MCP retry. Do NOT pretend the engine will come back. Use the fallback the moment it fails once.
 
-> The error happens because <root cause>. The fix is <one-line summary>.
+### 3. Hypothesize — one specific theory
 
-Then ask:
+State exactly one hypothesis, in one sentence, naming the file and line.
 
-> May I edit `<file>` to <do exactly this>?
+> **Good:** "Typo at `scripts/player.gd:14` — `GRAVTY` should be `GRAVITY`."
+> **Bad:** "Could be a typo, missing import, or wrong scope."
 
-Don't guess at multiple fixes at once. Pick one. If wrong, the next iteration is cheap.
+If you have multiple plausible theories, pick the highest-prior-probability one. The user can correct you if you're wrong; chasing all three at once wastes their time.
 
-### 5. Apply the fix
+**Verify the hypothesis without editing.** If the error mentions a missing node, call `summer_inspect_node` to confirm. If it's a missing resource, `summer_inspect_resource`. If it's a scene-graph issue, `summer_get_scene_tree`. **Confirm the world state matches the error before proposing a fix.**
 
-On user yes, edit the file with host tools (`Edit`/`Write`). Single focused change.
+### 4. Propose — ask before writing
 
-### 6. Verify
+Surface the proposed fix in plain language and ask permission. Two patterns:
 
-Re-run the relevant check:
+**Code fix:**
+> May I edit `scripts/player.gd` to rename `GRAVTY` → `GRAVITY` on line 14?
 
-```
-summer_get_script_errors        # If it was a compile error
-summer_play → summer_get_debugger_errors → summer_stop   # If runtime
-```
+**Scene fix vs code fix:**
+> The script calls `audio.play()` but the `AudioStreamPlayer` child is gone. Two options:
+> 1. Re-add the `AudioStreamPlayer` to `./Coin` (preserves the original behavior).
+> 2. Null-check in `coin.gd` (defensive, but the audio is silent).
+>
+> Which one do you want?
 
-Report:
+**Never** unilaterally pick when there are two equally valid fixes (scene vs code, defensive vs strict, fast vs correct). Ask.
 
-> Fixed. <One-line description of what changed.>
+### 5. Fix — minimal, focused
 
-If still broken: go back to step 4 with the new error state. State explicitly that the first hypothesis was wrong.
+- For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
+- For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
+- **Trap to avoid:** never call `summer_set_resource_property` against an inline `sub_resource` — the value is silently dropped. If the property is on a nested resource, first call `summer_set_prop` with the resource class name to instantiate a standalone resource, then drill in. See `_shared/mcp-tools-reference.md`.
 
-## Common bug patterns and how to spot them
+### 6. Verify — re-run the diagnostic that found it
 
-| Symptom | Likely cause | First check |
-|---|---|---|
-| `Invalid set index 'X' (on base: Nil)` | Node path resolved to null | `summer_inspect_node` the path |
-| `Identifier not declared` (script error) | Missing `class_name` or wrong scope | `summer_get_script_errors` |
-| Game runs but sprite doesn't appear | Node added but not visible (transform / parent / layer) | `summer_get_scene_tree` + inspect parent |
-| Signal handler never fires | Connection not made, or connected to wrong instance | `summer_inspect_node` of emitter, check connections |
-| Player falls through floor | CollisionShape3D has no shape, or shape is inline sub_resource | `summer_inspect_resource` on the CollisionShape |
-| Mouse capture stuck | `Input.set_mouse_mode` not paired with release on focus loss | `summer_get_console` for warnings |
-| Game hangs on start | Infinite loop in `_ready()` or `_process()` | `summer_get_debugger_errors` after a forced stop |
+The fix is not done until the same diagnostic that found the bug returns clean.
+
+- Script error → re-run `summer_get_script_errors`.
+- Runtime error → re-run the play/reproduce/check-debugger loop.
+- Console warning → `summer_clear_console`, then `summer_play` and confirm clean output.
 
-## Anti-patterns (don't do these)
+If the diagnostic is still red after the fix, you formed the wrong hypothesis. Go back to step 3 — do **not** make a second edit on top of the first. Revert if the first edit didn't help, then re-hypothesize.
 
-- **Don't** start by reading the user's whole codebase. The error tells you where to look.
-- **Don't** propose a sweeping refactor for a single bug. One file, one change, verify.
-- **Don't** call `summer_set_resource_property` on an inline `sub_resource` — it silently fails. See `_shared/mcp-tools-reference.md` § "Trap".
-- **Don't** call `summer_play` without `summer_clear_console` first if you want clean output to read.
-- **Don't** skip the user's description in step 1. "What were you trying to do" beats "what does the code do" 9/10 times.
+## Anti-Patterns
 
-## Collaborative protocol
+| Don't | Why |
+|---|---|
+| Grep the whole project before reading the error | The error already names the file and line. Save the user's tokens. |
+| Read whole files | 20–40 lines around the error is enough 90% of the time. |
+| Run multiple diagnostics in parallel | They mask each other's signal. Cheapest first, escalate. |
+| Edit before asking | The user owns the fix decision, you own the diagnosis. |
+| "Try this, see if it works" | That's not a hypothesis, that's gambling. State the theory or ask another question. |
+| Reformat the file while you're in it | Out-of-scope edits make the diff hostile to review. |
+| Auto-fix linter warnings unrelated to the bug | Same reason. |
+| Declare victory after editing | Re-run the diagnostic. Always. |
 
-This skill writes files. Always ask before each edit step. See `_shared/collaborative-protocol.md`.
+## Quick reference — common Godot bug families
 
-## Want a working starter?
+| Symptom | First tool | Common cause |
+|---|---|---|
+| "Identifier X not declared" | `summer_get_script_errors` | Typo, missing import, wrong scope |
+| "Invalid call. Nonexistent function 'X' in base 'Nil'" | `summer_get_debugger_errors` after `summer_play` | Node was deleted in editor, code still references it |
+| "Cannot find type 'X'" | `summer_get_script_errors` | Class name mismatch, missing autoload, missing `class_name` |
+| Game runs but visuals wrong | `summer_get_console` + `summer_inspect_node` | Material/light/camera misconfigured |
+| Game freezes (no crash) | `summer_get_console` after `summer_play` for ~3s | Infinite loop in `_process` or `_ready` |
+| `summer_set_resource_property` "succeeded" but nothing changed | n/a | Inline sub-resource silent-fail. Use `summer_set_prop` with class name first. |
 
-No template — this is a workflow, not a project scaffold. It works against any Godot/Summer project that has Summer MCP wired up.
+## Closing
 
-## See also
+A debug session is done when:
+1. The user-reported symptom no longer reproduces.
+2. The diagnostic that originally flagged the bug returns clean.
+3. No new errors or warnings have been introduced.
 
-- `_shared/mcp-tools-reference.md` — full tool list
-- `_shared/godot-version.md` — engine version + LLM cutoff risks
-- `scripting-patterns/gdscript-patterns/SKILL.md` — what good GDScript looks like
-- `scene-and-project/play/SKILL.md` — running the game
+Tell the user one short sentence: "Fixed `<file>:<line>` — `<change>`. Diagnostic clean." Then stop.

package/skills/multiplayer-and-networking/host-authoritative-state/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: host-authoritative-state
+description: Use when designing the state layer of a multiplayer Godot game — deciding what's host-owned, how clients request changes, how the host validates and broadcasts. Pairs with `/peer-to-peer-multiplayer`. Trigger on "host authority", "authoritative state", "state ownership", "MP cheating", "client validation", "RPC patterns".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: multiplayer-and-networking
+user-invocable: true
+allowed-tools: Read Grep summer_get_scene_tree summer_inspect_node summer_save_scene summer_get_script_errors
+---
+
+# /host-authoritative-state — Designing the State Layer
+
+## Overview
+
+This is **Layer 2** of multiplayer architecture. `/peer-to-peer-multiplayer` covers all four layers; this skill zooms in on the one that produces 90% of shipping-quality MP bugs. For every piece of state in your game, decide: **does the host own it, or does the client own it?** Get this wrong and you ship a cheat-vulnerable, desync-prone game where players "teleport," items dupe, and hit-detection lies. Get it right and the rest of multiplayer falls into place.
+
+## The fundamental question
+
+For every state field, ask one question:
+
+> **If a malicious client lies about this, does it break the game?**
+
+| Answer | Owner | Notes |
+|---|---|---|
+| Yes | **Host-authoritative.** | Clients send intent (RPC request); host validates and broadcasts. |
+| No | **Client-owned.** | Cosmetic. Replicated for visual sync only. |
+| Sometimes | **Host-authoritative with client prediction.** | Position is the canonical example: client predicts to feel responsive; host reconciles to prevent teleport-cheats. |
+
+This question is the entire decision tree. Apply it to every field, no exceptions.
+
+## The decision matrix
+
+The canonical state-ownership table for a typical 3D action game. Use this as your starting point and extend per game.
+
+| State field | Owner | Why | What an attacker could do if you got it wrong |
+|---|---|---|---|
+| `health` | host | core combat integrity | edit memory → infinite HP, ignore damage |
+| `mana` / `stamina` | host | gates ability/sprint use | infinite-cast spam, infinite-sprint |
+| `score` / `kills` / `objectives` | host | competitive integrity | self-award kills, fake leaderboard |
+| `inventory` contents | host | items must not dupe | broadcast "I picked it up" twice → duped item |
+| `currency` (gold, gems) | host | trade exploits | mint currency on the client |
+| `ability_cooldowns` | host | gates damage rate | spam-cast every frame |
+| `current_weapon` equipped | host | tied to inventory and damage tables | swap to "best gun" without owning it |
+| `team_assignment` | host | balance + friendly fire | switch sides mid-match |
+| `ready_state` (lobby) | host | match-start gating | force-start with one player |
+| `chat_messages` | host-relayed | moderation hooks, profanity filter | bypass mute, broadcast to muted peers |
+| `position` | client-predicted, host-reconciled | input latency feels awful otherwise | speed-hack, teleport — reconciliation catches both |
+| `velocity` | client-predicted, host-reconciled | same as position | same as position |
+| `look_direction` (yaw/pitch) | **client** | cosmetic; host doesn't need it for hit-reg if you raycast on host | cheating here doesn't help |
+| `animation_state` | **client** | visual; can lead the truth | wrong anim = visual glitch, not exploit |
+| `footstep_audio` | **client** | host doesn't care | spam → mild annoyance, not exploit |
+| `particle_fx` / `muzzle_flash` | **client** | host doesn't care | same |
+| `aim_assist_target` | **client** | local UX | spoofing it only hurts the spoofer |
+
+If a row is missing, run the fundamental question on it. When in doubt, host-own it — false positives are cheap, false negatives ship cheats.
+
+## The Manager pattern
+
+Every host-authoritative state field lives in a Manager autoload. Naming convention: `{Domain}Manager` — `HealthManager`, `ScoreManager`, `InventoryManager`, `CooldownManager`. This is the canonical state-ownership pattern across shipping-quality MP architectures.
+
+Each Manager has a fixed shape:
+
+```gdscript
+class_name HealthManager
+extends Node
+
+# ── Signals (UI / floating bars / scoreboard listen here) ──
+signal player_health_updated(peer_id: int, hp: int, max_hp: int)
+signal player_died(peer_id: int, killer_id: int)
+
+const DEFAULT_MAX_HEALTH := 100
+
+# Host-authoritative dictionary, keyed by peer_id.
+var _player_health: Dictionary = {}  # peer_id -> { hp, max_hp, is_dead }
+
+func _ready() -> void:
+    NetworkManager.peer_joined.connect(_on_peer_joined)
+    NetworkManager.peer_left.connect(_on_peer_left)
+
+# ── HOST-ONLY MUTATORS (state writes) ──────────────────────────
+func _host_apply_damage(target: int, amount: int, attacker: int) -> void:
+    if not NetworkManager.is_host: return
+    var entry = _player_health.get(target)
+    if entry == null or entry.is_dead: return
+    var new_hp = max(0, entry.hp - amount)
+    entry.hp = new_hp
+    _broadcast_health(target, new_hp, entry.max_hp)
+    if new_hp == 0:
+        entry.is_dead = true
+        _broadcast_death(target, attacker)
+
+# ── CLIENT REQUEST HANDLERS (validate then mutate) ─────────────
+@rpc("any_peer", "call_remote", "reliable")
+func _client_request_damage(target: int, amount: int) -> void:
+    if not NetworkManager.is_host: return
+    var sender := multiplayer.get_remote_sender_id()
+    if not _validate_damage_request(sender, target, amount): return
+    _host_apply_damage(target, amount, sender)
+
+# ── HOST-TO-CLIENT BROADCASTS (state reads) ────────────────────
+@rpc("authority", "call_remote", "reliable")
+func _broadcast_health(peer_id: int, hp: int, max_hp: int) -> void:
+    var entry = _player_health.get(peer_id, { "hp": hp, "max_hp": max_hp, "is_dead": false })
+    entry.hp = hp
+    entry.max_hp = max_hp
+    _player_health[peer_id] = entry
+    player_health_updated.emit(peer_id, hp, max_hp)
+
+@rpc("authority", "call_remote", "reliable")
+func _broadcast_death(peer_id: int, killer_id: int) -> void:
+    player_died.emit(peer_id, killer_id)
+```
+
+The shape:
+
+1. **Data** lives in a private `Dictionary` keyed by `peer_id`.
+2. **`_host_apply_*()` mutators** are the *only* functions that write the dictionary. First line: `if not NetworkManager.is_host: return`.
+3. **`_client_request_*()` RPC handlers** validate, then call the mutator. Never write directly.
+4. **`_broadcast_*()` RPC functions** push state to clients (`@rpc("authority", ...)`) so only host can call.
+5. **Lifecycle** via `NetworkManager.peer_joined` / `peer_left` — host registers and cleans up entries.
+
+Build one Manager per state domain. Don't put health and inventory in the same autoload — when one needs a refactor the other gets dragged along.
+
+## The four RPC flavors
+
+`/peer-to-peer-multiplayer` covers three; this skill goes deeper on a fourth (query/response). Every networked function maps to one of these. Pick the wrong one and you'll see the bug listed.
+
+### Flavor 1: Host → Client broadcast
+
+```gdscript
+@rpc("authority", "call_remote", "reliable")
+func _broadcast_score(peer: int, value: int) -> void:
+    _scores[peer] = value
+    score_updated.emit(peer, value)
+```
+
+- `authority` = only host can call this. Anyone else's call is dropped by Godot.
+- `call_remote` = doesn't run on the caller. Host already wrote the dictionary; no need to re-run locally.
+- `reliable` = state must arrive. Lost packets retry.
+- **Bug if wrong:** if you mark this `any_peer`, a client can fake a score broadcast → desync.
+
+### Flavor 2: Client → Host request
+
+```gdscript
+@rpc("any_peer", "call_remote", "reliable")
+func _client_request_use_item(item_id: String) -> void:
+    if not NetworkManager.is_host: return
+    var sender := multiplayer.get_remote_sender_id()
+    if not _validate_item_use(sender, item_id): return
+    _host_apply_item_use(sender, item_id)
+```
+
+- `any_peer` = any client can call.
+- First line is **always** `if not NetworkManager.is_host: return`. Defensive — Godot already routes correctly, this guards against misconfiguration.
+- `multiplayer.get_remote_sender_id()` is trustworthy — clients can't lie about who sent the request.
+- **Bug if wrong:** missing the `is_host` guard means peers process each other's requests and corrupt local state.
+
+### Flavor 3: Client → Client cosmetic relay
+
+```gdscript
+@rpc("any_peer", "call_remote", "unreliable")
+func _peer_play_emote(emote_id: String) -> void:
+    var sender := multiplayer.get_remote_sender_id()
+    _play_emote_visual(sender, emote_id)
+```
+
+- `unreliable` = fire-and-forget, lossy is fine for cosmetics.
+- No validation — worst case a player's emote desyncs by a frame.
+- **Bug if wrong:** marking this `reliable` for high-frequency cosmetic events (footsteps, particle spawns) blows up bandwidth.
+
+### Flavor 4: Query / response (the late-join flavor)
+
+The flavor not covered in `/peer-to-peer-multiplayer`. When one specific client needs the host to send them state — e.g. a peer just joined and needs the full game state — use `rpc_id` to target a single peer.
+
+```gdscript
+# Client side — peer asks the host for current state
+func client_request_full_state() -> void:
+    rpc_id(1, "_host_send_full_state_to_caller")
+
+@rpc("any_peer", "call_remote", "reliable")
+func _host_send_full_state_to_caller() -> void:
+    if not NetworkManager.is_host: return
+    var caller := multiplayer.get_remote_sender_id()
+    # send state ONLY to the caller, not all peers
+    for peer_id in _player_health:
+        var entry = _player_health[peer_id]
+        rpc_id(caller, "_broadcast_health", peer_id, entry.hp, entry.max_hp)
+
+# Host side — actually a flavor 1 broadcast, but targeted via rpc_id
+@rpc("authority", "call_remote", "reliable")
+func _broadcast_health(peer_id: int, hp: int, max_hp: int) -> void:
+    # same handler as flavor 1, but called via rpc_id(caller, ...) for targeting
+    pass
+```
+
+Use this for: late-join state replay, lobby info on connect, post-respawn loadout. **Always reliable** — partial state replay is worse than no replay.
+
+## Validation patterns
+
+Every `_client_request_*()` must validate **before** applying. The validation is the only thing standing between you and a cheat.
+
+```gdscript
+func _validate_damage_request(attacker: int, target: int, amount: int) -> bool:
+    # 1. Authority check — does this client own the attacker?
+    if attacker != target_attacker_owner(attacker): return false
+
+    # 2. Existence check
+    if not _player_health.has(target): return false
+    if _player_health[target].is_dead: return false
+
+    # 3. Resource check — does attacker have a weapon equipped?
+    if not InventoryManager.has_weapon_equipped(attacker): return false
+
+    # 4. Range check — within weapon's max range?
+    var weapon := InventoryManager.get_equipped_weapon(attacker)
+    var dist := _get_player_distance(attacker, target)
+    if dist > weapon.max_range + 0.5:  # epsilon for float compare
+        return false
+
+    # 5. Line-of-sight check — physics raycast on the host
+    if not _has_line_of_sight(attacker, target): return false
+
+    # 6. Cooldown check — is the weapon off cooldown?
+    if not CooldownManager.is_ready(attacker, weapon.id): return false
+
+    # 7. Damage cap — clamp `amount` to weapon.max_damage to defeat magnitude inflation
+    if amount > weapon.max_damage: return false
+
+    return true
+```
+
+Six common validators, in priority order:
+
+1. **Authority** — does this client own the entity they're modifying? (You can attack other players, but you can only modify your *own* inventory.)
+2. **Existence** — does the target still exist on the host? (Race vs. peer disconnect.)
+3. **Resource** — does the requester have the resources? (Mana, ammo, weapon.)
+4. **Range / distance** — physics-plausible? (Prevents shooting across the map.)
+5. **Line-of-sight** — raycast on the host. (Prevents shooting through walls.)
+6. **Cooldown** — within rate limits? (Prevents spam-cast.)
+7. **Magnitude** — is the requested amount within game-defined max? (Prevents inflation: clamp damage to weapon's `max_damage`, etc.)
+
+When validation fails: **drop silently or log + drop**. Never tell the client they tried to cheat — that just lets them probe. No error response, no friendly "you can't do that" message. The request simply has no effect.
+
+**Float epsilon:** range / distance / cooldown checks involve floats. Always allow a small epsilon (`+ 0.5` for distance, `> -0.05` for cooldown remaining). Strict equality on floats fails for legitimate clients due to physics jitter.
+
+## Late-join state sync
+
+When a peer joins mid-session, the host must replay current state to them. Without this, the new peer's HUD shows zeros and they think they have full HP.
+
+The pattern: every Manager exposes a `_send_full_state(peer_id)` method. Connect it to `NetworkManager.peer_joined`.
+
+```gdscript
+# In each Manager
+func _on_peer_joined(id: int) -> void:
+    if not NetworkManager.is_host: return
+    # Register the new peer
+    _player_health[id] = { "hp": DEFAULT_MAX_HEALTH, "max_hp": DEFAULT_MAX_HEALTH, "is_dead": false }
+    # Replay all existing state to them
+    _send_full_state(id)
+
+func _send_full_state(target_peer: int) -> void:
+    for peer_id in _player_health:
+        var entry = _player_health[peer_id]
+        rpc_id(target_peer, "_broadcast_health", peer_id, entry.hp, entry.max_hp)
+        if entry.is_dead:
+            rpc_id(target_peer, "_broadcast_death", peer_id, 0)
+```
+
+Use flavor 4 (`rpc_id`) so only the joining peer gets the replay. Broadcasting to all peers re-confirms state they already have — wastes bandwidth and may trigger "received update" hooks on UIs.
+
+**Idempotency:** `_send_full_state` may run a fraction of a second after `_broadcast_health` for the same peer. Make sure your Manager's broadcast handlers are idempotent — receiving the same state twice should be a no-op.
+
+## Common mistakes
+
+| Mistake | What goes wrong | Fix |
+|---|---|---|
+| Trusting client-supplied damage values | Client edits memory → 99999 damage one-shots everyone | Host computes damage from weapon resource; client supplies only `target` and `weapon_id`. |
+| Validating *after* applying instead of before | Cheat already took effect for a frame; reverting causes visual rubber-banding | Validate first, then mutate. The mutator never runs if validation fails. |
+| Broadcasting state changes via `signal.emit()` on host | Signals fire only on the emitter — clients never see the update | Use `@rpc("authority", ...)` broadcast functions. Signals are for *local* listeners (UI on the host). |
+| Forgetting `peer_left` cleanup | Dictionaries grow forever as players cycle through; eventual memory leak + ghost entries | Every Manager listens to `NetworkManager.peer_left` and `erase()`s its entry. |
+| Using `reliable` for high-frequency cosmetic state (footsteps, particles) | Bandwidth blowup; reliable retransmits on packet loss | `unreliable` for cosmetic; `reliable` only for state that *must* arrive. |
+| Comparing floats without epsilon in validation | Legitimate clients fail validation due to physics-step jitter; their hits get silently dropped | `dist > max_range + 0.5`, never `dist > max_range`. |
+| Writing to host dictionary from a non-host code path | One peer accidentally becomes "second host" → desyncs | First line of every mutator: `if not NetworkManager.is_host: return`. Treat as boilerplate. |
+
+## Anti-pattern: the "synced var" temptation
+
+Godot 4 ships a `MultiplayerSynchronizer` node that automatically replicates a list of properties across the network. It's tempting because it removes RPC boilerplate. **It is wrong for anything game-logic-relevant.**
+
+`MultiplayerSynchronizer`:
+- Has no validation hook. Writes go through unconditionally.
+- Has no concept of "host owns this, client requests changes."
+- Replicates whatever value the configured authority node sets — and the authority is per-node, not per-property.
+- Provides no audit trail when a value changes (compared to a Manager method you can breakpoint).
+
+It is the right tool for **cosmetic state only**:
+- Animation node parameters (`AnimationTree` blend values).
+- Look direction / camera yaw on remote peer's visuals.
+- Particle emission state on a non-gameplay decoration.
+
+Game-logic state — health, score, inventory, cooldowns, position-of-truth — goes through Managers with explicit validate-mutate-broadcast. The five extra lines of boilerplate per field are what keeps the game shippable.
+
+## Putting it together
+
+When you start a new MP game, the order is:
+
+1. Build `NetworkManager` (covered by `/peer-to-peer-multiplayer` Layer 1).
+2. List every piece of game state on a sheet.
+3. Run "if a malicious client lies, does it break?" on each.
+4. Group host-owned fields by domain → one Manager per domain.
+5. For each Manager: data dict, `_host_apply_*()` mutators, `_client_request_*()` RPCs with validators, `_broadcast_*()` RPCs, `peer_joined` / `peer_left` lifecycle, `_send_full_state()` for late-join.
+6. Cosmetic state goes through `MultiplayerSynchronizer` or a flavor-3 RPC.
+7. Position/velocity get host-reconciled prediction (covered by `/peer-to-peer-multiplayer` Layer 4).
+
+## Collaborative protocol
+
+This skill writes new autoload files (one per Manager). Always ask before each:
+
+> May I create `autoloads/HealthManager.gd` and register it as an autoload?
+> May I add the validation function to HealthManager? Here's what I'll check: [list].
+> May I wire HealthManager's `peer_joined` lifecycle?
+
+Don't bulk-create five Managers in one shot. Walk one Manager end-to-end (data → mutators → requests → broadcasts → lifecycle) so the user can verify the shape, then repeat for the next domain.
+
+After each Manager file lands, call `summer_get_script_errors` to confirm clean compile. See [`_shared/collaborative-protocol.md`](../../_shared/collaborative-protocol.md).
+
+## See also
+
+- [`peer-to-peer-multiplayer`](../peer-to-peer-multiplayer/SKILL.md) — the four-layer architecture overview. Read this first if you haven't.
+- [`setup-multiplayer`](../setup-multiplayer/SKILL.md) — lighter intro that just gets a session running. Use that one if the user just wants two players to see each other.
+- [`_shared/godot-version.md`](../../_shared/godot-version.md) — Godot 4.5 multiplayer API stability notes.
+- [`_shared/gd-style.md`](../../_shared/gd-style.md) — typed-GDScript conventions used in the examples above.
+- [`_shared/mcp-tools-reference.md`](../../_shared/mcp-tools-reference.md) — `summer_get_script_errors` for compile verification.

package/skills/rendering-and-lighting/3d-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 3d-lighting
-description: Lighting setup, WorldEnvironment, sky, and shadows for 3D scenes. Use when setting up a 3D scene, adding lights, configuring environment, or adjusting shadows. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient".
+description: Use when setting up lighting in a 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows. Covers DirectionalLight3D vs Omni vs Spot, shadow tuning, ambient/sky-driven lighting, and Godot 4.5-era conventions. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient", "sky", "light".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting