cqxqgtech/easy-scratch
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
easy-scratch/doc/scratch-vm/index.html

1720 lines
86 KiB
HTML
Raw Permalink Normal View History

easy-scratch项目源码
2025-02-12 12:27:32 +00:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Home - Documentation</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
<script src="scripts/nav.js" defer></script>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
<div class="navicon"></div>
</label>
<label for="nav-trigger" class="overlay"></label>
<nav >
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="-_StackFrame.html">_StackFrame</a><ul class='methods'><li data-type='method'><a href="-_StackFrame.html#.create">create</a></li><li data-type='method'><a href="-_StackFrame.html#.release">release</a></li><li data-type='method'><a href="-_StackFrame.html#reset">reset</a></li><li data-type='method'><a href="-_StackFrame.html#reuse">reuse</a></li></ul></li><li><a href="BLE.html">BLE</a><ul class='methods'><li data-type='method'><a href="BLE.html#connectPeripheral">connectPeripheral</a></li><li data-type='method'><a href="BLE.html#didReceiveCall">didReceiveCall</a></li><li data-type='method'><a href="BLE.html#disconnect">disconnect</a></li><li data-type='method'><a href="BLE.html#handleDisconnectError">handleDisconnectError</a></li><li data-type='method'><a href="BLE.html#isConnected">isConnected</a></li><li data-type='method'><a href="BLE.html#read">read</a></li><li data-type='method'><a href="BLE.html#requestPeripheral">requestPeripheral</a></li><li data-type='method'><a href="BLE.html#startNotifications">startNotifications</a></li><li data-type='method'><a href="BLE.html#write">write</a></li></ul></li><li><a href="BlockCached.html">BlockCached</a></li><li><a href="Blocks.html">Blocks</a><ul class='methods'><li data-type='method'><a href="Blocks.html#_addScript">_addScript</a></li><li data-type='method'><a href="Blocks.html#_deleteScript">_deleteScript</a></li><li data-type='method'><a href="Blocks.html#_getBackdropField">_getBackdropField</a></li><li data-type='method'><a href="Blocks.html#_getBlockParams">_getBlockParams</a></li><li data-type='method'><a href="Blocks.html#_getCostumeField">_getCostumeField</a></li><li data-type='method'><a href="Blocks.html#_getCustomBlockInternal">_getCustomBlockInternal</a></li><li data-type='method'><a href="Blocks.html#_getSoundField">_getSoundField</a></li><li data-type='method'><a href="Blocks.html#_getSpriteField">_getSpriteField</a></li><li data-type='method'><a href="Blocks.html#blocklyListen">blocklyListen</a></li><li data-type='method'><a href="Blocks.html#blockToXML">blockToXML</a></li><li data-type='method'><a href="Blocks.html#changeBlock">changeBlock</a></li><li data-type='method'><a href="Blocks.html#createBlock">createBlock</a></li><li data-type='method'><a href="Blocks.html#deleteBlock">deleteBlock</a></li><li data-type='method'><a href="Blocks.html#emitProjectChanged">emitProjectChanged</a></li><li data-type='method'><a href="Blocks.html#getAllVariableAndListReferences">getAllVariableAndListReferences</a></li><li data-type='method'><a href="Blocks.html#getBlock">getBlock</a></li><li data-type='method'><a href="Blocks.html#getBranch">getBranch</a></li><li data-type='method'><a href="Blocks.html#getFields">getFields</a></li><li data-type='method'><a href="Blocks.html#getInputs">getInputs</a></li><li data-type='method'><a href="Blocks.html#getMutation">getMutation</a></li><li data-type='method'><a href="Blocks.html#getNextBlock">getNextBlock</a></li><li data-type='method'><a href="Blocks.html#getOpcode">getOpcode</a></li><li data-type='method'><a href="Blocks.html#getProcedureDefinition">getProcedureDefinition</a></li><li data-type='method'><a href="Blocks.html#getProcedureParamNamesAndIds">getProcedureParamNamesAndIds</a></li><li data-type='method'><a href="Blocks.html#getProcedureParamNamesIdsAndDefaults">getProcedureParamNamesIdsAndDefaults</a></li><li data-type='method'><a href="Blocks.html#getScripts">getScripts</a></li><li data-type='method'><a href="Blocks.html#getTopLevelScript">getTopLevelScript</a></li><li data-type='method'><a href="Blocks.html#moveBlock">moveBlock</a></li><li data-type='method'><a href="Blocks.html#mutationToXML">mutationToXML</a></li><li data-type='method'><a href="Blocks.html#resetCache">resetCache</a></li><li data-type='method'><a href="Blocks.html#runAllMonitored">runAllMonitored</a></li><li data-type='method'><a href="Blocks.html#toXML">toXML</a></li><li data-type='method'><a href="Blocks.html#updateAssetName">updateAssetName</a></li><li data-type='method'><a href
</nav>
<div id="main">
<section class="package">
<h3> </h3>
</section>
<section class="readme">
<article><h2>scratch-vm</h2>
<h4>Scratch VM is a library for representing, running, and maintaining the state of computer programs written using <a href="https://github.com/LLK/scratch-blocks">Scratch Blocks</a>.</h4>
<p><a href="https://travis-ci.org/LLK/scratch-vm"><img src="https://travis-ci.org/LLK/scratch-vm.svg?branch=develop" alt="Build Status"></a>
<a href="https://coveralls.io/github/LLK/scratch-vm?branch=develop"><img src="https://coveralls.io/repos/github/LLK/scratch-vm/badge.svg?branch=develop" alt="Coverage Status"></a>
<a href="https://greenkeeper.io/"><img src="https://badges.greenkeeper.io/LLK/scratch-vm.svg" alt="Greenkeeper badge"></a></p>
<h2>Installation</h2>
<p>This requires you to have Git and Node.js installed.</p>
<p>To install as a dependency for your own application:</p>
<pre class="prettyprint source lang-bash"><code>npm install scratch-vm
</code></pre>
<p>To set up a development environment to edit scratch-vm yourself:</p>
<pre class="prettyprint source lang-bash"><code>git clone https://github.com/LLK/scratch-vm.git
cd scratch-vm
npm install
</code></pre>
<h2>Development Server</h2>
<p>This requires Node.js to be installed.</p>
<p>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, <a href="https://github.com/LLK/scratch-gui/wiki/Getting-Started">follow the instructions to link the VM to the GUI</a>.</p>
<h2>Running the Development Server</h2>
<p>Open a Command Prompt or Terminal in the repository and run:</p>
<pre class="prettyprint source lang-bash"><code>npm start
</code></pre>
<h2>Playground</h2>
<p>To view the Playground, make sure the dev server's running and go to <a href="http://localhost:8073/playground/">http://localhost:8073/playground/</a> - you will be directed to the playground, which demonstrates various tools and internal state.</p>
<p><img src="https://i.imgur.com/nOCNqEc.gif" alt="VM Playground Screenshot"></p>
<h2>Standalone Build</h2>
<pre class="prettyprint source lang-bash"><code>npm run build
</code></pre>
<pre class="prettyprint source lang-html"><code>&lt;script src=&quot;/path/to/dist/web/scratch-vm.js&quot;>&lt;/script>
&lt;script>
var vm = new window.VirtualMachine();
// do things
&lt;/script>
</code></pre>
<h2>How to include in a Node.js App</h2>
<p>For an extended setup example, check out the /src/playground directory, which includes a fully running VM instance.</p>
<pre class="prettyprint source lang-js"><code>var VirtualMachine = require('scratch-vm');
var vm = new VirtualMachine();
// Block events
Scratch.workspace.addChangeListener(vm.blockListener);
// Run threads
vm.start();
</code></pre>
<h2>Abstract Syntax Tree</h2>
<h4>Overview</h4>
<p>The Virtual Machine constructs and maintains the state of an <a href="https://en.wikipedia.org/wiki/Abstract_syntax_tree">Abstract Syntax Tree</a> (AST) by listening to events emitted by the <a href="https://github.com/LLK/scratch-blocks">scratch-blocks</a> workspace via the <code>blockListener</code>. 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 <code>vm.runtime.targets[...].blocks</code> object.</p>
<h4>Anatomy of a Block</h4>
<p>The VM's block representation contains all the important information for execution and storage. Here's an example representing the &quot;when key pressed&quot; script on a workspace:</p>
<pre class="prettyprint source lang-json"><code>{
&quot;_blocks&quot;: {
&quot;Q]PK~yJ@BTV8Y~FfISeo&quot;: {
&quot;id&quot;: &quot;Q]PK~yJ@BTV8Y~FfISeo&quot;,
&quot;opcode&quot;: &quot;event_whenkeypressed&quot;,
&quot;inputs&quot;: {
},
&quot;fields&quot;: {
&quot;KEY_OPTION&quot;: {
&quot;name&quot;: &quot;KEY_OPTION&quot;,
&quot;value&quot;: &quot;space&quot;
}
},
&quot;next&quot;: null,
&quot;topLevel&quot;: true,
&quot;parent&quot;: null,
&quot;shadow&quot;: false,
&quot;x&quot;: -69.333333333333,
&quot;y&quot;: 174
}
},
&quot;_scripts&quot;: [
&quot;Q]PK~yJ@BTV8Y~FfISeo&quot;
]
}
</code></pre>
<h2>Testing</h2>
<pre class="prettyprint source lang-bash"><code>npm test
</code></pre>
<pre class="prettyprint source lang-bash"><code>npm run coverage
</code></pre>
<h2>Publishing to GitHub Pages</h2>
<pre class="prettyprint source lang-bash"><code>npm run deploy
</code></pre>
<p>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:</p>
<pre class="prettyprint source lang-bash"><code>npm run deploy -- -r &lt;your repo url>
</code></pre>
<h2>Donate</h2>
<p>We provide <a href="https://scratch.mit.edu">Scratch</a> free of charge, and want to keep it that way! Please consider making a <a href="https://secure.donationpay.org/scratchfoundation/">donation</a> to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!</p></article>
</section>
<section>
<header>
<h2>
engine/block-utility.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Interface provided to block primitive functions for interacting with the
runtime, thread, target, and convenient methods.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/blocks.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Store and mutate the VM block representation,
and handle updates from Scratch Blocks events.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/blocks-execute-cache.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Access point for private method shared between blocks.js and execute.js for
caching execute information.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/blocks-runtime-cache.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>The BlocksRuntimeCache caches data about the top block of scripts so that
Runtime can iterate a targeted opcode and iterate the returned set faster.
Many top blocks need to match fields as well as opcode, since that matching
compares strings in uppercase we can go ahead and uppercase the cached value
so we don't need to in the future.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/comment.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Object representing a Scratch Comment (block or workspace).</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/profiler.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>A way to profile Scratch internal performance. Like what blocks run during a
step? How much time do they take? How much time is spent inbetween blocks?</p>
<p>Profiler aims for to spend as little time inside its functions while
recording. For this it has a simple internal record structure that records a
series of values for each START and STOP event in a single array. This lets
all the values be pushed in one call for the array. This simplicity allows
the contents of the start() and stop() calls to be inlined in areas that are
called frequently enough to want even greater performance from Profiler so
what is recorded better reflects on the profiled code and not Profiler
itself.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/target.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>A Target is an abstract &quot;code-running&quot; object for the Scratch VM.
Examples include sprites/clones or potentially physical-world devices.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
engine/variable.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Object representing a Scratch variable.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
extensions/scratch3_video_sensing/debug.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>debug.js</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
extensions/scratch3_video_sensing/library.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>library.js</p>
<p>Tony Hwang and John Maloney, January 2011
Michael &quot;Z&quot; Goddard, March 2018</p>
<p>Video motion sensing primitives.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
serialization/sb2_specmap.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>The specMap below handles a few pieces of &quot;translation&quot; work between
the SB2 JSON format and the data we need to run a project
in the Scratch 3.0 VM.
Notably:</p>
<ul>
<li>Map 2.0 and 1.4 opcodes (forward:) into 3.0-format (motion_movesteps).</li>
<li>Map ordered, unnamed args to unordered, named inputs and fields.
Keep this up-to-date as 3.0 blocks are renamed, changed, etc.
Originally this was generated largely by a hand-guided scripting process.
The relevant data lives here:
https://github.com/LLK/scratch-flash/blob/master/src/Specs.as
(for the old opcode and argument order).
and here:
https://github.com/LLK/scratch-blocks/tree/develop/blocks_vertical
(for the new opcodes and argument names).
and here:
https://github.com/LLK/scratch-blocks/blob/develop/tests/
(for the shadow blocks created for each block).
I started with the <code>commands</code> array in Specs.as, and discarded irrelevant
properties. By hand, I matched the opcode name to the 3.0 opcode.
Finally, I filled in the expected arguments as below.</li>
</ul></div>
</div>
</article>
</section>
<section>
<header>
<h2>
serialization/sb2.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Partial implementation of an SB2 JSON importer.
Parses provided JSON and then generates all needed
scratch-vm runtime structures.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
serialization/sb3.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>An SB3 serializer and deserializer. Parses provided
JSON and then generates all needed scratch-vm runtime structures.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
util/cast.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>Utilities for casting and comparing Scratch data-types.
Scratch behaves slightly differently from JavaScript in many respects,
and these differences should be encapsulated below.
For example, in Scratch, add(1, join(&quot;hello&quot;, world&quot;)) -&gt; 1.
This is because &quot;hello world&quot; is cast to 0.
In JavaScript, 1 + Number(&quot;hello&quot; + &quot;world&quot;) would give you NaN.
Use when coercing a value before computation.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
util/timer.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><h2>A utility for accurately measuring time.
To use:</h2>
<h2>var timer = new Timer();
timer.start();
... pass some time ...
var timeDifference = timer.timeElapsed();</h2>
<p>Or, you can use the <code>time</code> and <code>relativeTime</code>
to do some measurement yourself.</p></div>
</div>
</article>
</section>
<section>
<header>
<h2>
util/uid.js
</h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
<div class="description"><p>UID generator, from Blockly.</p></div>
</div>
</article>
</section>
</div>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>
<script>prettyPrint();</script>
<script src="scripts/polyfill.js"></script>
<script src="scripts/linenumber.js"></script>
</body>
</html>
Reference in New Issue Copy Permalink