mirror of
https://github.com/scratchfoundation/scratch-vm.git
synced 2024-12-25 15:32:40 -05:00
123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
## scratch-vm
|
|
#### Scratch VM is a library for representing, running, and maintaining the state of computer programs written using [Scratch Blocks](https://github.com/LLK/scratch-blocks).
|
|
|
|
[](https://travis-ci.org/LLK/scratch-vm)
|
|
[](https://coveralls.io/github/LLK/scratch-vm?branch=develop)
|
|
[](https://david-dm.org/LLK/scratch-vm)
|
|
[](https://david-dm.org/LLK/scratch-vm#info=devDependencies)
|
|
|
|
## Installation
|
|
This requires you to have Git and Node.js installed.
|
|
|
|
In your own node environment/application:
|
|
```bash
|
|
npm install https://github.com/LLK/scratch-vm.git
|
|
```
|
|
If you want to edit/play yourself:
|
|
```bash
|
|
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:
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
## Playground
|
|
To run the Playground, make sure the dev server's running and go to [http://localhost:8073/](http://localhost:8073/) - you will be directed to the playground, which demonstrates various tools and internal state.
|
|
|
|
|
|
|
|
|
|
## Standalone Build
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
```html
|
|
<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.
|
|
```js
|
|
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](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST) by listening to events emitted by the [scratch-blocks](https://github.com/LLK/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:
|
|
```json
|
|
{
|
|
"_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
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
```bash
|
|
npm run coverage
|
|
```
|
|
|
|
## Publishing to GitHub Pages
|
|
```bash
|
|
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:
|
|
```bash
|
|
npm run deploy -- -r <your repo url>
|
|
```
|
|
|
|
## Donate
|
|
We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!
|