mirror of
https://github.com/scratchfoundation/scratch-vm.git
synced 2024-12-24 23:12:24 -05:00
af77098161
A recent change moved the location of the playground source files and the URL used to access the playground when running the dev server. This change updates README.md to reflect the new locations.
122 lines
3.8 KiB
Markdown
122 lines
3.8 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://greenkeeper.io/)
|
|
|
|
## 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/playground/](http://localhost:8073/playground/) - 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 /src/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!
|