(Fix things I didn't properly explain)
(Automated edit: added dates to templates)
 
(One intermediate revision by one other user not shown)
Line 10: Line 10:
  
 
== Format ==
 
== Format ==
{{expand}}
+
{{expand|date=June 2019}}
  
 
=== Projects ===
 
=== Projects ===
Line 83: Line 83:
  
 
=== Blocks ===
 
=== Blocks ===
A ''shadow'' is a constant expression in a block input; Scratch internally considers these to be blocks although they are not usually thought of as such.
+
''Fields'' are text boxes, drop-down menus etc., but more often than not one should be able to drop a [[Reporter Block|reporter]] into an [[Argument|input]]. A ''shadow'' is a constant expression in a [[Blocks|block]] input which can be replaced by a reporter;<ref>https://groups.google.com/forum/#!topic/blockly/bXe4iEaVSao</ref> Scratch internally considers these to be blocks although they are not usually thought of as such. (These notions are inherited from [[wikipedia:Blockly|Blockly]], which [[Scratch Blocks]] is based on.)
  
Most [[blocks]] are represented by objects with the following properties:
+
Most blocks are represented by objects with the following properties:
  
 
;<code>opcode</code>
 
;<code>opcode</code>
Line 92: Line 92:
 
:The ID of the following block or <code>null</code>.
 
:The ID of the following block or <code>null</code>.
 
;<code>parent</code>
 
;<code>parent</code>
:If the block is a [[Stack Block|stack block]] and is preceded, this is the ID of the preceding block. If the block is a [[Reporter Block|reporter]] inside another block, this is the ID of the block into which it has been dropped. Otherwise it is <code>null</code>.
+
:If the block is a [[Stack Block|stack block]] and is preceded, this is the ID of the preceding block. If the block is the first stack block in a [[C Block|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 <code>null</code>.
 
;<code>inputs</code>
 
;<code>inputs</code>
:An object associating [[Argument|input]] names with arrays representing inputs. [[C Block|C mouths]] are considered inputs. 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 below. If there is an obscured shadow, the third element is its ID or an array representing it.<ref name="sb3.js">https://github.com/LLK/scratch-vm/blob/develop/src/serialization/sb3.js</ref>
+
:An object associating names with arrays representing inputs into which reporters may be dropped and 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 below. If there is an obscured shadow, the third element is its ID or an array representing it.<ref name="sb3.js">https://github.com/LLK/scratch-vm/blob/develop/src/serialization/sb3.js</ref>
 
;<code>fields</code>
 
;<code>fields</code>
:An object associating field names with arrays representing fields.{{issue|explain}}
+
:An object associating names with arrays representing fields. The first element of each array is the field's value which may be followed by an ID.
 
;<code>shadow</code>
 
;<code>shadow</code>
:True if this is a shadow.
+
:True if this is a shadow and false otherwise.
 
;<code>topLevel</code>
 
;<code>topLevel</code>
 
:False if the block has a parent and true otherwise.
 
:False if the block has a parent and true otherwise.
  
Top-level block objects also have the following properties:
+
A top-level block object also has the ''x''- and ''y''-coordinates of the block in the [[Code Area|code area]] as <code>x</code> and <code>y</code>, a block with a comment attached also has a <code>comment</code> property whose value is the comment's ID, and a block with a mutation also has a <code>mutation</code> property whose value is an object representing the mutation.{{issue|explain}}
 
 
;<code>x</code>
 
:The ''x''-coordinate of the block in the [[Code Area|code area]].
 
;<code>y</code>
 
:The ''y''-coordinate.
 
  
 
A few blocks are instead represented by arrays whose first element is a number representing the block:<sup>[''ambiguous'']</sup><ref name="sb3.js" />
 
A few blocks are instead represented by arrays whose first element is a number representing the block:<sup>[''ambiguous'']</sup><ref name="sb3.js" />
Line 119: Line 114:
 
! 5{{th}} element
 
! 5{{th}} element
 
|-
 
|-
|Number
+
|Number||4||the value
|4
 
|the value
 
 
|-
 
|-
|Positive number
+
|Positive number||5||"
|5
 
|"
 
 
|-
 
|-
|Positive integer
+
|Positive integer||6||"
|6
 
|"
 
 
|-
 
|-
|Integer
+
|Integer||7||"
|7
 
|"
 
 
|-
 
|-
|Angle
+
|Angle||8||"
|8
 
|"
 
 
|-
 
|-
|Color
+
|Color||9||"#" followed by a [[Computer Colors#Hexadecimal Colors|hexadecimal numeral representing the color]]
|9
 
|"#" followed by a [[Computer Colors#Hexadecimal Colors|hexadecimal numeral representing the color]]
 
 
|-
 
|-
|String
+
|String||10||the value
|10
 
|the value
 
 
|-
 
|-
|Broadcast
+
|Broadcast||11||the name||the ID
|11
 
|the name
 
|the ID
 
 
|-
 
|-
|<sb>(Variable)</sb>
+
|<sb>(Variable)</sb>||12||"||"||the ''x''-coordinate, if it is top-level||the ''y''-coordinate, if it is top-level
|12
 
|"
 
|"
 
|the ''x''-coordinate, if it is top-level
 
|the ''y''-coordinate, if it is top-level
 
 
|-
 
|-
|<sb>(List :: list)</sb>
+
|<sb>(List :: list)</sb>||13||"||"||"||"
|13
 
|"
 
|"
 
|"
 
|"
 
 
|}
 
|}
  

Latest revision as of 13:31, 9 July 2019

SandCastleIcon.png This page has links to websites or programs not trusted by Scratch or hosted by Wikipedia. Remember to stay safe while using the Internet, as we can't 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.

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", 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.

Format

Document.png Please expand this article or section. You can help by adding more information if you are an editor. More information might be found in a section of the talk page. (June 2019)

Projects

Projects have the following properties:

targets
An array of targets.
monitors
An array of monitors.
extensions
An array of the names of the extensions used.
meta
Metadata about the project's author.

Targets

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

isStage
True if this is the stage and false otherwise.
name
The name.
variables
An object associating IDs with arrays representing variables whose first element is the variable's name followed by it's value.
lists
An object associating IDs with arrays representing lists whose first element is the list's name followed by the list as an array.
broadcasts
An object associating IDs with broadcast names.
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.
volume
The volume.
layerOrder
The layer number.

The Stage

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

tempo
The tempo in BPM.
videoTransparency
The video transparency.
videoState
If video sensing has been turned off and is off, this is "off"; if the video is flipped, it is "on-flipped"; otherwise, it is "on".
textToSpeechLanguage
The language of the Text to Speech extension.

Sprites

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

visible
True if the sprite is visible and false otherwise.
x
The x-coordinate.
y
The y-coordinate.
size
The sprite's scaling factor as a percentage.
direction
The sprite's direction in degrees clockwise from North.
draggable
True if the sprite is draggable and false otherwise.
rotationStyle
The name of the rotation style: "all around", "left-right", or "don't rotate".

Blocks

Fields are text boxes, drop-down menus etc., but more often than not one should be able to drop a reporter into an input. A shadow is a constant expression in a block input which can be replaced by a reporter;[1] Scratch internally considers these to be blocks although they are not usually thought of as such. (These notions are inherited 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.
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 reporters may be dropped and 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 below. If there is an obscured shadow, the third element is its ID or an array representing it.[2]
fields
An object associating names with arrays representing fields. The first element of each array is the field's value which may be followed by an ID.
shadow
True if this is a shadow 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 also has a comment property whose value is the comment's ID, and a block with a mutation also has a mutation property whose value is an object representing the mutation.[explain]

A few blocks are instead represented by arrays whose first element is a number representing the block:[ambiguous][2]

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 " " " "

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

See Also

References

  1. https://groups.google.com/forum/#!topic/blockly/bXe4iEaVSao
  2. a b https://github.com/LLK/scratch-vm/blob/develop/src/serialization/sb3.js
  3. https://github.com/LLK/scratch-gui/issues/1820