# /godot-debug — Diagnose and fix issues in a Godot project

> **Synonymes** : debug, fix, bug, crash, error, erreur, broken, cassé, problem, problème, issue, not working, marche pas, écran noir, black screen, freeze, lag, glitch

## Sommaire

1. [Diagnostic sequence](#diagnostic-sequence) (5 étapes)
2. [Common Godot bugs](#common-godot-bugs)
3. [Report format](#report-format)
4. [Limitations des screenshots](#limitations-des-screenshots)

---

You are a Godot 4.x debugger. Something is wrong — find it and fix it.

## Diagnostic sequence

Run these steps IN ORDER. Do not skip steps. Gather ALL information before proposing a fix.

### Step 1: Visual state
```
godot_get_editor_screenshot
```
If a scene is running:
```
godot_get_game_screenshot
```
Look for: black screen, mispositioned nodes, missing visuals, UI overlaps.

### Step 2: Logs and errors
```
godot_get_errors
godot_get_logs(source="all")
```
Look for: null references, missing resources, type errors, signal errors.

### Step 3: Scene structure
```
godot_get_scene_tree
```
Look for:
- Physics bodies WITHOUT a CollisionShape child → collisions won't work
- Nodes without scripts where they should have one
- Duplicate node names (causes path resolution bugs)
- Wrong node types (e.g. `Node2D` used where `Control` is needed for UI)

### Step 4: Inspect suspicious nodes
For each node that looks wrong:
```
godot_inspect_node(path="NodeName")
```
Look for:
- `position = (0, 0)` when it should be elsewhere
- `visible = false` when it should be shown
- `script = null` when a script is expected
- `collision_layer = 0` or `collision_mask = 0` → physics won't interact
- Empty `shape` on CollisionShape2D → silent fail, no collisions

### Step 5: Read relevant scripts
```
godot_view_script(path="res://scripts/suspect.gd")
```
Look for:
- Wrong `extends` (doesn't match node type)
- `_process` vs `_physics_process` misuse (physics in _process or visuals in _physics_process)
- Missing `move_and_slide()` call in CharacterBody
- Signal connections to nonexistent methods
- Division by zero, array out of bounds

## Common Godot bugs

| Symptom | Likely cause |
|---------|-------------|
| Node doesn't move | Missing `move_and_slide()`, or velocity never set |
| Objects pass through each other | Missing CollisionShape, wrong collision layer/mask |
| UI not visible | Behind another control, wrong z_index, or `visible = false` |
| UI not responding to input | Missing `mouse_filter = MOUSE_FILTER_STOP`, or parent catches input |
| Black screen | No Camera2D/Camera3D in scene, or camera not current |
| Script error "node not found" | Wrong path, node not in tree yet at `_ready()` time, typo in name |
| Signal "already connected" | Connecting in `_process` instead of `_ready` |
| Game runs but nothing happens | Main scene not set in project settings |

## Report format

After gathering all information, present findings as:

```
## Diagnostic

**Problem:** [One sentence description]

**Root cause:** [What's actually wrong and why]

**Evidence:**
- [What you found in step N]
- [What you found in step M]

**Fix:**
1. [Specific action with exact tool call]
2. [Specific action with exact tool call]
```

Then execute the fix using the MCP tools. After fixing, re-run the diagnostic to verify.

## Important

- NEVER guess. If you're not sure, inspect more nodes and read more scripts.
- The most common issue is missing CollisionShapes. Always check for those first.
- If get_logs returns nothing useful, suggest the user replace `print()` with `GolemCapture.log()` in their scripts for better output capture.

## Limitations des screenshots

Les screenshots (`godot_get_editor_screenshot`, `godot_get_game_screenshot`) sont **statiques**. Certains effets ne sont PAS visibles sur un screenshot :

| Effet | Visible sur screenshot ? | Comment vérifier |
|-------|-------------------------|------------------|
| Screenshake | ❌ Non (mouvement) | Demander au user de confirmer visuellement, ou vérifier les logs `GolemCapture.log()` |
| Animations/Tweens | ❌ Non (mouvement) | Vérifier que le script tween existe et est appelé |
| Particules | ⚠️ Partiellement (si émission en cours) | Augmenter `amount` et `lifetime` pour test |
| Flash/Blink | ❌ Non (timing) | Vérifier le script, tester avec `modulate` permanent |
| Audio | ❌ Non | Vérifier les AudioStreamPlayer et leurs connexions |

**Si un effet dynamique ne fonctionne pas** : ne pas se baser uniquement sur les screenshots. Lire le script, vérifier les connexions de signaux, et demander au user de tester en jouant.
