docs(ir): example IR + authoring gap note

2026-06-11 03:07:14 +02:00
parent 7e690f5a20
commit dd6df1fa69
2 changed files with 86 additions and 0 deletions
@@ -0,0 +1,60 @@
+{
+  "schema_version": "zacus.runtime3.v1",
+  "scenario": {
+    "id": "EXAMPLE_LOCAL_PUZZLES",
+    "version": 3,
+    "title": "Exemple — enigmes locales P1 son / P3 QR",
+    "entry_step_id": "STEP_QR"
+  },
+  "steps": [
+    {
+      "id": "STEP_QR",
+      "scene_id": "SCENE_QR_DETECTOR",
+      "scene": {
+        "title": "MISSION QR",
+        "subtitle": "scannez les codes dans l'ordre",
+        "symbol": "RUN",
+        "effect": "gyro"
+      },
+      "puzzle": {
+        "id": 3,
+        "type": "qr",
+        "codes": ["zacus-qr-1", "zacus-qr-2"],
+        "fragment": [5]
+      },
+      "transitions": [
+        { "event_type": "unlock", "target_step_id": "STEP_SOUND" }
+      ]
+    },
+    {
+      "id": "STEP_SOUND",
+      "scene_id": "SCENE_LA_DETECTOR",
+      "scene": {
+        "title": "U-SON",
+        "subtitle": "jouez la melodie do re mi fa",
+        "symbol": "440",
+        "effect": "glitch"
+      },
+      "puzzle": {
+        "id": 1,
+        "type": "sound",
+        "melody": [60, 62, 64, 65],
+        "tolerance": 2,
+        "fragment": [1, 2]
+      },
+      "transitions": [
+        { "event_type": "unlock", "target_step_id": "STEP_CALME" }
+      ]
+    },
+    {
+      "id": "STEP_CALME",
+      "scene_id": "SCENE_FIN",
+      "scene": {
+        "title": "CODE ASSEMBLE",
+        "subtitle": "125",
+        "effect": "pulse"
+      },
+      "transitions": []
+    }
+  ]
+}
@@ -139,3 +139,29 @@ effect). All fields optional.

 - `title` <= 47 chars, `subtitle` <= 63, `symbol` <= 15.
 - `effect`: `pulse` (default) | `glitch` | `gyro` | `none`.
+
+### État de l'authoring et chaînon manquant
+
+Au stade actuel, les champs `puzzle`/`scene` sont **portés de bout en bout
+côté exécution** : le compilateur (`runtime3_common.py`) les transmet
+verbatim de l'IR au firmware, qui arme les énigmes locales (P1 son / P3 QR)
+et pilote l'écran. Un IR de référence exerçant ces champs est fourni :
+`hardware/firmware/data/story/runtime3/EXAMPLE_LOCAL_PUZZLES.json` (validé
+par `validate_runtime3_document`, testé en bout-à-bout via `POST /game/scenario`
+puis `POST /game/step`).
+
+**En revanche, l'authoring ne les génère pas encore.** Les scénarios
+canoniques (`game/scenarios/zacus_v2.yaml`, `zacus_v3.yaml`) décrivent les
+mêmes énigmes via un vocabulaire distinct — blocs `solution:`
+(`frequency_hz`, `qr_payload`, `sequence`) et `scene: SCENE_X` (référence
+d'ID d'écran, pas l'objet d'affichage) — qui **n'est pas traduit** vers les
+objets `puzzle`/`scene` de l'IR. L'IR embarqué `DEFAULT.json` ne contient
+donc aucun champ `puzzle`/`scene`.
+
+Chaînon à construire (tâche dédiée) : enseigner au compilateur la
+correspondance `solution:` → `puzzle:` (ex. `frequency_hz`+`tolerance_hz`
+→ `type:sound`/`melody`/`tolerance` ; `qr_payload`/`sequence`
+→ `type:qr`/`codes` ; allocation des `fragment` de code par énigme), et
+exposer un objet `scene` d'affichage dans l'authoring. En attendant,
+pousser directement un IR comme `EXAMPLE_LOCAL_PUZZLES.json` reste le moyen
+d'exercer les énigmes locales depuis la webUI/gateway.