|
2 | 2 |
|
3 | 3 | A detailed explanation of how Scratch 3.0 works as a programming language. |
4 | 4 |
|
5 | | -> [!IMPORTANT] |
6 | | -> **Changes are underway!** |
7 | | -> |
8 | | -> This spec is being transitioned over to Vitepress. Parts of it have already been copied over and deleted from here. It will no longer be included in the README. To view it, you'll have to go to the much better [published page](https://oceanisendless.github.io/scratch-spec/). See ya there when it's up and running! |
9 | | -> |
10 | | -
|
11 | | -## Contents |
12 | | - |
13 | | -* [Scratch Specification](#scratch-specification) |
14 | | - * [Contents](#contents) |
15 | | - * [TODO](#todo) |
16 | | - * [TODO: Blocks](#todo-blocks) |
17 | | - * [Palette](#palette) |
18 | | - * [Example block](#example-block) |
19 | | - * [Motion blocks](#motion-blocks) |
20 | | - * [Standard motion blocks](#standard-motion-blocks) |
21 | | - * [motion\_movesteps](#motion_movesteps) |
22 | | - * [Hidden motion blocks](#hidden-motion-blocks) |
23 | | - * [Looks blocks](#looks-blocks) |
24 | | - * [Standard looks blocks](#standard-looks-blocks) |
25 | | - * [Hidden looks blocks](#hidden-looks-blocks) |
26 | | - * [Sound blocks](#sound-blocks) |
27 | | - * [Standard sound blocks](#standard-sound-blocks) |
28 | | - * [Hidden sound blocks](#hidden-sound-blocks) |
29 | | - * [Events blocks](#events-blocks) |
30 | | - * [Standard events blocks](#standard-events-blocks) |
31 | | - * [Hidden events blocks](#hidden-events-blocks) |
32 | | - * [Control blocks](#control-blocks) |
33 | | - * [Standard control blocks](#standard-control-blocks) |
34 | | - * [Hidden control blocks](#hidden-control-blocks) |
35 | | - * [Sensing blocks](#sensing-blocks) |
36 | | - * [Standard sensing blocks](#standard-sensing-blocks) |
37 | | - * [sensing\_username](#sensing_username) |
38 | | - * [Hidden sensing blocks](#hidden-sensing-blocks) |
39 | | - * [Operators blocks](#operators-blocks) |
40 | | - * [Standard operators blocks](#standard-operators-blocks) |
41 | | - * [Hidden operators blocks](#hidden-operators-blocks) |
42 | | - * [Variables blocks](#variables-blocks) |
43 | | - * [Standard variables blocks](#standard-variables-blocks) |
44 | | - * [Hidden variables blocks](#hidden-variables-blocks) |
45 | | - * [List blocks](#list-blocks) |
46 | | - * [Standard list blocks](#standard-list-blocks) |
47 | | - * [Hidden list blocks](#hidden-list-blocks) |
48 | | - * [Custom blocks](#custom-blocks) |
49 | | - * [Standard custom blocks](#standard-custom-blocks) |
50 | | - * [Hidden custom blocks](#hidden-custom-blocks) |
51 | | - * [Special custom blocks](#special-custom-blocks) |
52 | | - * [Music blocks](#music-blocks) |
53 | | - * [Pen blocks](#pen-blocks) |
54 | | - * [Video Sensing blocks](#video-sensing-blocks) |
55 | | - * [Text to Speech blocks](#text-to-speech-blocks) |
56 | | - * [Translate blocks](#translate-blocks) |
57 | | - * [Makey Makey blocks](#makey-makey-blocks) |
58 | | - * [micro:bit blocks](#microbit-blocks) |
59 | | - * [LEGO EV3 blocks](#lego-ev3-blocks) |
60 | | - * [BOOST blocks](#boost-blocks) |
61 | | - * [WeDo 2.0 blocks](#wedo-20-blocks) |
62 | | - * [Force and Acceleration blocks](#force-and-acceleration-blocks) |
63 | | - * [CoreEx blocks](#coreex-blocks) |
64 | | - * [Standard CoreEx blocks](#standard-coreex-blocks) |
65 | | - * [Hidden CoreEx blocks](#hidden-coreex-blocks) |
66 | | - * [Appendices](#appendices) |
67 | | - * [File Format](#file-format) |
68 | | - * [SB3](#sb3) |
69 | | - * [SB2](#sb2) |
70 | | - * [SB](#sb) |
71 | | - * [Obsolete Blocks](#obsolete-blocks) |
72 | | - * [Nonstandard Blocks](#nonstandard-blocks) |
73 | | - * [Example nonstandard block](#example-nonstandard-block) |
74 | | - * [TurboWarp](#turbowarp) |
75 | | - * [TurboWarp blocks](#turbowarp-blocks) |
76 | | - * [Last key pressed block](#last-key-pressed-block) |
77 | | - * [Addon blocks](#addon-blocks) |
78 | | - * [PenguinMod](#penguinmod) |
79 | | - * [snail-ide](#snail-ide) |
80 | | - * [Unsandboxed](#unsandboxed) |
81 | | - * [Adding Platforms](#adding-platforms) |
82 | | - |
83 | | -## Appendices |
84 | | - |
85 | | -This section is for additional information about Scratch that is not necessarily relevant to its runtime behavior, but is good to know in addition, especially for creating highly compatible and feature-complete Scratch implementations. |
86 | | - |
87 | | -### File Format |
88 | | - |
89 | | -> This section will be expanded once other stuff gets documented. For now, runtime behavior is more pressing than file formatting. |
90 | | -
|
91 | | -Scratch projects can be saved and loaded from a computer as files. Scratch has several project file formats, each with their own complicated structures and loading behaviors. Even with a perfectly accurate [runtime](#runtime) environment, a saved project that is not properly loaded may not work as it was intended to, and could very well break! |
92 | | - |
93 | | -#### SB3 |
94 | | - |
95 | | -The .sb3 file format is the standard format for storing Scratch **3.0** projects, the version of Scratch that this specification documents. In reality, it is a renamed [.zip](https://en.wikipedia.org/wiki/ZIP_(file_format)) file that contains the following files: |
96 | | - |
97 | | -* `project.json`, a [.json](https://en.wikipedia.org/wiki/JSON) file storing info. |
98 | | -* Various image files used as [costumes](#costume). |
99 | | -* Various audio files used as [sounds](#sound). |
100 | | - |
101 | | -TODO: Specify!!! |
102 | | - |
103 | | -#### SB2 |
104 | | - |
105 | | -The .sb2 file format is the standard format for storing Scratch **2.0** projects, the version of Scratch preceding Scratch 3.0, the version that this specification documents. |
106 | | - |
107 | | -The standard Scratch 3.0 editor is compatible with .sb2 files. It has a procedure for converting .sb2 files to [.sb3](#sb3) files, which it then loads. |
108 | | - |
109 | | -TODO: Specify!! |
110 | | - |
111 | | -#### SB |
112 | | - |
113 | | -The .sb file format is the standard format for storing projects from Scratch **1.4** and earlier, which are early versions of Scratch that work drastically different than modern Scratch due to the major changes in between. Unlike [.sb2](#sb2) and [.sb3](#sb3) files, .sb files are stored in binary using a much less human-readable format. |
114 | | - |
115 | | -Despite major differences, the standard Scratch 3.0 editor remains compatible with .sb files. It has a procedure for converting .sb files to .sb2 files, which it then converts to .sb3 files and loads. |
116 | | - |
117 | | -TODO: Specify! |
118 | | - |
119 | | -### Obsolete Blocks |
120 | | - |
121 | | -> This is an interesting idea, but its inclusion is up for debate. Feel free to offer insight! |
122 | | -
|
123 | | -This section reimagines blocks that *were* supported in earlier versions of Scratch, but have since been removed from Scratch 3.0 or left in an inoperative state. Its goal is to closely recreate what the functionality of these blocks *would* have been if they had been kept in Scratch and were supported by Scratch 3.0. |
124 | | - |
125 | | -This way, one could theoretically create an implementation of Scratch 3.0 that accurately supports *every* block from *every* official Scratch version, though obviously with subtle differences due to changes in [runtime](#runtime) behavior between Scratch versions. |
126 | | - |
127 | | -Unlike the rest of this specification, the content of this section is more up to the imagination, as it dreams of how obsolete blocks *would* behave in modern Scratch, and is not actually observing the behavior of these blocks directly (though it should stay as close as possible to the block's original behavior). |
128 | | - |
129 | | -### Nonstandard Blocks |
130 | | - |
131 | | -> This section is not a high priority, as this specification is primarily meant to document standard Scratch. In the future, it is hoped this spec will include other branches of Scratch. This way, the behavior of projects created with them can be officially documented and remain recreatable if needed (e.g. for highly compatible [ports](https://en.wikipedia.org/wiki/Porting) of Scratch). |
132 | | -
|
133 | | -This section serves to document blocks that do not exist at all in Scratch, but have been added unofficially to [modifications](#mod) of Scratch. This includes both blocks added as "custom extensions," and blocks added directly to the [palette](#palette). They are specified here in order to allow projects using these nonstandard blocks to function properly if one were to reimplement the Scratch VM with implementing these blocks in mind. |
134 | | - |
135 | | -> This is a dynamic section and may never be able to satisfy any particular standards for completeness. [You can help](#contributing) by adding [missing blocks](#todo-blocks) with reliable sources (e.g. links to source code). |
136 | | -
|
137 | | -#### Example nonstandard block |
138 | | - |
139 | | -> This is an ***example* section** about a nonstandard block. It does not exist in Scratch or any modifications of it. |
140 | | -
|
141 | | -**Operation:** |
142 | | - |
143 | | -A brief overview of the block's function and essential info. |
144 | | - |
145 | | -**Block:** |
146 | | - |
147 | | -```sb |
148 | | -the block in scratchblocks with its [ARG]uments |
149 | | -``` |
150 | | - |
151 | | -**Arguments:** |
152 | | - |
153 | | -| Name: | [Casted](#casting) to: | Provides the: | |
154 | | -|:-----:|:-------------------------------------------------------------------------------------------------------------------------:|:------------------------------:| |
155 | | -| `ARG` | [the kind of value this argument is casted to before use by the block, linking to the procedure used to cast it](#values) | What it provides to the block. | |
156 | | - |
157 | | -**Procedure:** |
158 | | - |
159 | | -A deep dive into what the block does in fulfilling its operation. |
160 | | - |
161 | | -#### TurboWarp |
162 | | - |
163 | | -[TurboWarp](https://turbowarp.org/) is a Scratch mod that compiles projects to JavaScript to make them run really fast. It maintains strong compatibility with Scratch, while also supporting a wide range of custom extensions and weird, new blocks. |
164 | | - |
165 | | -TODO: Document TurboWarp blocks |
166 | | - |
167 | | -##### TurboWarp blocks |
168 | | - |
169 | | -These blocks are "weird, new blocks" specific to TurboWarp. This category of blocks is named after TurboWarp itself. |
170 | | - |
171 | | -###### Last key pressed block |
172 | | - |
173 | | -**Operation:** |
174 | | - |
175 | | -Reports the key that was most recently pressed on the keyboard. |
176 | | - |
177 | | -**Block:** |
178 | | - |
179 | | -```sb |
180 | | -(last key pressed) |
181 | | -``` |
182 | | - |
183 | | -**Arguments:** |
184 | | - |
185 | | -None |
186 | | - |
187 | | -**Procedure:** |
188 | | - |
189 | | -When the [runtime](#runtime) first starts, no [keys](#key) have been pressed. If the block is run before any keys are pressed, it reports the [empty string](#empty-string). Otherwise, the [name](#name) of the last key to have been pressed is reported. |
190 | | - |
191 | | -##### Addon blocks |
192 | | - |
193 | | -These blocks are added by TurboWarp addons. They are not actually real blocks, but rather [special custom blocks](#special-custom-blocks) without definitions in disguise! |
194 | | - |
195 | | -#### PenguinMod |
196 | | - |
197 | | -[PenguinMod](https://penguinmod.com/) is a mod of [TurboWarp](#turbowarp). It supports most TurboWarp extensions and introduces some community-made ones of its own. |
198 | | - |
199 | | -TODO: Document PenguinMod blocks |
200 | | - |
201 | | -#### snail-ide |
202 | | - |
203 | | -[Snail IDE](https://snail-ide.js.org/) is a mod of [PenguinMod](#penguinmod). It supports most of PenguinMod's blocks and adds some of its own. |
204 | | - |
205 | | -TODO: Document Snail IDE blocks |
206 | | - |
207 | | -#### Unsandboxed |
208 | | - |
209 | | -[Unsandboxed](https://alpha.unsandboxed.org/#0) is a mod of [TurboWarp](#turbowarp) for building games. It is compatible with TurboWarp's blocks and adds some of its own. |
210 | | - |
211 | | -TODO: Document Unsandboxed blocks |
212 | | - |
213 | | -#### Adding Platforms |
214 | | - |
215 | | -If you know of a Scratch modification that is in use by a decent number of people and has new blocks that should be specified, please [contribute](#contributing) information on it! Though if you do, please remember that this a language specification for Scratch's runtime behavior, not a [wiki](https://scratch-wiki.info/) or other online resource. General documentation for modifications are best put elsewhere. To add one, this specification needs: |
216 | | - |
217 | | -* An entry for the modification |
218 | | - * Add a section above this one under [Nonstandard blocks](#nonstandard-blocks) |
219 | | - * Give a brief description that highlights what it adds to Scratch as a language (must add new blocks and/or alter runtime behavior) |
220 | | -* Specification of its unique blocks |
221 | | - * See [Example nonstandard block](#example-nonstandard-block) for details on how to add an entry for a block. Be sure to put the entry under a relevant category, which should then be entered below the relevant platform's section. For example, the `log ()` block in [TurboWarp](#turbowarp) is in the [Addon blocks](#addon-blocks) category, which is then under the TurboWarp section, since that is the platform it was added to. |
222 | | - * If a mod adds a new block, and a mod is made of that mod (thus inheriting the new block), **do not document the block twice**. Blocks should be documented under the platform they first appear on. If blocks are shared between platforms, find the section for the one it was initially added to and specify it over there. |
223 | | - * If the same block just so happens to exist on several platforms without any clear origination (*or* does not work the same way), then it is OK to document them separately, especially if they have identical opcodes but different behavior. |
224 | | - |
225 | | -Though please make sure that the platform you wish to add is actually a modification of Scratch 3.0, and not an entirely different application. This spec is for Scratch 3.0 and offshoots of it, but a platform must share near identical base behaviors with Scratch 3.0 to be added here. For example, [Snap‍*!*](https://snap.berkeley.edu/) was built off of an early version of Scratch, but is now a completely independent first-class block-based language with its own programming paradigm, and is not built with or at all related to Scratch 3.0. Other block-based Scratch-*like* apps deserve [their own spec](https://snap.berkeley.edu/snap/help/SnapManual.pdf) instead. |
| 5 | +To read it, you can visit the [published page](https://oceanisendless.github.io/scratch-spec/), or view the source markdown files in this repository. |
0 commit comments