Runtime

Runtime

Manages targets, scripts, and the sequencer.

Constructor

new Runtime()

Members

(static, constant) BLOCK_DRAG_END :string

Event name for block drag end.

Type:
  • string

(static, constant) BLOCK_DRAG_UPDATE :string

Event name for block drag update.

Type:
  • string

(static, constant) BLOCK_GLOW_OFF :string

Event name for unglowing a block.

Type:
  • string

(static, constant) BLOCK_GLOW_ON :string

Event name for glowing a block.

Type:
  • string

(static, constant) BLOCKS_NEED_UPDATE :string

Event name for reporting that a block was updated and needs to be rerendered.

Type:
  • string

(static, constant) BLOCKSINFO_UPDATE :string

Event name for reporting that blocksInfo was updated.

Type:
  • string

(static, constant) EXTENSION_ADDED :string

Event name for reporting that an extension was added.

Type:
  • string

(static, constant) EXTENSION_FIELD_ADDED :string

Event name for reporting that an extension as asked for a custom field to be added

Type:
  • string

(static, constant) HAS_CLOUD_DATA_UPDATE :string

Event name for a cloud data update to this project.

Type:
  • string

(static, constant) MAX_CLONES :number

How many clones can be created at a time.

Type:
  • number

(static, constant) MIC_LISTENING :string

Event name to indicate that the microphone is being used to stream audio.

Type:
  • string

(static, constant) MONITORS_UPDATE :string

Event name for monitors update.

Type:
  • string

(static, constant) PERIPHERAL_CONNECTED :string

Event name for reporting that a peripheral has connected. This causes the status button in the blocks menu to indicate 'connected'.

Type:
  • string

(static, constant) PERIPHERAL_CONNECTION_LOST_ERROR :string

Event name for reporting that a peripheral connection has been lost. This causes a 'peripheral connection lost' error alert to display.

Type:
  • string

(static, constant) PERIPHERAL_DISCONNECTED :string

Event name for reporting that a peripheral has been intentionally disconnected. This causes the status button in the blocks menu to indicate 'disconnected'.

Type:
  • string

(static, constant) PERIPHERAL_LIST_UPDATE :string

Event name for updating the available set of peripheral devices. This causes the peripheral connection modal to update a list of available peripherals.

Type:
  • string

(static, constant) PERIPHERAL_REQUEST_ERROR :string

Event name for reporting that a peripheral has encountered a request error. This causes the peripheral connection modal to switch to an error state.

Type:
  • string

(static, constant) PERIPHERAL_SCAN_TIMEOUT :string

Event name for reporting that a peripheral has not been discovered. This causes the peripheral connection modal to show a timeout state.

Type:
  • string

(static, constant) PROJECT_CHANGED :string

Event name for report that a change was made that can be saved

Type:
  • string

(static, constant) PROJECT_LOADED :string

Event name for project loaded report.

Type:
  • string

(static, constant) PROJECT_RUN_START :string

Event name when threads start running. Used by the UI to indicate running status.

Type:
  • string

(static, constant) PROJECT_RUN_STOP :string

Event name when threads stop running Used by the UI to indicate not-running status.

Type:
  • string

(static, constant) PROJECT_START :string

Event name when the project is started (threads may not necessarily be running).

Type:
  • string

(static, constant) PROJECT_STOP_ALL :string

Event name for project being stopped or restarted by the user. Used by blocks that need to reset state.

Type:
  • string

(static, constant) RUNTIME_DISPOSED :string

Event name when the runtime dispose has been called.

Type:
  • string

(static, constant) RUNTIME_STARTED :string

Event name when the runtime tick loop has been started.

Type:
  • string

(static, constant) SCRIPT_GLOW_OFF :string

Event name for unglowing a script.

Type:
  • string

(static, constant) SCRIPT_GLOW_ON :string

Event name for glowing a script.

Type:
  • string

(static, constant) STAGE_HEIGHT :number

Height of the stage, in pixels.

Type:
  • number

(static, constant) STAGE_WIDTH :number

Width of the stage, in pixels.

Type:
  • number

(static, constant) STOP_FOR_TARGET :string

Event name for target being stopped by a stop for target call. Used by blocks that need to stop individual targets.

Type:
  • string

(static, constant) TARGETS_UPDATE :string

Event name for targets update report.

Type:
  • string

(static) THREAD_STEP_INTERVAL

How rapidly we try to step threads by default, in ms.

(static) THREAD_STEP_INTERVAL_COMPATIBILITY

In compatibility mode, how rapidly we try to step threads, in ms.

(static, constant) TOOLBOX_EXTENSIONS_NEED_UPDATE :string

Event name for report that a change was made to an extension in the toolbox.

Type:
  • string

(static, constant) TURBO_MODE_OFF :string

Event name for turning off turbo mode.

Type:
  • string

(static, constant) TURBO_MODE_ON :string

Event name for turning on turbo mode.

Type:
  • string

(static, constant) VISUAL_REPORT :string

Event name for visual value report.

Type:
  • string

(private) _blockInfo :Array.<CategoryInfo>

Map to look up all block information by extended opcode.

Type:

_cloneCounter :number

Currently known number of clones, used to enforce clone limit.

Type:
  • number

(nullable) _editingTarget :Target

Currently known editing target for the VM.

Type:

_hats :Object.<string, Object>

Map to look up hat blocks' metadata. Keys are opcode for hat, values are metadata objects.

Type:
  • Object.<string, Object>

_lastStepDoneThreads :Array.<Thread>

All threads that finished running and were removed from this.threads by behaviour in Sequencer.stepThreads.

Type:

_monitorState

Ordered map of all monitors, which are MonitorReporter objects.

_nonMonitorThreadCount :number

Number of non-monitor threads running during the previous frame.

Type:
  • number

_prevMonitorState

Monitor state from last tick

_primitives :Object.<string, function()>

Map to look up a block primitive's implementation function by its opcode. This is a two-step lookup: package name first, then primitive name.

Type:
  • Object.<string, function()>

_refreshTargets :boolean

Flag to emit a targets update at the end of a step. When target data changes, this flag is set to true.

Type:
  • boolean

(non-null) _scriptGlowsPreviousFrame :Array.<!string>

A list of script block IDs that were glowing during the previous frame.

Type:
  • Array.<!string>

(non-null) _steppingInterval :number

A reference to the current runtime stepping interval, set by a setInterval.

Type:
  • number

addCloudVariable :function

A function that tracks a new cloud variable in the runtime, updating the cloud variable limit. Calling this function will emit a cloud data update event if this is the first cloud variable being added.

Type:
  • function

canAddCloudVariable :function

A function which checks whether a new cloud variable can be added to the runtime.

Type:
  • function

compatibilityMode :Boolean

Whether the project is in "compatibility mode" (30 TPS).

Type:
  • Boolean

(non-null) currentStepTime :number

Current length of a step. Changes as mode switches, and used by the sequencer to calculate WORK_TIME.

Type:
  • number

executableTargets :Array.<!Target>

Targets in reverse order of execution. Shares its order with drawables.

Type:

(non-null) flyoutBlocks :Blocks

Storage container for flyout blocks. These will execute on _editingTarget.

Type:

hasCloudData :function

Check wether the runtime has any cloud data.

Type:
  • function

ioDevices :Object.<string, Object>

Type:
  • Object.<string, Object>

(private) monitorBlockInfo :object

Map to look up all monitor block information by opcode.

Type:
  • object

(non-null) monitorBlocks :Blocks

Storage container for monitor blocks. These will execute on a target maybe

Type:

peripheralExtensions

A list of extensions, used to manage hardware connection.

profiler :Profiler

A runtime profiler that records timed events for later playback to diagnose Scratch performance.

Type:

redrawRequested :boolean

Whether any primitive has requested a redraw. Affects whether Sequencer.stepThreads will yield after stepping each thread. Reset on every frame.

Type:
  • boolean

removeCloudVariable :function

A function which updates the runtime's cloud variable limit when removing a cloud variable and emits a cloud update event if the last of the cloud variables is being removed.

Type:
  • function

(non-null) sequencer :Sequencer

Type:

targets :Array.<!Target>

Target management and storage.

Type:

threads :Array.<Thread>

A list of threads that are currently running in the VM. Threads are added when execution starts and pruned when execution ends.

Type:

turboMode :Boolean

Whether the project is in "turbo mode."

Type:
  • Boolean

Methods

_buildCustomFieldTypeForScratchBlocks(fieldName, output, outputShape, categoryInfo) → {object}

Build the scratch-blocks JSON needed for a fieldType. Custom field types need to be namespaced to the extension so that extensions can't interfere with each other

Parameters:
Name Type Description
fieldName string

The name of the field
output string

The output of the field
outputShape number

Shape of the field (from ScratchBlocksConstants)
categoryInfo object

The category the field belongs to (Used to set its colors)
Returns:
  • Object to be inserted into scratch-blocks
Type
object

(private) _buildMenuForScratchBlocks(menuName, menuInfo, categoryInfo) → {object}

Properties:
Name Type Attributes Description
items *

an array of menu items or a function to retrieve such an array
acceptReporters boolean <optional>

if true, allow dropping reporters onto this menu

Build the scratch-blocks JSON for a menu. Note that scratch-blocks treats menus as a special kind of block.

Parameters:
Name Type Description
menuName string

the name of the menu
menuInfo object

a description of this menu and its items
categoryInfo CategoryInfo

the category for this block
Returns:
  • a JSON-esque object ready for scratch-blocks' consumption
Type
object

(private) _constructInlineImageJson(argInfo) → {object}

Helper for _convertPlaceholdes which handles inline images which are a specialized case of block "arguments".

Parameters:
Name Type Description
argInfo object

Metadata about the inline image as specified by the extension
Returns:

JSON blob for a scratch-blocks image field.

Type
object

(private) _convertBlockForScratchBlocks(blockInfo, categoryInfo) → {ConvertedBlockInfo}

Convert ExtensionBlockMetadata into scratch-blocks JSON & XML, and generate a proxy function.

Parameters:
Name Type Description
blockInfo ExtensionBlockMetadata

the block to convert
categoryInfo CategoryInfo

the category for this block
Returns:
  • the converted & original block information
Type
ConvertedBlockInfo

(private) _convertButtonForScratchBlocks(buttonInfo, categoryInfo) → {ConvertedBlockInfo}

Properties:
Name Type Description
func string

the callback name

Convert a button for scratch-blocks. A button has no opcode but specifies a callback name in the func field.

Parameters:
Name Type Description
buttonInfo ExtensionBlockMetadata

the button to convert
categoryInfo CategoryInfo

the category for this button
Returns:
  • the converted & original button information
Type
ConvertedBlockInfo

(private) _convertForScratchBlocks(blockInfo, categoryInfo) → {ConvertedBlockInfo}

Convert ExtensionBlockMetadata into data ready for scratch-blocks.

Parameters:
Name Type Description
blockInfo ExtensionBlockMetadata

the block info to convert
categoryInfo CategoryInfo

the category for this block
Returns:
  • the converted & original block information
Type
ConvertedBlockInfo

(private) _convertMenuItems(menuItems) → {object}

Convert the given extension menu items into the scratch-blocks style of list of pairs. If the menu is dynamic (e.g. the passed in argument is a function), return the input unmodified.

Parameters:
Name Type Description
menuItems object

an array of menu items or a function to retrieve such an array
Returns:
  • an array of 2 element arrays or the original input function
Type
object

(private) _convertPlaceholders(context, match, placeholder) → {string}

Helper for _convertForScratchBlocks which handles linearization of argument placeholders. Called as a callback from string#replace. In addition to the return value the JSON and XML items in the context will be filled.

Parameters:
Name Type Description
context object

information shared with _convertForScratchBlocks about the block, etc.
match string

the overall string matched by the placeholder regex, including brackets: '[FOO]'.
placeholder string

the name of the placeholder being matched: 'FOO'.
Returns:

scratch-blocks placeholder for the argument: '%1'.

Type
string

(private) _convertSeparatorForScratchBlocks(blockInfo, categoryInfo) → {ConvertedBlockInfo}

Generate a separator between blocks categories or sub-categories.

Parameters:
Name Type Description
blockInfo ExtensionBlockMetadata

the block to convert
categoryInfo CategoryInfo

the category for this block
Returns:
  • the converted & original block information
Type
ConvertedBlockInfo

_defaultScratchLinkSocketFactory(type) → {ScratchLinkSocket}

The default scratch link socket creator, using websockets to the installed device manager.

Parameters:
Name Type Description
type string

Either BLE or BT
Returns:

The new scratch link socket (a WebSocket object)

Type
ScratchLinkSocket

_emitProjectRunStatus(nonMonitorThreadCount)

Emit run start/stop after each tick. Emits when this.threads.length goes between non-zero and zero

Parameters:
Name Type Description
nonMonitorThreadCount number

The new nonMonitorThreadCount

(private) _fillExtensionCategory(categoryInfo, extensionInfo)

Read extension information, convert menus, blocks and custom field types and store the results in the provided category object.

Parameters:
Name Type Description
categoryInfo CategoryInfo

the category to be filled
extensionInfo ExtensionMetadata

the extension metadata to read

_getMonitorThreadCount(threadsnon-null) → {number}

Get the number of threads in the given array that are monitor threads (threads that update monitor values, and don't count as running a script).

Parameters:
Name Type Description
threads Array.<Thread>

The set of threads to look through.
Returns:

The number of monitor threads in threads.

Type
number

(private) _makeExtensionMenuId(menuName, extensionId) → {string}

Generate an extension-specific menu ID.

Parameters:
Name Type Description
menuName string

the name of the menu.
extensionId string

the ID of the extension hosting the menu.
Returns:
  • the constructed ID.
Type
string

_pushMonitors()

Queue monitor blocks to sequencer to be run.

_pushThread(idnon-null, targetnon-null, optsnullable) → (non-null) {Thread}

Create a thread and push it to the list of threads.

Parameters:
Name Type Attributes Description
id string

ID of block that starts the stack.
target Target

Target to run thread on.
opts object <nullable>

optional arguments

Properties
Name Type Attributes Description
stackClick boolean <nullable>

true if the script was activated by clicking on the stack
updateMonitor boolean <nullable>

true if the script should update a monitor value
Returns:

The newly created thread.

Type
Thread

(private) _refreshExtensionPrimitives(extensionInfo)

Reregister the primitives for an extension

Parameters:
Name Type Description
extensionInfo ExtensionMetadata

new info (results of running getInfo) for an extension

(private) _registerBlockPackages()

To Do:
  • Prefix opcodes with package name.

Register default block packages with this runtime.

(private) _registerExtensionPrimitives(extensionInfo)

Register the primitives provided by an extension.

Parameters:
Name Type Description
extensionInfo ExtensionMetadata

information about the extension (id, blocks, etc.)

_restartThread(threadnon-null) → {Thread}

Restart a thread in place, maintaining its position in the list of threads. This is used by startHats to and is necessary to ensure 2.0-like execution order. Test project: https://scratch.mit.edu/projects/130183108/

Parameters:
Name Type Description
thread Thread

Thread object to restart.
Returns:

The restarted thread.

Type
Thread

_step()

Repeatedly run sequencer.stepThreads and filter out inactive threads after each iteration.

_stopThread(threadnon-null)

Stop a thread: stop running it immediately, and remove it from the thread list later.

Parameters:
Name Type Description
thread Thread

Thread object to remove from actives

_updateGlows(optExtraThreadsopt)

Emit glows/glow clears for scripts after a single tick. Looks at this.threads and notices which have turned on/off new glows.

Parameters:
Name Type Attributes Description
optExtraThreads Array.<Thread> <optional>

Optional list of inactive threads.

addMonitorScript(topBlockIdnon-null, optTargetnullable)

Enqueue a script that when finished will update the monitor for the block.

Parameters:
Name Type Attributes Description
topBlockId string

ID of block that starts the script.
optTarget Target <nullable>

target Target to run script on. If not supplied, uses editing target.

addTarget(target)

Add a target to the runtime. This tracks the sprite pane ordering of the target. The target still needs to be put into the correct execution order after calling this function.

Parameters:
Name Type Description
target Target

target to add

allScriptsDo(fnon-null, optTargetopt)

Run a function f for all scripts in a workspace. f will be called with two parameters:

  • the top block ID of the script.
  • the target that owns the script.
Parameters:
Name Type Attributes Description
f function

Function to call for each script.
optTarget Target <optional>

Optionally, a target to restrict to.

attachAudioEngine(audioEnginenon-null)

Attach the audio engine

Parameters:
Name Type Description
audioEngine AudioEngine

The audio engine to attach

attachRenderer(renderernon-null)

Attach the renderer

Parameters:
Name Type Description
renderer RenderWebGL

The renderer to attach

attachStorage(storagenon-null)

Attach the storage module

Parameters:
Name Type Description
storage ScratchStorage

The storage module to attach

attachV2BitmapAdapter(bitmapAdapternon-null)

Set the bitmap adapter for the VM/runtime, which converts scratch 2 bitmaps to scratch 3 bitmaps. (Scratch 3 bitmaps are all bitmap resolution 2)

Parameters:
Name Type Description
bitmapAdapter function

The adapter to attach

attachV2SVGAdapter(svgAdapternon-null)

Set the svg adapter, which converts scratch 2 svgs to scratch 3 svgs

Parameters:
Name Type Description
svgAdapter SvgRenderer

The adapter to attach

changeCloneCounter(changeAmount)

Update the clone counter to track how many clones are created.

Parameters:
Name Type Description
changeAmount number

How many clones have been created/destroyed.

clonesAvailable() → {boolean}

Return whether there are clones available.

Returns:

True until the number of clones hits Runtime.MAX_CLONES.

Type
boolean

configureScratchLinkSocketFactory(factory)

Configure how ScratchLink sockets are created. Factory must consume a "type" parameter either BT or BLE.

Parameters:
Name Type Description
factory function

The new factory for creating ScratchLink sockets.

connectPeripheral(extensionId, peripheralId)

Connect to the extension's specified peripheral.

Parameters:
Name Type Description
extensionId string

the id of the extension.
peripheralId number

the id of the peripheral.

createNewGlobalVariable(variableName, optVarId, optVarType) → {Variable}

Create a new global variable avoiding conflicts with other variable names.

Parameters:
Name Type Description
variableName string

The desired variable name for the new global variable. This can be turned into a fresh name as necessary.
optVarId string

An optional ID to use for the variable. A new one will be generated if a falsey value for this parameter is provided.
optVarType string

The type of the variable to create. Defaults to Variable.SCALAR_TYPE.
Returns:

The new variable that was created.

Type
Variable

disableProfiling()

Turn off profiling.

disconnectPeripheral(extensionId)

Disconnect from the extension's connected peripheral.

Parameters:
Name Type Description
extensionId string

the id of the extension.

dispose()

Dispose all targets. Return to clean state.

disposeTarget(disposingTargetnon-null)

Dispose of a target.

Parameters:
Name Type Description
disposingTarget Target

Target to dispose of.

emitBlockDragUpdate(areBlocksOverGui)

Emit whether blocks are being dragged over gui

Parameters:
Name Type Description
areBlocksOverGui boolean

True if blocks are dragged out of blocks workspace, false otherwise

emitBlockEndDrag(blocks, topBlockId)

Emit event to indicate that the block drag has ended with the blocks outside the blocks workspace

Parameters:
Name Type Description
blocks Array.<object>

The set of blocks dragged to the GUI
topBlockId string

The original id of the top block being dragged

emitMicListening(listening)

Emit an event to indicate that the microphone is being used to stream audio.

Parameters:
Name Type Description
listening boolean

true if the microphone is currently listening.

emitProjectChanged()

Report that the project has changed in a way that would affect serialization

emitProjectLoaded()

Report that the project has loaded in the Virtual Machine.

enableProfiling(onFrame)

Turn on profiling.

Parameters:
Name Type Description
onFrame Profiler/FrameCallback

A callback handle passed a profiling frame when the profiler reports its collected data.

fireTargetWasCreated(newTarget, sourceTargetopt)

Report that a new target has been created, possibly by cloning an existing target.

Parameters:
Name Type Attributes Description
newTarget Target

the newly created target.
sourceTarget Target <optional>

the target used as a source for the new clone, if any.
Fires:

fireTargetWasRemoved(target)

Report that a clone target is being removed.

Parameters:
Name Type Description
target Target

the target being removed
Fires:
  • Runtime#event:targetWasRemoved

getBlocksJSON() → {Array.<string>}

Returns:
  • an array containing the scratch-blocks JSON information for each dynamic block.
Type
Array.<string>

getBlocksXML() → {Array.<object>}

Properties:
Name Type Description
id string

the category / extension ID
xml string

the XML text for this category, starting with <category> and ending with </category>
Returns:

scratch-blocks XML for each category of extension blocks, in category order.

Type
Array.<object>

getEditingTarget() → (nullable) {Target}

Get the editing target.

Returns:

The editing target.

Type
Target

getIsEdgeActivatedHat(opcodenon-null) → {boolean}

Return whether an opcode represents an edge-activated hat block.

Parameters:
Name Type Description
opcode string

The opcode to look up.
Returns:

True if the op is known to be a edge-activated hat.

Type
boolean

getIsHat(opcodenon-null) → {boolean}

Return whether an opcode represents a hat block.

Parameters:
Name Type Description
opcode string

The opcode to look up.
Returns:

True if the op is known to be a hat.

Type
boolean

getLabelForOpcode(extendedOpcode) → {object}

Properties:
Name Type Attributes Description
category string

the category for this opcode
labelFn function <optional>

function to generate the label for this opcode
label string <optional>

the label for this opcode if labelFn is absent

Get the label or label function for an opcode

Parameters:
Name Type Description
extendedOpcode string

the opcode you want a label for
Returns:
  • object with label and category
Type
object

getOpcodeFunction(opcodenon-null) → {function}

Retrieve the function associated with the given opcode.

Parameters:
Name Type Description
opcode string

The opcode to look up.
Returns:

The function which implements the opcode.

Type
function

getPeripheralIsConnected(extensionId) → {boolean}

Returns whether the extension has a currently connected peripheral.

Parameters:
Name Type Description
extensionId string

the id of the extension.
Returns:
  • whether the extension has a connected peripheral.
Type
boolean

getScratchLinkSocket(type) → {ScratchLinkSocket}

Get a scratch link socket.

Parameters:
Name Type Description
type string

Either BLE or BT
Returns:

The scratch link socket.

Type
ScratchLinkSocket

getSpriteTargetByName(spriteName) → (nullable) {Target}

Get the first original (non-clone-block-created) sprite given a name.

Parameters:
Name Type Description
spriteName string

Name of sprite to look for.
Returns:

Target representing a sprite of the given name.

Type
Target

getTargetByDrawableId(drawableID) → (nullable) {Target}

Get a target by its drawable id.

Parameters:
Name Type Description
drawableID number

drawable id of target to find
Returns:

The target, if found

Type
Target

getTargetById(targetId) → (nullable) {Target}

Get a target by its id.

Parameters:
Name Type Description
targetId string

Id of target to find.
Returns:

The target, if found.

Type
Target

getTargetForStage() → (nullable) {Target}

Get a target representing the Scratch stage, if one exists.

Returns:

The target, if found.

Type
Target

glowBlock(blockIdnullable, isGlowing)

Emit feedback for block glowing (used in the sequencer).

Parameters:
Name Type Attributes Description
blockId string <nullable>

ID for the block to update glow
isGlowing boolean

True to turn on glow; false to turn off.

glowScript(topBlockIdnullable, isGlowing)

Emit feedback for script glowing.

Parameters:
Name Type Attributes Description
topBlockId string <nullable>

ID for the top block to update glow
isGlowing boolean

True to turn on glow; false to turn off.

greenFlag()

Start all threads that start with the green flag.

isActiveThread(threadnullable) → {boolean}

Return whether a thread is currently active/running.

Parameters:
Name Type Attributes Description
thread Thread <nullable>

Thread object to check.
Returns:

True if the thread is active/running.

Type
boolean

isWaitingThread(threadnullable) → {boolean}

Return whether a thread is waiting for more information or done.

Parameters:
Name Type Attributes Description
thread Thread <nullable>

Thread object to check.
Returns:

True if the thread is waiting

Type
boolean

makeMessageContextForTarget(targetopt)

Create a context ("args") object for use with formatMessage on messages which might be target-specific.

Parameters:
Name Type Attributes Description
target Target <optional>

the target to use as context. If a target is not provided, default to the current editing target or the stage.

moveExecutable(executableTarget, delta) → {number}

Move a target in the execution order by a relative amount.

A positve number will make the target execute earlier. A negative number will make the target execute later in the order.

Parameters:
Name Type Description
executableTarget Target

target to move
delta number

number of positions to move target by
Returns:

new position in execution order

Type
number

quietGlow(scriptBlockIdnon-null)

"Quiet" a script's glow: stop the VM from generating glow/unglow events about that script. Use when a script has just been deleted, but we may still be tracking glow data about it.

Parameters:
Name Type Description
scriptBlockId string

Id of top-level block in script to quiet.

registerPeripheralExtension(extensionId, extension)

Register an extension that communications with a hardware peripheral by id, to have access to it and its peripheral functions in the future.

Parameters:
Name Type Description
extensionId string

the id of the extension.
extension object

the extension to register.

removeExecutable(executableTarget)

Remove a target from the execution set.

Parameters:
Name Type Description
executableTarget Target

target to remove

requestAddMonitor(monitornon-null)

Add a monitor to the state. If the monitor already exists in the state, updates those properties that are defined in the given monitor record.

Parameters:
Name Type Description
monitor MonitorRecord

Monitor to add.

requestBlocksUpdate()

Emit an event that indicates that the blocks on the workspace need updating.

requestHideMonitor(monitorIdnon-null) → {boolean}

Hides a monitor and returns success/failure of action.

Parameters:
Name Type Description
monitorId string

ID of the monitor to hide.
Returns:

true if monitor exists and was updated, false otherwise

Type
boolean

requestRedraw()

Tell the runtime to request a redraw. Use after a clone/sprite has completed some visible operation on the stage.

requestRemoveMonitor(monitorIdnon-null)

Removes a monitor from the state. Does nothing if the monitor already does not exist in the state.

Parameters:
Name Type Description
monitorId string

ID of the monitor to remove.

requestRemoveMonitorByTargetId(targetIdnon-null)

Removes all monitors with the given target ID from the state. Does nothing if the monitor already does not exist in the state.

Parameters:
Name Type Description
targetId string

Remove all monitors with given target ID.

requestShowMonitor(monitorIdnon-null) → {boolean}

Shows a monitor and returns success/failure of action. not exist in the state.

Parameters:
Name Type Description
monitorId string

ID of the monitor to show.
Returns:

true if monitor exists and was updated, false otherwise

Type
boolean

requestTargetsUpdate(targetnon-null)

Emit a targets update at the end of the step if the provided target is the original sprite

Parameters:
Name Type Description
target Target

Target requesting the targets update

requestToolboxExtensionsUpdate()

Emit an event that indicates that the toolbox extension blocks need updating.

requestUpdateMonitor(monitornon-null) → {boolean}

Update a monitor in the state and report success/failure of update.

Parameters:
Name Type Description
monitor Map

Monitor values to update. Values on the monitor with overwrite values on the old monitor with the same ID. If a value isn't defined on the new monitor, the old monitor will keep its old value.
Returns:

true if monitor exists in the state and was updated, false if it did not exist.

Type
boolean

scanForPeripheral(extensionId)

Tell the specified extension to scan for a peripheral.

Parameters:
Name Type Description
extensionId string

the id of the extension.

setCompatibilityMode(compatibilityModeOn)

Set whether we are in 30 TPS compatibility mode.

Parameters:
Name Type Description
compatibilityModeOn boolean

True iff in compatibility mode.

setEditingTarget(editingTargetnon-null)

Set the current editing target known by the runtime.

Parameters:
Name Type Description
editingTarget Target

New editing target.

setExecutablePosition(executableTarget, newIndex) → {number}

Set a target to execute at a specific position in the execution order.

Infinity will set the target to execute first. 0 will set the target to execute last (before the stage).

Parameters:
Name Type Description
executableTarget Target

target to move
newIndex number

position in execution order to place the target
Returns:

new position in the execution order

Type
number

start()

Set up timers to repeatedly step in a browser.

startHats(requestedHatOpcodenon-null, optMatchFieldsopt, optTargetopt) → {Array.<Thread>}

Start all relevant hats.

Parameters:
Name Type Attributes Description
requestedHatOpcode string

Opcode of hats to start.
optMatchFields object <optional>

Optionally, fields to match on the hat.
optTarget Target <optional>

Optionally, a target to restrict to.
Returns:

List of threads started by this function.

Type
Array.<Thread>

stopAll()

Stop "everything."

stopForTarget(targetnon-null, optThreadExceptionopt)

Stop any threads acting on the target.

Parameters:
Name Type Attributes Description
target Target

Target to stop threads for.
optThreadException Thread <optional>

Optional thread to skip.

toggleScript(topBlockIdnon-null, optsnullable)

Toggle a script.

Parameters:
Name Type Attributes Description
topBlockId string

ID of block that starts the script.
opts object <nullable>

optional arguments to toggle script

Properties
Name Type Attributes Description
target string <nullable>

target ID for target to run script on. If not supplied, uses editing target.
stackClick boolean <nullable>

true if the user activated the stack by clicking, false if not. This determines whether we show a visual report when turning on the script.

updateCurrentMSecs()

Update a millisecond timestamp value that is saved on the Runtime. This value is helpful in certain instances for compatibility with Scratch 2, which sometimes uses a currentMSecs timestamp value in Interpreter.as

visualReport(blockId, value)

Emit value for reporter to show in the blocks.

Parameters:
Name Type Description
blockId string

ID for the block.
value string

Value to show associated with the block.

Events

targetWasCreated

Event fired after a new target has been created, possibly by cloning an existing target.

Parameters:
Name Type Attributes Description
newTarget Target

the newly created target.
sourceTarget Target <optional>

the target used as a source for the new clone, if any.
Listeners of This Event: