---
description: Diagnose and fix issues in a Godot project step by step
user-invocable: false
---
# /godot-debug — Diagnose and fix issues in a Godot project

## 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.

## Native debug tools (sans MCP)

Quand l'utilisateur débugge manuellement ou quand les MCP tools ne suffisent pas, guider vers ces outils natifs Godot.

### Logging efficace

| Méthode | Couleur | Cliquable | Quand |
|---------|---------|-----------|-------|
| `push_error("msg")` | Rouge | Oui → ouvre le script à la ligne | Erreur récupérable, condition invalide |
| `push_warning("msg")` | Jaune | Oui → ouvre le script à la ligne | Situation anormale non-bloquante |
| `print_rich("[color=green]OK[/color]")` | Custom (BBCode) | Non | Logs colorés pour flux dense |
| `print()` | Blanc | Non | Prototypage uniquement — éviter en production |

Toujours recommander `push_error()` / `push_warning()` avant `print()` — le clic vers la ligne source accélère le diagnostic.

### Remote Scene Tree

L'outil le plus sous-estimé pour le debug runtime :

- **Local** = scène sauvegardée sur disque
- **Remote** = scène **en mémoire** pendant l'exécution (ennemis spawnés, HP modifiés, nodes dynamiques)

**Setup recommandé :**
1. `Editor Settings` → `Debugger` → activer **Auto Switch to Remote Scene Tree**
2. `Project Settings` → activer **Always on Top** pour la fenêtre de jeu
3. Résultat : le jeu reste au premier plan, l'inspecteur montre les valeurs live. On peut modifier des propriétés (vitesse, couleur, position) en temps réel pendant que le jeu tourne

### Breakpoints

- **F9** sur une ligne = breakpoint. Le jeu gèle quand l'exécution atteint cette ligne
- **Stack Trace** = inspecter toutes les variables locales au moment du freeze
- **F11 (Step Into)** = avancer ligne par ligne pour suivre le flux d'exécution
- Utiliser quand un bug est non-reproductible par les logs — geler le state exact au moment du problème

### Dev tools protégés

Encapsuler les raccourcis de debug (god mode, reload, teleport) pour qu'ils n'existent jamais dans le build final :

```gdscript
func _unhandled_input(event: InputEvent) -> void:
    if not OS.is_debug_build():
        return
    if Input.is_action_just_pressed("debug_reload"):
        get_tree().reload_current_scene()
    if Input.is_action_just_pressed("debug_god_mode"):
        _god_mode = !_god_mode
```

`OS.is_debug_build()` retourne `false` dans les exports — zéro risque que les joueurs y accèdent.

## 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.
- When MCP tools can't diagnose the issue (dynamic timing, race conditions), recommend **breakpoints** or **Remote Scene Tree** to the user.

## 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.

## See also

| Skill | Quand l'utiliser |
|-------|-----------------|
| `/godot-test` | Après le fix — vérifier automatiquement que le bug est résolu |
| `/godot-scene` | Si le problème est structurel (nodes manquants, hiérarchie cassée) |
| `/learn` | Documenter le fix et les leçons apprises |
