Eng:Scratch File Format (2.0)

The Scratch 2.0 file format is the file format used to encode Scratch 2.0 projects when they are downloaded to a user's computer. Unlike the binary Scratch 1.4 file format, the 2.0 format comprises a ZIP archive containing project information encoded in a text-based format called JSON and project media in separate files. Projects conventionally have the extension, and sprites the extension.

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 interact with 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 the Scratch studio; e.g., they can make custom blocks with color inputs or place reporters in slots where they cannot normally be dropped.

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. JSON represents objects with the syntax, where key is the string key in double quotation marks and value is the value for that key. Similarly, it represents arrays as. Values can be other objects, arrays, strings (delimited by double-quotation marks, e.g., ), numbers (e.g.,   or  ), or Boolean values (  or  ).

Syntax
JSON consists of 4 types of objects. The root tag of JSON can either be an object, or an array.

Objects
An object in JSON, is a list of any kind of JSON objects, each object can be referred to individually by its key, which is always a string.

Syntax: , separated by commas, all inside curly brackets

Example: 

Arrays
An array in JSON, is a list of any kind of JSON objects, the order of the items is kept. Each item can be referred to with its number (starts at 0) A number is automatically assigned when an object is added to the array, based on how many objects are in the array already.

Syntax:  Any type of objects, separated by commas, all inside square brackets

Example:  -

Strings
A string in JSON is a way of storing text as an object.

Syntax:  " value "

Example:  "This is a string it is 41 characters long"

Integers
An integer is a number, that cannot contain anything other than numbers

Syntax:  495729471

Example:  1038473924

Floating-Point Numbers
Floating-Point Numbers are just like integers, just they have decimal places.

Syntax:  978329.4383

Example:  24231643.34

Boolean Identifiers
Boolean means True or False. They are represented in JSON by "true" and "false".

Syntax:  " " or " "

Example:  {"has-eye-missing":false, "is-hurt":true}

None
None, represented by "null", means no data. None is usually used to represent nothing, without causing reference errors.

Syntax:  " "

Example:  {"second-middle-name":null}

Example
A simple example of JSON syntax: {"color":"green", "size":3.5, "number_of\"eyes\"":3, "eye_colors":["red","green","blue"], "status":"terminated","alive":true, "children":{"color":"blue", …}} Since this can be hard to read, this article uses pretty-printed JSON, indenting each sub-element 4 spaces: {   "color": "green", "size": 3.5, "number_of\"eyes\"": 3, "eye_colors": [ "red", "green", "blue" ],   "status": "terminated", "alive": true, "children": { "color": "blue", …   } } Note: Escaping is used in this example

Parsing JSON
Python's json module can be used to read and write JSON data: import json json.loads("{}") json.dumps({"a":[1,2,3]})

JavaScript can also be used, which has a built-in object called  that allows you to encode and decode JSON data:

JSON.stringify({a: [1, 2, 3]}) //=> "{\"a\":[1,2,3]}" JSON.parse("{\"a\":[1,2,3]}") //=> {a: [1, 2, 3]}

json.org provides an extensive list of libraries for parsing and generating JSON in many different programming languages.

Getting Project Data
There is one public way to download get a project.

Downloading a ZIP
You can save a project to your computer from the Scratch studio:


 * 1) Navigate to the project and click See Inside
 * 2) Click File > Download to your computer
 * 3) In the dialog, type a filename and replace the file extension  with  
 * 4) Once saved, unarchive it; double-clicking the ZIP will do this on many operating systems

Format
The project metadata, sprites, scripts, and information about project media are all stored in a single JSON file called. The subsections below describe individual objects in that file.

Stage objects
A Stage object is the root object in a  file. It contains the following keys and values:


 * The name of the stage. Usually, but will change depending on the project's language.
 * The name of the stage. Usually, but will change depending on the project's language.


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


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


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


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


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


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


 * The backdrop number of the stage.
 * The backdrop number of the stage.


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


 * The MD5 hash name for the image of the pen trails on the stage when the project was saved.
 * The MD5 hash name for the image of the pen trails on the stage when the project was saved.


 * The tempo when the project was saved.
 * The tempo when the project was saved.


 * The video transparency when the project was saved.
 * The video transparency when the project was saved.


 * 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.
 * 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.


 * Extra information about the user and the project, as an Info object.
 * 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 keys and values:


 * The name of the sprite.
 * The name of the sprite.


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


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


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


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


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


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


 * The costume number of the sprite.
 * The costume number of the sprite.


 * The X position of the sprite, relative to the center of the stage.
 * The X position of the sprite, relative to the center of the stage.


 * The Y position of the sprite, relative to the center of the stage.
 * The Y position of the sprite, relative to the center of the stage.


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


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


 * The rotation style of the sprite as a string; either,  , or
 * The rotation style of the sprite as a string; either,  , or


 * if the sprite is draggable;  otherwise.
 * if the sprite is draggable;  otherwise.


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


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


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

StageMonitor objects
A StageMonitor object stores information about a stage monitor. It contains the following keys and values:


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


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


 * The type of stage monitor. Valid values are:
 * The type of stage monitor. Valid values are:

! !Description !
 * The answer.
 * The backdrop number of the stage.
 * The costume number of the stage monitor's target.
 * A variable monitor.
 * The variable name.
 * The direction of the stage monitor's target.
 * The size of the stage monitor's target.
 * The backdrop name of the stage.
 * The video motion on the stage monitor's target.
 * where type is  or   and thing is   or
 * The loudness.
 * The tempo.
 * A value of the current block.
 * ,,  ,  ,  ,  , or  , depending on which one the monitor is showing
 * The timer.
 * The volume of the stage monitor's target.
 * The X position of the stage monitor's target.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The size of the stage monitor's target.
 * The backdrop name of the stage.
 * The video motion on the stage monitor's target.
 * where type is  or   and thing is   or
 * The loudness.
 * The tempo.
 * A value of the current block.
 * ,,  ,  ,  ,  , or  , depending on which one the monitor is showing
 * The timer.
 * The volume of the stage monitor's target.
 * The X position of the stage monitor's target.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The loudness.
 * The tempo.
 * A value of the current block.
 * ,,  ,  ,  ,  , or  , depending on which one the monitor is showing
 * The timer.
 * The volume of the stage monitor's target.
 * The X position of the stage monitor's target.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The timer.
 * The volume of the stage monitor's target.
 * The X position of the stage monitor's target.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The volume of the stage monitor's target.
 * The X position of the stage monitor's target.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * The Y position of the stage monitor's target.
 * }
 * A parameter to the stage monitor command. See the table above.
 * A parameter to the stage monitor command. See the table above.
 * A parameter to the stage monitor command. See the table above.


 * The color of the stage monitor, as a hexadecimal color of the form.
 * The color of the stage monitor, as a hexadecimal color of the form.


 * The label text for the stage monitor.
 * The label text for the stage monitor.


 * The stage monitor mode, either,  , or.
 * The stage monitor mode, either,  , or.

! !Meaning
 * Normal readout
 * Large readout
 * Slider (see below for configuration keys)
 * }
 * The minimum value of the stage monitor's slider.
 * Large readout
 * Slider (see below for configuration keys)
 * }
 * The minimum value of the stage monitor's slider.
 * }
 * The minimum value of the stage monitor's slider.
 * The minimum value of the stage monitor's slider.


 * The maximum value of the stage monitor's slider.
 * The maximum value of the stage monitor's slider.


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


 * The X position of the stage monitor, relative to the top-left corner of the stage.
 * The X position of the stage monitor, relative to the top-left corner of the stage.


 * The Y position of the stage monitor, relative to the top-left corner of the stage.
 * The Y position of the stage monitor, relative to the top-left corner of the stage.


 * if the stage monitor is shown on the stage;  if it is hidden.
 * if the stage monitor is shown on the stage;  if it is hidden.

Variable objects
A Variable object stores information about a variable. It contains the following keys and values:


 * The variable name.
 * The variable name.


 * The variable value.
 * The variable value.


 * if the variable is a cloud variable;  otherwise.
 * if the variable is a cloud variable;  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 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 keys and values:


 * The list name.
 * The list name.


 * An array of the items in the list.
 * An array of the items in the list.


 * if the list is a cloud list;  otherwise.
 * if the list is a cloud list;  otherwise.


 * The X position (relative to the top-left corner of the stage) of the stage monitor for the list.
 * The X position (relative to the top-left corner of the stage) of the stage monitor for the list.


 * The Y position (relative to the top-left corner of the stage) of the stage monitor for the list.
 * The Y position (relative to the top-left corner of the stage) of the stage monitor for the list.


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


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


 * if the stage monitor for the list is shown on the stage.
 * 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
 * The distance between the left edge of the script and the left edge of the scripts area.


 * y
 * 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 input slots are stored as numbers or strings. 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/else blocks have two arrays. For example:

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

Custom Blocks
Custom blocks are represented as normal scripts. The procedure definition block follows the format.


 * spec
 * A string that identifies the labels and inputs to the block. Plain words produce labels in the block prototype;  produces an input slot of the type identified by the character c ; and   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
 * if the block should run without screen refresh;  otherwise.

Comment tuples
A comment tuple stores a comment as a JSON array. Each comment is an array of length seven, in the form.


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


 * y
 * 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
 * if the comment is a full (expanded) comment;  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  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 keys and values:


 * The total number of scripts in the project.
 * The total number of scripts in the project.


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


 * The total number of sprites in the project.
 * The total number of sprites in the project.


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


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


 * if the project uses cloud data;  otherwise.
 * if the project uses cloud data;  otherwise.


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


 * This project's ID on the scratch website.
 * This project's ID on the scratch website.


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

An Info object also contains the following keys and values in projects converted from Scratch 1.4 projects:


 * The username of the project's author.
 * The username of the project's author.


 * The long version name of Scratch in which the project was created.
 * The long version name of Scratch in which the project was created.


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


 * The operating system on which the project was created.
 * The operating system on which the project was created.


 * A log of all actions performed on the project.
 * A log of all actions performed on the project.


 * The language Scratch was using when the project was saved.
 * The language Scratch was using when the project was saved.


 * The project notes.
 * The project notes.

Extension objects
An Extension object stores information about an extension. It contains the following keys and values:


 * The name of the extension.
 * The name of the extension.


 * The port on which the extension runs.
 * The port on which the extension runs.


 * An array of the extension's block specs.
 * An array of the extension's block specs.

Media
The media (costumes, sounds, and backgrounds) in the zipped directory are named sequentially from zero with image file extensions for costumes (usually  or  ) and audio file extensions for sounds (usually  ).

Costume objects
A Costume object stores extra metadata for a costume or backdrop. It contains the following keys and values:


 * The name of the costume.
 * The name of the costume.


 * The number of the corresponding image file in the project ZIP archive.
 * Note: Value is -1 unless downloaded via Scratch GUI
 * Note: Value is -1 unless downloaded via Scratch GUI


 * The MD5 hash of the contents of the costume, followed by a U+002E FULL STOP and the file extension (usually   or  ).
 * The MD5 hash of the contents of the costume, followed by a U+002E FULL STOP and the file extension (usually   or  ).


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


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


 * The Y coordinate of the costume's rotation center, relative to the top-left of the image.
 * 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 keys and values:


 * The name of the font used to display the text.
 * The name of the font used to display the text.


 * The size of the font used to display the text.
 * The size of the font used to display the text.


 * The text as a string.
 * The text as a string.


 * The color of the text as a hexadecimal color of the form
 * The color of the text as a hexadecimal color of the form


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


 * The MD5 hash of the rendering of the text, followed by a U+002E FULL STOP and the file extension (usually  ).
 * The MD5 hash of the rendering of the text, followed by a U+002E FULL STOP and the file extension (usually  ).


 * An array of the X and Y positions 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.
 * An array of the X and Y positions 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 keys and values:


 * The name of the sound.
 * The name of the sound.


 * The number of the corresponding sound file in the project ZIP archive.
 * Note: Value is -1 unless downloaded via Scratch GUI
 * Note: Value is -1 unless downloaded via Scratch GUI


 * The MD5 hash of the contents of the sound, followed by a U+002E FULL STOP and the file extension (usually  ).
 * The MD5 hash of the contents of the sound, followed by a U+002E FULL STOP and the file extension (usually  ).


 * The number of samples in the sound.
 * The number of samples in the sound.


 * The sampling rate of the sound.
 * The sampling rate of the sound.


 * A string describing the sound format. Usually the empty string.
 * A string describing the sound format. Usually the empty string.

Example Projects
Some example  files, exported on Chrome 30.0.1552.0 with Flash player 11.8.800.94 on Mac OS X 10.8.4 with Scratch studio version v341.

An empty project
A blank stage with no sprites or scripts and a single backdrop.  {   "objName": "Stage", "costumes": [{ "costumeName": "backdrop1", "baseLayerID": 1, "baseLayerMD5": "510da64cf172d53750dffd23fbf73563.png", "bitmapResolution": 1, "rotationCenterX": 240, "rotationCenterY": 180 }],   "currentCostumeIndex": 0, "penLayerMD5": "279467d0d49e152706ed66539b577c00.png", "tempoBPM": 60, "videoAlpha": 0.5, "children": [], "info": { "scriptCount": 0, "flashVersion": "MAC 11,8,800,94", "spriteCount": 0, "swfVersion": "v341", "videoOn": false, "projectID": "11175527", "userAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/30.0.1552.0 Safari\/537.36", "hasCloudData": false } }

The default project
The project which appears when Create is selected from the header navigation.  {   "objName": "Stage", "sounds": [{ "soundName": "pop", "soundID": 1, "md5": "83a9787d4cb6f3b7632b4ddfebf74367.wav", "sampleCount": 258, "rate": 11025, "format": "" }],   "costumes": [{ "costumeName": "backdrop1", "baseLayerID": 3, "baseLayerMD5": "510da64cf172d53750dffd23fbf73563.png", "bitmapResolution": 1, "rotationCenterX": 240, "rotationCenterY": 180 }],   "currentCostumeIndex": 0, "penLayerMD5": "279467d0d49e152706ed66539b577c00.png", "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": { "scriptCount": 0, "flashVersion": "MAC 11,8,800,94", "spriteCount": 1, "hasCloudData": false, "videoOn": false, "userAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/30.0.1552.0 Safari\/537.36", "projectID": "11175527", "swfVersion": "v341" } }