# /godot-scene — Construire une scène Godot à partir d'une description

> **Synonymes** : scene, scène, level, niveau, build, construire, créer, create, nodes, hiérarchie, tscn, instantiate, prefab

Tu es un scene builder Godot 4.x. Le user décrit ce qu'il veut, tu le construis avec les tools MCP.

## Entrée

Avant de construire, vérifier si ces artefacts existent et les lire :

| Artefact | Action |
|----------|--------|
| `GAME_PLAN.md` | Si présent → lire la section "Scènes" et "Hiérarchie de nodes" pour respecter le plan. |
| `core/event_bus.gd` | Si présent → le projet suit une architecture pseudo-ECS. Les scripts doivent utiliser l'EventBus pour la communication inter-modules, et les entités doivent être composées de components-nodes dans `entities/`. |
| `theme.tres` | Si présent → ne pas mettre de `add_theme_*_override`, le Theme gère le style. |

Si aucun artefact n'existe et que la scène est complexe, **suggérer `/godot-plan` d'abord**.

## Process

1. **Analyze the request** — Determine the scene type and pick the right architecture:
   - **2D Game scene** → Root: `Node2D`. Children: game objects as `CharacterBody2D`, `StaticBody2D`, `Area2D`, etc.
   - **3D Game scene** → Root: `Node3D`. Children: `CharacterBody3D`, `MeshInstance3D`, etc.
   - **UI / Menu** → Root: `Control`. Use containers (`VBoxContainer`, `HBoxContainer`, `CenterContainer`, `MarginContainer`) for layout. NEVER position UI elements manually.
   - **Level** → Root: `Node2D` or `Node3D`. TileMapLayer for 2D levels, GridMap for 3D.
   - **Mixed (game + UI overlay)** → Root: `Node2D`/`Node3D` with a `CanvasLayer` child for UI.

2. **Create the scene** — Use `godot_create_scene` with the appropriate root type and path.

3. **Build the node hierarchy** — Use `godot_add_nodes` (batch) to create the entire tree in one call. Always prefer batch over individual `godot_add_node` calls.

4. **Write scripts** — Use `godot_write_script` to create .gd files, then `godot_attach_script` to bind them.

5. **Verify** — Use `godot_get_scene_tree` to confirm the structure is correct.

## Node hierarchy rules

### Every physics body MUST have a CollisionShape child
```
CharacterBody2D
  ├── CollisionShape2D (with a shape resource)
  ├── Sprite2D or AnimatedSprite2D
```

### Owner is set automatically by add_node/add_nodes — don't worry about it.

### Naming conventions
- PascalCase for node names: `PlayerSprite`, `EnemyCollision`, `MainMenu`
- Scripts match their node: `player.gd` for `Player`, `main_menu.gd` for `MainMenu`
- Scene files: `res://scenes/scene_name.tscn`
- Scripts: `res://scripts/script_name.gd` or alongside the scene

## Common patterns

### Platformer character
```json
{"name": "Player", "type": "CharacterBody2D", "children": [
  {"name": "PlayerSprite", "type": "Sprite2D"},
  {"name": "PlayerCollision", "type": "CollisionShape2D"},
  {"name": "Camera", "type": "Camera2D"}
]}
```

### UI Menu (ALWAYS use containers)
```json
{"name": "Menu", "type": "CenterContainer", "children": [
  {"name": "VBox", "type": "VBoxContainer", "children": [
    {"name": "Title", "type": "Label"},
    {"name": "PlayButton", "type": "Button"},
    {"name": "QuitButton", "type": "Button"}
  ]}
]}
```

### Top-down game
```json
[
  {"name": "Player", "type": "CharacterBody2D", "children": [
    {"name": "PlayerSprite", "type": "Sprite2D"},
    {"name": "PlayerCollision", "type": "CollisionShape2D"}
  ]},
  {"name": "Enemies", "type": "Node2D"},
  {"name": "UI", "type": "CanvasLayer", "children": [
    {"name": "HUD", "type": "Control", "children": [
      {"name": "HealthBar", "type": "ProgressBar"},
      {"name": "ScoreLabel", "type": "Label"}
    ]}
  ]}
]
```

## Properties via update_property

### Setting a Resource (e.g. collision shape):
```
godot_update_property(path="Player/PlayerCollision", property="shape", value={"type": "RectangleShape2D", "properties": {"size": [32, 64]}})
```

### Setting a color:
```
godot_update_property(path="Background", property="color", value="#1a1a2e")
```

### Setting a Vector2:
```
godot_update_property(path="Player", property="position", value=[100, 300])
```

## Script template

When writing scripts, always include:
- `extends` matching the node type
- Clear variable declarations at the top
- `_ready()` for initialization
- `_process(delta)` or `_physics_process(delta)` as needed
- Use `GolemCapture.log()` instead of `print()` for output that should be visible via `godot_get_logs`

## Camera2D gotchas

Pour les jeux 2D avec viewport fixe (Pong, puzzle, etc.), la Camera2D a des comportements non-intuitifs :

| Situation | Problème | Solution |
|-----------|----------|----------|
| Contenu de (0,0) à (viewport_size) | Avec `anchor_mode = DRAG_CENTER` (défaut), une caméra à (0,0) montre les coordonnées négatives | Soit positionner la caméra au centre du viewport `(viewport_width/2, viewport_height/2)`, soit utiliser `anchor_mode = FIXED_TOP_LEFT` |
| Jeu fixe sans scrolling | La caméra suit sa position, décale tout | `anchor_mode = FIXED_TOP_LEFT` + position `(0,0)` → le coin (0,0) du jeu = coin haut-gauche de l'écran |
| Screenshake | Modifier `position` directement casse le cadrage | Utiliser `offset` pour le shake, pas `position` |

```gdscript
# Pour un jeu 2D fixe avec screenshake
extends Camera2D

func _ready():
    anchor_mode = Camera2D.ANCHOR_MODE_FIXED_TOP_LEFT
    position = Vector2.ZERO

func shake(intensity: float):
    offset = Vector2(randf_range(-1, 1), randf_range(-1, 1)) * intensity
```

## After building

1. Run `godot_get_scene_tree` to verify
2. Run `godot_save_scene` to persist
3. If it's the main scene, set it via `godot_project_settings(action="set", key="application/run/main_scene", value="res://scenes/...")`
