summer-engine 1.3.1 → 1.4.0

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

package/skills/performance/tune-performance/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: tune-performance
+description: Use when the user reports the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware. Profiles the running game via summer_get_diagnostics, identifies hotspots (rendering / physics / scripting), and proposes specific fixes with before/after metric expectations. Trigger on "slow", "lag", "fps drop", "stuttering", "performance", "optimize", "profile", "framerate".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: performance
+user-invocable: true
+allowed-tools: Read Grep Glob Edit summer_get_diagnostics summer_get_console summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_play summer_stop summer_is_running summer_clear_console summer_set_prop summer_project_setting
+paths: ["**/*.gd", "**/*.tscn", "**/*.tres", "project.godot"]
+---
+
+# /tune-performance — Profile, Diagnose, Fix
+
+## Overview
+
+Performance tuning without measurement is gambling. This skill enforces a measure-first loop: read diagnostics, identify the dominant cost (rendering / physics / scripting / startup), drill into the specific pattern, propose one fix, verify the metric moved. No shotgun optimization.
+
+**Core principle:** the engine's diagnostics tell you which subsystem is bleeding. Don't optimize a different subsystem.
+
+## Steps
+
+### 1. Get the user's symptom precisely
+
+> What's slow? Pick the closest: framerate drops in scene X / startup is long / freezes for a moment / runs fine on my machine but bad on hardware Y.
+
+Wait. The answer narrows the fix domain by 5x:
+
+| Symptom | Likely subsystem |
+|---|---|
+| Framerate drops as more enemies spawn | Scripting (`_process` per-instance) or physics |
+| Framerate is fine standing still, drops looking at level X | Rendering (overdraw, draw calls, lights) |
+| Stutter every N seconds | GC pause, autoload loop, or async load |
+| Long startup | Asset import, autoload `_ready` work, shader compilation |
+| Runs fine on dev machine, bad on user machine | Resolution, GPU features (compute, GI), shadow quality |
+
+### 2. Take a baseline measurement
+
+Don't guess. Read the engine's actual numbers.
+
+**Preferred (Summer MCP):**
+
+```
+summer_clear_console
+summer_play
+# user reproduces the slowdown for 5–10 seconds
+summer_get_diagnostics
+summer_get_console               # check for warnings (e.g. "shader compilation hot-path")
+summer_stop
+```
+
+`summer_get_diagnostics` returns the aggregate metrics. Note (write down before fixing anything):
+
+- Average FPS during the slow section
+- Frame time (ms) — anything over 16.67 ms = below 60 fps
+- Draw calls per frame
+- Active physics bodies
+- Active GPUParticles instances
+- Script time vs. physics time vs. render time
+
+**Fallback (no MCP):** ask the user to enable Godot's built-in monitor (`Debug → Monitor` or in-game with `Performance.get_monitor`) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.
+
+### 3. Identify the dominant cost
+
+The biggest number wins your attention. Don't optimize the second-biggest — that's a 5% win when 30% is sitting next to it.
+
+Decision tree:
+
+- **Render time > 50% frame budget** → rendering hotspot (Step 4a)
+- **Physics time > 30% frame budget** → physics hotspot (Step 4b)
+- **Script time > 30% frame budget** → GDScript hotspot (Step 4c)
+- **Frame time spikes (jitter) but average is fine** → GC / shader compile / async (Step 4d)
+- **FPS is fine but startup is slow** → import / autoload (Step 4e)
+
+### 4a. Rendering hotspot
+
+Common Godot 4.5 rendering costs, ordered by frequency:
+
+| Pattern | Symptom | Fix |
+|---|---|---|
+| Too many MeshInstance3D | Draw calls > 1000 | MultiMeshInstance3D for repeated meshes (foliage, debris). 5000 trees = 1 draw call. |
+| Overdraw (transparent stacked) | Render time spikes when looking at particles/glass/UI | Reduce particle `amount`, disable `transparent` on opaque materials, check Compositor settings |
+| Real-time lights > 4 visible | Frame time doubles in well-lit rooms | Bake static lighting (`LightmapGI`), make distant lights `shadow_enabled = false` |
+| Shadow map size too high | Render time spikes near light sources | DirectionalLight3D `directional_shadow_max_distance` lower, OmniLight3D shadow_bias up, shadow size 2048 → 1024 |
+| No occlusion culling | Far rooms drawn through walls | OccluderInstance3D + bake. Painful but high-impact for indoor scenes. |
+| Missing LOD on complex meshes | Drop in framerate when far away | MeshInstance3D `visibility_range_begin` + manual LOD swaps |
+
+To inspect a suspect node:
+
+```
+summer_inspect_node "./World/Enemy"
+summer_inspect_resource "./World/Enemy"   # for mesh/material/shape details
+```
+
+### 4b. Physics hotspot
+
+Top patterns:
+
+| Pattern | Fix |
+|---|---|
+| 100+ active RigidBody3D | Sleep them when idle (`can_sleep = true`), or convert to Area3D where collision response isn't needed |
+| Concave collision shapes on dynamic bodies | Convert to ConvexPolygonShape3D or compound primitives (sphere/capsule/box). Concave costs 5–20x more. |
+| Physics tick at 120 Hz default | Lower `physics/common/physics_ticks_per_second` to 60 if visual smoothness allows |
+| Per-frame raycast in `_physics_process` | Cache the result, raycast every N frames, or use ShapeCast3D |
+| Hundreds of overlap queries | Use Area3D with `monitoring = true` only on the bodies that need to detect — turn it off on environment |
+
+### 4c. GDScript hotspot
+
+Per-frame work in `_process` is the #1 GDScript cost. Read the script, look for:
+
+```gdscript
+# BAD — runs every frame
+func _process(delta: float) -> void:
+    var enemies = get_tree().get_nodes_in_group("enemies")  # tree walk!
+    for enemy in enemies:
+        var dist = global_position.distance_to(enemy.global_position)
+        if dist < 10.0:
+            ...
+```
+
+Fixes:
+
+- Cache the group lookup in `_ready()` if the group composition is stable.
+- Move per-frame work to a timer at 10 Hz (`_on_timer_timeout`), not 60 Hz.
+- Replace `distance_to` with `distance_squared_to` in comparisons (no sqrt).
+- Push hot loops to a `@tool`-able C# script or GDExtension if it's truly per-frame.
+
+### 4d. Frame time spikes (jitter)
+
+If FPS is good but frame time spikes:
+
+- **Shader compilation**: precompile shaders during loading screen via `RenderingServer.shader_compile_from_code` or by warming up the scene off-screen.
+- **GC / object allocation**: `var x := []` inside `_process` allocates each frame. Pre-allocate.
+- **Async resource load**: ensure `ResourceLoader.load_threaded_request` is finished before referencing.
+
+Check `summer_get_console` for shader-compile warnings.
+
+### 4e. Startup time
+
+```
+summer_clear_console
+summer_play
+# stop after first scene loads
+summer_stop
+summer_get_console
+```
+
+Look for:
+
+- Long autoload `_ready()` work (move to `call_deferred` or background thread).
+- Asset import on first run (cache `.import` files in source control).
+- `preload()` of huge scenes at script-parse time — switch to `load()` on demand.
+
+### 5. Propose ONE fix with a metric expectation
+
+Don't bundle five fixes. Pick the highest-leverage one.
+
+> The dominant cost is **rendering** at 14.2 ms / frame (85% of budget). The biggest source is 240 individual MeshInstance3D for foliage. Replacing them with one MultiMeshInstance3D should drop render time to ~3 ms (estimate: 5–7 ms). May I refactor `./World/Foliage` to use MultiMeshInstance3D?
+
+Format the proposal as: (a) what the dominant cost is, (b) the specific source, (c) the fix, (d) the expected metric movement, (e) the ask.
+
+### 6. Apply, re-measure, report
+
+After the user approves:
+
+```
+# apply the fix (Edit / summer_add_node / summer_set_prop / etc)
+summer_save_scene
+summer_clear_console
+summer_play
+# user reproduces the same scenario
+summer_get_diagnostics
+summer_stop
+```
+
+Compare: was the metric movement at least 50% of what was promised? If yes, ship it. If no, the hypothesis was wrong — go back to step 3 with the new numbers.
+
+> Before: 14.2 ms render / 22 fps. After: 4.1 ms render / 58 fps. Shipped.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Optimize without baseline metrics | Always `summer_get_diagnostics` before and after | "Felt faster" is not a measurement |
+| Fix the second-biggest cost | Fix the biggest first, re-measure, re-prioritize | Amdahl's law — the small win evaporates next to the big one |
+| Bundle 5 fixes into one PR | One fix at a time, verify each | Bundles hide regressions. Hard to attribute the win or the loss. |
+| `_process` for everything | 10 Hz timer for AI / distance checks / range polls | 60 Hz AI is wasted CPU |
+| `distance_to` in hot loop | `distance_squared_to` in comparisons | sqrt is expensive at scale |
+| 200 RigidBody3D for debris | MultiMeshInstance3D + manual physics, or bake | Each rigid body = solver work every tick |
+| Real-time GI everywhere | Bake static lighting; real-time only for movable lights | Real-time GI is a per-frame budget killer |
+| Shadow map at 4096 on every light | 4096 for sun, 1024 or off for fillers | Shadow map writes are hidden render passes |
+| Concave shape on dynamic body | Compound primitives (sphere + box + capsule) | Concave shape physics is 5–20x slower |
+| `get_nodes_in_group` every frame | Cache once in `_ready()` | Tree walks aren't free |
+
+## Anti-patterns from the field
+
+- **"Just disable VSync to see real FPS."** Disabling VSync helps you measure, but performance work targets perceived smoothness (16.7 ms, locked). Re-enable before shipping.
+- **Premature C++ rewrite.** A GDScript hotpath at 5% of frame time isn't the bottleneck. Profile first.
+- **"It's slow on user machines, must be the GPU."** Often it's resolution scale + shadow quality + GI settings. Add a quality preset switcher first.
+- **Threading gameplay code.** Godot's gameplay layer isn't thread-safe. Threading is for asset load, network, AI compute — not `_physics_process`.
+
+## Collaborative protocol
+
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow. Performance tuning is project-specific by definition.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list
+- `_shared/godot-version.md` — Godot 4.5 renderer notes (Compositor, RenderSceneBuffers churn)
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
+- `performance/profiling-godot/SKILL.md` — deeper Godot profiler usage
+- `performance/draw-call-batching/SKILL.md` — MultiMeshInstance3D patterns
+- `performance/lod-and-culling/SKILL.md` — LOD setup
+- `debugging/debug/SKILL.md` — bug triage (related but different)
+- `rendering-and-lighting/baked-vs-realtime-lighting/SKILL.md` — bake decisions

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

@@ -102,3 +102,23 @@ Always use `Color(r, g, b, a)` with values 0.0–1.0:
 - Cool white: `Color(0.9, 0.95, 1, 1)`
 - Orange (torch): `Color(1, 0.6, 0.2, 1)`
 - Green (alien): `Color(0.5, 1, 0.5, 1)`
+
+## Fallback (no MCP — edit `.tscn` directly)
+
+If Summer MCP isn't connected, append the lighting block to your scene file:
+
+```
+[node name="Sun" type="DirectionalLight3D" parent="World"]
+transform = Transform3D(0.866, 0, -0.5, 0.354, 0.707, 0.612, 0.354, -0.707, 0.612, 0, 0, 0)
+light_color = Color(1, 0.95, 0.9, 1)
+light_energy = 1.0
+shadow_enabled = true
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="World"]
+```
+
+Then create `Environment` and `Sky` resources via the inspector or load from `.tres`.
+
+## Collaborative protocol
+
+This skill mutates the scene (adds lights + WorldEnvironment + tunes Environment sub-properties). Always ask before applying: "May I add a DirectionalLight3D Sun with shadows + a WorldEnvironment with a procedural sky?". See `../../_shared/collaborative-protocol.md`.