scratch-run is a headless command-line interpreter for Scratch projects, built on TurboWarp/scratch-vm.
It was created to judge solutions written in Scratch: a project reads from standard input and writes to standard output, so it can be graded like any other program. scratch-run powers Scratch problems on our online judge VNOJ, but it works standalone too.
- No runtime dependencies — a single self-contained executable, packed with @yao-pkg/pkg.
- Fast — runs in turbo mode through the scratch-vm compiler, with no rendering, audio, or extensions.
- Supports
.sb,.sb2,.sb3, and rawproject.json.
Download a prebuilt binary for your platform from Releases. Builds are provided for Linux, macOS, and Windows, on both x64 and arm64.
scratch-run <project-file> [options]For example:
scratch-run tests/echo.sb3Type something and it is echoed back.
| Option | Description |
|---|---|
--check |
Validate the project file and exit (status 0 if valid, 1 otherwise). |
--print-generated-js |
Print the JavaScript compiled from the project instead of running it. |
--version |
Print the version. |
--help |
Print usage. |
scratch-run exits 0 on success and 1 on error — an unreadable or invalid file, or use of an unsupported extension. Error messages are written to standard error.
A Scratch project communicates with standard input and output through ordinary blocks:
| Block | Effect |
|---|---|
say [text] |
Write text followed by a newline to stdout. |
think [text] |
Write text to stdout with no trailing newline. |
ask [read_token] and wait |
Read one whitespace-separated token from stdin into answer. |
ask [...] and wait |
Read a full line from stdin into answer (any prompt other than read_token). |
In short: say prints a line, think prints without a newline, and ask reads input — a single token when the question is exactly read_token, otherwise a whole line. The value read is available in the built-in answer reporter.
Standard output is fully buffered (like C++'s std::cout when piped): output is flushed before each ask, and again when the project stops.
See the wiki for a fuller guide and worked examples.
git clone https://github.com/VNOI-Admin/scratch-run.git
cd scratch-run
yarn install
yarn buildyarn build bundles the VM with webpack and packages standalone executables into bin/<platform>/. By default it builds all targets; to build a single one, pass the pkg target and output directory through to build.sh:
./build.sh linux-x64 linux-amd64Running the test suite additionally requires Python:
python tests/test.py