Skip to content

README.md

Latest commit

History

History
171 lines (144 loc) · 7.44 KB

README.md

File metadata and controls

171 lines (144 loc) · 7.44 KB
Raw

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" }
]
}
]
}
}
FieldDescription
title(required) Project name displayed in the editor.
sb3URL to a .sb3 file to load into the VM.
ui.allowExtensionsShow or hide the extensions button.
toolbox.categoriesArray of enabled block categories (motion, looks, sound, events, control, sensing, operators, variables, myBlocks).
toolbox.blocksObject mapping category names to arrays of allowed block opcodes for fine-grained filtering.
stepsArray of tutorial steps, each with title, text, image, and/or video.
costumesCustom costumes. Can be a flat array of items (backward compatible) or an object with enabled, showBuiltin, tags, and library.
costumes.enabledShow or hide the Costumes/Backdrops tab (default: true).
costumes.showBuiltinShow or hide built-in costumes in the costume library (default: true).
costumes.tagsArray of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
costumes.libraryArray of costume items, each with name, url, optional centerX/centerY, and optional tags (array of tag keys).
soundsCustom sounds. Can be a flat array or an object with enabled, showBuiltin, tags, and library.
sounds.enabledShow or hide the Sounds tab (default: true).
sounds.showBuiltinShow or hide built-in sounds in the sound library (default: true).
sounds.tagsArray of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
sounds.libraryArray of sound items, each with name, url, and optional tags (array of tag keys).
backdropsCustom backdrops. Can be a flat array or an object with showBuiltin, tags, and library.
backdrops.showBuiltinShow or hide built-in backdrops in the backdrop library (default: true).
backdrops.tagsArray of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
backdrops.libraryArray of backdrop items, each with name, url, optional centerX/centerY, and optional tags (array of tag keys).
spritesCustom sprites. Can be a flat array or an object with showBuiltin, tags, and library.
sprites.showBuiltinShow or hide built-in sprites in the sprite library (default: true).
sprites.tagsArray of tag definitions ({key, label}) for filtering. Appended to built-in tags; shown alone when showBuiltin is false.
sprites.libraryArray 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.