Project structure and assets
Supported authored schema: 110. The root of an editable .zq archive contains:
project.jsonmanifest/assets.jsonblobs/sha256/<64-character lowercase SHA-256>preview/thumb.webp optionalEvery declared blob appears under its content hash. manifest/assets.json must contain the same JSON data as project.json.assetManifest. Arbitrary files and extra blobs are rejected. The cover image is independent derived preview data, not an authored asset. Do not put instructions or unrelated documents inside the archive.
Project identity
Section titled “Project identity”project.json.version must be 110. projectId is the stable identity of the authored project; name is its display title. Keep the ID when updating a project. Mint a new ID for an independent project. output is required: adaptive fills its host, while fixed specifies width and height; both carry an FPS cap or null for unlimited realtime playback.
The JSON Schema lists every top-level collection, required field, and variant. Collections such as layers, projectInputs, bindingGraphs, particleTemplates, scene3DResources, simulationDefinitions, and simulationInstances are authored project data. Simulations save declarations, kernels, parameters, inputs, clock and quality settings. Live state, device buffers, compiled kernels and pending transactions are recreated on activation. Device selections, Portal ownership links, runtime media streams, and editor panel layout are not saved.
Asset descriptors and references
Section titled “Asset descriptors and references”assetManifest has version 1 and an assets array. Each descriptor has a stable id, kind, capabilities, display and source names, normalized importKey, MIME type, byte size, lowercase SHA-256 contentHash, folder placement, and decoded metadata. References inside project objects use project-asset:<asset-id>, never a ZIP path or filename. assetFolders supplies stable folder identities; moving an asset does not change its ID.
The extracted workspace uses the descriptor’s importKey as its local asset path, for example assets/poster.webp. The CLI keeps the ID and refreshes byte size and hash when repacking changed bytes. To add a new source:
node tools/project-format/dist/cli.mjs asset add my-project ./poster.webp --key assets/poster.webp --name PosterThe command copies the file, adds its descriptor, and prints project-asset:<new-id>. Insert that reference into the appropriate Project Input, texture binding, model entity, or environment field. asset add cannot choose the artistic use of the asset for you.
ZIP path traversal, missing blobs, undeclared blobs, mismatched hashes, stale manifests, and unknown schema versions fail validation. See Validation and portability.
Preview thumbnail
Section titled “Preview thumbnail”preview/thumb.webp is an optional, derived WebP image of the rendered project, independent of authored asset descriptors. Prepare it with a longest edge of 1024 pixels, the fixed project’s aspect ratio or 16:9 for adaptive output, and WebP quality approximately 0.92. The archive limit is 2 MiB. Centre-crop to cover that ratio; Studio captures against opaque black.
The CLI preserves previews but does not render them. You can omit the thumbnail entirely. To obtain Studio’s rendered preview, open and review the project, export with File → Export Project, then extract that exported .zq; use its preview/thumb.webp in your workspace. Capture may be omitted if unavailable. Alternatively capture the Stage yourself and prepare a WebP using the dimensions and quality above. Repack and validate after replacing it. A thumbnail does not prove rendering in every host.