Archive.png This article or section documents something not included in the current version of Scratch (3.0). It is only useful from a historical perspective.

This is a tutorial for modifying the JSON code of a Scratch 2.0 project.

Note Warning: Modifying the JSON code of a project could break it, so making a backup is recommended.
Note Caution: The hacked blocks in this article do not work with Scratch 3.0.
This has been discussed. We currently don't see a way for us to support all types of "hacked blocks" in Scratch 3.0. Some of the ways in which undocumented / unsupported behavior works in Scratch 2.0 may continue to work in Scratch 3.0 but we cannot guarantee anything. We will be putting checks in place to try to prevent hacked blocks from simply crashing the Scratch 3.0 editor however.

– February 27, 2018 thisandagain[1]

Before you Begin

Scratch 2.0 project files are saved with the .sb2 file extension. Ignoring this extension, the project file is a ZIP archive containing the project.json file and the sound and image resources. The project file can be treated like a ZIP archive to allow modification of project.json by simply changing the file extension. Therefore, Windows and Mac users must make the following changes to unhide file extensions:



This tutorial is intended to give first-timers a look into the potential usefulness of "hacked blocks" and to make them more comfortable with JSON modification. The goal is to recreate:

set [var v] to []


set [var v] to []::custom

Firstly, start out with a new project. Both the online and offline editors will suffice. To make JSON editing easier, we need to create some sort of structure that can be modified, rather than trying to write fresh JSON code by hand. Define a new custom block like so:

define set (string1) to (string2)
set [var v] to (string2)

The resulting block will look like this:

set [] to []::custom

Then, save the project to your computer as MyProject.


Opening JSON file in a text editor (Notepad++). The highlighted line corresponds with the aforementioned custom block.

Now we must change the file extension of our project. Rename MyProject.sb2 to You may get a warning regarding changing the file extension; ignore this. Extract the ZIP archive, then open project.json with a text editor. If you are using the offline editor on Windows then you may have to create a .zip file at first and then copy the MyProject.sb2 file to the .zip file. Then you will be able to safely rename MyProject.sb2 to

Look for the following segment of code:

["procDef", "set %s to %s", ["string1", "string2"], ["", ""], false]

It may look confusing, so let's break it down:

  • "procDef" - "proc" means "procedure" and "def" means "definition". It tells Scratch that this is the definition for a custom block. Don't edit this part.
  • "set %s to %s" - This is our custom block's signature. "%s" is a string input. Doesn't it look familiar?
  • ["string1", "string2"] - These are our block's parameters. Again, it should look familiar.
  • ["", ""] - These are the default values for our parameters. In this case, they are blank.
  • false - Boolean value for enabling "run without screen refresh"

Change the code to: ["procDef", "set %m.var to %s", ["var", "value"], ["var", ""], true]

Another change still has to be made. At this point, the project would look like this:

define set (var) to (value)
set [var v] to (string2::undefined)//"string2" doesn't exist anymore

In addition to fixing string2, there is another problem. What if we were to try the following?

set [differentVar v] to [something]::custom

No matter what variable we choose, we will always be altering var. Our script has to be changed to:

define set (var) to (value)
set (var) to (value)


["setVar:to:", "var", ["getParam", "string2", "r"]]


["setVar:to:", ["getParam", "var", "r"], ["getParam", "value", "r"]]

Finally, update the ZIP archive with the updated project.json file. You DO NOT need to change the file extension back to .sb2; Scratch 2.0 can still load this file. For the online editor, choose File » Upload from your computer, for the offline editor, choose File » Open. Now, test out your "hacked block," and if it works, congratulations!

Reference - Scratch 2.0 Input Specifiers


Name Description Visual
%b Boolean slot
example <>::#808080
%c Color slot
example [#0000C0]::#808080
%d.<menu> Numeric slot with menu
example (123 v)::#808080
%m.<menu> Read only slot with menu
example [menu v]::#808080
%n Numeric slot
example (123)::#808080
%s String slot
example [string]::#808080


Name Description
attribute List of object attribute names
backdrop List of backdrop names
booleanSensor List of Boolean sensor names
broadcast List of broadcast messages
broadcastInfoMenu List of broadcast messages and options for showing senders/receivers
colorPicker Color picker
costume List of costume names
direction List of sprite directions
drum List of drums
effect List of effect names
instrument List of instruments
key List of key names
list List of list names
listDeleteItem List of special deletion indices for lists
listItem List of special indices for lists
mathOp List of math operations
motorDirection List of motor directions
note List of note names
procMenu "edit" and block context menu items
rotationStyle List of rotation styles
scrollAlign Deprecated. "bottom-left", "bottom-right", "middle", "top-left", "top-right"
sensor List of numeric sensor names
sound List of sound names and "record..."
spriteOnly List of sprites and "myself"
spriteOrMouse List of sprites and "mouse-pointer"
spriteOrStage List of sprites and "Stage"
stop "all", "this script", and "other scripts in sprite"
timeAndDate List of time and date names
touching List of sprites, "mouse-pointer" and "edge"
triggerSensor List of sensor names which can trigger a hat block
var List of variable names
videoMotionType "motion" and "direction"
videoState "off", "on", and "on-flipped"


Cookies help us deliver our services. By using our services, you agree to our use of cookies.