Provenance des assets

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

Une release dit d’où vient chaque image, son, voix et vidéo qu’elle livre, sous quelle licence, et prouve que les fichiers sont bien ceux que quelqu’un a relus. Cette page montre comment écrire provenance.json, le verrouiller après une relecture, et passer une release ou une release commerciale.

Ce que vous obtenez

Un provenance.json qui couvre chaque asset livré exactement une fois, un provenance.lock.json qui garde le SHA-256 et la taille de chaque fichier avec les déclarations sous lesquelles il a été relu, et une vérification de release qui échoue dès qu’un fichier ou une déclaration change sans nouvelle relecture.

Contexte et versions

Le dépôt du moteur (games/<id>/provenance.json) et le projet créé (game/provenance.json). Vrai à partir de 4.2.5 (le nom de commande quest-n-click). Le verrou date de 3.3.0, la vérification commerciale de 3.3.1, les fichiers de licence de l’archive livrée de 3.7.1.

Prérequis

• Les assets préparés : npm run assets a tourné, donc assets.gen.json et public/assets/ existent. Les vérifications lisent les fichiers de public/assets (ASSETS_DIR pointe ailleurs, pour une fixture de test).
• Pour chaque asset, vous connaissez sa source, sa licence et son auteur.

Où lancer les commandes

Sur votre machine, à la racine du dépôt du moteur (npm run …) ou du projet créé (npx quest-n-click …, npm run release).

Étapes

1. Écrire une entrée par source dans provenance.json. Un projet créé en a déjà une : les images de son modèle sont des emplacements dessinés à partir de formes, marqués placeholder.

   {
     "licences": { "allow": ["CC BY 4.0", "own work"] },
     "assets": [
       { "match": "img:*", "source": "Drawn for the game from the prompts in prompts.md", "author": "Wano",
         "licence": "CC BY 4.0", "status": "final" },
       { "match": "sfx:door_*.mp3", "source": "Recorded at home", "author": "Wano", "licence": "own work",
         "status": "final" }
     ]
   }
   

   Les champs sont dans la référence plus bas. Chaque asset doit correspondre à exactement une entrée.

2. Vérifier la couverture.

   # dans le dépôt du moteur
   npm run provenance          # les assets par licence, et ce qui a changé depuis le verrou (code 1 : quelque chose à relire)
   npm run validate            # un jeu avec provenance.json : chaque asset couvert une fois, chaque entrée complète
   

   # dans le projet créé
   npx quest-n-click provenance
   npx quest-n-click validate
   

3. Relire, puis verrouiller. Regardez chaque fichier et son entrée. Puis :

   # dans le dépôt du moteur
   npm run provenance -- --lock
   

   # dans le projet créé
   npx quest-n-click provenance --lock
   

   La commande refuse de verrouiller tant qu’un asset n’est pas couvert, est ambigu, a une entrée incomplète ou un fichier manquant (✖ … not locked: fix the provenance first).

4. Passer les portes de release.

   # dans le dépôt du moteur
   npm run verify:release      # validate --release, weight --release, i18n status, voices check --release, playtests stricts
   npm run verify:commercial   # verify:release, puis validate --commercial, puis verify:dist
   

   # dans le projet créé
   npm run release                         # comprend validate --release
   npm run release -- --commercial         # avec validate --commercial en plus
   

Garantie · provenance-lock-detects-change · référencée · exécutée sur aff6caab7514 · portée vérifiée par son auteur (IA), pas relue Après --lock, un fichier dont les octets ont changé, un asset livré depuis, un fichier manquant ou une entrée dont la licence a été modifiée est signalé.

validate --release échoue sur chacun, un validate simple ne fait qu’avertir. Un motif ou un statut modifié est signalé comme une licence modifiée.

Limite · claims-not-truth Les vérifications disent que les déclarations sont complètes et permettent la release (ou la vente), pas qu’elles sont vraies. Une mauvaise licence écrite de bonne foi passe. La relecture avant --lock est le travail d’une personne.

Résultat attendu, et comment le vérifier

npm run provenance se termine par ✔ [<jeu>] provenance clean: every file is the one reviewed, et verify:release (projet créé : npm run release) passe. Ce qu’une exception laisse passer s’affiche en ℹ accepted: …, nommément, pas comme un avertissement à corriger.

Erreurs fréquentes

Fichiers ou données modifiés

• provenance.json (vous l’écrivez), provenance.lock.json (--lock l’écrit).
• Le build écrit, dans dist/licenses/ : LICENSE, LICENSE-ASSETS, CREDITS.md, THIRD_PARTY_NOTICES.txt et assets-manifest.json (voir la référence).

Revenir en arrière

Un verrou est un fichier : sous git, git checkout -- provenance.lock.json ramène le précédent. Changer un fichier après un verrou n’est pas une erreur à annuler : relisez-le, puis verrouillez de nouveau.

Référence : provenance.json

Les entrées

assets: [{ match, source, licence, author?, url?, prompt?, status, note? }]

Les clés correspondent aux fichiers construits : img:<id> → public/assets/img/<id>.webp, sfx:<fichier> → audio/sfx/<fichier>, music:<fichier> → audio/music/<fichier>, voice:<fichier> → audio/voices/<fichier>, video:<fichier> → video/<fichier>.

Politique de licences et exceptions

• licences: { allow: ['CC BY 4.0', 'own work'] } : une release l’exige ; toute autre licence échoue, sauf exception qui nomme l’asset.
• releaseExceptions: [{ match, reason }] : laisse passer un emplacement ou une licence nommés dans une release, avec sa raison. Une exception ne couvre jamais un emplacement ajouté plus tard.

Ce que vérifie chaque commande

npm run new-game (dépôt du moteur) écrit un provenance.json pour les images qu’il emprunte au jeu d’exemple : que des emplacements, en CC BY 4.0. Le fichier du jeu d’exemple n’a aucune exception : tous ses assets sont en CC BY 4.0 depuis 3.7, et il passe verify:commercial. tests/fixtures/release-game y échoue exprès.

Ce que contient l’archive livrée (3.7.1)

Les vérifications ci-dessus lisent le graphe d’assets du jeu ; l’archive, c’est ce que Vite copie dans dist/, et dans le dépôt du moteur public/ est partagé par tous les jeux. Chaque build se termine donc par tools/dist.ts seal (un plugin Vite) : les assets qui ne sont pas à ce jeu sont retirés, et dist/licenses/ est écrit : la LICENSE du moteur, LICENSE-ASSETS (celle du jeu s’il en a une), CREDITS.md tiré de sa provenance, THIRD_PARTY_NOTICES.txt (la licence de chaque paquet dont le bundle a pris du code, celle de Workbox pour le service worker, l’OFL des polices) et assets-manifest.json (chaque fichier : chemin, auteur, source, licence, SHA-256, statut). Puis npm run verify:dist (une étape de npm run build, donc de la release) classe chaque fichier de dist/ : du code, un asset verrouillé dont les octets sont ceux relus, un fichier de données que le jeu nomme (ending.file), une police, une icône, une notice. Tout le reste échoue, de même qu’un fichier verrouillé ou une notice qui manque. La release joint le manifeste des assets à côté de l’archive.

Les budgets de poids et les vérifications de traduction que lancent les mêmes portes de release sont dans Images, Build et release et Traductions.

Limite · audit-is-different npm run audit (dépôt du moteur) est une autre vérification : elle tient les noms d’un projet privé hors du dépôt public. Elle ne dit rien des licences.

Références

• tools/provenance.ts, tools/provenance-files.ts, src/engine/tools/provenance.ts, tools/dist.ts, tests/provenance.test.ts.
• Build et release · Images · Bruitages · Voix · Licences et crédits.

Modifier la source de cette page · Signaler une erreur