L'électron rare
20aed903ba
- Voice pipeline: ESP32 WebSocket client → voice bridge → LLM → Piper TTS (Tower :8001) - Hints engine: 3 puzzles (LA_440, LEFOU_PIANO, QR_FINALE), anti-cheat, 3 hint levels - MCP hardware server: 6 tools (puzzle, audio, LED, camera, scenario, status), stdio transport - Analytics: ESP32 module + 6 web endpoints + Dashboard UI with chat interface - Security: auth middleware (Bearer NVS), rate limiting, input validation on 30 endpoints - Frontend: code-split (1.1MB → 210KB initial), ErrorBoundary, API timeout, WS reconnect - Tests: 24 Python + 38 TypeScript + 18 MCP = 80 project tests (+ 19 mascarade) - Specs: AI_INTEGRATION_SPEC, MCP_HARDWARE_SERVER_SPEC, QA_TEST_MATRIX_SPEC - Docs: SECURITY, DEPLOYMENT_RUNBOOK, voice pipeline guide, AI architecture map - 6 AI agent definitions (.github/agents/ai_*.md) - TUI orchestration script (tools/dev/zacus_tui.py) - Docker compose TTS for Tower + KXKM-AI - CHANGELOG, README, mkdocs.yml updated - Cycle detection (DFS) in runtime3 validator - Sprint plan: plans/SPRINT_AI_INTEGRATION.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.1 KiB
Générer un scénario STORY V2
Ce guide explique comment créer, compiler et tester un scénario avec le Runtime 3 sans toucher au moteur C++.
Prérequis
- Python 3.x avec PyYAML installé (
pip install pyyaml) - Le dépôt cloné à la racine du projet
1) Source canonique du scénario
Le fichier de référence est :
game/scenarios/zacus_v2.yaml
C'est la single source of truth. Toute modification de scénario doit passer par ce fichier YAML.
2) Édition visuelle (studio Blockly)
Pour éditer le scénario graphiquement, utiliser le studio React + Blockly :
cd frontend-scratch-v2
npm install
npm run dev
Le studio permet de manipuler les étapes, transitions et événements visuellement, puis d'exporter vers le format YAML V2.
3) Valider le scénario
make scenario-validate
Cette commande vérifie :
- la conformité de structure au schéma V2,
- les IDs / références croisées,
- la cohérence des transitions,
- les bindings des mini-apps.
Corriger les erreurs jusqu'à obtenir une validation propre.
4) Compiler avec le Runtime 3
make runtime3-compile
Cela exécute tools/scenario/compile_runtime3.py sur le scénario par défaut. Pour spécifier un fichier :
make runtime3-compile SCENARIO=game/scenarios/zacus_v2.yaml
5) Simuler le scénario
make runtime3-simulate
Cela exécute tools/scenario/simulate_runtime3.py et déroule le scénario hors firmware pour vérifier les transitions et les états finaux.
6) Vérifier les pivots et générer le bundle firmware
make runtime3-verify
make runtime3-firmware-bundle
runtime3-verifyvalide les points pivots du graphe de scénario.runtime3-firmware-bundleproduit le bundle prêt à flasher sur l'ESP32.
7) Lancer les tests unitaires Runtime 3
make runtime3-test
8) Compiler et flasher le firmware
cd ESP32_ZACUS
pio run -e esp32dev
pio run -e esp32dev -t upload --upload-port /dev/ttyUSB0
9) Tester côté série
Dans le moniteur série, commandes utiles :
STORY_V2_ENABLE ONSTORY_V2_LISTSTORY_V2_SCENARIO <id>STORY_V2_STATUSSTORY_V2_EVENT <name>STORY_V2_VALIDATE
Workflow court (copier-coller)
make scenario-validate
make runtime3-compile
make runtime3-simulate
make runtime3-verify
Toutes les cibles Makefile disponibles
| Cible | Description |
|---|---|
scenario-validate |
Validation YAML du scénario |
runtime3-compile |
Compilation Runtime 3 |
runtime3-simulate |
Simulation hors firmware |
runtime3-verify |
Vérification des pivots |
runtime3-test |
Tests unitaires Runtime 3 |
runtime3-firmware-bundle |
Export bundle firmware ESP32 |
Conseils pour éviter les blocages
- Commencer simple : 3 à 4 étapes max au début.
- N'ajouter qu'un seul nouveau type d'événement à la fois.
- Toujours valider (
make scenario-validate) avant de compiler. - Tester chaque transition clé au moniteur série (
STORY_V2_EVENT ...). - Utiliser
make runtime3-simulatepour déboguer sans flasher.