Tales-of-PKMN/docs/README.md

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.