le-mystere-professeur-zacus/README.md

Le Mystere du Professeur Zacus

Zacus est en refonte vers un produit hybride unique:

• un jeu terrain fiable sur carte Freenove ESP32-S3,
• un studio auteur moderne en React + Blockly,
• un runtime portable "Zacus Runtime 3" compile depuis le YAML canonique.

Canon actuel

• Source narrative: game/scenarios/zacus_v3_complete.yaml
• Studio auteur: frontend-v3/apps/atelier (monorepo pnpm + turbo ; frontend-scratch-v2/ est abandonné depuis le hard cutover du 2026-05)
• Hub game-master: apps/zacus-hub (app SwiftUI native)
• Gateway d'orchestration: tools/zacus-gateway (FastAPI, port 8400) — compile le YAML → Runtime 3 IR et pousse aux cartes
• Runtime portable: tools/scenario/compile_runtime3.py + tools/scenario/simulate_runtime3.py
• Cible hardware principale: ESP32_ZACUS/idf_zacus (ESP-IDF, Freenove ESP32-S3) — submodule sur Gitea ; hardware/firmware (ancien build Arduino) est legacy
• Plans et memoire: memory/, plans/, todos/
• Architecture et cartes Mermaid: docs/architecture/

Démarrage rapide

1. Bootstrap validation

bash tools/setup/install_validators.sh
bash tools/test/run_content_checks.sh

2. Compiler et simuler Runtime 3

python3 tools/scenario/compile_runtime3.py game/scenarios/zacus_v3_complete.yaml
python3 tools/scenario/simulate_runtime3.py game/scenarios/zacus_v3_complete.yaml
python3 tools/scenario/export_runtime3_firmware_bundle.py game/scenarios/zacus_v3_complete.yaml

3. Démarrer le studio React + Blockly

cd frontend-v3
pnpm install
pnpm test
# Bases de liaison : gateway (:8400), firmware (:80), hints (:8311), voice-bridge (:8200)
VITE_GATEWAY_BASE_URL=http://localhost:8400 \
VITE_ESP32_BASE_URL=http://zacus-master.local \
pnpm dev

4. Utiliser le shell canonique

./tools/dev/zacus.sh content-checks
./tools/dev/zacus.sh runtime3-compile
make runtime3-verify
make runtime3-test
./tools/dev/zacus.sh frontend-test
./tools/dev/zacus.sh frontend-build
./tools/dev/zacus.sh menu

Cartographie du dépôt

• game/: scénarios YAML canoniques.
• audio/: manifestes audio et assets associés.
• printables/: manifestes et exports imprimables.
• kit-maitre-du-jeu/: matériel MJ et déroulé terrain.
• frontend-v3/: studio auteur (apps/atelier + apps/dashboard), monorepo pnpm + turbo. Webapp courante.
• apps/zacus-hub/: hub game-master (app SwiftUI native).
• tools/zacus-gateway/: gateway FastAPI (:8400) — orchestration studio/flash, compile YAML → Runtime 3 IR.
• ESP32_ZACUS/: firmware ESP-IDF (submodule Gitea), cible principale idf_zacus.
• frontend-scratch-v2/: studio auteur React + Blockly (legacy, abandonné).
• hardware/firmware/: ancien firmware Arduino freenove (legacy).
• tools/: validateurs, compilateur/simulateur Runtime 3, shells d'automatisation.
• docs/: quickstart, architecture, benchmark OSS et runbooks.
• memory/, plans/, todos/: pilotage de la refonte.

AI Integration

Le projet intègre une couche IA pour enrichir l'expérience terrain :

• Voice pipeline : wake word (ESP-SR) → ASR → LLM → TTS (Piper / XTTS-v2) → speaker. Scaffold prêt, voir docs/voice/VOICE_PIPELINE_GUIDE.md.
• Vision : détection d'objets via ESP-DL pour indices contextuels.
• LLM hints : le Professeur Zacus répond aux joueurs via mascarade.
• TUI dev : script interactif d'orchestration → python3 tools/dev/zacus_tui.py

Analyse complète : docs/AI_INTEGRATION_ANALYSIS.md

Sécurité & Déploiement

• docs/SECURITY.md — audit firmware, HMAC auth, rate limiting
• docs/DEPLOYMENT_RUNBOOK.md — procédures de déploiement terrain

Statut du projet

• Runtime 3 : compilateur + simulateur + export firmware bundle OK
• Studio auteur : React 19 + Blockly, 18 tests passing
• Firmware : sécurité P0 intégrée (HMAC, rate limit, safe OTA)
• Voice pipeline : scaffold ESP-SR prêt, TTS Docker validé
• Specs : ZACUS_RUNTIME_3_SPEC.md, STORY_DESIGNER_SCRATCH_LIKE_SPEC.md

Documentation à lire

• docs/QUICKSTART.md
• docs/architecture/index.md
• docs/AI_INTEGRATION_ANALYSIS.md
• specs/ZACUS_RUNTIME_3_SPEC.md
• specs/STORY_DESIGNER_SCRATCH_LIKE_SPEC.md
• docs/benchmark-oss.md

Notes de refonte

• Le YAML reste la source de vérité pendant la migration.
• Le Runtime 3 devient le contrat portable entre studio, simulateur et firmware.
• hardware/firmware/esp32/ reste en lecture seule.
• Les chemins legacy ne doivent être supprimés qu'après preuve de remplacement.

Licences

• Code: MIT (LICENSE)
• Contenu créatif: CC BY-NC 4.0 (LICENSE-CONTENT.md)