Install this CLAUDE.md template.
Name: Godot 4 Game Project Template
Save to: ./CLAUDE.md in the current project

---
# CLAUDE.md — Godot 4 Game Project

## Project overview
<!-- One-sentence description: e.g., "2D roguelite with procedural generation" -->

## Tech stack
- **Engine**: Godot 4.3+
- **Language**: GDScript (typed where possible)
- **Target**: Desktop (Windows/macOS/Linux)

## Project structure
```
project.godot          # project config
scenes/
  main.tscn            # entry scene
  ui/                  # UI scenes (menus, HUD, dialogs)
  levels/              # level scenes
  entities/            # player, enemies, NPCs
  components/          # reusable scene components
scripts/
  autoload/            # singleton scripts (GameManager, AudioManager)
  resources/           # custom Resource scripts
  utils/               # helper functions
assets/
  sprites/             # 2D textures and spritesheets
  audio/               # SFX and music
  fonts/               # custom fonts
  shaders/             # .gdshader files
```

## Coding conventions
- Use **static typing** everywhere: `var speed: float = 100.0`
- Autoloads for global state: registered in Project → Autoload
- Signals over direct references: `signal health_changed(new_value: int)`
- Use `@export` for inspector-editable variables
- Use `@onready` for node references: `@onready var sprite := $Sprite2D`
- Scene composition over inheritance — attach component scenes as children
- Group nodes for batch operations: `get_tree().get_nodes_in_group("enemies")`

## Input mapping
Define actions in Project → Input Map, reference by name:
```gdscript
func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("jump"):
        _jump()
```

## Common patterns

### State machine
```gdscript
enum State { IDLE, RUN, JUMP, ATTACK }
var current_state: State = State.IDLE

func _physics_process(delta: float) -> void:
    match current_state:
        State.IDLE: _idle_state(delta)
        State.RUN: _run_state(delta)
```

### Scene transitions
```gdscript
# In autoload GameManager:
func change_scene(path: String) -> void:
    get_tree().change_scene_to_file(path)
```

## Common pitfalls
- Always use `_physics_process` for movement, not `_process`
- `await` in `_ready()` can cause ordering issues — prefer signals
- Node references (`$Child`) are null until `_ready()` — use `@onready`
- Export arrays of resources need explicit type: `@export var items: Array[ItemResource]`