diff --git a/README.md b/README.md index 6b5d929..49f89d7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,118 @@ # PokeAPI Importer -git submodule add addons/pokeapi_importer \ No newline at end of file +Plugin d'éditeur Godot 4 qui importe des données Pokémon depuis [PokeAPI](https://pokeapi.co) sous forme de ressources `.tres`, prêtes à être utilisées dans un jeu — sans dépendance réseau à l'exécution. + +Contrairement à un import de masse, tu choisis explicitement quels pokémon importer (par id, nom, ou plage d'ids). + +## Installation + +Ajoute ce dépôt comme sous-module dans ton projet : + +```bash +git submodule add addons/pokeapi_importer +``` + +Le dossier **doit** s'appeler `pokeapi_importer` : les ressources générées référencent les scripts de l'addon par leur chemin. + +Puis active le plugin dans **Projet > Paramètres du projet > Extensions**. + +## Réglages + +Dans **Paramètres du projet**, sous `pokeapi_importer/` : + +| Réglage | Défaut | Rôle | +|---|---|---| +| `data_dir` | `res://data/pokeapi` | Dossier racine où sont écrites toutes les données importées | +| `languages` | `["fr", "en"]` | Langues importées pour les noms et descriptions (codes PokeAPI) | +| `models_dir` | *(vide)* | Dossier contenant tes modèles `.glb` faits maison, pour liaison automatique. Vide = pas de liaison | +| `max_concurrent_requests` | `8` | Nombre de requêtes HTTP simultanées pendant un import | + +## Utilisation + +Un dock **PokeAPI** apparaît dans l'éditeur (coin supérieur droit par défaut). Ordre d'import recommandé, car chaque étape peut dépendre de la précédente : + +1. **Importer les types** — indépendant, à faire une fois. +2. **Importer les talents** — indépendant, à faire une fois. +3. **Importer toutes les capacités** — indépendant, à faire une fois (~900 requêtes, quelques minutes). +4. **Importer les pokémon** — saisis une liste dans le champ texte (ids, noms, ou plages) : + ``` + 25, eevee, 1-9, mr-mime, charizard + ``` + Les pokémon déjà importés sont ignorés, sauf si tu coches **Écraser les fichiers existants**. + +Les formes méga-évolution et gigamax d'un pokémon sont importées automatiquement avec lui, à partir de `pokemon-species.varieties`. + +## Ce qui est importé + +| Donnée | Dossier | Ressource | +|---|---|---| +| Pokémon (et leurs formes méga/gmax) | `/pokemon/` | `PokemonData` (`.tres`), nommé `_.tres` | +| Sprites (normal + shiny) | `/sprites/` | `.png`, liés dans `PokemonData.menu_sprite` / `shiny_menu_sprite` | +| Cri | `/cries/` | `.ogg`, lié dans `PokemonData.cry_latest` | +| Capacités | `/moves/` | `MoveData` (`.tres`), un fichier par capacité | +| Types | `/types/` | `TypeData` (`.tres`), un fichier par type, avec relations d'efficacité | +| Talents | `/abilities/` | `AbilityData` (`.tres`), un fichier par talent | +| Chaînes d'évolution | `/evolution/` | `EvolutionNode` (`.tres`), un fichier par chaîne, référencé depuis `PokemonData.evolution_chain` | + +### `PokemonData` + +Champs principaux : `id`, `api_name`, `names` / `descriptions` (par langue), `types` (`Array[TypeData]`), `abilities` (`Array[PokemonAbility]`, avec `is_hidden`), `base_stats`, `height`, `weight`, `menu_sprite`, `shiny_menu_sprite`, `cry_latest`, `learnset` (`Array[LearnedMove]`), `evolution_chain`, `forms` (`Array[PokemonForm]`). + +Deux champs ne sont **jamais** remplis par l'import et à assigner toi-même dans l'inspecteur : +- `model_scene` / `shiny_albedo` — liés automatiquement seulement si `models_dir` est configuré et qu'un fichier `.glb` / `_shiny.png` existe à cet endroit. +- `TypeData.icon` — illustration de type, jamais fournie par PokeAPI ; assigne-la une fois, elle survit aux ré-imports suivants. + +### Localisation + +`get_display_name()` et `get_description()` (sur `PokemonData` et `MoveData`) renvoient le texte dans la langue courante de Godot (`TranslationServer.get_locale()`), avec repli sur l'anglais. + +### Évolutions + +Une chaîne (`EvolutionNode`) est un arbre récursif : `species_name` + `evolves_to` (`Array[EvolutionEdge]`). Chaque `EvolutionEdge` pointe vers un `EvolutionNode` cible et porte un tableau `conditions` (`Array[EvolutionCondition]`) — plusieurs conditions sur une même arête sont **alternatives** (une seule suffit), pour les cas comme Tyrogue qui évolue différemment selon ses stats. + +## Ce que le plugin ne fournit pas + +- **Le Pokedex** (autoload d'accès aux données en jeu) : volontairement laissé hors de l'addon, car pas utile à tous les projets. Un exemple d'implémentation est disponible dans le jeu qui a servi à concevoir ce plugin. +- **Les modèles 3D** : PokeAPI n'en fournit pas. Le plugin lie seulement tes propres `.glb` par convention de nommage. +- **Le calcul de combat, la capture, les stats réelles** (IV/EV) : ce plugin s'arrête à l'import des données brutes. + +## Limitations connues + +- **`EvolutionCondition.relative_physical_stats`** : l'API distingue "pas de condition" (`null`) de "attaque = défense" (`0`), ce que le champ entier ne distingue pas une fois converti. Concerne une poignée d'évolutions (Silcoon/Cascoon). +- **`PokemonForm.required_item`** est deviné à partir du nom de la forme (convention `ite` / `ite-x/-y`), PokeAPI ne liant pas explicitement l'objet de méga-évolution au pokémon. Corrige-le à la main si besoin : la valeur est préservée aux ré-imports suivants. +- **Formes régionales** (Alola, Galar, Hisui...) ne sont pas traitées comme des `PokemonForm` : ce sont des espèces à part entière à importer directement par leur nom complet (ex. `raichu-alola`). +- Le plugin télécharge à chaque import ce qui n'existe pas encore sur disque ; il ne revérifie jamais si les données de PokeAPI ont changé pour un fichier déjà présent (sauf avec **Écraser**). + +## Structure du dépôt + +``` +pokeapi_importer/ +├── plugin.cfg +├── plugin.gd # enregistrement du plugin et du dock +├── settings.gd # réglages du projet + chemins dérivés +├── data/ # types de ressources, utilisés aussi à l'exécution par le jeu +│ ├── l10n.gd +│ ├── move_data.gd +│ ├── learned_move.gd +│ ├── type_data.gd +│ ├── ability_data.gd +│ ├── pokemon_ability.gd +│ ├── evolution_condition.gd +│ ├── evolution_edge.gd +│ ├── evolution_node.gd +│ ├── pokemon_form.gd +│ └── pokemon_data.gd +└── editor/ # uniquement utilisé dans l'éditeur + ├── importer_dock.gd + ├── pokeapi_client.gd + ├── api_text.gd + ├── type_importer.gd + ├── ability_importer.gd + ├── move_importer.gd + ├── evolution_importer.gd + └── pokemon_importer.gd +``` + +## Compatibilité + +Testé avec Godot 4.4+. Le chargement des pokémon par id dans un `Pokedex` côté jeu s'appuie sur `ResourceLoader.list_directory()`, disponible à partir de la 4.4. \ No newline at end of file