Getting Started

[Smokey needs Your help to keep this documentation up to date!]

The staging version of the Scratch GUI, a.k.a. the to-be-released Scratch 3.0 Editor, can be viewed at https://llk.github.io/scratch-gui/.

Scratch editor diagram

The Scratch editor is built up modularly from several repos. Each can stand alone, but for development purposes you may need to make dependent changes in multiple repos at once. This guide covers how to link repos.

Repos

You probably won't need all the repos. Clone the repo for the issue you are working on, and clone and link other repos as you need them.

The main ones are:

GUI - the React-based front end
VM - Manages state and does business logic. It sends the state to the GUI.
Scratch Blocks - branched from Blockly. This repo handles both the UI and logic for the portions of the editor that blocks appear in. Talks to the GUI, which often pipes things through to the VM.
Renderer - WebGL-based handler of what appears in the stage area. The GUI tells this what to do.

There are also others, like scratch-storage and scratch-audio.

Prereqs:

Node 8 (e.g. brew install node)
- If you have multiple versions of Node, you can switch between them using nvm on Mac or https://github.com/coreybutler/nvm-windows on windows
Git (e.g. brew install git)
GitHub account with SSH key set up

Getting the GUI

Make a fork of GUI
git clone your fork and cd into it
git remote add upstream https://github.com/LLK/scratch-gui.git
git config branch.develop.remote upstream (develop will be where you pull in changes from the official repo)
npm install - gets dependencies
npm start - starts local server which is hot reloaded
Open http://localhost:8601

Getting the VM

Make a fork of VM
git clone your fork and cd into it
git remote add upstream https://github.com/LLK/scratch-vm.git
git config branch.develop.remote upstream (develop will be where you pull in changes from the official repo)
npm install - gets dependencies
~~npm run watch - starts local server, and also will tell gui to reload if it changes~~
Playground which doesn't use GUI available at http://localhost:8073/playground/

Same process as VM for render, audio, etc.

Slightly different for scratch-blocks

Make a fork of Scratch blocks
git clone your fork and cd into it
git remote add upstream https://github.com/LLK/scratch-blocks.git
git config branch.develop.remote upstream (develop will be where you pull in changes from the official repo)
npm install - gets dependencies -- If you run into the error 'Closure not found', follow the instructions on the scratch-blocks wiki to install the closure library.
npm link
INSTEAD OF npm run watch, you need to run npm run prepublish each time you make a change to scratch blocks that should be reflected in the GUI, then hard refresh. (No hot reloading)
INSTEAD OF having to run a server for testing, simply open file:////tests/vertical_playground.html in a browser

Linking repos

cd the dependency repo and run npm link
cd the GUI and run npm link <dependency>

Example (Scratch GUI, VM and Blocks linked):

mkdir Scratch

cd Scratch

git clone https://github.com/llk/scratch-gui # if making changes fork the project and check out your copy

git clone https://github.com/llk/scratch-vm # if making changes fork the project and check out your copy

git clone https://github.com/llk/scratch-blocks # if making changes fork the project and check out your copy

cd scratch-vm

npm install

npm link

npm run watch

cd ../scratch-blocks

npm install

npm link

cd ../scratch-gui

npm install

npm link scratch-vm scratch-blocks

npm start

http://localhost:8601