(Redirected from Scratch 2.0 File Format)

SandCastleIcon.png This article has links to websites or programs not trusted by Scratch or hosted by 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[1].

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 a .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 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:[2]
  • pen
  • wedo2
  • music
  • microbit
  • text2speech
  • translate
  • videoSensing
  • ev3
  • makeymakey
  • boost
  • gdxfor
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:[3]

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 and the second is the value.
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".[4] 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.[5]

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".[6]

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.[7] 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. The opcode of a "core" block may be found in the Scratch source code here or here for shadows, and the opcode of an extension's block may be found in the extension's source code 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.[8] 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.[9]
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 third element, which is the ID of the field's value.[10]
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.[11][12]

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) or "procedures_prototype" (i.e. the inner part of define custom block). Mutations have the following properties:

tagName
Always equal to "mutation".
children
Seems to always be an empty array.
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.
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.
warp
Whether to run the block without screen refresh or not.

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:[13]

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.[14]
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.

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.

Meta

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

References

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