How to Make a Scratch Modification

This article has links to websites or programs outside of Scratch and Wikipedia. Remember to stay safe while using the internet as we cannot guarantee the safety of other websites.

This article or section documents the current version of Scratch (version 3.0). For this article in Scratch 2.0, see How to Make a Scratch Modification (2.0). For this article in Scratch 1.4, see How to Make a Scratch Modification (1.4).

Scratch modifications or mods can add more features and blocks, customize the user interface (UI) or improve performance. They are made by modifying the Scratch source code, which is written in JavaScript.

Before You Begin

Requirements

Software

Before modding Scratch 3.0, you must have the following installed on your computer:

• Git: Git allows you to clone (download) the Scratch 3.0 source code and then, if you want, upload it to a repository that you can share with others.
• NodeJS: NodeJS is a tool for running JavaScript code in the command line, and includes a package manager, NPM.
• Code Editor (optional): Although a Scratch 3.0 mod could be made in a text editor like Notepad, it's easier with a code editor, such as Visual Studio Code.
• Windows Subsystem for Linux (optional): If using Windows, running the commands in a Linux environment will help prevent errors.

Knowledge

Before starting, you should have some knowledge of the following:

• JavaScript
• TypeScript
• NPM
• Git

To change the user interface, you also need to know the basics of:

• React (JavaScript library)
• HTML
• CSS

How Scratch 3.0 is organized

Main article: Scratch Source Code#Scratch 3.0

Scratch 3.0 is designed in a modular way. Every part is a different repository on GitHub.

As you add functionality to your mod, your mod's folder will contain a sub-folder for each component. For example, your mod may look like this:

scratch_mod
    scratch-editor
        ...
    scratch-blocks
        ...

Most mods will only require modifications to scratch-editor and scratch-blocks.

Getting Started

Create a new folder for your mod. Before making any changes, the source code for at least scratch-editor will need to be downloaded and its dependencies will need to be installed.

Adding a component to your mod

Open a terminal from your mod's folder, run the command

git clone https://github.com/scratchfoundation/scratch-*.git

replacing the asterisk with the component's name, for example, scratch-editor. When cloning scratch-editor, it is recommended to add

--depth=1

to the end of the cloning command since the Git history contains large files.

This will clone (download) the source code for the that component into into a new folder with the same name. The command will take some time to complete.

After the command completes, run

cd scratch-*

to switch to the component's folder and then

npm install

to install the dependencies.

Opening the editor

The development version of the Scratch 3.0 editor

Clone and install the dependencies for scratch-editor.

From the scratch-editor folder, run

npm run build
npm start

and open localhost:8601 in a browser. You should see your mod running! The editor will automatically reload whenever any changes are made to your mod if the terminal is left open.

Linking other components

To link other components to the editor, start by cloning and installing them, then run

npm link

from the component's folder and

npm link scratch-*

from the scratch-editor folder. This removes the editor's original dependency and replaces it with a reference to the new component's folder.

Adding or Changing a Block

Please expand this article or section. You can help by adding more information if you are an editor. More information might be found in a section of the talk page. (August 2022)

Before adding or changing any blocks, scratch-blocks will need to be linked to editor.

Changing a block in Scratch Blocks

To change or create a block, open scratch-blocks/src/blocks which contains a file for each block category. Each file contains the code defining each block in that category, for example, the move (10) steps block looks like this:

//motion.ts
Blockly.Blocks.motion_movesteps = {
  /**
   * Block to move steps.
   */
  init: function (this: Blockly.Block) {
    this.jsonInit({
      message0: Blockly.Msg.MOTION_MOVESTEPS,
      args0: [
        {
          type: 'input_value',
          name: 'STEPS',
        },
      ],
      extensions: ['colours_motion', 'shape_statement'],
    })
  },
}

To change a block's label, open scratch-blocks/msg/messages.js and find the block, for example, the move (10) steps block looks like this:

Blockly.Msg.MOTION_MOVESTEPS = 'move %1 steps'

Adding the block to the editor

To add a block to the editor or change its location or default values, open scratch-editor/packages/scratch-gui/src/lib/make-toolbox-xml.js and find the block, for example, the move (10) steps block:

<block type="motion_movesteps">
  <value name="STEPS">
    <shadow type="math_number">
      <field name="NUM">10</field>
    </shadow>
  </value>
</block>

Changing a block's behavior

To change a block's behavior or add a new one, find the block's category under scratch-editor/packages/scratch-vm/src/blocks, for example, scratch3_motion.js.

To change a block's behavior, find the function for the block you want to change. For example, the move (10) steps block looks like this:

moveSteps (args, util) {
  const steps = Cast.toNumber(args.STEPS);
  const radians = MathUtil.degToRad(90 - util.target.direction);
  const dx = steps * Math.cos(radians);
  const dy = steps * Math.sin(radians);
  util.target.setXY(util.target.x + dx, util.target.y + dy);
}

To add a new block, add an entry for it in the getPrimitives function, and map it to a new function.

class Scratch3MotionBlocks {
getPrimitives () {
    return {
        motion_movesteps: this.moveSteps,
        //Other blocks
    };
};

Building and Releasing

To build Scratch 3.0, in the scratch-editor folder, run

npm run build

Then, open scratch-editor/packages/scratch-gui/build/index.html in your browser. Your Scratch 3.0 mod should be running on its own without any localhost server running.

You can upload the contents of the build folder to whatever hosting service you want (GitHub Pages, Firebase Hosting, etc), or your own server, and share your mod on Scratch.

See Also

• Scratch Modification
• List of Scratch Modifications

External Links

• Guide to Modding Scratch 3.0 on the forums
• Scratch's GitHub organization
• The development branch of the Scratch 3.0 editor