Virtual Machine used to represent, run, and maintain the state of programs for Scratch 3.0
Find a file
Andrew Sliwinski 5daaaa4438 Merge pull request #362 from thisandagain/bugfix/coverage
Add integration test coverage
2017-01-03 09:38:14 -05:00
.github Remove Type section 2016-10-05 10:19:25 -04:00
playground Report full sprite info in targetsUpdate 2016-12-07 17:11:08 -05:00
src Merge pull request #362 from thisandagain/bugfix/coverage 2017-01-03 09:38:14 -05:00
test Resolve lint issues 2016-12-23 21:31:00 -05:00
.editorconfig Add .editorconfig 2016-06-08 16:27:38 -04:00
.eslintignore Add coverage/* to eslintignore 2016-10-24 11:58:38 -04:00
.eslintrc.js Update to eslint-config-scratch 2.0 2016-10-24 11:39:39 -04:00
.gitattributes Add .gitattributes so eslint can run on Windows 2016-10-18 09:38:28 -04:00
.gitignore Lint 2016-10-17 13:54:27 -04:00
.npmignore Publish to NPM 2016-09-26 09:42:53 -04:00
.travis.yml Fix "stable" specifier for Travis 2016-12-21 09:20:18 -05:00
CONTRIBUTING.md Add CONTRIBUTING.md for scratch-vm (#244) 2016-10-05 16:37:55 -04:00
LICENSE Initial commit 2016-03-28 12:53:44 -04:00
package.json Build out integration test SB2 files 2016-12-23 21:08:13 -05:00
README.md Removed reference to StartServerWindows.bat 2016-12-26 23:03:55 -06:00
TRADEMARK Initial commit 2016-03-28 12:53:44 -04:00
webpack.config.js Merge pull request #335 from rschamp/feature/port 2016-11-21 14:32:44 -05:00

scratch-vm

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

Build Status Coverage Status Dependency Status devDependency Status

Installation

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

In your own node environment/application:

npm install https://github.com/LLK/scratch-vm.git

If you want to edit/play yourself:

git clone https://github.com/LLK/scratch-vm.git
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).

Running the Development Server

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

npm start

Playground

To run the Playground, make sure the dev server's running and go to http://localhost:8073/ - 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/vm.js"></script>
<script>
    var vm = new window.VirtualMachine();
    // do things
</script>

How to include in a Node.js App

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

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

// Block events
workspace.addChangeListener(vm.blockListener);

// Run threads
vm.start();

Abstract Syntax Tree

Overview

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": [
    "Q]PK~yJ@BTV8Y~FfISeo"
  ]
}

Testing

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>

Donate

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!