Skip to main content

Setting Up

Create a folder for your mod​

The first step for creating a mod is creating a folder/directory to store it in. This tutorial uses the highly imaginative name of "Tutorial Mod", so I will use the folder name "TutorialMod".

The structure of this folder will end up looking like this at the end of this page:

TutorialMod/
    scratch-gui/
        package.json
        README.md
        ...
    scratch-vm/
        package.json
        README.md
        ...
    scratch-blocks/
        package.json
        README.md
        ...

Setting Up scratch-gui​

scratch-gui is the core of the Scratch editor, so it is where we will start.

Obtaining scratch-gui​

tip

Forking the Scratch repositories on GitHub and cloning your fork will allow you to more easily release your mod on GitHub later.

Optional Step: Fork the repository on GitHub and clone your fork instead.
Open a Command Prompt or Terminal and run this command:

git clone https://github.com/scratchfoundation/scratch-gui.git --depth=1
cd scratch-gui

This will create a folder called scratch-gui and download scratch-gui inside it. The --depth=1 option instructs Git to only download the latest version and not download the entire history of scratch-gui.

Installing the dependencies​

In the Command Prompt or Terminal (if you don't already have one open, open one), enter this command:

npm install
info

It may take a while to download all the dependencies.

info

You may see a lot of deprecation warnings and security vulnerability warnings, you can ignore these.

Making sure it works​

In the Command Prompt or Terminal, enter this command:

npm start

It may take a few seconds to become ready, but when you see this, it is ready:

i ｢wdm｣: Compiled successfully.

You should now be able to access the editor by visiting http://localhost:8601 in your web browser.

tip

You can press Ctrl+C to stop the editor server and return to the command line.

scratch-vm​

scratch-vm contains the code that actually runs the projects and all the code for the blocks and built in extensions.

Obtaining scratch-vm​

warning

Make sure you put scratch-vm in your TutorialMod (or whatever you called it) folder, not the scratch-gui folder.

Optional Step: Fork the repository on GitHub and clone your fork instead.

git clone https://github.com/scratchfoundation/scratch-vm.git --depth=1
cd scratch-vm

This will create a folder called scratch-vm and download scratch-vm inside it.

Installing the dependencies​

In the Command Prompt or Terminal, in the scratch-vm folder, enter this command:

npm install

scratch-blocks​

scratch-blocks is the block editing workspace, it also contains the definitions for what the blocks look like.

Obtaining scratch-blocks​

warning

Make sure you put scratch-blocks in your TutorialMod (or whatever you called it) folder, not the scratch-gui or scratch-vm folder.

Optional Step: Fork the repository on GitHub and clone your fork instead.

git clone https://github.com/scratchfoundation/scratch-blocks.git --depth=1
cd scratch-blocks

This will create a folder called scratch-blocks and download scratch-blocks inside it.

Installing the dependencies​

warning

scratch-blocks may have issues on Windows, I recommend running it on Windows Subsystem for Linux to ensure it works without any issues.

note

scratch-blocks now supports building with both Python 3 and Python 2. In case you are modding with an older version of scratch-blocks, the Python 2 specific information is still available below:

Python 2 Instructions

Older versions of scratch-blocks require Python 2 for its build script and it expects the Python 2 command to be python.

If your Python 2 command is python2, edit package.json to change python to python2.

scratch-blocks/package.json
{
    // ...
    "scripts" :{
        // ...
        "prepublish": "python2 build.py && webpack"
        // ...
    }
    // ...
}

In the Terminal, in the scratch-blocks folder, enter this command:

npm install

Linking scratch-gui to scratch-blocks and scratch-vm​

Currently, scratch-gui, scratch-vm and scratch-blocks are entirely separate, but we want to be able to modify scratch-vm and scratch-blocks, so we can add a block.

In your scratch-gui folder, run this command:

npm link ../scratch-blocks ../scratch-vm

This command will replace the copy of scratch-blocks and scratch-vm that your package manager automatically downloaded with a symbolic link to the one you can modify.

Scratch commit hashes at the time of this tutorial
scratch-gui:        db1933b2aea9f9dbe51e0ad2d750a2550179314a
scratch-vm:         d6420c4c9826d360adee118e0e9e255536be7f7c
scratch-blocks:     f116732bbbc6b1e0d95119c6ff8d4e23e27da8c0