Vérifier son jeu

English · Type : procédure · Public : auteur · Contexte : dépôt du moteur, projet créé · Statut : prête · S'applique depuis : 4.3.0

Quatre commandes disent l'essentiel de ce qui ne va pas dans un jeu avant que quiconque y joue : validate vérifie le contenu, solve trouve un chemin jusqu'à la fin, lint lit le graphe de puzzles pour y trouver ce qui ferait trébucher un joueur, et solve --prove prouve qu'aucun joueur ne peut rester bloqué. Ensuite, le jeu est joué pour de vrai : par un parcours scripté, dans un navigateur, sur un téléphone, et par une personne.

Ce que vous obtenez

Un jeu dont toutes les références existent, qui se finit depuis « Nouvelle partie », dont les blocages sont exclus par une preuve exhaustive, et dont vous avez lu les avertissements restants pour les corriger ou les garder exprès. Pour finir, la liste Avant de partager le lien.

Contexte et versions

• Le dépôt du moteur (un clone de quest-n-click, pour travailler sur le moteur ou ses jeux d'exemple) : les commandes sont des scripts npm, npm run validate. Le jeu est GAME=<id>, sinon config.game de package.json.
• Un projet créé (par npx quest-n-click create) : les commandes sont des sous-commandes de quest-n-click, npx quest-n-click validate, et les scripts du projet npm run verify, npm run build, npm run release. Le jeu est dans game/.
• Cette page décrit la 4.3.0 et après (le hero-looks-default du lint est arrivé en 4.3.0). Le statut d'une exécution du solveur est le même depuis la 3.3.

Prérequis

• Le moteur installé : Installer depuis le dépôt ou un projet créé (Votre premier jeu).
• Un jeu d'au moins un lieu. La boucle de travail est dans La boucle de travail.

Où lancer les commandes

Sur votre machine, à la racine du dossier :

Dans le dépôt du moteur, les options viennent après -- (npm run solve -- --prove) ; avec npx quest-n-click, elles suivent directement la sous-commande.

Étapes

1. Validez le contenu.

   # dans le dépôt du moteur
   npm run validate
   # dans un projet créé
   npx quest-n-click validate
   

   Tout ce qui est référencé existe, chaque chose visible a sa ligne Regarder, les textes ne sont ni vides ni trop longs, les flags sont posés et lus. Code 1 sur une erreur. Ce qu'il vérifie est listé dans Ce que regarde chaque vérification.

2. Trouvez un chemin jusqu'à la fin.

   # dans le dépôt du moteur
   npm run solve
   # dans un projet créé
   npx quest-n-click solve
   

   Il affiche ✔ The game can be finished, le chemin, et trois alertes à lire : impasses, objets obtenus mais jamais utilisés, objets jamais obtenus (les alertes). Un chemin gagnant n'est pas une preuve.

3. Passez le lint sur le contenu.

   # dans le dépôt du moteur
   npm run lint
   # dans un projet créé
   npx quest-n-click lint
   

   Des conditions que rien ne peut satisfaire, des règles qu'une autre cache, des fausses pistes, des indices qui ne peuvent pas se déclencher, des actions que le solveur n'a jamais jouées. Corrigez chaque remarque, ou gardez-la exprès dans game.ts (lint.ignore, plus bas).

4. Prouvez qu'il n'y a aucun blocage.

   # dans le dépôt du moteur : la preuve globale, la preuve par chapitres, chaque monde Reality
   npm run prove:game
   # dans un projet créé
   npx quest-n-click solve --prove
   

   Seul un solved obtenu avec --prove exclut les blocages. Un résultat truncated ne prouve rien : augmentez le budget (Options du solveur).

5. Jouez-y pour de vrai. Un parcours scripté et l'e2e dans le navigateur (Prouver que ça se joue), un vrai téléphone en paysage (Tester sur un téléphone en réseau local), puis une personne qui n'a jamais vu le jeu (Playtests).

6. Parcourez la liste Avant de partager le lien.

Ce que regarde chaque vérification

• Validé. Les références cassées, les lieux inatteignables et les lignes non traduites sont trouvés avant que quiconque joue. validate vérifie les formes et les références : tout ce qui est référencé existe, chaque chose visible a sa ligne Regarder, les textes ne sont ni vides ni trop longs, les flags sont posés et lus. Il signale les lieux vers lesquels rien ne mène et les sorties déclarées sans retour (oneWay: true si c'est voulu). Il vérifie les paramètres obligatoires de chaque mini-jeu (required), les images citées dans leurs params, chaque id de skin (images du manifeste, sons audio) et ending.scratch, et que le fallback d'un signal Reality requis nomme une règle.

• Résolu. Le solveur fait tourner le vrai moteur, sans second modèle du contenu. solve demande un témoin, un chemin jusqu'à une fin ; solve --prove explore chaque état atteignable et échoue sur un blocage ou une recherche tronquée. Ce sont deux promesses différentes, et une release demande la seconde (Ce que prouve le solveur). solve signale aussi les invariants (GameDef.invariants) devenus vrais, avec leur chemin.

• Passé au lint. lint dit ce que validate ne peut pas voir (il vérifie formes et références) et ce que solve ne dit pas fort (il répond à « peut-on finir »). Depuis le graphe de puzzles :

  • une condition que rien ne pose (cond-never-true, une erreur) ;
  • une règle qu'une autre règle attrape d'abord (rule-shadowed) ;
  • un objet dont aucune règle n'a besoin (item-red-herring) ou que rien ne donne (item-never-gained) ;
  • un indice qui attend quelque chose que rien ne pose (hint-stuck, une erreur), ou qui partage son until avec un indice précédent (hint-never-fires) ;
  • un sujet, une option de choix ou un écouteur morts ; un choix à une seule option ; une sortie avec une condition et sans ligne locked ;
  • une action qui ne change que ce que rien de vivant ne lit (action-dead, info ; un flag que lit la variante d'un personnage ou un changement de texte ne compte pas pour rien, donc le choix du héros à l'intro n'est pas signalé) ;
  • deux valeurs ou plus du flag du héros qu'aucune variante de héros ne reconnaît, si bien que ces héros ressemblent à celui qui est écrit (hero-looks-default, info, 4.3.0 ; voir Héros) ;
  • une cible derrière un lien de marche fermé par une condition, dont la règle ne vérifie pas cette condition (walk-link-gate : le lien arrête la marche, jamais l'action).

  Après une exécution du solveur, aussi : un fallback de signal requis que le témoin du monde fermé ne joue jamais (fallback-unplayed, un avertissement) ; une action vivante que le témoin n'a jamais jouée et un lieu où il n'est jamais entré (rule-never-run, room-never-reached : information avec le témoin, avertissements avec un --prove terminé ; une preuve tronquée les garde comme information et le dit, elle ne déclare jamais rien inatteignable) ; une action vivante jouée sans jamais changer l'état (rule-no-effect, info : un sujet qui ne fait que parler, ou un set déjà vrai). L'atteignabilité compte chaque essai du solveur, qu'il ait changé l'état ou non.

  Chaque remarque nomme son lieu et son chemin (celui qu'affiche l'onglet Rooms du Studio), son id stable, et ce qu'il faut faire. Codes de sortie : 0 propre, 1 une erreur non ignorée, 2 la recherche a été tronquée (--json porte status et truncated). --prove lance d'abord la recherche exhaustive (lente sur un gros jeu), --static ne lance aucun solveur, --max=<n> fixe le budget de la recherche (20 000). L'onglet Check du Studio montre la même liste avec des liens vers Rooms ; l'outil MCP lint la rend en Markdown. verify:game le lance, la CI aussi.

• Rejoué. Une session est l'unité de reproduction (Playtests) ; les sauvegardes se chargent d'une version à l'autre, avec une sauvegarde figée par release depuis la 3.0.0 (État et sauvegardes).

• Accessible autant qu'une machine peut le dire. axe-core sur chaque écran, jeu au clavier et au toucher en CI. Ce n'est pas une déclaration de conformité WCAG : les passes au lecteur d'écran et sur de vrais appareils reviennent à une personne (Accessibilité, Passes de terrain).

Garder une remarque exprès. Une fausse piste voulue, ou un flag décoratif (posé, jamais lu), se fait taire dans game.ts ; la même liste retire flag-never-read:<flag> des avertissements de validate :

lint: { ignore: ['item-red-herring:rubber_chicken', 'rule-shadowed:house/on[4]'] },   // un code, `code:<id>` ou `code:<lieu>/<chemin>`

ui.shareSession nomme la ligne du menu pause qui envoie un playtest depuis un téléphone (Playtests).

Commandes

Chaque commande ci-dessous se lance dans le dépôt du moteur avec npm run. La deuxième colonne donne l'équivalent dans un projet créé quand il existe ; « — » veut dire que le projet créé n'en a pas.

Le contenu du jeu

Les garde-fous du jeu

Les vérifications propres au dépôt du moteur

Dans un navigateur (dépôt du moteur ; le serveur de dev ou une build de production qui répond déjà à <url>)

Documentation et outillage du dépôt (dépôt du moteur)

Prouver que ça se joue

Dans le dépôt du moteur, npm test lance les tests du moteur et le parcours du jeu : une partie complète scriptée sur le vrai moteur (tests/demo-walkthrough.test.ts pour la démo). npm run e2e joue tout le jeu au toucher dans un Chromium à la taille d'un téléphone et enregistre une capture de chaque étape : regardez-les, ou faites-les regarder par votre assistant, pour attraper ce que le solveur ne voit pas (un personnage debout sur une table, une ligne coupée par le bord de l'écran).

# dans le dépôt du moteur : lancez le serveur de dev, puis dans un autre terminal
npm run dev
npm run e2e -- http://localhost:5173/

npm run e2e prend le chemin du solveur (npm run solve -- --json, ses steps) et le tapote. Il ne passe que si l'exécution du solveur est solved (son code de sortie, son statut et ses pas sont vérifiés) et que le moteur lui-même signale la fin (state.done) : un jeu tronqué ou non résolu est un échec, jamais « le meilleur chemin rejoué quand même ». games/demo/e2e.mjs est l'exemple d'un script e2e propre à un jeu : il part de l'écran titre, joue pour de vrai les mini-jeux des tuyaux et de la cueillette et le ticket à gratter de la fin scellée au lieu de les passer, puis vérifie la carte finale.

Limite · created-project-no-e2e Un projet créé n'a pas de commande test ni e2e : ses vérifications sont verify, build et release. L'e2e dans le navigateur et les vérifications visuelles, d'accessibilité, de performance et de musique tournent dans le dépôt du moteur.

En CI (le .github/workflows/ci.yml du dépôt du moteur) : chaque push sur main, chaque tag et chaque pull request lancent npm run build:game (les garde-fous du jeu, le bundle, les audits des spoilers et des assets) et npm run prove:game sur le jeu d'exemple ; les jobs plus lourds (l'e2e de production dans plusieurs navigateurs, les parties au clavier et en français, un second jeu fait depuis le modèle…) tournent quand ci:plan dit que le changement en a besoin. main se déploie sur Pages ; un tag publie une release. Le workflow hebdomadaire prove (le lundi, ou à la main) lance prove:game, les playtests stricts et le bench sur un jeu généré de 100 lieux. Dependabot propose les mises à jour npm et Actions chaque semaine, pip chaque mois (PR des bots).

Avant de partager le lien

• [ ] Prémisse, envie, obstacle par lieu et fin tiennent en quatre lignes.
• [ ] Le storyboard est définitif, et chaque texte de lieu en vient.
• [ ] Chaque lieu a un but, 3 à 6 étapes, un « aha », 8 à 15 choses nommées.
• [ ] Chaque chose nommée a sa ligne Regarder ; les regards répétés suivent normal, normal, normal, absurde.
• [ ] Chaque personnage a 2 à 4 sujets, un hug, un refuse et une couleur à lui.
• [ ] Chaque verbe a 3 à 6 réponses par défaut dans la voix du héros. Pas de « Ça ne marche pas ».
• [ ] Les indices couvrent chaque étape de chaque lieu, dans l'ordre, jusqu'à la fin.
• [ ] Chaque mini-jeu a une raison dans l'histoire, un bouton Passer, et dure une trentaine de secondes.
• [ ] La carte ne montre que les lieux débloqués ; les marques de nouveauté pointent vers l'étape suivante.
• [ ] Chaque changement d'état a un son.
• [ ] Aucune ligne de plus de 90 caractères.
• [ ] validate : aucune erreur. solve : fini, sans impasse, sans objet inutilisé. solve --prove : solved.
• [ ] Dépôt du moteur : npm test et npm run e2e passent ; captures relues.
• [ ] Joué du début à la fin sur un vrai téléphone, en paysage.
• [ ] Fin scellée vérifiée avec npm run check:spoilers (La fin scellée).
• [ ] Quelqu'un d'autre y a joué sans aide (Playtests).

Ensuite, construisez et livrez : Construire et publier un jeu.

Résultat attendu, et comment le vérifier

• validate : sa dernière ligne commence par ✔ [<jeu>] et compte les lieux, objets et personnages ; code 0. Les avertissements (⚠) ne le font pas échouer. « (images not checked: run npm run assets) » veut dire que les images n'ont pas été vérifiées.
• solve : ✔ The game can be finished et ✔ Witness solved: …, code 0.
• solve --prove : ✔ Proof solved: the ending stays reachable from every one of the N reachable states, code 0.
• lint : code 0 ; les remarques qui restent sont de l'information, ou ignorées exprès.

Le code de sortie est le verdict : 0 réussi, 1 un problème à corriger, 2 la recherche a été tronquée et rien n'est prouvé.

Erreurs fréquentes

Fichiers ou données modifiés

Les vérifications ne font que lire votre jeu. Ce qu'elles écrivent : .cache/proofs/ (le cache de preuves), et les dossiers que vous nommez avec --out. npm run e2e écrit ses captures dans E2E_OUT (par défaut /tmp/e2e). validate --report écrit dans le terminal ; page:world et page:puzzles écrivent leur page sous dist-pages/ (ou --out <dossier|fichier.html>). ids --write et provenance --lock sont les exceptions qui changent des fichiers que vous commitez : ce ne sont pas des vérifications, et elles le disent.

Revenir en arrière

Rien à défaire : une vérification ne change pas le jeu. Pour repartir de zéro, supprimez .cache/proofs/.

Références

• tools/validate.ts, tools/solve.ts, tools/lint.ts, cli/quest-n-click.mjs
• Ce que prouve le solveur, Options du solveur, Playtests
• L'onglet Check du Studio, Outils MCP
• Scripts npm, CLI

Modifier la source de cette page · Signaler une erreur