La boucle de travail

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

Écrire une règle, la placer, la vérifier, y jouer : la boucle par laquelle passe chaque modification d'un jeu, avec les commandes de chaque étape dans un projet créé et dans le dépôt du moteur.

Ce que vous obtenez

Un jeu qui tourne dans votre navigateur et se recharge à chaque modification, un éditeur de placement pour la géométrie, le validateur et le solveur relancés après chaque changement, et des vues de débogage qui démarrent le jeu à n'importe quel point de reprise.

Contexte et versions

Un projet créé (quest-n-click create, le jeu dans game/) ou le dépôt du moteur (les jeux dans games/<id>/). La page d'organisation dit quels scripts existent où.
Depuis 4.3.0. Le jeu courant est un lien dans .cache/game depuis 4.1.6 (jusqu'en 4.1.5, npm run dev réécrivait tsconfig.json).

Prérequis

Node 22.12 ou plus récent, et les dépendances du projet installées (npm install dans un projet créé, npm ci dans le dépôt du moteur) : prérequis.
Python 3 avec Pillow pour npm run assets (chaîne d'images).
Un jeu : votre premier jeu en fabrique un.

Où lancer les commandes

Toutes les commandes se lancent à la racine du projet, sur votre machine : le dossier qui contient package.json (le dossier du projet créé, ou le clone du dépôt du moteur). npm run dev et npm run studio existent aux deux endroits ; npm run validate et npm run solve sont des scripts du seul dépôt du moteur, et s'écrivent npx quest-n-click validate et npx quest-n-click solve dans un projet créé.

Étapes

Préparez les images et les sons une première fois, puis à chaque ajout :
```
# dans le projet créé, ou dans le dépôt du moteur
npm run assets
```

Lancez le jeu. Il s'ouvre sur http://127.0.0.1:5173/ et se recharge quand un fichier du jeu change :
```
# dans le projet créé, ou dans le dépôt du moteur
npm run dev
```
Ou lancez le Studio, le vrai moteur avec un éditeur par-dessus, sur http://127.0.0.1:5173/__studio/ (le Studio local) :
```
# dans le projet créé, ou dans le dépôt du moteur
npm run studio
```

Écrivez ce qui se passe dans rooms/<salle>.ts (accessoires, acteurs, zones, textes Regarder, réactions, sujets, indices), avec l'histoire dans storyboard.json (salles, le storyboard).

Placez ce que vous avez écrit : ouvrez ?edit=<salle> sur le serveur de développement, ou l'onglet Rooms du Studio. L'éditeur écrit layout/<salle>.json (géométrie).

Vérifiez. L'onglet Check du Studio relance le validateur et le solveur après chaque enregistrement ; depuis le terminal :

# dans le dépôt du moteur
npm run validate
npm run solve

# dans le projet créé
npx quest-n-click validate
npx quest-n-click solve
npm run verify        # validate, solve, i18n status, lint, playtests

Jouez la salle : /?dev&at=<point> démarre sur un point de reprise avec la couche de débogage (paramètres d'URL ci-dessous). Sur un téléphone, voir tester par le réseau local.

Choisir le jeu (`GAME`)

Dans un projet créé il n'y a qu'un jeu, game/, rien à choisir.

Le dépôt du moteur peut contenir plusieurs jeux, chacun dans games/<id>/. Le jeu courant est, dans cet ordre (tools/game.ts) :

la variable d'environnement GAME (GAME=demo npm run dev) ;
sinon le jeu vers lequel pointe .cache/game (posé par npm run game ou npm run new-game) ;
sinon package.json → "config": { "game": "demo" } ;
sinon demo.

GAME_DIR=<dossier> dirige les outils vers un dossier de jeu hors de games/ (une fixture de test, par exemple).

La règle est codée une seule fois, dans tools/game.ts, et lue par vite.config.ts (l'alias @game → games/<GAME>/index.ts, les layouts de l'éditeur écrits dans games/<GAME>/layout/), tools/validate.ts, tools/solve.ts, tools/refs.ts ; tools/assets.py fait la même lecture en Python.

tsconfig.json ne sait pas lire une variable d'environnement : ses chemins @game et @game/* regardent dans .cache/game, un lien symbolique que npm run game (tools/select-game.ts) fait pointer vers le jeu courant, avec games/demo en repli tant qu'aucun lien n'existe. npm run dev, npm run studio, npm run check et npm run build le lancent d'abord ; GAME=<id> npm run game et npm run new-game changent de jeu. Vite et Vitest n'ont pas besoin du lien : ils résolvent l'alias dans vite.config.ts.

# dans le dépôt du moteur
GAME=heroes npm run game     # heroes devient le jeu courant
npm run dev                  # joue games/heroes

Les tests du moteur ne dépendent pas du jeu courant : ils tournent sur tests/fixture/ (un tout petit jeu), et les tests propres à un jeu importent directement ses fichiers (tests/demo.test.ts, tests/walkthrough.test.ts).

Jouer et déboguer

# dans le dépôt du moteur
npm run dev        # serveur de développement, boucle locale seulement
npm run dev:lan    # mode réseau local explicite pour un téléphone ; affiche une URL à jeton valable une session
npm run studio     # Studio, boucle locale seulement
npm run studio:lan # Studio protégé par jeton sur le réseau local

Paramètres d'URL, serveur de développement seulement (le build de production les ignore ; la liste complète est sur paramètres d'URL de développement) :

URL	Effet
`/`	Le jeu normal : écran titre, Nouvelle partie / Continuer.
`/?dev`	Démarre sur le premier point de reprise, avec la couche de débogage et le panneau DEV. La touche D masque la couche.
`/?dev&at=<point>`	Démarre sur ce point de reprise (défini dans les `checkpoints` du jeu).
`/?edit=<salle>`	L'éditeur de placement de la salle.
`/?edit=<salle>&at=<point>`	Pareil, dans l'état de ce point de reprise (utile pour placer un accessoire dans un état donné).

Résultat attendu, et comment le vérifier

La page se recharge avec votre modification ; l'onglet Check du Studio, ou validate, n'affiche aucune erreur.
solve affiche un chemin de Nouvelle partie jusqu'à la fin, étape par étape.
/?dev montre les zones de la salle (zone de marche en vert, zones cliquables en bleu, accessoires en violet, points d'approche en pastilles).

Erreurs fréquentes

Symptôme	Cause	Correction
`npm run validate` répond « Missing script »	Vous êtes dans un projet créé	`npx quest-n-click validate`
Le serveur joue un autre jeu que celui que vous modifiez	`GAME` est posé dans votre shell, ou `.cache/game` pointe ailleurs	`GAME=<id> npm run game`, ou retirez `GAME`
Une image manque à l'écran	`npm run assets` n'a pas tourné depuis son ajout	Lancez `npm run assets`
`?dev` ou `?edit` ne fait rien	Vous avez ouvert un build de production (`npm run preview`)	Passez par le serveur de développement
« no layout: nothing will be clickable »	La salle n'a jamais été placée	Ouvrez `?edit=<salle>` et enregistrez

Fichiers ou données modifiés

npm run assets : public/assets/ et assets.gen.json, .cache/refs.json.
L'éditeur de placement et le Studio : layout/<salle>.json (et les fichiers que vous modifiez dans le Studio).
npm run game, npm run new-game : le lien .cache/game (dépôt du moteur).

Reprise ou retour arrière

Tout ce qu'écrit la boucle est un fichier de votre projet : commitez avant un gros changement, et git restore les fichiers pour revenir en arrière. public/assets/ se reconstruit avec npm run assets.

Références

Modifier la source de cette page · Signaler une erreur