Scratch File Format

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 Scratch File Format (2.0). For this article in Scratch 1.4, see Scratch File Format (1.4).

The Scratch 3.0 file format is the format used to store exported Scratch 3.0 projects and sprites. These are ZIP archives which contain information encoded in a text-based format called JSON and project media in separate files. Projects have the extension .sb3, and sprites .sprite3. The MIME type of .sb3 files is application/x.scratch.sb3.

Project Files

An .sb3 file is a ZIP archive containing one JSON file, project.json, representing the project. (On most operating systems, one can extract an .sb3 file by first renaming it so that it ends with .zip (settings of the file manager might need to be changed to show file extensions), or one can use a program such as 7-Zip.) Backdrops, costumes, and sounds are stored as individual files with names beginning with their MD5 checksums followed by a file extension.

Sprite Files

.sprite3 files are the same as project files except that the JSON file is named sprite.json and it represents the sprite as a target.

Format

Projects

Projects have the following properties:

targets

An array of targets, in the same order as in the Scratch User Interface.

monitors

An array of monitors, in their layer order.

extensions

An array of the identifiers of the extensions used. The following values are possible:

• pen (Pen Extension)
• wedo2 (LEGO Education WeDo 2.0 Extension)
• music (Music Extension)
• microbit (micro:bit Extension)
• text2speech (Text to Speech Extension)
• translate (Translate Extension)
• videoSensing (Video Sensing Extension)
• ev3 (LEGO MINDSTORMS EV3 Extension)
• makeymakey (Makey Makey Extension)
• boost (LEGO BOOST Extension)
• gdxfor (Go Direct Force & Acceleration Extension)

meta

Metadata about the project's author and the Scratch version used.

Targets

A target is the stage or a sprite. Targets have the following properties:

isStage

True if this is the stage and false otherwise. Defaults to false.

name

The name of the sprite. Always "Stage" for the stage. If not provided, the target will not be loaded.

variables

An object associating IDs with arrays representing variables. The first element of the array is the variable name, the second is the value and the third is `true` if the variable is a cloud variable, or otherwise not present.

lists

An object associating IDs with arrays representing lists. The first element of the array is the list name and the second is the list as an array.

broadcasts

An object associating IDs with broadcast names. Normally only present in the stage.

blocks

An object associating IDs with blocks.

comments

An object associating IDs with comments.

currentCostume

The costume number.

costumes

An array of costumes.

sounds

An array of sounds.

layerOrder

The layer number.

volume

The volume

Stage

The stage has the following properties as well as those of all targets.

tempo

The tempo in BPM.

videoState

Possible values are "on", "off" and "on-flipped". Determines if video is visible on the stage and if it is flipped. Has no effect if the project does not use an extension with video input.

videoTransparency

The video transparency. Defaults to 50. Has no effect if videoState is "off" or if the project does not use an extension with video input.

textToSpeechLanguage

The language of the Text to Speech extension. Defaults to the editor language.

Sprites

Sprites have the following properties as well as those of all targets:

visible

True if the sprite is visible and false otherwise. Defaults to true.

x

The x-coordinate. Defaults to 0.

y

The y-coordinate. Defaults to 0.

size

The sprite's size as a percentage. Defaults to 100.

direction

The sprite's direction in degrees clockwise from up. Defaults to 90.

draggable

True if the sprite is draggable and false otherwise. Defaults to false.

rotationStyle

The Rotation Style. Possible values are "all around", "left-right", or "don't rotate".

Blocks

Fields are text boxes, drop-down menus, etc. These are used directly in blocks where there is an input into which one cannot drop a reporter. However, more often than not, one should be able to do this; in this case no field exists directly in the block, but an input does, and that input may have a shadow block in it.

A shadow block is a reporter in an input for which one can enter or pick a value, and which cannnot be dragged around but can be replaced by a normal reporter. Scratch internally considers these to be blocks although they are not usually thought of as such. (These notions come from Blockly, which Scratch Blocks is based on.)

Most blocks are represented by objects with the following properties:

opcode

A string naming the block. A list of block opcodes can be found here.

next

The ID of the following block or null.

parent

If the block is a stack block and is preceded, this is the ID of the preceding block. If the block is the first stack block in a C mouth, this is the ID of the C block. If the block is an input to another block, this is the ID of that other block. Otherwise it is null.

inputs

An object associating names with arrays representing inputs into which other blocks may be dropped, including C mouths. The first element of each array is 1 if the input is a shadow, 2 if there is no shadow, and 3 if there is a shadow but it is obscured by the input. The second is either the ID of the input or an array representing it as described in the table below. If there is an obscured shadow, the third element is its ID or an array representing it.

fields

An object associating names with arrays representing fields. The first element of each array is the field's value. For certain fields, such as variable and broadcast dropdown menus, there is also a second element, which is the ID of the field's value.

shadow

True if this is a shadow block and false otherwise.

topLevel

False if the block has a parent and true otherwise.

A top-level block object also has the x- and y-coordinates of the block in the code area as x and y. A block with a comment attached has a comment property whose value is the comment's ID. A block with a mutation also has a mutation property whose value is an object representing the mutation.

A few blocks are instead represented by arrays whose first element is a number representing the block applied.

Block	1st element	2nd element	3rd element	4th element	5th element
Number	4	the value
Positive number	5
Positive integer	6
Integer	7
Angle	8
Color	9	"#" followed by a hexadecimal numeral representing the color
String	10	the value
Broadcast	11	the name	the ID
(Variable)	12			the x-coordinate, if it is top-level	the y-coordinate, if it is top-level
(List:: list)	13

Mutations

Mutations are present on blocks where the opcode property is equal to "procedures_call" (i.e. custom block:: custom), "procedures_prototype" (i.e. the inner part of define custom block) or "control_stop". Mutations have the following properties:

tagName

Always equal to "mutation".

children

Seems to always be an empty array.

"procedures_prototype" and "procedures_call" mutations have the following additional properties:

proccode

The name of the custom block, including inputs: %s for string/number inputs and %b for boolean inputs.

argumentids

An array of the ids of the arguments; these can also be found in the input property of the main block.

warp

Whether to run the block without screen refresh or not.

"procedures_prototype" mutations also have the following additional properties:

argumentnames

An array of the names of the arguments. This is only present when the block has an opcode of procedures_prototype.

argumentdefaults

An array of the defaults of the arguments; for string/number arguments, this is an empty string, and for boolean arguments it is false. This is only present when the block has an opcode of procedures_prototype.

"control_stop" mutations have the following additional property:

hasnext

Whether the block has a block following it or not (false for stop all and stop all in sprite, true for stop other scripts in sprite)

Comments

Comments have the following properties:

blockId

The ID of the block the comment is attached to.

x

The x-coordinate of the comment in the code area.

y

The y-coordinate.

width

The width.

height

The height.

minimized

True if the comment is collapsed and false otherwise.

text

The text.

Assets

An asset is a costume or sound. (Backdrops are considered costumes.) They have the following properties:

assetId

The MD5 hash of the asset file.

name

The name.

md5ext

The name of the asset file.

dataFormat

The name of the format of the asset file.

Costumes

Costumes have the following properties as well as those of all assets:

bitmapResolution

The reciprocal of a costume scaling factor for bitmap costumes. This may be absent. In Scratch 3.0, all bitmap costumes are double-resolution.

rotationCenterX

The x-coordinate of the rotation center.

rotationCenterY

The y-coordinate of the rotation center.

Sounds

Sounds have the following properties as well as those of all assets:

rate

The sampling rate of the sound in Hertz.

sampleCount.

The number of samples.

These additional properties are ignored and overwritten when sounds are loaded, so may be omitted entirely.

Monitors

Monitors have the following properties:

id

The ID.

mode

The name of the monitor's mode: "default", "large", "slider", or "list".

opcode

The opcode of the block the monitor belongs to.

params

An object associating names of inputs of the block the monitor belongs to with their values.

spriteName

The name of the target the monitor belongs to, if any.

value

The value appearing on the monitor.

width

The width.

height

The height.

x

The x-coordinate.

y

The y-coordinate.

visible

True if the monitor is visible and false otherwise.

Monitors that do not belong to lists also have these properties:

sliderMin

The minimum value of the monitor's slider.

sliderMax

The maximum value of the monitor's slider.

isDiscrete

True if the monitor's slider allows only integer values and false otherwise.

Metadata

The meta property of project JSON files has the following properties:

semver

Always 3.0.0.

vm

The version of the Scratch VM that the project was created with.

agent

The user agent of the last person to edit the project.

See Also

• Exporting and Importing