In other languages

Help the wiki!

The Scratch Wiki is made by and for Scratchers. Do you want to contribute?

Learn more about joining as an editor!

See discussions in the Community Portal

JSON Tutorial

This is a tutorial for modifying the Scratch JSON code.

Warning Warning: Only change code if you consider yourself advanced with computers. You may permanently damage or break your project if you modify it incorrectly and do not know how to revert your code. A backup is recommended!

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. Our goal will be 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.

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"
  • This page was last modified on 17 June 2017, at 01:00.