From bdd95840b2f40586c1550e4b78ff64c661f4a85a Mon Sep 17 00:00:00 2001 From: Inter-Raptor Date: Fri, 10 Apr 2026 15:19:26 +0200 Subject: [PATCH 1/4] docs: expand READMEs with fun intro and deep technical sections --- README.md | 195 +++++++++---- RaptorLauncher_GameSDK/README.md | 268 +++++++----------- RaptorLauncher_GameSDK/dependencies/README.md | 74 +++-- .../examples/WiFiTouchConsole/README.md | 127 ++++----- .../exemple_games/JurassicLife/README.md | 188 ++++-------- .../JurassicLife/READMEcodeEN.md | 188 ++++-------- .../JurassicLife/READMEcodeFR.md | 188 ++++-------- 7 files changed, 518 insertions(+), 710 deletions(-) diff --git a/README.md b/README.md index c10e14e..600a44a 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,142 @@ -# RaptorLauncher00 - -## Erreurs fréquentes (version courte) -- **Ne surchargez pas `setup()`** : initialisez seulement le matériel critique, puis laissez le reste non-bloquant dans `loop()`. -- **Toujours valider la SD avant lancement** : un jeu sans `game.bin` ou avec `meta.json` invalide doit être refusé proprement. -- **Assets visuels optionnels** : `home_bg.bmp` et `splash.bmp` doivent toujours avoir un fallback (pas de crash si absents/corrompus). -- **Sprites/images trop lourds** : surveiller RAM/PSRAM, surtout pendant les chargements BMP/RAW. -- **Ne pas masquer les erreurs série** : le moniteur série est la source principale de diagnostic terrain. - -## Retours d'expérience (détaillé) - -### 1) ParaRunner -- **Problème observé** : ralentissements/intermittences quand beaucoup de sprites sont manipulés en même temps. -- **Cause probable** : allocations fréquentes et redraw trop complet. -- **Solution recommandée** : - - Précharger les ressources critiques. - - Éviter les allocations répétées dans la boucle jeu. - - Limiter les redraws aux zones réellement modifiées. - -### 2) WiFiTouchConsole -- **Problème observé** : démarrage instable quand WiFi + init tactile + rendu lourd sont déclenchés trop tôt. -- **Cause probable** : pics CPU/mémoire au boot et délais bloquants dans `setup()`. -- **Solution recommandée** : - - Garder `setup()` court. - - Déporter les actions non critiques en tâches progressives dans `loop()`. - - Ajouter des logs explicites avant/après chaque étape de boot. - -### 3) Gestion sprites / performances -- **Problème observé** : frame drops et micro-freezes avec de nombreuses images ou redimensionnements. -- **Cause probable** : traitements graphiques coûteux en continu. -- **Solution recommandée** : - - Préférer assets à la bonne résolution. - - Éviter les conversions à chaud. - - Garder une cadence stable (boucle courte, pas de délais longs). - -### 4) `setup()` vs `loop()` -- **Problème observé** : crashes aléatoires quand "trop de choses" démarrent en même temps. -- **Cause probable** : contention mémoire/temps CPU au boot. -- **Solution recommandée** : - - `setup()` : init minimale et robuste. - - `loop()` : orchestration progressive/non-bloquante. - - Sur erreur, toujours remonter un code/raison lisible au série. - -### 5) Logique d'état launcher -- **Problème observé** : ambiguïtés UX (touches non évidentes, pagination confuse, retour page 1 implicite). -- **Cause probable** : zones tactiles trop proches ou feedback visuel insuffisant. -- **Solution recommandée** : - - Définir des hitbox nettes. - - Ajouter un feedback visuel instantané. - - Afficher un indicateur de page clair (`1/3`) et un retour page 1 explicite. - -## Historique / corrigé -Certaines remarques anciennes peuvent être partiellement obsolètes (ex. correctifs matériels/pins RGB déjà appliqués). Conserver ces points comme **historique**, et préciser l'état **corrigé/non corrigé** au fur et à mesure. +# 🦖 RaptorLauncher00 — Le repaire des jeux dinos + +Bienvenue ! Ici tu peux lancer des jeux sur ESP32 depuis la SD, avec une UX propre, des sauvegardes stables et un debug sérieux. +Ce README est volontairement en **2 niveaux** : + +- **Partie 1 (Fun & simple)** 👉 pour démarrer vite sans se noyer. +- **Partie 2 (Ultra technique)** 👉 pour comprendre *tous* les détails, les limites et les bonnes pratiques pro. + +--- + +## 🎉 Partie 1 — Version fun et simple + +## 1) Le concept en 20 secondes +RaptorLauncher = un menu tactile qui lit des dossiers de jeux sur la carte SD. +Chaque jeu doit avoir des fichiers clés (`meta.json`, `game.bin`, visuels, save). + +Si un fichier est absent, on ne lance pas le jeu. +Si un jeu plante, on veut un retour launcher propre au boot suivant. + +## 2) Les 5 règles d’or (anti galère) +1. **`setup()` court** : init minimale seulement. +2. **`loop()` intelligente** : tâches lourdes en mode progressif/non bloquant. +3. **SD validée** avant lancement (`meta.json` + `game.bin`). +4. **Fallback visuel** si image absente/corrompue (`home_bg.bmp`, `splash.bmp`). +5. **Logs série** activés pendant le dev. + +## 3) Ta mini checklist avant test +- [ ] le launcher démarre sans freeze +- [ ] la pagination est claire et tactile +- [ ] un jeu invalide est refusé proprement +- [ ] retour launcher fonctionne après reboot forcé +- [ ] pas de redraw complet en boucle inutile + +## 4) Résumé “ce qui casse le plus souvent” +- trop de choses lancées dans `setup()` +- grosses images mal dimensionnées +- scans réseau bloquants +- peu de logs quand ça part en vrille + +--- + +## 🛠️ Partie 2 — Version très technique (détaillée) + +## A) Pipeline de boot recommandé + +### Étape A1 — Init critique (dans `setup()`) +- init écran + I/O minimum +- init stockage SD +- afficher un état de boot explicite +- **ne pas** lancer les jobs longs ici + +### Étape A2 — Armement sécurité launcher +- activer le mécanisme de retour launcher “prochain boot” +- utile contre crash watchdog / reboot inattendu + +### Étape A3 — Passage en orchestration `loop()` +- scanner, décoder, charger progressif +- éviter les `delay()` longs et appels bloquants + +## B) Validation stricte d’un dossier jeu + +Un dossier jeu valide doit fournir au minimum : +- `meta.json` +- `game.bin` + +Fichiers usuels recommandés : +- `icon.raw` +- `title.raw` +- `sauv.json` (généré ou pré-existant selon jeu) + +### Contrôles `meta.json` recommandés +- champs texte non vides (`name`, `author`) +- dimensions cohérentes (`icon_w/h`, `title_w/h`) +- noms de fichiers référencés réellement présents +- format JSON strict (pas de trailing comma) + +## C) Rendu graphique et performances + +### C1 — Éviter le scintillement +- utiliser un rendu événementiel +- redessiner uniquement les zones invalidées +- éviter refresh plein écran à chaque frame + +### C2 — Budget mémoire +- surveiller RAM/PSRAM avant/après chargements +- préférer assets à résolution native écran +- limiter les conversions runtime (BMP/JPG/PNG -> RAW) + +### C3 — Boucle de rendu +- cadence stable +- pas de double boucle pixel si pas nécessaire +- grouper les opérations de dessin par couche logique + +## D) UX launcher (navigation tactile) + +- hitbox séparées et lisibles +- feedback visuel immédiat au tap +- indicateur de page (`1/3`, `2/3`, ...) +- transitions simples, prévisibles et rapides + +## E) Journalisation / Debug terrain + +Logs minimum utiles : +- état SD (montage OK/KO) +- parse JSON OK/KO + code erreur +- chargement assets (succès/échec + taille) +- état mémoire avant/après action lourde +- transitions d’état UI (menu/page/selection) + +## F) Gestion des erreurs (stratégie) + +- **Erreur non critique** (asset manquant) : fallback visuel + log +- **Erreur critique** (binaire absent/corrompu) : refus lancement + message clair +- **Erreur système** (reset/crash) : retour launcher armé + +## G) Historique des retours dev (synthèse technique) + +### ParaRunner +- ralentissements causés par redraw trop global + allocations répétées +- fix : préchargement + redraw local + +### WiFiTouchConsole +- boot instable quand Wi‑Fi + tactile + rendu lourd démarrent ensemble +- fix : setup minimal + tâches réseau progressives en loop + +### Cas général +- collisions/logique gameplay à verrouiller tôt pour éviter désynchronisations +- constantes critiques centralisées pour faciliter tuning et maintenance + +--- + +## 📌 Convention de maintenance docs + +Pour chaque changement important, documenter : +1. **Quoi** (fonction, écran, pipeline) +2. **Pourquoi** (bug, perf, UX, compat) +3. **Impact** (launcher, jeux existants, assets) +4. **Statut** (`corrigé`, `à surveiller`, `non corrigé`) + +--- + +Amuse-toi bien, et fais rugir les dinos… sans faire rugir le watchdog 🦕🔥 diff --git a/RaptorLauncher_GameSDK/README.md b/RaptorLauncher_GameSDK/README.md index fb6f840..4f8d45f 100644 --- a/RaptorLauncher_GameSDK/README.md +++ b/RaptorLauncher_GameSDK/README.md @@ -1,64 +1,75 @@ -# RaptorLauncher Game SDK PRO (Arduino IDE) +# 🧰 RaptorLauncher Game SDK PRO (Arduino IDE) -Ce dépôt vise un principe simple : **API publique, documentation et implémentation doivent rester alignées**. +Ce SDK te permet de créer des jeux compatibles RaptorLauncher avec un cadre stable. +Doc en **2 niveaux** : +- **Partie 1** : démarrage rapide, fun, sans friction. +- **Partie 2** : détails techniques complets (API, contraintes, workflow pro). -La **source de vérité** est : -- `arduino_template/src/raptor_game_sdk.h` - -Si une fonction n'est pas déclarée dans ce fichier, elle ne doit pas être présentée comme disponible. +> Source de vérité API publique : `arduino_template/src/raptor_game_sdk.h` --- -## 1) Structure du kit +## 🎉 Partie 1 — Démarrage rapide (fun & simple) -- `docs/ASSETS_AUDIO_WIFI_POWER.md` - - guide complet assets/audio/wifi/luminosité/batterie/sd -- `docs/API_PUBLIC.md` - - liste exacte des fonctions exposées + distinction core/optionnel -- `arduino_template/` - - `arduino_template.ino` : template jeu prêt à compiler - - `src/raptor_game_config.h` : pins + conventions meta/save - - `src/raptor_game_sdk.h/.cpp` : API publique et implémentation -- `examples/SDK_TestLab/` - - sketch de validation officiel du SDK (compile = cohérence API) -- `sd_template/games/MonJeu/` - - `meta.json` modèle compatible launcher - - `assets/` pour tes ressources -- `docs/libraries_arduino_ide.txt` - - liste des bibliothèques IDE Arduino -- `dependencies/README.md` - - stratégie recommandée pour gérer les dépendances sans alourdir le repo +## 1) Ce que fait le SDK +- te donne une API de rendu, input, save, Wi‑Fi, etc. +- uniformise le comportement entre jeux +- protège la compatibilité launcher + +## 2) Les dossiers clés +- `arduino_template/` : base de ton jeu +- `sd_template/` : structure SD modèle +- `docs/API_PUBLIC.md` : fonctions réellement exposées +- `examples/SDK_TestLab/` : validation de référence + +## 3) Les 4 étapes pour lancer un jeu +1. Installe le core ESP32 + libs listées +2. Copie `arduino_template/` dans ton dossier sketch +3. Mets le bon `SDK_GAME_FOLDER_NAME` +4. Compile, flash, place `game.bin` + `meta.json` sur la SD + +## 4) Astuce sécurité +Le SDK arme automatiquement le retour launcher au prochain boot via `sdk.begin()` (boot safety). --- -## 2) Niveaux de support +## 🧪 Partie 2 — Détails techniques complets + +## A) Arborescence du kit (rôle de chaque bloc) -### SDK de base (disponible) -- affichage simple (`clear`, `drawRect`, `fillRect`, texte) -- boutons (MCP23017) -- tactile (`touchX/touchY`, pressed/released) -- `drawRaw565(...)` -- `playBeep(...)` -- JSON save/load (`saveJson/loadJson`) +- `arduino_template/` + - `arduino_template.ino` : point d’entrée sketch + - `src/raptor_game_sdk.h/.cpp` : API + implémentation + - `src/raptor_game_config.h` : constantes projet (dossier jeu, pins, options) +- `docs/API_PUBLIC.md` : index API officiel +- `docs/ASSETS_AUDIO_WIFI_POWER.md` : détails assets/audio/réseau/power +- `sd_template/games/MonJeu/` : structure SD compatible launcher +- `examples/SDK_TestLab/` : exemple de non-régression fonctionnelle +- `dependencies/README.md` : stratégie dépendances + +## B) API publique — périmètre réel + +### B1 — Fonctions cœur disponibles +- rendu 2D basique (`clear`, `drawRect`, `fillRect`, texte) +- input boutons MCP23017 +- input tactile (`touchX`, `touchY`, pressed/released) +- rendu raw (`drawRaw565`) +- bip (`playBeep`) +- persistance (`saveJson`, `loadJson`, `saveJsonPath`) - LED RGB -- capteur luminosité +- capteur lumière - batterie (si ADC configuré) - Wi‑Fi via `settings.json` -- boot safety / retour launcher -### SDK optionnel selon build -- `drawBmp(...)` -- `drawJpg(...)` -- `drawPng(...)` -- `playWav(...)` -- `playMp3(...)` +### B2 — Fonctions optionnelles selon build/libs +- `drawBmp`, `drawJpg`, `drawPng` +- `playWav`, `playMp3` -Ces appels existent toujours dans l'API publique, mais leur réussite dépend des capacités compilées. +> Elles peuvent exister dans l’API mais retourner `false` si le support n’est pas compilé ou dépendances absentes. ---- - -## 3) Fonctions de capacité (à vérifier avant usage optionnel) +## C) Négociation de capacités (obligatoire avant appel optionnel) +Vérifie systématiquement : - `hasBmpSupport()` - `hasJpgSupport()` - `hasPngSupport()` @@ -70,97 +81,37 @@ Exemple recommandé : ```cpp if (sdk.hasPngSupport()) { (void)sdk.drawPng(sdk.assetPath("overlay.png"), 0, 0); +} else { + // fallback simple (texte / raw) } ``` ---- - -## 4) Tableau de support réel (état actuel) - -| Fonction | État | -|---|---| -| `drawRaw565` | OK | -| `drawBmp` | OK (si fichier présent sur SD) | -| `drawJpg` | OK (si fichier présent sur SD) | -| `drawPng` | OK (si fichier présent sur SD) | -| `playBeep` | OK | -| `playWav` | OK si lib audio installée; sinon `false` | -| `playMp3` | OK si lib audio installée; sinon `false` | -| `saveJson/loadJson` | OK | -| `wifi*` | OK (si paramètres présents) | -| `battery*` | OK (si pin ADC batterie configurée) | -| `touch*` | OK | - -### Limites connues -- GIF/WebP non supportés. -- Les wrappers audio WAV/MP3 sont bloquants (lecture synchrone). - -### ⚠️ Erreurs fréquentes à éviter (version courte) -- Ne pas faire de redraw complet à chaque frame (risque de scintillement). -- Éviter les boucles de rendu pixel-par-pixel (`fillRect(1x1)`), coûteuses en performances. -- Ne pas lancer de tâches lourdes en `setup()` (scan réseau, traitements bloquants). -- Caler tôt la physique + hitbox (stand/duck/jump) pour garder un gameplay cohérent. -- Centraliser pins/constantes/timings pour faciliter debug et équilibrage. -- Utiliser le moniteur série pour diagnostiquer vite (SD, meta, bin, mémoire, réseau). -- Préférer un rendu événementiel: redraw uniquement quand l'état change. - -### Retours d'expérience DEV (version détaillée) -- **Scintillement UI** - - Cause: redraw complet en boucle. - - Solution: rendu événementiel (redraw seulement quand l'état change). -- **Chutes de performances** - - Cause: rendu pixel-par-pixel massif (`fillRect(1x1)` en doubles boucles). - - Solution: réduire ces zones, regrouper les dessins, pré-calculer ce qui peut l'être. -- **Freeze / retour launcher au boot** - - Cause: opérations lourdes en `setup()`. - - Solution: setup minimal, puis traitement progressif en `loop()` (asynchrone/étagé). -- **Collisions ou sensations de saut incohérentes** - - Cause: physique et hitbox réglées trop tard. - - Solution: verrouiller tôt `GRAVITY`, `JUMP_VELOCITY`, positions Y et presets hitbox. -- **Debug difficile** - - Cause: constantes dispersées et manque de logs. - - Solution: centraliser les paramètres clés + logs série simples (`spawn/hit/despawn/state`). - ---- - -## 5) Règles PRO prévues - -### A. Boot safety launcher -Au `sdk.begin()`, le SDK appelle automatiquement `armReturnToLauncherOnNextBoot()`. -Donc même si le jeu crash/reboot, le prochain boot repart sur le launcher (si le label launcher a été mémorisé par le launcher). - -### B. Sauvegarde JSON standard -Le chemin de save est construit automatiquement: +## D) Conventions launcher imposées par le SDK +### D1 — Sauvegarde +Chemin standard : `/games//sauv.json` -Fonctions prêtes: -- `sdk.saveJson(doc)` -- `sdk.loadJson(doc)` -- `sdk.saveJsonPath()` +### D2 — `meta.json` +Conventions attendues : +- `icon_w=50`, `icon_h=50` +- `title_w=320`, `title_h=240` +- `save="sauv.json"` +- `bin="game.bin"` -### C. Meta.json contraint -Par convention de ce kit: -- `icon_w = 50`, `icon_h = 50` -- `title_w = 320`, `title_h = 240` -- `save = "sauv.json"` -- `bin = "game.bin"` +### D3 — Calibration tactile +Le SDK lit `/settings.json` pour : +- `touch_x_min/max`, `touch_y_min/max` +- `touch_offset_x/y` -### D. Calibration tactile depuis le launcher -Le SDK lit automatiquement `/settings.json` (même fichier que le launcher) pour récupérer: -- `touch_x_min`, `touch_x_max`, `touch_y_min`, `touch_y_max` -- `touch_offset_x`, `touch_offset_y` +Fallback sur macros de `raptor_game_config.h` si fichier absent/invalide. -Si le fichier est absent/invalide, le SDK retombe sur les macros de `raptor_game_config.h`. +## E) Installation et build (procédure complète) ---- - -## 6) Installation rapide - -1. Installer la carte **ESP32 by Espressif**. +1. Installer **ESP32 by Espressif** (Board Manager). 2. Installer les libs de `docs/libraries_arduino_ide.txt`. -3. Copier `arduino_template/` dans ton dossier de sketch. -4. Garder la structure **officielle unique** suivante : +3. Copier `arduino_template/` vers `MonJeu/`. +4. Vérifier la structure : ```text MonJeu/ @@ -171,44 +122,41 @@ MonJeu/ └── raptor_game_config.h ``` -5. Mettre le bon nom de dossier jeu dans `SDK_GAME_FOLDER_NAME` (`src/raptor_game_config.h`). -6. Compiler/flash. +5. Renseigner `SDK_GAME_FOLDER_NAME`. +6. Compiler. +7. Produire `game.bin`. +8. Créer dossier SD `/games/MonJeu/` + `meta.json` + assets. ---- +## F) Contrat de test avant release -## 7) Exemple meta.json (obligatoire) - -```json -{ - "name": "Mon Jeu", - "author": "Ton Nom", - "description": "Mon premier jeu compatible RaptorLauncher", - "type": "mixed", - "icon": "icon.raw", - "icon_w": 50, - "icon_h": 50, - "title": "title.raw", - "title_w": 320, - "title_h": 240, - "bin": "game.bin", - "save": "sauv.json" -} -``` +### F1 — Fonctionnel +- boot jeu sans freeze +- START/quit retour launcher +- tactile cohérent avec calibration +- save/load JSON validé + +### F2 — Robustesse +- comportement si asset manquant +- comportement si `settings.json` absent +- comportement si fonction optionnelle indisponible + +### F3 — Performance +- pas de redraw intégral permanent +- pas de charges lourdes en `setup()` +- logs série exploitables + +## G) Documentation visuelle (images/GIF) + +Si tu ajoutes des images/GIF par écran/realm : +- garde les médias proches du README concerné, +- ajoute un caption “ce qu’on voit / ce qu’on teste”, +- indique si le visuel correspond à 2432S022, 2432S028 ou ILI9341. --- -## 8) Checklist avant test - -- [ ] dossier SD: `/games/MonJeu/` -- [ ] `meta.json` présent -- [ ] `game.bin` présent -- [ ] `icon.raw` en **50x50** -- [ ] `title.raw` en **320x240** -- [ ] nom de dossier aligné avec `SDK_GAME_FOLDER_NAME` -- [ ] `settings.json` launcher présent (optionnel mais recommandé) -- [ ] test bouton START (retour launcher) -- [ ] test tactile (coordonnées et déplacement) -- [ ] test écriture `sauv.json` -- [ ] test exemple `examples/SDK_TestLab` - -Ce kit te donne une base solide pour créer vite, proprement, et garder la compatibilité launcher. +## ✅ Checklist rapide finale +- [ ] API utilisée = déclarée dans `raptor_game_sdk.h` +- [ ] `meta.json` conforme +- [ ] fallback si optionnel absent +- [ ] save path correct +- [ ] tests manuels validés diff --git a/RaptorLauncher_GameSDK/dependencies/README.md b/RaptorLauncher_GameSDK/dependencies/README.md index 0defb62..a74e2e4 100644 --- a/RaptorLauncher_GameSDK/dependencies/README.md +++ b/RaptorLauncher_GameSDK/dependencies/README.md @@ -1,27 +1,65 @@ -# Dépendances Arduino - RaptorLauncher GameSDK +# 📦 Dépendances Arduino — RaptorLauncher GameSDK -Ce dossier remplace l'idée d'un dossier `bibliotheque/` avec des copies complètes de libs. +README en 2 parties : +- rapide pour comprendre la logique +- technique pour verrouiller la reproductibilité -## Pourquoi -Versionner des bibliothèques entières dans le repo alourdit fortement le projet et crée vite des conflits. +--- -## Stratégie recommandée -- Garder ici uniquement **la liste des dépendances validées**. -- Installer les libs via l'IDE Arduino (Library Manager). -- Ne pas commiter les sources complètes des libs externes, sauf besoin exceptionnel. +## 🎉 Partie 1 — version simple -## Dépendances nécessaires (SDK de base) +## Pourquoi on ne commit pas toutes les libs ? +Parce que ça alourdit le repo et crée vite des conflits de versions. + +## Règle simple +- installer les dépendances via Arduino Library Manager +- garder ici la doc des libs validées + +## Dépendances cœur - LovyanGFX - XPT2046_Touchscreen -- Adafruit MCP23017 (Adafruit_MCP23X17) +- Adafruit_MCP23X17 - ArduinoJson -- ESP32 board package (Espressif) +- Core ESP32 (Espressif) + +## Optionnelles +- PNGdec +- JPEGDEC +- ESP8266Audio + +--- + +## 🛠️ Partie 2 — version très technique + +## A) Politique de dépendances + +### A1 — Principe +Le repository versionne le code applicatif + docs, pas des copies complètes de libs tierces (sauf exception critique). + +### A2 — Objectifs +- réduire poids Git +- simplifier merges/rebases +- faciliter montée de version contrôlée + +## B) Installation recommandée + +1. Installer le board package ESP32 (Espressif) +2. Installer les libs cœur +3. Ajouter optionnelles selon fonctionnalités activées (PNG/JPG/Audio) + +## C) Verrouillage de versions (reproductibilité) + +Créer `versions.lock.md` avec : +- nom de chaque lib +- version exacte +- version core ESP32 +- version Arduino IDE +- date et contexte de validation -## Dépendances optionnelles (features avancées) -- PNGdec (PNG custom) -- JPEGDEC (JPEG custom) -- ESP8266Audio (WAV/MP3 avancé) +## D) Stratégie de debug dépendances -## Remarque -Si tu veux figer des versions exactes, ajoute un fichier `versions.lock.md` dans ce dossier -avec les numéros de version testés dans ton environnement. +Quand un build casse après update : +1. comparer avec `versions.lock.md` +2. revenir à la dernière combinaison validée +3. retester `SDK_TestLab` +4. ne promouvoir une nouvelle version qu’après tests fonctionnels (rendu, input, save, audio) diff --git a/RaptorLauncher_GameSDK/examples/WiFiTouchConsole/README.md b/RaptorLauncher_GameSDK/examples/WiFiTouchConsole/README.md index 4bed1f9..5fb8ea1 100644 --- a/RaptorLauncher_GameSDK/examples/WiFiTouchConsole/README.md +++ b/RaptorLauncher_GameSDK/examples/WiFiTouchConsole/README.md @@ -1,19 +1,34 @@ -# WiFiTouchConsole +# 📶 WiFiTouchConsole -Exemple SDK "pas un jeu" pour piloter un mini outil réseau en tactile. +Exemple SDK "outil réseau tactile". +Doc en 2 parties : rapide puis technique. -## Oui, tu peux le mettre sur la carte SD -Le dossier du jeu doit être présent sur la SD dans `/games//` avec `meta.json`, `game.bin`, `icon.raw`, `title.raw` et `config.json`. +--- -Un template prêt à copier est maintenant fourni ici: +## 🎉 Partie 1 — version simple -`RaptorLauncher_GameSDK/sd_template/games/WiFiTouchConsole/` +## À quoi sert ce projet ? +- voir les Wi‑Fi autour +- se connecter au réseau perso +- scanner les appareils du LAN +- garder un historique sur SD -Un template de `settings.json` est fourni dans: +## Contrôles rapides +- onglets haut : M1/M2/M3/M4 +- `Quit` : retour launcher +- glisser vertical : scroll +- bandeau rouge : annuler action en cours -`RaptorLauncher_GameSDK/sd_template/settings.json` +## Fichiers SD à avoir +Dans `/games/WiFiTouchConsole/` : +- `meta.json`, `config.json`, `game.bin`, `icon.raw`, `title.raw` +- `sauv.json` sera créé automatiquement -## Arborescence SD complète (attendue) +--- + +## 🛠️ Partie 2 — version très technique + +## A) Structure SD détaillée ```text /games/WiFiTouchConsole/ @@ -22,81 +37,59 @@ Un template de `settings.json` est fourni dans: ├── game.bin ├── icon.raw ├── title.raw -├── sauv.json (créé automatiquement) +├── sauv.json └── assets/ ``` -> Important: le nom du dossier SD doit correspondre à `SDK_GAME_FOLDER_NAME` au moment de la compilation. - +Templates : +- `RaptorLauncher_GameSDK/sd_template/games/WiFiTouchConsole/` +- `RaptorLauncher_GameSDK/sd_template/settings.json` -## Compilation Arduino IDE (important) -Cet exemple inclut des fichiers pont (`raptor_game_sdk.cpp/.h` et `raptor_game_config.h`) -pour éviter l'erreur de link "undefined reference to `RaptorGameSDK::...`" -quand tu compiles directement `WiFiTouchConsole.ino`. +Contrainte : nom dossier SD == `SDK_GAME_FOLDER_NAME` compilé. -Tu peux donc ouvrir ce dossier tel quel dans Arduino IDE et compiler sans copier manuellement le SDK. +## B) Build Arduino IDE -## Fonctionnalités -- **Menu 1 (M1 WiFi)**: scanner tous les Wi-Fi à portée (SSID, puissance RSSI, canal, chiffrement). -- **Menu 2 (M2 LAN)**: se connecter au réseau perso via `/settings.json` puis lister les appareils détectés sur le sous-réseau local. -- **Menu 3 (M3 WiFiH)**: historique des reseaux Wi-Fi vus (meme apres disparition) avec dernier signal + min/max + dernier "vu". -- **Menu 4 (M4 DevH)**: historique des appareils vus sur ton reseau perso avec dernier "vu" + min/max du signal lien Wi-Fi (RSSI AP). -- Scroll **tactile vertical** (glisser haut/bas) pour parcourir de longues listes. +Ce dossier inclut des fichiers pont : +- `raptor_game_sdk.cpp/.h` +- `raptor_game_config.h` -## Wi-Fi depuis /settings.json (racine SD) -Le menu 2 lit d'abord les identifiants dans le fichier global du launcher: +But : éviter `undefined reference to RaptorGameSDK::...` en compile directe. -`/settings.json` - -Champs attendus: - -```json -{ - "wifi_ssid": "MonWifi", - "wifi_pass": "MonMotDePasse" -} -``` +## C) Menus et responsabilités -Le menu 2 utilise uniquement `/settings.json` (meme format que le launcher). -Lors d'un tap sur **Se connecter**, le jeu lit `wifi_ssid`/`wifi_pass` et force la tentative de connexion (meme si `wifi_enabled` est a `false`). +- **M1 WiFi** : scan SSID/RSSI/canal/chiffrement +- **M2 LAN** : connexion Wi‑Fi + découverte hôtes locaux +- **M3 WiFiH** : historique réseaux vus (min/max/dernier) +- **M4 DevH** : historique devices vus (min/max/dernier) -## Contrôles (100% tactile) -- **Onglets hauts**: M1 WiFi / M2 LAN / M3 WiFiH / M4 DevH -- **Bouton haut droite `Quit`**: retour launcher -- **Barre action (ligne 2)**: lancer scan Wi‑Fi, se connecter, ou rescanner le LAN -- **Glisser verticalement** dans la zone de contenu: scroll longues listes -- **Tap sur un Wi‑Fi / appareil**: affiche plus de details dans le bandeau du bas -- **Bandeau rouge en bas** (quand visible): annuler une connexion ou un scan réseau en cours +## D) Paramètres Wi‑Fi -## Note sur la découverte d'appareils -La détection est faite en 2 etapes sur le `/24` local: -1) sonde ARP indirecte (emission UDP pour forcer la resolution ARP), -2) fallback par tentatives TCP multi-ports (80, 443, 53, 22, 445, 139, 1883, 554, 8008). +Source utilisée : `/settings.json` (racine SD) +Champs attendus : `wifi_ssid`, `wifi_pass`. -Important: ce n'est toujours **pas** une liste absolue de tous les clients connectés au routeur. -Le scan marque aussi un hote comme probable actif si la connexion echoue tres vite (heuristique RST/ICMP). -Malgre ca, certains appareils peuvent encore ne pas apparaitre (isolation AP, VLAN, pare-feu, etc.). +Au tap `Se connecter`, tentative forcée avec ces valeurs. -## Anti-scintillement -Le rendu est maintenant **événementiel**: l'écran se redessine seulement quand quelque chose change (tap, scroll, nouveaux résultats), au lieu d'un refresh permanent. +## E) Mécanisme de découverte LAN +Pipeline en 2 étages sur `/24` : +1. stimulation ARP indirecte via UDP +2. fallback TCP multi-ports (80, 443, 53, 22, 445, 139, 1883, 554, 8008) -## Stabilite launcher -- Le premier scan Wi-Fi est lance apres le boot (pas dans `setup()`). -- Le scan Wi-Fi est non bloquant (asynchrone). -- Le scan LAN est progressif (par etapes dans `loop()`), pour eviter les freezes et retours launcher. +Limites connues : AP isolation/VLAN/firewall peuvent masquer certains hôtes. +## F) Anti-freeze / anti-scintillement -## UX connexion -- Quand tu tapes **Se connecter**, l'etat passe immediatement a `Connexion...` (feedback direct). -- Le jeu reste tactile pendant l'attente et tu peux annuler via le bandeau du bas. +- rendu événementiel uniquement +- scan Wi‑Fi asynchrone +- scan LAN progressif en `loop()` +- feedback d’état immédiat côté UI +## G) Historique persistant -## Fichiers historiques sur SD -Le jeu enregistre automatiquement dans: -- `/games/WiFiTouchConsole/seen_wifi.log` (journal brut) -- `/games/WiFiTouchConsole/seen_devices.log` (journal brut) -- `/games/WiFiTouchConsole/seen_wifi_stats.json` (resume persistant: min/max/dernier vu) -- `/games/WiFiTouchConsole/seen_devices_stats.json` (resume persistant: min/max/dernier vu) +Fichiers générés : +- `seen_wifi.log` +- `seen_devices.log` +- `seen_wifi_stats.json` +- `seen_devices_stats.json` -Chaque scan met a jour les journaux + les resumes JSON. Ces historiques sont consultables dans M3 et M4. +Ces fichiers alimentent M3/M4. diff --git a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/README.md b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/README.md index 080f59d..05c814b 100644 --- a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/README.md +++ b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/README.md @@ -1,166 +1,80 @@ -# 🦖 JurassicLife (Arduino / ESP32) +# 🦖 JurassicLife — README principal (EN) -This code is made to run on: -- **2432S022** -- **2432S028** -- **Classic ESP32 + ILI9341 320×240 screen** (profile `DISPLAY_PROFILE_ILI9341_320x240`) - -The idea is simple: you change 2–3 lines at the top of the code, then you **upload**. +Two-level documentation: +1. **Fun quick start** (fast setup) +2. **Technical deep dive** (all key details) --- -## 📌 Table of contents -1. Supported boards -2. Change the board type (line 11) -3. Enable / disable audio (line 14) -4. Upload -5. Optional: clickable rotary encoder or 3 buttons -6. Change the pins (the `#if DISPLAY_PROFILE...` block) -7. Wiring diagrams (encoder / buttons) -8. UI differences between 2432S022 and 2432S028 -9. Save: SD card required +## 🎉 Part 1 — Quick start (friendly) ---- +## Hardware supported +- 2432S022 +- 2432S028 +- ESP32 + ILI9341 320×240 + +## Super short setup +1. Set `DISPLAY_PROFILE` +2. Set `ENABLE_AUDIO` (0/1) +3. Upload from Arduino IDE +4. Put SD card if you want persistent saves -## 1) ✅ Supported boards +## Controls +- touch is always supported +- encoder / buttons are optional (board dependent) -- **2432S022**: supported (warning: no physical controls planned) -- **2432S028**: supported (physical controls possible) -- **ESP32 + ILI9341 320×240**: supported via `DISPLAY_PROFILE_ILI9341_320x240` +## Visual docs +Use your screenshots/GIFs as reference for each screen/realm. --- -## 2) 🔁 Change the board type in the code (line 11) +## 🛠️ Part 2 — Technical deep dive -To choose your board, edit line **11**: +## A) Display profile selection +Edit the profile macro in code: ```cpp #define DISPLAY_PROFILE DISPLAY_PROFILE_2432S022 ``` -You replace **only the right side** with: - -### ➜ For 2432S028 -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_2432S028 -``` - -### ➜ For ESP32 + ILI9341 320×240 screen -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_ILI9341_320x240 -``` - -> ✅ Do not change `#define DISPLAY_PROFILE`: you only change the value after it. - ---- - -## 3) 🔊 Enable / disable audio (line 14) +Allowed values: +- `DISPLAY_PROFILE_2432S022` +- `DISPLAY_PROFILE_2432S028` +- `DISPLAY_PROFILE_ILI9341_320x240` -You can enable or disable audio by editing line **14**: +## B) Audio switch ```cpp #define ENABLE_AUDIO 1 ``` -- `#define ENABLE_AUDIO 0` → audio disabled -- `#define ENABLE_AUDIO 1` → audio enabled - -✅ If you enable audio, a **new button** will appear in the UI that lets you: -- **switch** between the different audio modes -- and also **increase / decrease the volume** - ---- - -## 4) ⬆️ Upload (the easy part) - -Once you have chosen: -- your board (`DISPLAY_PROFILE`) -- and whether you want audio (`ENABLE_AUDIO`) - -➡️ You just need to **upload** from the Arduino IDE. - ---- - -## 5) 🎮 Optional: add a clickable encoder or 3 buttons +- `0`: disable audio paths +- `1`: enable audio UI/control paths -Optionally, you can add: -- a **clickable rotary encoder** -- or **3 navigation buttons** (Left / OK / Right) +## C) Optional physical inputs -⚠️ **Warning: this is not possible on 2432S022** (not enough accessible pins, so it’s not planned “properly”). -➡️ On **2432S022**, the recommended use = **touch only**. +You can configure: +- rotary encoder (A/B/button) +- or 3 buttons (Left/OK/Right) -On **2432S028** and on the **ESP32 + ILI9341** profile, it’s possible. +Pin logic: +- pin `-1` means disabled +- use encoder **or** buttons, not both simultaneously ---- - -## 6) 🧷 Change the used pins (block in the code) - -Pins are changed here (in your code): - -```cpp -#if DISPLAY_PROFILE == DISPLAY_PROFILE_2432S022 - static const int ENC_A = -1; - static const int ENC_B = -1; - static const int ENC_BTN = -1; - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#elif DISPLAY_PROFILE == DISPLAY_PROFILE_2432S028 - static const int ENC_A = 22; // A=22 - static const int ENC_B = 27; // B=27 - static const int ENC_BTN = 35; // BTN=35 (or -1 to disable) - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#else // DISPLAY_PROFILE_ILI9341_320x240 (classic ESP32 with a screen) - static const int ENC_A = 22; // default encoder pins - static const int ENC_B = 27; - static const int ENC_BTN = 35; - - // 3-button option: set ENC_* to -1 and define BTN_* (default pins to adapt) - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#endif -``` - -✅ How it works: -- Setting a pin to `-1` = **disabled** -- You choose **either** encoder **or** 3 buttons: - - **Encoder**: set `ENC_A / ENC_B / ENC_BTN` and keep `BTN_* = -1` - - **3 buttons**: set `ENC_* = -1` then define `BTN_LEFT / BTN_RIGHT / BTN_OK` - -⚠️ On 2432S028, if you use `ENC_BTN = 35` (or another similar pin), you may need to add a **pull-up resistor** (see your diagram). - ---- - -## 7) 🧷 Wiring diagrams (encoder / buttons) - -I made a wiring diagram for: -- **encoder** mode -- **3 buttons** mode - -➡️ They are in the `screenshot/` folder of the repo (wiring images). - ---- - -## 8) ⚠️ UI differences: 2432S022 vs 2432S028 - -Warning: if you are on **2432S022**, you won’t have exactly the same UI as on **2432S028**. - -- **2432S028** has a bigger screen → allows a different, more comfortable layout -- **2432S022** is smaller → the UI is adapted to that size - -So it’s normal if the display isn’t identical. - ---- +## D) Board-specific notes +- 2432S022: limited accessible pins, touch-first recommendation +- 2432S028: more practical for physical controls +- ILI9341 profile: flexible custom wiring -## 9) 💾 Save: SD card required +## E) UI/layout differences +Screen size differs by board, so layout can differ intentionally. -In all cases, if you want a **save after power-off** for your dinosaur: -➡️ you need a **microSD card**. +## F) Persistence model +Persistent dinosaur save requires microSD. +No SD = no power-off persistence. -Without an SD card, you will lose the save after power-off/restart. +## G) Visual QA guidance +For each screenshot/GIF, add: +- hardware profile used +- expected user interaction +- expected result (state/UI feedback) diff --git a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeEN.md b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeEN.md index 080f59d..176851c 100644 --- a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeEN.md +++ b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeEN.md @@ -1,166 +1,78 @@ -# 🦖 JurassicLife (Arduino / ESP32) +# 🦖 JurassicLife — Code Guide (EN) -This code is made to run on: -- **2432S022** -- **2432S028** -- **Classic ESP32 + ILI9341 320×240 screen** (profile `DISPLAY_PROFILE_ILI9341_320x240`) - -The idea is simple: you change 2–3 lines at the top of the code, then you **upload**. +This file is split in two levels: +- **Part 1**: simple onboarding +- **Part 2**: technical, step-by-step reference --- -## 📌 Table of contents -1. Supported boards -2. Change the board type (line 11) -3. Enable / disable audio (line 14) -4. Upload -5. Optional: clickable rotary encoder or 3 buttons -6. Change the pins (the `#if DISPLAY_PROFILE...` block) -7. Wiring diagrams (encoder / buttons) -8. UI differences between 2432S022 and 2432S028 -9. Save: SD card required +## 🎉 Part 1 — Friendly onboarding ---- +## 1) What to edit first +At the top of the sketch, update: +- `DISPLAY_PROFILE` +- `ENABLE_AUDIO` + +Then upload. That’s the minimum path. -## 1) ✅ Supported boards +## 2) If you want physical controls +- choose rotary encoder **or** 3-button mode +- keep unused pins to `-1` -- **2432S022**: supported (warning: no physical controls planned) -- **2432S028**: supported (physical controls possible) -- **ESP32 + ILI9341 320×240**: supported via `DISPLAY_PROFILE_ILI9341_320x240` +## 3) If you want real save persistence +Insert microSD card. --- -## 2) 🔁 Change the board type in the code (line 11) +## 🛠️ Part 2 — Full technical reference -To choose your board, edit line **11**: +## A) Supported profiles +- `DISPLAY_PROFILE_2432S022` +- `DISPLAY_PROFILE_2432S028` +- `DISPLAY_PROFILE_ILI9341_320x240` + +Macro shape (do not rename left side): ```cpp #define DISPLAY_PROFILE DISPLAY_PROFILE_2432S022 ``` -You replace **only the right side** with: - -### ➜ For 2432S028 -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_2432S028 -``` - -### ➜ For ESP32 + ILI9341 320×240 screen -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_ILI9341_320x240 -``` - -> ✅ Do not change `#define DISPLAY_PROFILE`: you only change the value after it. - ---- - -## 3) 🔊 Enable / disable audio (line 14) - -You can enable or disable audio by editing line **14**: +## B) Audio mode ```cpp #define ENABLE_AUDIO 1 ``` -- `#define ENABLE_AUDIO 0` → audio disabled -- `#define ENABLE_AUDIO 1` → audio enabled - -✅ If you enable audio, a **new button** will appear in the UI that lets you: -- **switch** between the different audio modes -- and also **increase / decrease the volume** - ---- - -## 4) ⬆️ Upload (the easy part) - -Once you have chosen: -- your board (`DISPLAY_PROFILE`) -- and whether you want audio (`ENABLE_AUDIO`) - -➡️ You just need to **upload** from the Arduino IDE. - ---- +Behavior: +- value `0`: audio code paths disabled +- value `1`: audio controls shown and active -## 5) 🎮 Optional: add a clickable encoder or 3 buttons +## C) Input routing strategy -Optionally, you can add: -- a **clickable rotary encoder** -- or **3 navigation buttons** (Left / OK / Right) +The code typically uses compile-time pin assignment blocks (`#if DISPLAY_PROFILE ...`). -⚠️ **Warning: this is not possible on 2432S022** (not enough accessible pins, so it’s not planned “properly”). -➡️ On **2432S022**, the recommended use = **touch only**. +Rules: +1. `-1` => logical disable +2. Encoder mode: define `ENC_A`, `ENC_B`, optional `ENC_BTN`; keep `BTN_*=-1` +3. Button mode: set `ENC_*=-1`; define `BTN_LEFT/BTN_OK/BTN_RIGHT` +4. Avoid mixed mode unless explicitly implemented -On **2432S028** and on the **ESP32 + ILI9341** profile, it’s possible. - ---- - -## 6) 🧷 Change the used pins (block in the code) - -Pins are changed here (in your code): - -```cpp -#if DISPLAY_PROFILE == DISPLAY_PROFILE_2432S022 - static const int ENC_A = -1; - static const int ENC_B = -1; - static const int ENC_BTN = -1; - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#elif DISPLAY_PROFILE == DISPLAY_PROFILE_2432S028 - static const int ENC_A = 22; // A=22 - static const int ENC_B = 27; // B=27 - static const int ENC_BTN = 35; // BTN=35 (or -1 to disable) - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#else // DISPLAY_PROFILE_ILI9341_320x240 (classic ESP32 with a screen) - static const int ENC_A = 22; // default encoder pins - static const int ENC_B = 27; - static const int ENC_BTN = 35; - - // 3-button option: set ENC_* to -1 and define BTN_* (default pins to adapt) - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#endif -``` - -✅ How it works: -- Setting a pin to `-1` = **disabled** -- You choose **either** encoder **or** 3 buttons: - - **Encoder**: set `ENC_A / ENC_B / ENC_BTN` and keep `BTN_* = -1` - - **3 buttons**: set `ENC_* = -1` then define `BTN_LEFT / BTN_RIGHT / BTN_OK` - -⚠️ On 2432S028, if you use `ENC_BTN = 35` (or another similar pin), you may need to add a **pull-up resistor** (see your diagram). - ---- - -## 7) 🧷 Wiring diagrams (encoder / buttons) - -I made a wiring diagram for: -- **encoder** mode -- **3 buttons** mode - -➡️ They are in the `screenshot/` folder of the repo (wiring images). - ---- - -## 8) ⚠️ UI differences: 2432S022 vs 2432S028 - -Warning: if you are on **2432S022**, you won’t have exactly the same UI as on **2432S028**. - -- **2432S028** has a bigger screen → allows a different, more comfortable layout -- **2432S022** is smaller → the UI is adapted to that size - -So it’s normal if the display isn’t identical. - ---- +## D) Electrical notes +- Some input pins may require pull-up resistor depending on board/pin type. +- Validate debouncing strategy in software if mechanical jitter appears. -## 9) 💾 Save: SD card required +## E) Display/UI expectations +- 2432S028 offers more room than 2432S022. +- UI differences between profiles are expected and normal. -In all cases, if you want a **save after power-off** for your dinosaur: -➡️ you need a **microSD card**. +## F) Save behavior +- Persistent save after reboot/power loss requires SD. +- Without SD, runtime state is volatile. -Without an SD card, you will lose the save after power-off/restart. +## G) Recommended validation checklist +- profile selected correctly +- touch input mapped correctly +- physical input mode consistent with pin settings +- audio button visible only when expected +- save survives reboot with SD inserted +- visual screens match screenshot/GIF documentation diff --git a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeFR.md b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeFR.md index 1b25640..2cc7308 100644 --- a/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeFR.md +++ b/RaptorLauncher_GameSDK/exemple_games/JurassicLife/READMEcodeFR.md @@ -1,166 +1,80 @@ -# 🦖 JurassicLife (Arduino / ESP32) +# 🦖 JurassicLife — Guide code (FR) -Ce code est fait pour tourner sur : -- **2432S022** -- **2432S028** -- **ESP32 classique + écran ILI9341 320×240** (profil `DISPLAY_PROFILE_ILI9341_320x240`) - -Le principe est simple : tu modifies 2–3 lignes au début du code, puis tu **téléverses**. +Ce guide est en 2 niveaux : +- **Partie 1** : prise en main simple et sympa +- **Partie 2** : référence technique complète, étape par étape --- -## 📌 Table des matières -1. Cartes supportées -2. Modifier le type de carte (ligne 11) -3. Activer / désactiver l’audio (ligne 14) -4. Téléverser -5. Option : encodeur rotatif cliquable ou 3 boutons -6. Modifier les pins (bloc `#if DISPLAY_PROFILE...`) -7. Schémas de câblage (encodeur / boutons) -8. Différences d’interface entre 2432S022 et 2432S028 -9. Sauvegarde : carte SD obligatoire +## 🎉 Partie 1 — prise en main simple ---- +## 1) Les 2 lignes à modifier en premier +En haut du sketch : +- `DISPLAY_PROFILE` +- `ENABLE_AUDIO` -## 1) ✅ Cartes supportées +Puis tu téléverses. C’est le chemin minimal. -- **2432S022** : supportée (attention : pas de contrôles physiques prévus) -- **2432S028** : supportée (contrôles physiques possibles) -- **ESP32 + ILI9341 320×240** : supportée via `DISPLAY_PROFILE_ILI9341_320x240` +## 2) Contrôles physiques (si tu veux) +- soit encodeur rotatif +- soit 3 boutons ---- +Garde les pins inutilisées à `-1`. -## 2) 🔁 Modifier le type de carte dans le code (ligne 11) +## 3) Sauvegarde persistante +Si tu veux garder la progression après extinction : carte microSD obligatoire. -Pour choisir ta carte, tu modifies la ligne **11** : +--- -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_2432S022 -``` +## 🛠️ Partie 2 — référence technique complète -Tu remplaces **uniquement la partie de droite** par : +## A) Profils d’affichage supportés +- `DISPLAY_PROFILE_2432S022` +- `DISPLAY_PROFILE_2432S028` +- `DISPLAY_PROFILE_ILI9341_320x240` -### ➜ Pour 2432S028 -```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_2432S028 -``` +Structure macro à conserver (ne pas renommer la partie gauche) : -### ➜ Pour ESP32 + écran ILI9341 320×240 ```cpp -#define DISPLAY_PROFILE DISPLAY_PROFILE_ILI9341_320x240 +#define DISPLAY_PROFILE DISPLAY_PROFILE_2432S022 ``` -> ✅ Ne change pas `#define DISPLAY_PROFILE` : tu changes seulement la valeur après. - ---- - -## 3) 🔊 Activer / désactiver l’audio (ligne 14) - -Tu peux activer ou désactiver l’audio en modifiant la ligne **14** : +## B) Activation audio ```cpp #define ENABLE_AUDIO 1 ``` -- `#define ENABLE_AUDIO 0` → audio désactivé -- `#define ENABLE_AUDIO 1` → audio activé - -✅ Si tu actives l’audio, tu verras apparaître dans l’interface **un nouveau bouton** qui permet : -- de **switcher** entre les différents modes audio -- et aussi **augmenter / réduire le volume** - ---- - -## 4) ⬆️ Téléverser (le plus simple) - -Une fois que tu as choisi : -- ta carte (`DISPLAY_PROFILE`) -- et si tu veux l’audio (`ENABLE_AUDIO`) - -➡️ Tu n’as plus qu’à **téléverser** depuis l’Arduino IDE. - ---- - -## 5) 🎮 Option : ajouter un encodeur cliquable ou 3 boutons - -En option, tu peux ajouter : -- un **encodeur rotatif cliquable** -- ou **3 boutons** de navigation (Gauche / OK / Droite) - -⚠️ **Attention : ce n’est pas possible sur 2432S022** (manque de pins accessibles, donc ce n’est pas prévu “proprement”). -➡️ Sur **2432S022**, l’utilisation recommandée = **tactile uniquement**. - -Sur **2432S028** et sur le profil **ESP32 + ILI9341**, c’est possible. - ---- - -## 6) 🧷 Modifier les pins utilisées (bloc dans le code) - -Les pins se modifient ici (dans ton code) : - -```cpp -#if DISPLAY_PROFILE == DISPLAY_PROFILE_2432S022 - static const int ENC_A = -1; - static const int ENC_B = -1; - static const int ENC_BTN = -1; - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#elif DISPLAY_PROFILE == DISPLAY_PROFILE_2432S028 - static const int ENC_A = 22; // A=22 - static const int ENC_B = 27; // B=27 - static const int ENC_BTN = 35; // BTN=35 (ou -1 pour désactiver) - - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#else // DISPLAY_PROFILE_ILI9341_320x240 (ESP32 classic avec écran) - static const int ENC_A = 22; // pins de base encoder - static const int ENC_B = 27; - static const int ENC_BTN = 35; - - // Option 3 boutons : mettre ENC_* à -1 et définir BTN_* (pins de base à adapter) - static const int BTN_LEFT = -1; - static const int BTN_RIGHT = -1; - static const int BTN_OK = -1; -#endif -``` - -✅ Comment ça marche : -- Mettre une pin à `-1` = **désactiver** -- Tu choisis **soit** encodeur **soit** 3 boutons : - - **Encodeur** : tu remplis `ENC_A / ENC_B / ENC_BTN` et tu laisses `BTN_* = -1` - - **3 boutons** : tu mets `ENC_* = -1` et tu définis `BTN_LEFT / BTN_RIGHT / BTN_OK` - -⚠️ Sur 2432S028, si tu utilises `ENC_BTN = 35` (ou un autre pin du même genre), il peut être nécessaire d’ajouter une **résistance pull-up** (voir ton schéma). - ---- - -## 7) 🧷 Schémas de câblage (encodeur / boutons) +Comportement : +- `0` = chemins audio inactifs +- `1` = contrôles audio visibles + actifs -J’ai fait un schéma de câblage pour : -- le mode **encodeur** -- le mode **3 boutons** +## C) Stratégie de mapping des entrées -➡️ Ils sont dans le dossier `screenshot/` du repo (images de câblage). +Le sketch utilise généralement des blocs de config compile-time (`#if DISPLAY_PROFILE ...`). ---- +Règles : +1. `-1` => entrée désactivée +2. Mode encodeur : renseigner `ENC_A`, `ENC_B`, `ENC_BTN` (optionnel), laisser `BTN_*=-1` +3. Mode boutons : mettre `ENC_*=-1`, définir `BTN_LEFT/BTN_OK/BTN_RIGHT` +4. Éviter mode mixte sauf implémentation explicite -## 8) ⚠️ Différences d’interface : 2432S022 vs 2432S028 - -Attention : si tu es sur **2432S022**, tu n’auras pas exactement la même interface que sur **2432S028**. - -- La **2432S028** a un écran plus grand → permet un affichage différent et plus confortable -- La **2432S022** est plus petite → l’interface est adaptée à cette taille - -Donc c’est normal si l’affichage n’est pas identique. - ---- +## D) Notes électriques +- Selon la pin/carte, un pull-up peut être nécessaire. +- Si rebonds mécaniques: activer/renforcer le debouncing logiciel. -## 9) 💾 Sauvegarde : carte SD obligatoire +## E) UI selon la carte +- 2432S028 offre plus d’espace d’affichage que 2432S022. +- Des différences de layout sont donc normales. -Dans tous les cas, si tu veux une **sauvegarde après coupure** de ton dinosaure : -➡️ il est nécessaire d’utiliser une **carte microSD**. +## F) Modèle de sauvegarde +- Sauvegarde persistante après reboot/coupure = microSD requise. +- Sans SD, l’état reste volatile. -Sans carte SD, tu perdras la sauvegarde après coupure/redémarrage. +## G) Checklist de validation recommandée +- bon profil sélectionné +- tactile correctement mappé +- mode d’entrée physique cohérent avec pins définies +- bouton audio visible uniquement quand attendu +- sauvegarde intacte après reboot avec SD +- écrans conformes aux captures/GIF de documentation From 4806366cdcf23b7f4264b12581beced08450df17 Mon Sep 17 00:00:00 2001 From: Inter-Raptor Date: Fri, 10 Apr 2026 15:29:19 +0200 Subject: [PATCH 2/4] docs: embed project images and gifs in main README --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 600a44a..aff2fd6 100644 --- a/README.md +++ b/README.md @@ -24,14 +24,31 @@ Si un jeu plante, on veut un retour launcher propre au boot suivant. 4. **Fallback visuel** si image absente/corrompue (`home_bg.bmp`, `splash.bmp`). 5. **Logs série** activés pendant le dev. -## 3) Ta mini checklist avant test +## 3) Aperçu visuel (images + GIF) + +> Tu me l’as demandé : voici les visuels directement dans le README principal ✅ + +### 🚀 Lancement du launcher +![Animation lancement launcher](presentation%20Lancement%20Launcher.gif) + +### 🧩 Pages applications +![Page 1 applications](page1%20des%20application.jpg) +![Page 2 applications](page2%20des%20application.jpg) + +### ⚙️ Paramètres +![Affichage des paramètres](affichage%20des%20setting%20parametre.jpg) + +### 🎮 Présentation jeux / applications +![Présentation jeux et applications](Presentation%20de%20queljeu%20et%20application.gif) + +## 4) Ta mini checklist avant test - [ ] le launcher démarre sans freeze - [ ] la pagination est claire et tactile - [ ] un jeu invalide est refusé proprement - [ ] retour launcher fonctionne après reboot forcé - [ ] pas de redraw complet en boucle inutile -## 4) Résumé “ce qui casse le plus souvent” +## 5) Résumé “ce qui casse le plus souvent” - trop de choses lancées dans `setup()` - grosses images mal dimensionnées - scans réseau bloquants From c4a1ce0a42ac85a8eb40df44a9407c03ff19c708 Mon Sep 17 00:00:00 2001 From: Inter-Raptor Date: Fri, 10 Apr 2026 15:38:06 +0200 Subject: [PATCH 3/4] docs: improve main README intro with project vision and benefits --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aff2fd6..79dd25c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,19 @@ -# 🦖 RaptorLauncher00 — Le repaire des jeux dinos +# 🦖 RaptorLauncher00 — La console qui libère les jeux SD -Bienvenue ! Ici tu peux lancer des jeux sur ESP32 depuis la SD, avec une UX propre, des sauvegardes stables et un debug sérieux. -Ce README est volontairement en **2 niveaux** : +RaptorLauncher00, c’est l’idée d’une **console ouverte** : +une base ESP32 qui te permet de **créer, lire et organiser tes jeux directement depuis la carte SD**. + +🎯 Le but : +- **ajouter autant de jeux que tu veux** (pratiquement illimité, selon la taille SD), +- **changer de jeu en quelques secondes** (copier/remplacer un dossier, sans tout recompiler), +- **garder une expérience fun et simple** pour jouer, tester, partager. + +En gros : tu traites tes jeux comme une bibliothèque vivante. +Tu poses un nouveau dossier sur la SD, et boum — un nouveau jeu dans la console. +> On peut le voir comme une nouvelle génération “DIY” entre Arduboy / ESPboy et une logique moderne orientée contenus SD : plus flexible, plus évolutive, plus créative. + +Ce README est volontairement en **2 niveaux** : - **Partie 1 (Fun & simple)** 👉 pour démarrer vite sans se noyer. - **Partie 2 (Ultra technique)** 👉 pour comprendre *tous* les détails, les limites et les bonnes pratiques pro. From 691b6faf419274a08e75b16287bc36cbf9488318 Mon Sep 17 00:00:00 2001 From: Inter-Raptor Date: Fri, 10 Apr 2026 15:38:18 +0200 Subject: [PATCH 4/4] docs: add full A4-style intro to main README --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 79dd25c..141f53c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,86 @@ -# 🦖 RaptorLauncher00 — La console qui libère les jeux SD +# 🦖 RaptorLauncher00 — La console SD fun, créative et ultra libre -RaptorLauncher00, c’est l’idée d’une **console ouverte** : -une base ESP32 qui te permet de **créer, lire et organiser tes jeux directement depuis la carte SD**. +Imagine une console où tu n’es pas enfermé dans une liste de jeux figée. +Imagine une machine que tu peux faire évoluer comme tu veux, où chaque nouvelle idée peut devenir un jeu jouable en quelques minutes. +C’est exactement l’esprit de **RaptorLauncher00**. -🎯 Le but : -- **ajouter autant de jeux que tu veux** (pratiquement illimité, selon la taille SD), -- **changer de jeu en quelques secondes** (copier/remplacer un dossier, sans tout recompiler), -- **garder une expérience fun et simple** pour jouer, tester, partager. +RaptorLauncher00 est pensé comme une plateforme de jeu basée ESP32 (famille **2432S0xx**, par exemple **2432S028** et variantes comme **2432S032R** selon ton montage), avec un écran tactile **320×240**. +Ce combo change tout : +- un processeur assez costaud pour faire tourner des jeux variés, +- un écran couleur confortable, +- et surtout un **tactile** qui ouvre des mécaniques de gameplay beaucoup plus riches que des consoles mini classiques. -En gros : tu traites tes jeux comme une bibliothèque vivante. -Tu poses un nouveau dossier sur la SD, et boum — un nouveau jeu dans la console. +--- + +## 🌟 Pourquoi l’utiliser ? (le vrai "pourquoi") + +### 1) Parce que ta bibliothèque de jeux devient vivante +Avec RaptorLauncher00, les jeux sont stockés sur la carte SD. +Donc ce n’est plus “1 firmware = 1 jeu”. +Tu peux : +- ajouter un nouveau jeu en copiant un dossier, +- en retirer un en supprimant ce dossier, +- mettre à jour un jeu sans reflasher tout l’écosystème. + +👉 Résultat : **nombre de jeux quasi illimité** (limité surtout par la capacité de la SD). + +### 2) Parce que c’est simple à maintenir +Tu sépares clairement : +- la logique launcher, +- les dossiers de jeux, +- les assets (icônes, titres, sons, sauvegardes). + +Ça évite les projets “monolithiques” impossibles à faire évoluer. + +### 3) Parce que le tactile + 320×240, c’est un terrain de jeu énorme +Avec une dalle tactile et une résolution 320×240, tu peux faire : +- des jeux d’arcade nerveux, +- des jeux de gestion/menu très lisibles, +- des interfaces riches (inventaires, cartes, HUD détaillés), +- des mini-apps interactives en plus des jeux. + +Tu n’es pas coincé dans un gameplay ultra minimaliste : +**tu peux viser des expériences vraiment ambitieuses** pour du DIY embarqué. + +### 4) Parce que c’est fun pour jouer **et** pour créer +RaptorLauncher00 n’est pas juste une console “consommation”. +C’est une console “maker” : +- tu testes vite, +- tu itères vite, +- tu partages vite. + +Tu peux créer un prototype le soir, le copier sur SD, et le faire tester immédiatement. + +### 5) Parce que c’est l’esprit “futur Arduboy / ESPboy” +Même philosophie maker, mais avec une approche moderne : +- plus de souplesse contenu, +- plus de confort visuel, +- plus de place pour des jeux complexes, +- plus de liberté pour les créateurs. + +--- + +## 🧠 Ce que RaptorLauncher00 apporte concrètement + +- **Modularité** : chaque jeu est un module SD. +- **Scalabilité** : la collection de jeux grandit sans refaire toute l’architecture. +- **Fiabilité** : conventions claires (`meta.json`, `game.bin`, fallback assets, boot safety). +- **Expérience utilisateur** : navigation tactile moderne + pages visuelles. +- **Expérience développeur** : debug série, organisation propre, workflow rapide. + +En bref : +> Tu construis une vraie petite console de salon DIY, mais avec la flexibilité d’un système de contenu moderne. + +--- + +## 📘 Comment lire ce README -> On peut le voir comme une nouvelle génération “DIY” entre Arduboy / ESPboy et une logique moderne orientée contenus SD : plus flexible, plus évolutive, plus créative. +Ce document est volontairement en **2 niveaux** : +- **Partie 1 (Fun & simple)** 👉 pour prendre en main rapidement. +- **Partie 2 (Ultra technique)** 👉 pour maîtriser tous les détails (architecture, perf, validation, robustesse). -Ce README est volontairement en **2 niveaux** : -- **Partie 1 (Fun & simple)** 👉 pour démarrer vite sans se noyer. -- **Partie 2 (Ultra technique)** 👉 pour comprendre *tous* les détails, les limites et les bonnes pratiques pro. +Si tu débutes : lis la partie 1 puis teste. +Si tu veux industrialiser tes jeux : plonge dans la partie 2. ---