Values
Values are data stored in the runtime that can be interacted with and manipulated by blocks. In Scratch, the following types of values exist:
There are lots of terms used to refer to these types of values and particular subsets of them. They are referenced throughout this specification and explained below:
Value
A general value. This can be a string, number, boolean, or in rare cases undefined. Variables can hold individual values, and a list can store many of them as items.
Angle
A number intended to be in degrees. [sin v] of (), [cos v] of (), and [tan v] of () expect angles as input.
Answer
A string provided to the project by the user as input via the ask and wait block.
Boolean
A special type of value used to represent the result of a logical operation. It is always either true or false.
True
A kind of boolean used to represent a yes or an affirmative answer as a result of a logical operation. When casted to a string, it is written as true. When casted to a number, it is casted to 1. It is considered truthy, as it is itself the definition of truthy.
False
A kind of boolean used to represent a no or a negative answer as a result of a logical operation. When casted to a string, it is written as false. When casted to a number, it is casted to 0. It is considered falsy, as it is itself the definition of falsy.
Direction
An angle determining how a sprite is pointed on the screen. It is always wrapped to remain in the range -179 and 181 (exclusive). An angle
Or in scratchblocks:
The way a sprite's direction impacts how it is rendered is determined by its rotation style.
Integer
A whole number, or a number that is not a fraction (e.g. 42, -37). Many blocks report integers (e.g. round (), costume [number v], loudness, item # of () in [list v]) and expect integers (e.g. item () of [list v]), just to name a few.
Item
Key
A name used by Scratch for referring to a key on the user's keyboard. Specific keys are referred to by name. To refer to any arbitrary key (as in, "press any key to continue"), the name any can be used.
It is good to note that Scratch does not standardly support special keys other than the ones listed below, making it more versatile across platforms (i.e. it won't conflict with keyboard shortcuts used by other applications running on the user's computer).
| Keyboard Key | Key Name (string) |
|---|---|
| ⌨️ (any key) | any |
| space bar | space |
| ↑ arrow | up arrow |
| ↓ arrow | down arrow |
| → arrow | right arrow |
| ← arrow | left arrow |
| Return ↵ | enter |
| A, B, ...Z (alphabet keys) | a, b, ...z(the lowercase letter) |
| 1, 2, ...0 (number keys) | 1, 2, ...0(the numerical digit) |
| Other keys | The label of the key or the letter it makes when typed as text |
TODO: Document all keys and figure out exactly what keys Scratch does and doesn't support and how it handles unlisted keys)
Length
A positive integer representing how many letters or items there are in a string or list, respectively.
Letter
An individual UTF-16 code unit. Several joined together create a string. In Scratch, letters cannot be directly interacted with per se; getting a letter from a string just reports another string containing only that letter.
Name
A string with the intention of identifying something. This can be applied to a great number of things, but is usually used in regards to a variable, list, costume, sound, user, or sprite.
Number
A numerical value. Most numbers are real and can be positive (+), negative (-), whole (#), or fractional (#.#). In JavaScript, these numbers are internally stored as double-precision 64-bit binary format IEEE 754 values. Thus, Scratch follows largely the same rules JavaScript does when operating on numbers, though with exceptions. In addition to real numbers, special kinds of numbers exist too, which are for situations that cannot be fully expressed with real numbers.
Infinity
A special number that is always greater than any other number. When casted to a string, it is written as Infinity. It is created when the result of a mathematical operation is too large to be represented as a real number.
-Infinity
A special number that is always lower than any other number. When casted to a string, it is written as -Infinity. It is created in the same manner as Infinity.
Whether -Infinity or Infinity is produced by an operation is determined in the same way that a real number would be negative or not. For example, (1) / (n) produces a positive number, while (-1) / (n) produces a negative number. In the same manner, (1) / (0) produces positive infinity, while (-1) / (0) produces negative infinity.
NaN
A special number that is literally not a number. When casted to a string, it is written as NaN. It is created by doing unknown or unrepresentable things with numbers, such as multiplying Infinity by 0, adding Infinity to -Infinity, or getting the square root of a negative number. Unlike Infinity, it does not have a negative counterpart. It is interpreted as a 0 when passed as input to other mathematical operations, unlike in JavaScript where it causes most operations to report NaN.
Opcode
A name that identifies the operation a block performs when run. For example, the opcode of the move () steps block is motion_movesteps, and when run it moves the sprite by the given number of steps, as named.
Rotation Style
A string that determines how a sprite's direction impacts the way it is visibly rotated when rendered. Officially, it can only be one of the following strings: all around, left-right, or don't rotate.
all around: The sprite faces in its direction clockwise. At0, it faces up; at90, it faces right; at180, it faces down; and at-90, it faces left.left-right: If the sprite's direction is less than0, it faces left (-90). Otherwise, it faces right (90).don't rotate: The sprite always faces right (90).
The following table describes a sprite's rendered direction when using different rotation styles. (Its actual direction value remains the same; only the way it looks like it's pointed changes.)
| Direction | All Around | Left-Right | Don't Rotate |
|---|---|---|---|
| 0 | 0 (up) | 90 (right) | 90 (right) |
| 45 | 45 (up-right) | 90 (right) | 90 (right) |
| 90 | 90 (right) | 90 (right) | 90 (right) |
| 135 | 135 (down-right) | 90 (right) | 90 (right) |
| 180 | 180 (down) | 90 (right) | 90 (right) |
| -135 | -135 (down-left) | -90 (left) | 90 (right) |
| -90 | -90 (left) | -90 (left) | 90 (right) |
| -45 | -45 (up-left) | -90 (left) | 90 (right) |
All Around
Left-Right
Don't Rotate
String
A type of value consisting of a series (i.e. string) of letters, also known as text. All strings are considered truthy except for the empty string, the string 0, and the string false (case-insensitive), which are considered falsy.
Empty String
A string containing no letters. It has a length of 0 and is one of the only strings considered falsy. Also known as a "null string," it is typically used in place of a value where there is none, e.g. getting an item from a list when it does not exist, or getting the answer provided by a user when they have not been asked anything yet.
Undefined
A special value that represents nothing. When converted to a string, it is written as undefined. This type of value is uncommon but can be produced by hidden reporter blocks. In most cases, however, Scratch uses 0 or an empty string to represent nothing.
Username
A name used to reference a user. In standard Scratch, usernames:
- Are always 3 to 20 letters long (inclusive)
- Can only contain the following symbols:
- Uppercase Latin letters (A-Z)
- Lowercase Latin letters (a-z)
- Numerical digits (0-9)
- Underscores (_)
- Hyphens (-)
Also, official ("real") usernames are registered with the Scratch website. They are unique (different from each other) and are case-insensitive, meaning that if a username "Endless-Ocean" is registered, there cannot also be an "endless-ocean" or "EndlEss-ocEan", though there can also be an "endless_ocean", "Endless--Ocean", and "Endless-Ocean1" if not already registered.
Official usernames can only be changed under extraordinarily rare circumstances (e.g. the username contained sensitive information about the user that the Scratch team decided to change for them), meaning that once it is created, it usually cannot be altered later.
Scripts can detect the current user's username via the (username) block. If the user is signed in, the block reports their username. If the user is signed out, the block reports an empty string. In the official Scratch editor, the username reported by the username block should remain constant for the entire run of the project.
The only exception to this rule in official contexts is when the user does the following steps in sequence:
- Uses the official Scratch website
- The user cannot sign into their account from the offline editor
- Loads a shared project while signed out of their account
- This does not work with an unshared project because the user cannot view it while signed out
- Signs in to their account from the same window while the project is open
- A menu exists for the user to sign in to their account without reloading the page
Then the reported username is changed from the empty string to the username that the user signed in with, without reloading the project. After this happens, the user cannot change their username again without reloading the project or modifying the runtime directly, e.g. via developer tools.
Due to the aforementioned limitations of real usernames, project can technically check if the user's username is "real" or not by:
- Crossreferencing it with a list of known usernames (or making a request to the Scratch API using cloud variables and an external service such as scratchattach) to see if it is registered with the Scratch website
- Remembering the usernames that the username block has reported (e.g. via cloud variables) to see if it encounters the same username with different casing
- Checking if the username is changed while the project is running (impossible through normal means unless the user is signing in after being signed out)
A project could potentially utilize any of these ways to detect if it is actually being run in the official Scratch environment or an unofficial version of it.
Thus, for a truly accurate recreation of Scratch, the (username) block should only report registered usernames with the Scratch website, and a project which remembers usernames (e.g. via cloud variables) should never encounter the same username it has seen before with different casing, except in extraordinarily rare cases where the casing of a user's username was officially changed by the Scratch team, which is not known to have happened ever. The username should also not be changed while the project is running; the moment the project is started, whatever username the username block reports will be the username for the entire duration of time for which it runs, unless the user was signed out when the project began and signs in while the project is running.
In most cases, however, projects will probably not notice anything wrong with the username (but a few niche ones could break), so long as it only contains valid characters (A-Z, a-z, 0-9, _, -) and is between 3-20 letters in length, as previously stated. In general, usernames are really just any arbitrary string that identifies a user.
X Position
A number representing a horizontal position on the Scratch coordinate plane. All sprites have one.
TODO: document coordinate system
Y Position
A number representing a vertical position on the Scratch coordinate plane. All sprites have one.
TODO: document coordinate system
Other Values
Inclusion of this section is up for debate. Feel free to offer insight!
Other kinds values can potentially exist in modified or bugged versions of Scratch. This is because Scratch is built on JavaScript, and although it is highly unlikely for a project to work with any type of value other than the ones listed above, there is always the potential for other JavaScript primitives to be glitched into the project, e.g. by setting the value via developer tools, or some wider unknown issue.
They will not be specified in this specification as of yet (since they cannot be obtained through official means), but other values that could potentially be encountered in the rarest of cases are:
null: A special value representing nothing. Distinct from undefined in that it is meant to explicitly be nothing, whereas undefined exists for representing unknown behavior or values.- The writers of this specification do not know if
nullcan be produced by existing blocks without modification.- If it is found to be an obtainable value, it may be documented further. Otherwise, it will not be, and is likely not necessary for inclusion in a reimplementation of Scratch.
- This value can be casted to other data types. (
nullwas obtained via "custom extensions" in a modification of Scratch that still has largely the same behaviors as standard Scratch to see how it would behave if somehow obtained.)
- The writers of this specification do not know if