Skip to content
Virtual Machine used to represent, run, and maintain the state of programs for Scratch 3.0
JavaScript Other
Branch: develop
Clone or download
knandersen Merge pull request #2231 from knandersen/bugfix/2230
Implements BLE manufacturer data-feature in LEGO BOOST extension
Latest commit 23d94b3 Sep 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Improve contribution guidelines and issue/pr templates Jan 17, 2017
.tx Update tx/config for Scratch 3.0 May 11, 2018
docs respond to code review Jun 18, 2019
src Merge pull request #2231 from knandersen/bugfix/2230 Sep 19, 2019
test Merge pull request #2192 from apple502j/list-cast-safely Sep 18, 2019
.editorconfig Add .editorconfig Jun 8, 2016
.eslintignore Add benchmark to ignore files Nov 21, 2017
.eslintrc.js Use ES6 linting rules in the project root Apr 24, 2017
.gitattributes Move build outputs into a `dist/` subdirectory (#375) Jan 13, 2017
.gitignore Remove cache from Travis, begin using npm ci Jun 28, 2018
.jsdoc.json Add jsdoc to package json and test/build tasks Jul 31, 2018
.npmignore Remove webpack config from npm ignore. Custom branches that depend di… Jul 10, 2018
.travis.yml Add scratch-l10n dependency (#1799) Dec 3, 2018
LICENSE Initial commit Mar 28, 2016 Update README for current process Jun 15, 2017
package.json Revert "Update gh-pages to the latest version 🚀" Aug 5, 2019
webpack.config.js use xmlEscape instead of escape-html for extensions Apr 17, 2019


Scratch VM is a library for representing, running, and maintaining the state of computer programs written using Scratch Blocks.

Build Status Coverage Status Greenkeeper badge


This requires you to have Git and Node.js installed.

To install as a dependency for your own application:

npm install scratch-vm

To set up a development environment to edit scratch-vm yourself:

git clone
cd scratch-vm
npm install

Development Server

This requires Node.js to be installed.

For convenience, we've included a development server with the VM. This is sometimes useful when running in an environment that's loading remote resources (e.g., SVGs from the Scratch server). If you would like to use your modified VM with the full Scratch 3.0 GUI, follow the instructions to link the VM to the GUI.

Running the Development Server

Open a Command Prompt or Terminal in the repository and run:

npm start


To view the Playground, make sure the dev server's running and go to http://localhost:8073/playground/ - you will be directed to the playground, which demonstrates various tools and internal state.

VM Playground Screenshot

Standalone Build

npm run build
<script src="/path/to/dist/web/scratch-vm.js"></script>
    var vm = new window.VirtualMachine();
    // do things

How to include in a Node.js App

For an extended setup example, check out the /src/playground directory, which includes a fully running VM instance.

var VirtualMachine = require('scratch-vm');
var vm = new VirtualMachine();

// Block events

// Run threads

Abstract Syntax Tree


The Virtual Machine constructs and maintains the state of an Abstract Syntax Tree (AST) by listening to events emitted by the scratch-blocks workspace via the blockListener. Each target (code-running object, for example, a sprite) keeps an AST for its blocks. At any time, the current state of an AST can be viewed by inspecting the vm.runtime.targets[...].blocks object.

Anatomy of a Block

The VM's block representation contains all the important information for execution and storage. Here's an example representing the "when key pressed" script on a workspace:

  "_blocks": {
    "Q]PK~yJ@BTV8Y~FfISeo": {
      "id": "Q]PK~yJ@BTV8Y~FfISeo",
      "opcode": "event_whenkeypressed",
      "inputs": {
      "fields": {
        "KEY_OPTION": {
          "name": "KEY_OPTION",
          "value": "space"
      "next": null,
      "topLevel": true,
      "parent": null,
      "shadow": false,
      "x": -69.333333333333,
      "y": 174
  "_scripts": [


npm test
npm run coverage

Publishing to GitHub Pages

npm run deploy

This will push the currently built playground to the gh-pages branch of the currently tracked remote. If you would like to change where to push to, add a repo url argument:

npm run deploy -- -r <your repo url>


We provide Scratch free of charge, and want to keep it that way! Please consider making a donation to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!

You can’t perform that action at this time.