quest'n'click 4.5.0 · r1

Construite pour quest'n'click 4.5.0, révision r1. Si elle est publiée, et laquelle est la courante, est dit par publication.json.

Démarrage rapide

English · Type : tutoriel · Public : auteur, administrateur · Contexte : Reality Bridge · Statut : prête · S'applique depuis : 4.2.5

Le Reality Bridge, profil local (SQLite) · contrat : stable · vérifié par la CI (matrice de support de la 4.4.0, 2026-10-23) : Node 22.13+ avec node:sqlite, sous Ubuntu ; Chromium et WebKit de bout en bout · vérifications automatiques : jobs reality, reality-xcheck ; plan de CI reality ; 2 fichiers de tests · passes humaines : aucune · limites connues : bridge-quick-start-local

En un quart d’heure environ, sur votre machine, vous faites réagir le jeu d’exemple signals au monde extérieur : d’abord avec le Bridge simulé du Studio, puis avec un vrai Bridge sur 127.0.0.1, un signal envoyé par son webhook de démonstration, et le même signal envoyé deux fois. Rien ne sort de votre machine.

Ce que vous allez construire

Le jeu d’exemple games/signals s’ouvre sur un jardin, un portail fermé et une vieille radio posée sur un banc. À la fin de ce tutoriel :

Ce qu’il vous faut

L’essayer d’abord dans le Studio

  1. Lancez le Studio sur le jeu d’exemple :

    # dans le dépôt du moteur
GAME=signals npm run studio

    L’onglet Jouer affiche un panneau Reality, parce que le jeu déclare reality : un bouton par signal, des pannes à ajouter (un délai, un doublon, une mauvaise signature, une expiration), la file inversée, la connexion coupée puis reprise, et ce qu’est devenue chaque livraison. Appuyez sur le bouton de mail.answer.correct : le portail s’ouvre.

    C’est un Bridge simulé avec une clé de développement, qui tourne dans la page : le signal passe par la même vérification, la même session, la même sauvegarde et la même déduplication qu’un vrai. Arrêtez le Studio (Ctrl-C) avant de continuer.

Étapes avec un vrai Bridge

  1. Créez les clés et la configuration du Bridge pour le jeu :

    # dans le dépôt du moteur
GAME=signals npm run bridge -- init

    Vous voyez ✔ …/.cache/bridge/config.json (keys, webhook secrets and tokens; mode 600), …/root.key (the root key: grant only) and …/admin-token, puis la liste des webhooks de démonstration, un par source des signaux du jeu : /v1/hooks/badge, /v1/hooks/webhook, /v1/hooks/email, /v1/hooks/mail, /v1/hooks/terminal. Les valeurs par défaut conviennent à ce tutoriel : les origines du jeu http://127.0.0.1:5173 et http://localhost:5173, le journal comme stockage.

  1. Lancez-le, dans un premier terminal :

    # dans le dépôt du moteur, terminal 1
GAME=signals npm run bridge -- serve

    Il affiche une ligne JSON, {"event":"bridge.listening","url":"http://127.0.0.1:8787/","game":"signals",…}, et continue de tourner. Chaque événement suivant (un appairage, un signal) ajoute une ligne ici.

  1. Lancez le jeu, dans un deuxième terminal, et ouvrez http://127.0.0.1:5173/ :

    # dans le dépôt du moteur, terminal 2
GAME=signals npm run dev

    Le reality.bridge du jeu vaut déjà http://127.0.0.1:8787/ (games/signals/game.ts).

  1. Liez le jeu. Ouvrez le menu pause, ligne World link, et choisissez « Link this game » (les textes anglais par défaut du moteur) : le jeu affiche un code de 8 caractères (lettres et chiffres, sans 0, O, 1, I ni L). Il attend qu’un connecteur le confirme.

  1. Confirmez le code comme le ferait un connecteur, dans un troisième terminal. Le webhook de démonstration de la source mail a un jeton qui peut confirmer des appairages ; remplacez ABCD2345 par votre code :

    # dans le dépôt du moteur, terminal 3
TOKEN=$(node -p 'require("./.cache/bridge/config.json").webhooks.mail.token')
curl -s -X POST http://127.0.0.1:8787/v1/pairings/ABCD2345/confirm -H "Authorization: Bearer $TOKEN"

    La réponse est {"playerId":"p-…"} : 16 chiffres hexadécimaux, un identifiant pseudonyme inventé par le Bridge. Le terminal 1 journalise "event":"pairing.confirmed". Le jeu demande au Bridge toutes les deux secondes si son code a été confirmé : il récupère son lien tout seul et dit qu’il est lié. Notez le playerId pour l’étape suivante.

  1. Envoyez le signal par le webhook de démonstration. Une requête de webhook est signée par un HMAC-SHA256 de son corps sous le secret du webhook ; cette commande lit le secret dans la configuration et signe. Remplacez le p-… :

    # dans le dépôt du moteur, terminal 3
node -e '
const { createHmac } = require("node:crypto");
const [playerId] = process.argv.slice(1);
const { secret } = require("./.cache/bridge/config.json").webhooks.mail;
const body = JSON.stringify({ playerId, event: "answer.correct", id: "try-1" });
const signature = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
fetch("http://127.0.0.1:8787/v1/hooks/mail", { method: "POST", body,
  headers: { "Content-Type": "application/json", "X-Web-Scumm-Signature": signature } })
  .then(async (r) => console.log(r.status, await r.text()));
' p-0123456789abcdef

    Elle affiche 202 {"id":"s-…","sequence":1,"duplicate":false}. Dans le jeu, le portail s’ouvre. L’événement answer.correct du webhook mail est le signal mail.answer.correct ; id nomme cette livraison.

  1. Relancez la même commande. Elle affiche 200 {"id":"s-…","sequence":1,"duplicate":true} : le même identifiant, la même séquence. Le Bridge a gardé le premier ; le jeu ne change rien.
  1. Arrêtez le Bridge et le jeu par Ctrl-C dans leurs terminaux. Le Bridge écrit "event":"bridge.stopping" et s’arrête.

Limite · bridge-quick-start-local Ce tutoriel tourne sur une seule machine, en HTTP simple, avec des webhooks de démonstration qui peuvent envoyer n’importe quel signal de leur source pour n’importe quel joueur pendant 30 jours. C’est pour le développement seulement : sur Internet, le Bridge tourne derrière HTTPS, avec init --no-demo-webhooks et un grant étroit par connecteur (Installer et lancer le Bridge).

Entre les mains du joueur

Ce que vous venez de faire à la main, un connecteur le fait pour un joueur. Côté joueur :

Ce que garde la sauvegarde, et ce qui se passe quand une sauvegarde rencontre le lien d’un autre joueur : Garanties.

Pour aller plus loin : le chapitre d’exemple

games/signals a un chapitre, « la boîte aux lettres et le terminal », joué avec les vrais connecteurs. Liez le jeu (menu pause, World link), puis :

Rien de tout cela n’est nécessaire pour finir le jeu : la radio sur le banc ouvre toujours le portail. Le terminal Telnet est le plus rapide à essayer en local. Avec le Bridge de l’étape 2 en marche :

# dans le dépôt du moteur, terminal 3
GAME=signals npm run bridge -- grant --connector=shed-telnet --source=terminal --signals=terminal.lamp --pair > .cache/bridge/telnet.token
cat > .cache/bridge/telnet.json <<'EOF'
{
  "bridge": { "url": "http://127.0.0.1:8787/", "tokenFile": "telnet.token" },
  "gameId": "signals",
  "health": { "port": 9301 },
  "telnet": { "port": 2323 }
}
EOF
npm run connector -- telnet --config .cache/bridge/telnet.json

Puis, depuis un quatrième terminal, nc 127.0.0.1 2323 (ou telnet 127.0.0.1 2323) : la bannière de la cabane demande le code d’appairage que montre votre jeu ; tapez-le, puis lamp on. Le terminal répond « Click. Somewhere in the garden, a lamp glows. ». Chaque connecteur a sa page : Telnet, SSH, e-mail, Open Badges.

Ce que vous avez appris

Et ensuite

Modifier la source de cette page · Signaler une erreur