Skip to content

.zq project file format

Supported authored schema: 110. This reference describes editable .zq source projects. A project is a ZIP archive with JSON and optional media blobs. ZoneQ Studio remains the visual editor and preview surface.

Schema 110 and CLI 0.6.0 are available in the repository; a matching standalone CLI has not been published. The published CLI 0.3.0 supports schema 105. The schema-105 examples remain available.

For the current source format, build the CLI from a repository checkout with Node 22 or newer, then download the Stripes example:

Terminal window
npm --prefix tools/project-format ci
npm --prefix tools/project-format run build
node tools/project-format/dist/cli.mjs extract stripes.zq --out my-project --fork
# Edit my-project/project.json or add assets.
node tools/project-format/dist/cli.mjs pack my-project --out my-project.zq
node tools/project-format/dist/cli.mjs validate my-project.zq --json

Open my-project.zq with File → Open File… in Studio. Inspect the Stage and graph, play at several times, and save if the result is right. validate checks structure and references; it cannot judge the image, motion, or sound.

extract preserves the project’s identity by default. Use --fork when creating a different project from an example. Keep the projectId stable when editing your own project.

The JSON Schema covers structure. The local validator also checks graph wiring, cross-object references, archive integrity, and rules a structural schema cannot express.

Read Project structure and assets for ZIP layout, identity, asset references, and thumbnails. The CLI reference covers every command and the Portal download → upgrade → extract → edit → pack → validate workflow. Older Portal examples can be inspected after explicit local upgrade, without application source.

CLI release 0.3.0 · Reference updated 2026-10-02.

SurfaceSchema supportVerification
Authoring reference and examples110Updated 2026-10-07; Repository format source and reference. The standalone CLI verification above identifies the published format-tool version.
CLI 0.3.0Extract, pack, validate: 105. Upgrade: 101, 102, 103, 104, 105 → 105Verified public standalone CLI download; npm registry publication is not used for this release — 2026-10-02
Hosted Studio 1.0.0-beta.18, build 1092Reads 101, 102, 103, 104, 105; saves 105Verified hosted Studio and Player rendering — 2026-10-02
Portal uploadsCurrent authored schema 105Verified live ordinary-account upload, processing and exact source download — 2026-10-02; revision a7f5e6b6a17a

This is a dated release record, not live service status. Older Portal downloads retain their recorded source schema; upgrade before editing with the CLI. Details and evidence are in the release record. Entries marked unverified are not compatibility guarantees.

Read the schema and CLI changelog before editing an older file. If Studio reports a different expected schema, compare its displayed build with this table and reload to obtain the current hosted artifact. Report any remaining mismatch; do not change only the JSON version number.

ProjectDemonstrates
StripesImage generator and exposed controls
Color Grade + GlowEmbedded image and layered processing
Audio-Reactive GlowAudio source and parameter binding
Shared Texture RoutingSharing a produced field across layers
Reflective 3D SkullScene3D resource, materials, lighting, and model asset
Particle DriftParticle template and layer card

Continue with Archive and assets, Layers, inputs, and bindings, Shaders, Scene3D, and particles, and Validation and portability.