Virtual Machine used to represent, run, and maintain the state of programs for Scratch 3.0
Find a file
Christopher Willis-Ford 840ffb5df0 test: don't use process.exit to end tests
Newer versions of `tap` run more asynchronously, so sometimes using `process.nextTick(process.exit)`
to end a test would prevent the test from completing correctly. Removing all instances of
`process.nextTick(process.exit)` put tests into three categories:
* the test still worked correctly -- no fixup needed.
* the test would hang because the VM's `_steppingInterval` was keeping
  Node alive. These tests call a new `quit()` method which ends the
  stepping interval.
* the `load-extensions` test needed special attention because the "Video
  Sensing" extension starts its own loop using `setTimeout`. I added a
  `_stopLoop()` method on the extension and directly call that from the
  test. I'm not completely happy with this solution but anything more
  general would likely require a change to the extension spec, so I'm
  leaving that as a followup task.
2022-06-07 11:44:06 -07:00
.circleci ci: add initial CircleCI config 2022-06-07 11:44:06 -07:00
.github update contributor guidelines 2020-05-28 15:25:11 -04:00
.husky chore: add husky hook for commitlint 2022-06-07 11:44:05 -07:00
.tx Update tx/config for Scratch 3.0 2018-05-11 08:20:20 -04:00
docs remove links to older extensions page 2021-06-24 13:46:03 -04:00
src test: don't use process.exit to end tests 2022-06-07 11:44:06 -07:00
test test: don't use process.exit to end tests 2022-06-07 11:44:06 -07:00
.editorconfig Add .editorconfig 2016-06-08 16:27:38 -04:00
.eslintignore Add benchmark to ignore files 2017-11-20 19:18:18 -05:00
.eslintrc.js Use ES6 linting rules in the project root 2017-04-24 15:37:58 -04:00
.gitattributes use scratch-renovate-config:conservative 2021-07-26 16:28:07 -07:00
.gitignore Remove cache from Travis, begin using npm ci 2018-06-28 10:52:04 -04:00
.jsdoc.json Add jsdoc to package json and test/build tasks 2018-07-31 11:22:42 -04:00
.npmignore Remove webpack config from npm ignore. Custom branches that depend directly on the repo need this to work. 2018-07-10 16:41:43 -04:00
.travis.yml ci(node): update CI config to use Node LTS (was 8 & 10) 2022-05-23 16:28:23 -07:00
commitlint.config.js chore: add commitlint 2022-06-07 11:44:05 -07:00
LICENSE Initial commit 2016-03-28 12:53:44 -04:00
package-lock.json test: upgrade tap, configure coverage thresholds 2022-06-07 11:44:06 -07:00
package.json test: upgrade tap, configure coverage thresholds 2022-06-07 11:44:06 -07:00
README.md Remove greenkeeper lockfile 2021-03-23 17:13:08 -04:00
release.config.js chore: add semantic-release settings 2022-06-07 11:44:06 -07:00
renovate.json5 use scratch-renovate-config:conservative 2021-07-26 16:28:07 -07:00
TRADEMARK Update TRADEMARK 2018-06-18 13:13:09 -04:00
webpack.config.js replace nets with Fetch API 2021-02-19 10:56:33 -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

Installation

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 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). 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

Playground

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>
<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 /src/playground directory, which includes a fully running VM instance.

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

// Block events
Scratch.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!