Events

VirtualMachine extends Node's EventEmitter. The editor and player listen to these events to keep the UI in sync, and you can too:

vm.on('PROJECT_CHANGED', () => {
    console.log('the project was edited');
});

The VM re-emits most of the runtime's events under the same name, so you usually listen on vm. A few things fire only on vm.runtime; those are noted below. This list is drawn from scratch-vm/src/virtual-machine.js and scratch-vm/src/engine/runtime.js.

Playback and running

Event	Fires when
`PROJECT_START`	The green flag is pressed.
`PROJECT_RUN_START`	Threads begin running this frame (was idle, now active).
`PROJECT_RUN_STOP`	All threads have stopped (was active, now idle).
`PROJECT_CHANGED`	The project was edited in a way that affects serialization.
`PROJECT_LOADED`	A project finished loading. Fires on `vm.runtime`.
`TURBO_MODE_ON` / `TURBO_MODE_OFF`	Turbo mode was toggled.
`RUNTIME_STARTED` / `RUNTIME_STOPPED`	The runtime's step loop started or stopped.

Loading progress

Event	Payload
`LOAD_PROGRESS`	`{stage, loaded, total}` where `stage` is one of `unzipping`, `parsing`, `checking`, `building`, `installing`.
`ASSET_PROGRESS`	`(finished, total)` as project assets download.

Targets, blocks, and the workspace

Event	Payload
`targetsUpdate`	`{targetList, editingTarget}`. The list of targets changed or the selection changed.
`workspaceUpdate`	The editing target's blocks, for rebuilding the block workspace.
`MONITORS_UPDATE`	The current monitor (stage watcher) state.
`BLOCK_DRAG_UPDATE` / `BLOCK_DRAG_END`	A block is being dragged over the GUI / a drag finished.
`VISUAL_REPORT`	A value to show as a bubble next to a clicked reporter.
`SCRIPT_GLOW_ON` / `SCRIPT_GLOW_OFF`	A script started or stopped glowing.
`BLOCK_GLOW_ON` / `BLOCK_GLOW_OFF`	A single block started or stopped glowing.
`PROJECT_STOP_ALL`, `STOP_FOR_TARGET`	The stop button was hit / one target was stopped. Fire on `vm.runtime`.

Extensions

Event	Fires when
`EXTENSION_ADDED`	An extension's block category was registered. Payload is the category info.
`EXTENSION_REMOVED`	An extension was removed.
`EXTENSIONS_REORDERED`	Extension order changed.
`EXTENSION_FIELD_ADDED`	An extension registered a custom field type.
`BLOCKSINFO_UPDATE`	An extension's blocks were refreshed (for example after a locale change).
`PERIPHERAL_LIST_UPDATE`, `USER_PICKED_PERIPHERAL`, `PERIPHERAL_CONNECTED`, `PERIPHERAL_DISCONNECTED`, `PERIPHERAL_REQUEST_ERROR`, `PERIPHERAL_CONNECTION_LOST_ERROR`, `PERIPHERAL_SCAN_TIMEOUT`	Peripheral scanning and connection lifecycle.

Settings that changed

These fire after the matching setter runs, so the UI can update:

Event	Payload
`RUNTIME_OPTIONS_CHANGED`	The current runtime options.
`COMPILER_OPTIONS_CHANGED`	The current compiler options.
`FRAMERATE_CHANGED`	The new frame rate.
`INTERPOLATION_CHANGED`	Whether interpolation is on.
`STAGE_SIZE_CHANGED`	`(width, height)`.
`COMPILE_ERROR`	`(target, error)` when a script fails to compile.
`HAS_CLOUD_DATA_UPDATE`	Whether the project uses cloud variables.
`MIC_LISTENING`	Whether the microphone is active.
`LOCALE_CHANGED`	The new locale, after `setLocale`.

Blocks that ask the host something

Some blocks need the host UI to respond. These fire on vm.runtime:

SAY: a sprite says or thinks something (say/think blocks).
QUESTION: an ask and wait block is waiting for input. The host collects an answer and emits an ANSWER event on the runtime to unblock the script.

Playback and running​

Loading progress​

Targets, blocks, and the workspace​

Extensions​

Settings that changed​

Blocks that ask the host something​

See also​