Asset provenance

Français · Type: how-to + reference · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 4.2.5

A release says where every image, sound, voice and video it ships comes from, under which licence, and proves that the files are the ones someone reviewed. This page shows how to write provenance.json, lock it after a review, and pass a release or a commercial release.

What you get

A provenance.json that covers every shipped asset exactly once, a provenance.lock.json holding each file's SHA-256 and size with the claims it was reviewed under, and a release check that fails as soon as a file or a claim changes without a new review.

Context and versions

The engine repository (games/<id>/provenance.json) and the created project (game/provenance.json). True from 4.2.5 (the quest-n-click command name). The lock dates from 3.3.0, the commercial check from 3.3.1, the shipped archive's licence files from 3.7.1.

Prerequisites

• The assets prepared: npm run assets has run, so assets.gen.json and public/assets/ exist. The checks read the files under public/assets (ASSETS_DIR points elsewhere, for a test fixture).
• For each asset, you know its source, its licence and its author.

Where to run the commands

On your machine, at the root of the engine repository (npm run …) or of the created project (npx quest-n-click …, npm run release).

Steps

1. Write an entry per source in provenance.json. A created project starts with one: its template art is a placeholder drawn from shapes, marked 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" }
     ]
   }
   

   The fields are in the reference below. Each asset must match exactly one entry.

2. Check the coverage.

   # in the engine repository
   npm run provenance          # assets by licence, and what changed since the lock (exit 1: something to review)
   npm run validate            # a game with provenance.json: every asset covered once, every entry complete
   

   # in the created project
   npx quest-n-click provenance
   npx quest-n-click validate
   

3. Review, then lock. Look at every file and its entry. Then:

   # in the engine repository
   npm run provenance -- --lock
   

   # in the created project
   npx quest-n-click provenance --lock
   

   It refuses to lock while an asset is uncovered, ambiguous, its entry incomplete, or its file missing (✖ … not locked: fix the provenance first).

4. Pass the release gates.

   # in the engine repository
   npm run verify:release      # validate --release, weight --release, i18n status, voices check --release, strict playtests
   npm run verify:commercial   # verify:release, then validate --commercial, then verify:dist
   

   # in the created project
   npm run release                         # includes validate --release
   npm run release -- --commercial         # also validate --commercial
   

Guarantee · provenance-lock-detects-change · referenced · executed on aff6caab7514 · scope self-checked by the author (AI), not reviewed After --lock, a file whose bytes changed, an asset shipped since, a file missing or an entry whose licence was edited is reported.

validate --release fails on each of these, a plain validate only warns. An edited pattern or status is reported like an edited licence.

Limit · claims-not-truth The checks say the claims are complete and allow the release (or the sale), not that they are true. A wrong licence written in good faith passes. The review before --lock is a person's job.

Expected result, and how to check it

npm run provenance ends with ✔ [<game>] provenance clean: every file is the one reviewed, and verify:release (created project: npm run release) passes. What an exception lets through is printed as ℹ accepted: …, by name, not as a warning to fix.

Common errors

Files or data changed

• provenance.json (you write it), provenance.lock.json (--lock writes it).
• The build writes, into dist/licenses/: LICENSE, LICENSE-ASSETS, CREDITS.md, THIRD_PARTY_NOTICES.txt and assets-manifest.json (see the reference).

Recovery or going back

A lock is a file: under git, git checkout -- provenance.lock.json brings the previous one back. Changing a file after a lock is not a mistake to undo: review it again, then lock again.

Reference: provenance.json

Entries

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

The keys map to the built files: img:<id> → public/assets/img/<id>.webp, sfx:<file> → audio/sfx/<file>, music:<file> → audio/music/<file>, voice:<file> → audio/voices/<file>, video:<file> → video/<file>.

Licence policy and exceptions

• licences: { allow: ['CC BY 4.0', 'own work'] }: a release needs it; any other licence fails unless an exception names the asset.
• releaseExceptions: [{ match, reason }]: lets a named placeholder or licence through a release, with its reason. An exception never covers a placeholder added later.

What each command checks

npm run new-game (engine repository) writes a provenance.json for the art it borrows from the sample game: all placeholders, CC BY 4.0. The sample game's own file has no exception: every one of its assets is CC BY 4.0 since 3.7, and it passes verify:commercial. tests/fixtures/release-game fails it on purpose.

What the shipped archive holds (3.7.1)

The checks above read the game's asset graph; the archive is what Vite copies into dist/, and in the engine repository public/ is shared by every game. So every build ends with tools/dist.ts seal (a Vite plugin): the assets that are not this game's are removed, and dist/licenses/ is written: the engine's LICENSE, LICENSE-ASSETS (the game's own if it has one), CREDITS.md from its provenance, THIRD_PARTY_NOTICES.txt (the licence of every package the bundle took code from, Workbox's for the service worker, the fonts' OFL) and assets-manifest.json (each file: path, author, source, licence, SHA-256, status). Then npm run verify:dist (a step of npm run build, so of the release) classifies every file of dist/: code, a locked asset whose bytes are the ones reviewed, a data file the game names (ending.file), a font, an icon, a notice. Anything else fails, and so does a locked file or a notice that is missing. The release attaches the assets manifest beside the archive.

The weight budgets and translations checks that the same release gates run are in Images, Build and release and Translations.

Limit · audit-is-different npm run audit (engine repository) is a different check: it keeps names from a private project out of the public repository. It says nothing about licences.

References

• tools/provenance.ts, tools/provenance-files.ts, src/engine/tools/provenance.ts, tools/dist.ts, tests/provenance.test.ts.
• Build and release · Images · Sound effects · Voices · Licences and credits.

Edit the source of this page · Report an error