# Tales of Pokémon — Organisation du projet

Jeu 3D développé avec Godot (GDScript). Ce document décrit comment le projet est rangé et les conventions à suivre pour s'y retrouver.

## Principe général

- **On range par fonctionnalité**, pas par type de fichier : le script d'une scène vit à côté de sa scène.
- **Règle de test** : si je supprime la fonctionnalité X, je ne supprime qu'un seul dossier.
- Les **fichiers bruts** (images, sons, modèles 3D) sont dans `assets/`, les **ressources de données** (`.tres`) dans `data/`, le **code et les scènes** dans `game/`.

## Arborescence

```
res://
├── addons/                  # plugins (pokeapi_importer, controller_icons) — ne pas modifier à la main
├── assets/                  # fichiers bruts uniquement
│   ├── textures/            # fonds, splash…
│   ├── ui/types/            # symboles des types
│   └── audio/
├── data/                    # ressources .tres (importées ou faites à la main)
│   ├── pokemon/             # fichiers préfixés par l'id (ex. 0025_pikachu.tres)
│   ├── moves/
│   ├── types/
│   ├── items/
│   └── mounts/
├── game/
│   ├── core/                # autoloads : game_data, pokedex, ui_audio
│   ├── player/
│   │   ├── player_character.tscn / .gd
│   │   ├── camera/          # camera_holder
│   │   ├── input/           # input_management_component
│   │   ├── aim/             # aim_target
│   │   └── states/          # state, state_machine, idle_state, walk_state, …
│   ├── pokemon/             # pokemon_instance, pokemon_team, pokemon_nature, move_slot, trainer_data…
│   ├── mount/               # mount_profile, mount_registry
│   ├── storage/             # pokemon_box, pokemon_storage, pc_screen (+ .tscn)
│   ├── ui/
│   │   ├── main_menu/       # scène + script
│   │   ├── pause_menu/      # scène + script + shader
│   │   ├── splash_screen/
│   │   └── hud/
│   └── world/               # main.tscn et futures zones
├── docs/                    # documentation (ce fichier)
├── project.godot
└── icon.svg
```

## Conventions de nommage

| Élément | Convention | Exemple |
|---|---|---|
| Fichiers et dossiers | `snake_case` | `pokemon_team.gd`, `main_menu.tscn` |
| `class_name` | `PascalCase` | `PokemonTeam`, `AimTarget` |
| Variables et fonctions | `snake_case` | `move_speed`, `gravity_apply()` |
| Constantes | `MAJUSCULES_SNAKE` | `MAX_TEAM_SIZE` |
| Signaux | `snake_case`, verbe au passé | `transitioned` |
| Ressources de données Pokémon | préfixe par l'id | `0025_pikachu.tres` |

## Les grands systèmes

### Joueur et state machine (`game/player/`)

Le joueur est un `CharacterBody3D` piloté par une state machine : le nœud `StateMachine` contient un nœud enfant par état.

- Chaque état hérite de `State` et implémente `enter()`, `exit()`, `update()` et `physics_update()`.
- Un état demande un changement avec `transitioned.emit(self, "NomDuNoeud")`. Le nom correspond au **nom du nœud enfant** dans la scène (insensible à la casse). Si aucun nœud ne porte ce nom, la transition est ignorée sans erreur.
- États en place ou prévus : Idle, Walk, Run, Jump, Inair, Crouch, Dodge, Aim, Mounted.
- Les variables partagées entre états (vitesses, cooldowns de saut, `walk_or_run`…) sont sur `PlayerCharacter`.

**Ajouter un état :**
1. Créer `xxx_state.gd` dans `game/player/states/` (`extends State`, avec un `class_name` et un `state_name`).
2. Ajouter un nœud enfant sous `StateMachine` dans `player_character.tscn`, avec le même nom que celui utilisé dans les transitions, et lui attacher le script.
3. Ajouter les transitions entrantes et sortantes dans les états concernés.

### Visée (`game/player/aim/`)

`AimState` fait un auto-lock sur les `AimTarget` du groupe `aim_targets`. Les actions d'entrée sont configurables dans l'inspecteur de l'état.

### Pokémon, équipe et PC (`game/pokemon/`, `game/storage/`)

- `PokemonInstance` : un Pokémon concret (capacités débloquées, nature, sans IV ni EV).
- `PokemonTeam` : équipe de 6 maximum, utilisée par le joueur et les PNJ.
- `TrainerData` / `TrainerPartyEntry` : équipes des PNJ dresseurs.
- `PokemonStorage` / `PokemonBox` / `pc_screen` : stockage de type « boîte PC » quand l'équipe est pleine.

### Montures (`game/mount/` et `data/mounts/`)

Certains Pokémon peuvent être montés hors combat. Le code est dans `game/mount/`, les profils de monture (`.tres`) dans `data/mounts/`.

### Données Pokémon (`addons/pokeapi_importer/` et `data/`)

- Le plugin d'éditeur **pokeapi_importer** importe depuis PokeAPI uniquement les Pokémon, capacités et objets choisis, et les écrit en `.tres` dans `data/`.
- Il est autonome (prévu pour un dépôt séparé) : le jeu utilise ses données, mais ne doit pas le modifier.
- Le `Pokedex` (autoload) est côté jeu, dans `game/core/`.

### Interfaces

Le jeu est pensé **manette d'abord** (clavier et souris restent possibles). Toute nouvelle interface doit être entièrement utilisable à la manette, avec un focus initial défini. Les icônes de touches viennent du plugin `controller_icons`.

## Autoloads

| Autoload | Rôle |
|---|---|
| `game_data` | Sauvegarde et progression |
| `pokedex` | Accès aux Pokémon et capacités par id ou nom |
| `ui_audio` | Sons d'interface |

## Règles pour garder le projet rangé

1. Un script et sa scène vont dans le même dossier.
2. Aucun script dans `assets/`, aucun gros fichier brut dans `game/`.
3. Déplacer et renommer les fichiers **depuis le dock FileSystem de Godot**, jamais depuis l'explorateur de l'OS.
4. Après un déplacement, chercher `res://` dans le projet : les chemins écrits en chaîne de caractères ne sont pas mis à jour automatiquement.
5. Ne pas mélanger un renommage et un déplacement dans le même commit Git.
6. Mettre ce document à jour quand un nouveau dossier ou système apparaît.