Adding Demo Experiments

Demo experiments are pre-exported JSON bundles stored on Cloudflare R2. The pipeline converts checkpoint files from an evolution run into static JSON that the viewer can display without a backend.

Demo Source Structure

Each demo experiment lives in Engine/demos/ under a domain/experiment path:

Engine/demos/
└── your_domain/
    └── experiment_name/
        ├── demo.yaml                    # experiment metadata
        ├── best.quale-brain             # champion brain file
        └── checkpoints/                 # preserved checkpoint files
            ├── checkpoint_gen100.quale-ckpt
            └── checkpoint_gen200.quale-ckpt

demo.yaml

Each demo directory must contain a demo.yaml with experiment metadata:

name: Your Experiment Name
domain: your_domain                     # R2 folder path (e.g. human_factors/rail)
domainRegistry: your_domain             # Go domain registry name (e.g. rail, survival)
domainLabel: Your Domain                # display label for badge pill
description: One-line description of what this experiment demonstrates
replayTicks: 300                        # simulation length for replay export
quale: path/to/experiment.quale         # .quale file for domain config (optional)

domain is the hierarchical path used for R2 folder structure and display grouping
domainRegistry matches the domain name used internally by the export pipeline for replay generation
quale points to the .quale project file needed to configure the GenericDomain for replay generation (required for domains that need route data or world configuration)

Export Command

The export-demo CLI command converts a demo source directory into the full JSON bundle:

quale export-demo demos/your_domain/experiment_name/ \
  --output /tmp/export/your_domain/experiment_name/

This generates:

File	Contents
`evolution.json`	Per-generation fitness/species history + brain topology at each checkpoint
`brains/best.json`	Champion brain topology
`brains/genN.json`	Brain topology at each checkpoint generation
`replays/best.json`	Tick-by-tick simulation replay for the champion
`replays/genN.json`	Replay for each checkpoint’s brain
`meta.json`	Experiment metadata for the landing page cards

The command handles two modes automatically:

Full checkpoint directory - when .quale-ckpt files are present, exports complete evolution history with per-checkpoint brains and replays
Brain-file-only - when only a .quale-brain file exists (no checkpoints), exports the single brain with its replay

Preserving Checkpoints

The evolution engine prunes old checkpoints to keep only the latest 3 by default (checkpoint_keep in the evolve block). To preserve checkpoints for demos:

Copy checkpoint files to Engine/demos/ immediately after a run completes, before the next run prunes them
Or increase checkpoint_keep in the .quale spec before running experiments intended as demos

CI/CD Pipeline

When demo source files are committed to the Engine repo under Engine/demos/, a GitHub Actions workflow automatically:

Builds the quale binary
Exports all demos to JSON via quale export-demo
Uploads JSON bundles to Cloudflare R2
Triggers the discovery endpoint to regenerate the experiment index

New demos appear on quale.run within minutes of pushing.