(Redirected from Modding Tutorial)
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).
Although Scratch can seem complicated to some users, some Scratchers make Modifications, or Mods of the program to add more features or blocks, customize the User Interface (UI) or improve performance. Scratch 3.0 was developed 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.
- Python (optional): If your mod adds new blocks, you'll need Python.
- Java Compiler (optional): Scratch Blocks requires Java to build. Although there is an online compiler, it can cause problems.[1]
- Windows Subsystem for Linux (optional): If using Windows, running the commands in a Linux environment will help prevent errors.[2]
Knowledge
Additionally you should have some knowledge of the following:
- JavaScript
- React (JavaScript library)
- HTML
- CSS
- NPM
- Git
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-gui ... scratch-vm ... scratch-blocks ...
Most mods will only require modifications to Scratch GUI, Scratch Blocks, and Scratch VM.
Getting Started
Create a new folder for your mod. Before making any changes, the source code for at least Scratch GUI will need to be downloaded 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-gui
. When cloning scratch-gui, 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 GUI
Clone and install the dependencies for scratch-gui
.
From the Scratch GUI folder, run
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.
Setting up Scratch Blocks
Setting up Scratch Blocks is a little different from the other components since it requires Python, Java and Google's closure library to compile and must be re-compiled every time a change is made. After cloning it, run ln -s $(npm root)/google-closure-library ../closure-library
to download the closure library into a new sub-folder of the mod's main folder.
You can safely ignore most warnings, but if npm install
fails with an error, delete the closure-library folder's contents and extract the March 2019 release into it instead.
Run
npm run prepublish
when changes are made to Scratch Blocks to re-compile it so that they are reflected by the GUI.
Linking other components
To link other components, start by cloning and installing them, then run
npm link
from the component's folder and
npm link scratch-*
from the GUI folder. This removes the original dependency inside the GUI 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 and Scratch VM will need to be linked to the GUI.
Changing a block in Scratch Blocks
To change or create a block, open scratch-blocks/blocks_vertical
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.js
Blockly.Blocks['motion_movesteps'] = {
/**
* Block to move steps.
* @this Blockly.Block
*/
init: function() {
this.jsonInit({
"message0": Blockly.Msg.MOTION_MOVESTEPS,
"args0": [
{
"type": "input_value",
"name": "STEPS"
}
],
"category": Blockly.Categories.motion,
"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 GUI
To add a block to the GUI or change its location or default values, open 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-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 GUI folder, run
npm run build
Then, open scratch-gui/build/index.html
in your browser. 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
References
- ↑ kccuber. (11/2/2022). "Actually, the correct way is to install default-jre on WSL Ubuntu, which fixes this odd bug." post:6026696
- ↑ JGames101. (21/1/2018). "Run the command from a Bash Terminal, such as the one that comes with Git on Windows, or in a Windows Subsystem for Linux environment." topic:289503