Repository files navigation

The Scratch Team has migrated thescratch-vm module into a new mono-repo,scratch-editor. This independentscratch-vm repositorywill be archived. Any new issues or pull requests should be opened in the mono-repo.

The new mono-repo version ofscratch-vm is published to the NPM registry as@scratch/scratch-vm.

Contributors:

• I would like to thank all past contributors for their work on this repository.
• If you are aware of valuable issues or pull requests, please consider re-opening them in the mono-repo. If you doso, please link the new issue or pull request to the original one in this repository to help others find it and toreduce the chance of duplicate work.
• We apologize for the inconvenience and greatly appreciate your help with this transition!

For more information, see thescratch-editor repository on GitHub.

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/scratchfoundation/scratch-vm.gitcd scratch-vmnpm install

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.

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 tohttp://localhost:8073/playground/ - you will be directed to the playground, which demonstrates various tools and internal state.

npm run build

<scriptsrc="/path/to/dist/web/scratch-vm.js"></script><script>varvm=newwindow.VirtualMachine();// do things</script>

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

varVirtualMachine=require('scratch-vm');varvm=newVirtualMachine();// Block eventsScratch.workspace.addChangeListener(vm.blockListener);// Run threadsvm.start();

The Virtual Machine constructs and maintains the state of anAbstract Syntax Tree (AST) by listening to events emitted by thescratch-blocks workspace via theblockListener. 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 thevm.runtime.targets[...].blocks object.

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"  ]}

npmtest

npm run coverage

npm run deploy

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

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

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