Blockflow

Blockflow is a fork of the Scratch editor by the Scratch Foundation. It extends Scratch with configurable project files that let you customize the editor UI, restrict available blocks, and embed step-by-step tutorials — all controlled via a single URL parameter.

This makes Blockflow well-suited for educational settings where you want to provide learners with a focused, guided Scratch experience.

Key Features

• Project Files — Define a JSON configuration that controls which blocks, tabs, and UI elements are available, and optionally loads an .sb3 project.
• Tutorials — Embed step-by-step instructions with text, images, and videos directly into the editor.
• Toolbox Filtering — Restrict the block palette to specific categories or individual blocks.
• Generator — A built-in visual tool (generator.html) for creating project file configurations without writing JSON by hand.
• Player Mode — A dedicated full-screen playback mode that hides the editor.

Project File

A project file is a JSON object that configures the Blockflow editor. It is passed via the ?project= URL parameter, which accepts:

• A base64-encoded JSON string
• A URL to a .json project file
• A URL to an .sb3 Scratch project

Structure

{
  "title": "My Project",
  "sb3": "https://example.com/project.sb3",
  "ui": {
    "allowExtensions": false
  },
  "toolbox": {
    "categories": ["motion", "looks", "events", "control"],
    "blocks": {
      "motion": ["motion_movesteps", "motion_turnright"]
    }
  },
  "steps": [
    {
      "title": "Step 1",
      "text": "Drag a move block into the workspace.",
      "video": "https://example.com/step1.mp4"
    },
    {
      "title": "Step 2",
      "text": "Drag a move another block into the workspace.",
      "image": "https://example.com/step2.png"
    }
  ],
  "costumes": {
    "enabled": false,
    "showBuiltin": false,
    "tags": [
      { "key": "animal", "label": "Animal" },
      { "key": "person", "label": "Person" }
    ],
    "library": [
      { "name": "Cat", "url": "https://example.com/cat.svg", "tags": ["animal"] },
      { "name": "Photo", "url": "https://example.com/photo.png", "centerX": 100, "centerY": 80, "tags": ["person"] }
    ]
  },
  "sounds": {
    "enabled": false,
    "showBuiltin": false,
    "tags": [
      { "key": "effect", "label": "Effect" }
    ],
    "library": [
      { "name": "Meow", "url": "https://example.com/meow.mp3", "tags": ["effect"] }
    ]
  },
  "backdrops": {
    "showBuiltin": false,
    "library": [
      { "name": "Beach", "url": "https://example.com/beach.png" }
    ]
  },
  "sprites": {
    "showBuiltin": false,
    "tags": [
      { "key": "animal", "label": "Animal" }
    ],
    "library": [
      {
        "name": "Dog",
        "tags": ["animal"],
        "costumes": [
          { "name": "dog-a", "url": "https://example.com/dog-a.svg" }
        ],
        "sounds": [
          { "name": "bark", "url": "https://example.com/bark.mp3" }
        ]
      }
    ]
  }
}

Field	Description
title	(required) Project name displayed in the editor.
sb3	URL to a .sb3 file to load into the VM.
ui.allowExtensions	Show or hide the extensions button.
toolbox.categories	Array of enabled block categories (motion, looks, sound, events, control, sensing, operators, variables, myBlocks).
toolbox.blocks	Object mapping category names to arrays of allowed block opcodes for fine-grained filtering.
steps	Array of tutorial steps, each with title, text, image, and/or video.
costumes	Custom costumes. Can be a flat array of items (backward compatible) or an object with enabled, showBuiltin, tags, and library.
costumes.enabled	Show or hide the Costumes/Backdrops tab (default: true).
costumes.showBuiltin	Show or hide built-in costumes in the costume library (default: true).
costumes.tags	Array of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
costumes.library	Array of costume items, each with name, url, optional centerX/centerY, and optional tags (array of tag keys).
sounds	Custom sounds. Can be a flat array or an object with enabled, showBuiltin, tags, and library.
sounds.enabled	Show or hide the Sounds tab (default: true).
sounds.showBuiltin	Show or hide built-in sounds in the sound library (default: true).
sounds.tags	Array of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
sounds.library	Array of sound items, each with name, url, and optional tags (array of tag keys).
backdrops	Custom backdrops. Can be a flat array or an object with showBuiltin, tags, and library.
backdrops.showBuiltin	Show or hide built-in backdrops in the backdrop library (default: true).
backdrops.tags	Array of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
backdrops.library	Array of backdrop items, each with name, url, optional centerX/centerY, and optional tags (array of tag keys).
sprites	Custom sprites. Can be a flat array or an object with showBuiltin, tags, and library.
sprites.showBuiltin	Show or hide built-in sprites in the sprite library (default: true).
sprites.tags	Array of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
sprites.library	Array of sprite items, each with name, costumes, sounds, and optional tags (array of tag keys).

Relative URLs in sb3, image, video, and asset url fields are resolved relative to the project file URL.

Generator

The Generator (generator.html) is a visual tool for creating project file configurations. It provides:

• Form fields for general settings (title, sb3 URL, UI toggles)
• A toolbox editor to toggle categories and pick individual blocks
• A tutorial step manager to add, remove, and edit steps
• Export as downloadable .json, copyable URL (base64-encoded), or raw JSON

Packages

The packages directory contains:

• scratch-gui — Editor UI, menus, and the glue that brings the other modules together. Includes the project file system, generator, and player mode.
• scratch-vm — Virtual machine that runs Scratch projects.
• scratch-render — Renders backdrops, sprites, and clones on the stage.
• scratch-svg-renderer — Processes SVG images for use in Scratch projects.
• task-herder — Async task queue with token-bucket rate limiting and concurrency control.

Getting Started

npm install
npm run build

To start the development server:

cd packages/scratch-gui
npm start

Then open http://localhost:8601 in your browser.

License

This project is licensed under AGPL-3.0-only, the same license as the upstream Scratch editor.

Acknowledgments

Blockflow is built on the incredible work of the Scratch Foundation and the global community of Scratch contributors. Thank you for making Scratch open source.

If you'd like to support the original Scratch project, please consider making a donation to the Scratch Foundation.