TurboWarp/scratch-vm

Modified Scratch VM with a JIT compiler and more features.

The public API of TurboWarp/scratch-vm should be compatible with LLK/scratch-vm. See "Public API" section below for more information.

Setup

See https://github.com/TurboWarp/scratch-gui/wiki/Getting-Started to setup the complete TurboWarp environment.

If you just want to play with the VM then it's the same process as upstream scratch-vm.

Extension authors

If you only use the standard reporter, boolean, and command block types, everything should just work without any changes.

Compiler Overview

For a high-level overview of how the compiler works, see https://docs.turbowarp.org/how

For more technical information, read the code in src/compiler.

Public API

This section has not been updated in a while and is probably out of date.

Any public-facing API in LLK/scratch-vm should work just fine in TurboWarp/scratch-vm. Anything that doesn't is a bug. TurboWarp adds some new methods to the public API.

Runtime.setFramerate / VirtualMachine.setFramerate

setCompatibilityMode is deprecated (but still works) in favor of a generic setFramerate method.

runtime.setFramerate(60);

There is an event for framerate changes on Runtime and VirtualMachine: FRAMERATE_CHANGED (emitted with new framerate as only argument)

Runtime.setInterpolation / VirtualMachine.setInterpolation

Toggles frame interpolation, an experimental feature that tries to make project motion smoother without changing the script tick rate.

There is an event for changes on Runtime and VirtualMachine: INTERPOLATION_CHANGED

Runtime.setCompilerOptions / VirtualMachine.setCompilerOptions

This lets you change the behavior of the compiler. This method takes an object with the following arguments:

• enabled (boolean; default true) - controls whether the JIT compiler is enabled
• warpTimer (boolean; default false) - controls whether to use a warp timer to limit how long warp scripts can run. Can have significant performance impact

runtime.setCompilerOptions({
  enabled: true,
  warpTimer: true
});
// Partial updates are also supported -- this will only change `enabled` and not any other properties
runtime.setCompilerOptions({ enabled: false });

There is an event for compiler option changes on Runtime and VirtualMachine: COMPILER_OPTIONS_CHANGED (called with current options)

Runtime.setRuntimeOptions / VirtualMachine.setRuntimeOptions

Similar to setCompilerOption. This lets you control some behavior of the runtime.

• maxClones (number; default 300) - controls the clone limit; Infinity to disable
• miscLimits (boolean; default true) - controls various limits such as pitch, pan, etc.
• fencing (number; default true) - controls whether sprite fencing should be enabled

There is an event for runtime option changes on Runtime and VirtualMachine: RUNTIME_OPTIONS_CHANGED (called with current options)

Runtime.stop / VirtualMachine.stop

Stops the tick loop. This does not touch the active thread list. Anything currently active will be resumed when start is called again.

There is an event for stop on Runtime and VirtualMachine: RUNTIME_STOPPED (similar to RUNTIME_STARTED)

Runtime.stageWidth / Runtime.stageHeight

These control the width and height of the stage. Set them to values other than 480 and 360 respectively to get custom stage sizes. Keep in mind that you need to manually resize the renderer as well.

COMPILE_ERROR event

A COMPILE_ERROR is fired on Runtime and VirtualMachine when a script couldn't be compiled.

License

TurboWarp's modifications to Scratch are licensed under the GNU Lesser General Public License version 3. See COPYING and COPYING.LESSER for more information.

The following is the original license for scratch-gui, which we are required to retain. This is NOT the license of this project.

Copyright (c) 2016, Massachusetts Institute of Technology
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.