Scratch File Format (2.0) - Scratch Wiki (original) (raw)

	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.

The Scratch 2.0 file format is the file format used to store exported Scratch 2.0 projects. Unlike Scratch 1.4 files, Scratch 2.0 files are ZIP archives containing project information encoded in a text-based format called JSON and project media in separate files. Projects conventionally have the extension .sb2,[1] and sprites the extension .sprite2.

Because JSON is a text-based format and many libraries exist for reading and writing JSON files, it is much easier for advanced users to make programs that read and write Scratch files than it was in Scratch 1.4. Users can also easily make modifications to a project by hand in a text editor to achieve things that cannot be done in Scratch itself; e.g., they can make custom blocks with color inputs or place reporters in inputs where they cannot normally be dropped.

JSON

Main article: JSON

JSON, short for JavaScript Object Notation, is the data format used by Scratch 2.0 to store the information and scripts in a project. An object associates names with values; these are written with the syntax {"name": value, …}. An array is a sequence of values; these are written with the syntax [value, …]. Values can be other objects; arrays; numbers; strings, which are written between quotation marks, e.g., "Arkansas"; Booleans, true or false; or null, a special value which is used to represent nothing.

Project Files

An .sb2 file is a ZIP archive containing one JSON file, project.json, which represents the stage. (On most operating systems, one can extract an .sb2 file by first renaming it so that it ends with ".zip", or one can use a program such as 7-Zip.) Sprites are considered children of the stage. Pen trails, backdrops, costumes, and sounds are stored as individual files with names beginning with a numeral followed by an extension: pen trails, backdrops, and costumes are numbered consecutively beginning with 0 and are stored as PNG and SVG files; sounds are numbered consecutively and are stored as WAVE files.

Sprite Files

.Sprite2 files are the same except the JSON file is named "sprite.json" and it represents the sprite.

Following are descriptions of the types of objects in project.json and sprite.json.

Stage Objects

A Stage object is the root object of project.json. It contains the following properties:

objName

The name of the stage. This is usually "Stage" but depends on the language chosen.

variables

The project's global variables, as an array of Variable objects.

lists

The project's global lists, as an array of List objects.

scripts

The stage's scripts, as an array of script tuples.

scriptComments

The stage's comments, as an array of comment tuples.

sounds

The stage's sounds, as an array of Sound objects.

costumes

The stage's backdrops, as an array of Costume objects.

currentCostumeIndex

The backdrop number of the stage.

penLayerID

The number of the image file in the project ZIP archive containing the pen trails on the stage when the project was saved.

Note:	This is -1 if project.json was downloaded from Scratch's servers.

penLayerMD5

The MD5 hash of the pen trails image file followed by its file extension.

tempoBPM

The tempo when the project was saved.

videoAlpha

The video transparency when the project was saved.

children

The sprites and stage monitors in the project, as an array of Sprite, StageMonitor, and List objects. Objects which appear later in the array are on top of those which appear earlier.

info

Extra information about the user and the project, as an Info object.

Sprite Objects

A Sprite object stores information about a sprite. It contains the following properties:

objName

The name of the sprite.

variables

The sprite's variables, as an array of Variable objects.

lists

The sprite's lists, as an array of List objects.

scripts

The sprite's scripts, as an array of script tuples.

scriptComments

The sprite's comments, as an array of comment tuples.

sounds

The sprite's sounds, as an array of Sound objects.

costumes

The sprite's costumes, as an array of Costume objects.

currentCostumeIndex

The costume number of the sprite.

scratchX

The _x_-coordinate of the sprite, relative to the center of the stage.

scratchY

The _y_-coordinate of the sprite, relative to the center of the stage.

scale

The size of the sprite as a number, where 1 = 100%.

direction

The direction of the sprite as a number in degrees measured clockwise from 0 = upward.

rotationStyle

The rotation style of the sprite as a string; either "normal", "leftRight", or "none"

isDraggable

true if the sprite is draggable; false otherwise.

indexInLibrary

A number indicating the ordering of the sprite in the sprite list.

visible

true if the sprite was shown when the project was saved; false if it was hidden.

spriteInfo

Extra information about the sprite. Currently, this is always an empty object.

StageMonitor Objects

A StageMonitor object stores information about a stage monitor not belonging to a list. It contains the following properties:

target

The name of the stage or sprite to which the stage monitor refers.

Note that the name of the stage matches the objName property of the Stage object, which can vary according to the project's language.

cmd

The selector of the block the monitor belongs to. Valid values are:

cmd	Description	param
"answer"	The answer.	null
"backgroundIndex"	The backdrop number of the stage.	null
"costumeIndex"	The costume number of the stage monitor's target.	null
"getVar:"	A variable monitor.	The variable name.
"heading"	The direction of the stage monitor's target.	null
"scale"	The size of the stage monitor's target.	null
"sceneName"	The backdrop name of the stage.	null
"senseVideoMotion"	The video motion on the stage monitor's target.	"type,thing" where type is motion or direction and thing is Stage or this sprite
"soundLevel"	The loudness.	null
"tempo"	The tempo.	null
"timeAndDate"	A value of the Current () block.	"year", "month", "date", "day of week", "hour", "minute", or "second", depending on which one the monitor is showing
"timer"	The timer.	null
"volume"	The volume of the stage monitor's target.	null
"xpos"	The _x_-coordinate of the stage monitor's target.	null
"ypos"	The _y_-coordinate of the stage monitor's target.	null

param

A parameter to the stage monitor command. See the table above.

color

The color of the stage monitor as a 24-bit RGB value.

label

The label text for the stage monitor.

mode

The stage monitor mode, either 1, 2, or 3.

mode	Meaning
1	Normal readout
2	Large readout
3	Slider (see below for configuration)

sliderMin

The minimum value of the stage monitor's slider.

sliderMax

The maximum value of the stage monitor's slider.

isDiscrete

true if the stage monitor's slider should only allow integer values; false otherwise.

x

The _x_-coordinate of the stage monitor, relative to the top-left corner of the stage.

y

The _y_-coordinate of the stage monitor, relative to the top-left corner of the stage.

visible

true if the stage monitor is shown on the stage; false if it is hidden.

Variable Objects

A Variable object stores information about a variable. It contains the following properties:

name

The variable name.

value

The variable value.

isPersistent

true if the variable is a cloud variable; false otherwise.

List Objects

A List object stores information about a list and its stage monitor. Each list has two corresponding List objects in an SB2 file: one in its sprite's "lists" array (used to show the sprite to which sprite the list belongs) and one in the stage's "children" array (used to show the order of stage monitors and other objects on the stage). It contains the following properties:

listName

The list name.

contents

An array of the items in the list.

isPersistent

true if the list is a cloud list; false otherwise.

x

The _x_-coordinate (relative to the top-left corner of the stage) of the stage monitor for the list.

y

The _y_-coordinate (relative to the top-left corner of the stage) of the stage monitor for the list.

width

The width in pixels of the stage monitor for the list.

height

The height in pixels of the stage monitor for the list.

visible

true if the stage monitor for the list is shown on the stage.

Script Tuples

A script tuple stores a script as a JSON array. Each script is an array of length three, in the form [x, y, blocks].

The distance between the left edge of the script and the left edge of the scripts area.

The distance between the top edge of the script and the top edge of the scripts area.

blocks

The blocks in the script, as an array of block tuples.

For example, this script tuple:

[99,
    50,
    [["whenGreenFlag"],
        ["doUntil", [">", ["timer"], "10"], [["gotoSpriteOrMouse:", "_mouse_"]]],
        ["think:duration:elapsed:from:", "Scratch 2.0 is amazing!", 3]]]

produces this script:

when gf clicked repeat until <(timer) > [10]> go to [mouse-pointer v] end think [Scratch 2.0 is amazing!] for (3) secs

and appears 99 pixels to the right and 50 down from the top left of the scripts area when the project is imported into Scratch.

Block Tuples

A block tuple stores a block as a JSON array. The first element in the array is an opcode: a string which identifies the block (see Scratch File Format (2.0)/Block Selectors for a list of the opcodes in Scratch 2.0). The remaining elements in the array store the arguments to the block.

Literal values in numeric, textual, or drop-down inputs are stored as numbers or strings. Literal values in color inputs are stored as 32-bit ARGB values. For example:

["wait:elapsed:from:", 1] ["say:", "Hello!"]

Nested reporter blocks are represented as block tuples. For example:

["wait:elapsed:from:", ["*", 3, 2]]

The contents of C blocks are arrays of block tuples. For example:

["doForever", [["comeToFront"]]] ["doIf", ["mousePressed"], [["say:", "yes"]]]

If () Then, Else blocks have two arrays. For example:

["doIfElse", ["mousePressed"], [["say:", "yes"]], [["say:", "no"]]]

Custom Blocks

Custom blocks are represented as normal scripts. The Define () block follows the format ["procDef", "spec", inputNames, defaultValues, atomic].

spec

A string that identifies the labels and inputs to the block. Plain words produce labels in the block prototype; %c produces an input slot of the type identified by the character c; and %c.menuName produces an input slot of the type identified by the character c with a menu of the type identified by menuName. See here for a full list of input types.

inputNames

An array of input names for each %-slot in spec.

defaultValues

An array of default values for each %-slot in spec.

atomic

true if the block should run without screen refresh; false otherwise.

A comment tuple stores a comment as a JSON array. Each comment is an array of length seven, in the form [x, y, width, height, isOpen, blockID, text].

The distance between the left edge of the comment and the left edge of the scripts area.

The distance between the top edge of the comment and the top edge of the scripts area.

width

The width of the comment's frame in pixels.

height

The height of the comment's frame in pixels.

isOpen

true if the comment is a full (expanded) comment; false otherwise.

blockID

The index (in the list of all blocks in the sprite or Stage to which this comment belongs) of the block to which this comment is attached, or -1 if this comment is not attached to a block.

text

The text contents of the comment.

Info Objects

An Info object stores information about a project and the studio used to create it. It contains the following properties:

scriptCount

The total number of scripts in the project.

videoOn

true if the video was turned on when the project was saved; false otherwise.

spriteCount

The total number of sprites in the project.

swfVersion

The version of the Scratch studio with which the project was saved.

flashVersion

The version of the Flash Player plugin in which the Scratch studio was running.

hasCloudData

true if the project uses cloud data; false otherwise.

userAgent

The user agent string of the browser in which the Scratch studio was running.

projectID

This project's ID on the scratch website.

savedExtensions

The extensions which have been imported into the project, as an array of Extension objects.

An Info object also contains the following properties in projects converted from Scratch 1.4 projects:

author

The username of the project's author.

scratch-version

The version of Scratch 1.4 in which the project was created.

os-version

The version of the operating system on which the project was created.

platform

The operating system on which the project was created.

history

A log of all actions performed on the project.

language

The language Scratch was using when the project was saved.

comment

The project notes.

Extension Objects

An Extension object stores information about an extension. It contains the following properties:

extensionName

The name of the extension.

extensionPort

The port on which the extension runs.

blockSpecs

An array of the extension's block specs.

Costume Objects

A Costume object stores data about a costume or backdrop. It contains the following properties:

costumeName

The name of the costume.

baseLayerID

The number of the corresponding image file in the project ZIP archive.

Note:	This is -1 if project.json was downloaded from Scratch's servers.

baseLayerMD5

The MD5 hash of the image file followed by its file extension.

bitmapResolution

In a bitmap costume image, the number of pixels which fit along the X axis of a single screen pixel. Usually 1, or 2 when the costume includes bitmap text.

rotationCenterX

The _x_-coordinate of the costume's rotation center, relative to the top-left of the image.

rotationCenterY

The _y_-coordinate of the costume's rotation center, relative to the top-left of the image.

A Costume object with text created in the Scratch 1.4 paint editor also contains the following properties:

fontName

The name of the font used to display the text.

fontSize

The size of the font used to display the text.

text

The text as a string.

textColor

The color of the text as a 32-bit ARGB value.

textLayerID

The number of the image file containing a rendering of the text in the project ZIP archive.

Note:	This is -1 if project.json was downloaded from Scratch's servers.

textLayerMD5

The MD5 hash of the text image file followed by its file extension.

textRect

An array of the _x_- and _y_-coordinates of the rectangle containing the text, relative to the top-left of the image, followed by the width and height of the rectangle containing the text.

Sound Objects

A Sound object stores extra metadata for a sound in either a sprite or the stage. It contains the following properties:

soundName

The name of the sound.

soundID

The number of the corresponding sound file in the project ZIP archive.

Note:	This is -1 if project.json was downloaded from Scratch's servers.

md5

The MD5 hash of the sound file followed by its file extension.

sampleCount

The number of samples in the sound.

rate

The sampling rate of the sound in Hertz.

format

A string describing the sound format. Usually the empty string, "".

Example Projects

Some example project.json files, exported with the Scratch 2.0 Offline Editor v461 on Windows 10.

An Empty Project

The following is for a blank stage with no sprites, scripts, or sounds and a single backdrop:

{
    "objName": "Stage",
    "costumes": [{
            "costumeName": "backdrop1",
            "baseLayerID": 1,
            "baseLayerMD5": "739b5e2a2435f6e1ec2993791b423146.png",
            "bitmapResolution": 1,
            "rotationCenterX": 240,
            "rotationCenterY": 180
        }],
    "currentCostumeIndex": 0,
    "penLayerMD5": "5c81a336fab8be57adc039a8a2b33ca9.png",
    "penLayerID": 0,
    "tempoBPM": 60,
    "videoAlpha": 0.5,
    "children": [],
    "info": {
        "userAgent": "Scratch 2.0 Offline Editor",
        "videoOn": false,
        "scriptCount": 0,
        "flashVersion": "WIN 32,0,0,182",
        "spriteCount": 0,
        "swfVersion": "v461"
    }
}

The Default Project

The following is for the project which appeared when "Create" was selected on the Scratch 2.0 website or when the offline editor was opened.

{
    "objName": "Stage",
    "sounds": [{
            "soundName": "pop",
            "soundID": 1,
            "md5": "83a9787d4cb6f3b7632b4ddfebf74367.wav",
            "sampleCount": 258,
            "rate": 11025,
            "format": ""
        }],
    "costumes": [{
            "costumeName": "backdrop1",
            "baseLayerID": 3,
            "baseLayerMD5": "739b5e2a2435f6e1ec2993791b423146.png",
            "bitmapResolution": 1,
            "rotationCenterX": 240,
            "rotationCenterY": 180
        }],
    "currentCostumeIndex": 0,
    "penLayerMD5": "5c81a336fab8be57adc039a8a2b33ca9.png",
    "penLayerID": 0,
    "tempoBPM": 60,
    "videoAlpha": 0.5,
    "children": [{
            "objName": "Sprite1",
            "sounds": [{
                    "soundName": "meow",
                    "soundID": 0,
                    "md5": "83c36d806dc92327b9e7049a565c6bff.wav",
                    "sampleCount": 18688,
                    "rate": 22050,
                    "format": ""
                }],
            "costumes": [{
                    "costumeName": "costume1",
                    "baseLayerID": 1,
                    "baseLayerMD5": "f9a1c175dbe2e5dee472858dd30d16bb.svg",
                    "bitmapResolution": 1,
                    "rotationCenterX": 47,
                    "rotationCenterY": 55
                },
                {
                    "costumeName": "costume2",
                    "baseLayerID": 2,
                    "baseLayerMD5": "6e8bd9ae68fdb02b7e1e3df656a75635.svg",
                    "bitmapResolution": 1,
                    "rotationCenterX": 47,
                    "rotationCenterY": 55
                }],
            "currentCostumeIndex": 0,
            "scratchX": 0,
            "scratchY": 0,
            "scale": 1,
            "direction": 90,
            "rotationStyle": "normal",
            "isDraggable": false,
            "indexInLibrary": 1,
            "visible": true,
            "spriteInfo": {
            }
        }],
    "info": {
        "userAgent": "Scratch 2.0 Offline Editor",
        "videoOn": false,
        "scriptCount": 0,
        "flashVersion": "WIN 32,0,0,182",
        "spriteCount": 1,
        "swfVersion": "v461"
    }
}

External Links

Input Type Specifiers

References

↑ Lightnin. (8/4/2012). "It'll be: .sb2" ar-post:1199472

The Wiki is working on a dark theme, and you're seeing it! Got feedback? Post on the Wiki Forum Topic.

Scratch File Format (2.0) - Scratch Wiki (original) (raw)

JSON

Project Files

Sprite Files

Stage Objects

Sprite Objects

StageMonitor Objects

Variable Objects

List Objects

Script Tuples

Block Tuples

Custom Blocks

Info Objects

Extension Objects

Costume Objects

Sound Objects

Example Projects

An Empty Project

The Default Project

See Also

External Links

References