Skip to main content

Scratch object API

The global Scratch object is how an extension talks to Bilup. It carries the registration function, the type constants, casting helpers, and (for unsandboxed extensions) direct access to the VM and permission APIs.

Sandboxed extensions get a limited Scratch; the VM, renderer, and block utility are unsandboxed only.

Registration and structure​

(function(Scratch) {
  'use strict';
  class MyExtension {
    getInfo() {
      return {
        id: 'myextension',
        name: 'My Extension',
        blocks: [
          {
            opcode: 'myBlock',
            blockType: Scratch.BlockType.REPORTER,
            text: 'convert [VALUE] to number',
            arguments: { VALUE: { type: Scratch.ArgumentType.STRING, defaultValue: '42' } }
          }
        ]
      };
    }
    myBlock(args) {
      return Scratch.Cast.toNumber(args.VALUE);
    }
  }
  Scratch.extensions.register(new MyExtension());
})(Scratch);
  • Scratch.extensions.register(instance): register your extension. Call it exactly once.
  • Scratch.extensions.unsandboxed: true when running unsandboxed. Check it before using any unsandboxed-only API.

Type constants​

Scratch.BlockType​

ConstantValueMeaning
COMMANDcommandStack block, no return value
REPORTERreporterRound block returning a string or number
BOOLEANBooleanHexagonal block returning true/false
HAThatConditionally starts a stack (see Events and hats)
EVENTeventStarts a stack on an event; has no function
CONDITIONALconditionalif/else style C block (see Custom C blocks)
LOOPlooprepeat/forever style C block
BUTTONbuttonA palette button, not a real block
LABELlabelA text label in the palette, not a real block
XMLxmlRaw Blockly XML

Scratch.ArgumentType​

STRING, NUMBER, BOOLEAN, COLOR, ANGLE, MATRIX, NOTE, COSTUME, SOUND, IMAGE. See Dealing with inputs for what each accepts.

Scratch.TargetType​

SPRITE ('sprite') and STAGE ('stage'), used with a block's filter.

Scratch.Cast​

Scratch-semantic conversions. Full detail on the Utility APIs page.

Scratch.Cast.toNumber('3.14');   // 3.14
Scratch.Cast.toString(42);       // '42'
Scratch.Cast.toBoolean('false'); // false
Scratch.Cast.compare('10', '9'); // > 0

Scratch.vm (unsandboxed only)​

The VM instance. See the VM API page for the full surface.

const vm = Scratch.vm;
const runtime = vm.runtime;

vm.greenFlag();
vm.stopAll();
vm.setTurboMode(true);

runtime.targets;               // all sprites and the stage
runtime.getTargetForStage();   // the stage
vm.editingTarget;              // sprite selected in the editor

runtime.on('PROJECT_RUN_START', () => { /* ... */ });

Scratch.renderer (unsandboxed only)​

The WebGL renderer. See the Renderer API page.

const renderer = Scratch.renderer;
renderer.draw();
const canvas = renderer.canvas;

The block utility (unsandboxed only)​

Unsandboxed block functions receive a second parameter, util, valid only while the block runs (see Unsandboxed extensions).

myBlock(args, util) {
  const target = util.target;   // the sprite running the block
  const runtime = util.runtime; // the runtime
  const thread = util.thread;   // the running thread
  const frame = util.stackFrame; // scratch space for this block invocation
}

Common uses:

// Target properties
util.target.x; util.target.y; util.target.direction; util.target.size;
util.target.setXY(100, 50);
util.target.setDirection(90);

// Variables and lists (type '' for a variable, 'list' for a list)
const v = util.target.lookupVariableByNameAndType('score', '');
if (v) v.value = 100;

// Start hat/event scripts (see the Events and hats page)
util.startHats('event_whenbroadcastreceived', { BROADCAST_OPTION: 'go' });

// C-block branches (see the Custom C blocks page)
util.startBranch(1, true);

Permission APIs (unsandboxed only)​

Unsandboxed extensions must ask before reaching the network or the outside world. See Unsandboxed extensions for why and how.

// Network
if (await Scratch.canFetch(url)) { /* WebSocket, Image, etc. */ }
const res = await Scratch.fetch(url);

// Windows / navigation
if (await Scratch.canOpenWindow(url)) { /* ... */ }
await Scratch.openWindow(url);
if (await Scratch.canRedirect(url)) { /* ... */ }
await Scratch.redirect(url);

// Devices
await Scratch.canRecordAudio();
await Scratch.canRecordVideo();
await Scratch.canReadClipboard();
await Scratch.canNotify();
await Scratch.canGeolocate();

Translation​

Scratch.translate marks strings for translation:

const message = Scratch.translate({
  id: 'myextension.hello',
  default: 'Hello {name}!',
  description: 'Greeting'
}, { name: args.NAME });

Editing Blockly directly​

For deep editor customization you can reach the global ScratchBlocks object. See the GUI API for details.

See also​