This thread provides a place for discussing extensions to Scratch 2.0. The topic post provides a description of the current state of extensions in Scratch. Credit to nXIII for the original post, John Maloney for sending me the preliminary spec, and blob8108 for making me write this post.

Experimental Extensions
Experimental extensions can be imported into Scratch by shift-clicking the File menu and selecting Import Experimental Extension in the offline editor. The resulting file dialog allows you to select an extension manifest JSON file, which contains the extension name, the port on which the extension runs, and the blocks which the extension defines. It follows this format:
The extension name should be an alphanumeric string in CamelCase, e.g., SensorBoard. The extension port can be any valid port number (above 1024).

Block specs include a block type (“ ” for command blocks, “w” for command blocks that wait until completion to continue, “f” for cap blocks, “r” for reporter blocks, or “b” for boolean reporter blocks), a block spec, and a selector (which should be a lowerCamelCase identifier). Selectors must not start with an underscore, as these are reserved for Scratch (more on that later). They can have additional array elements, which specify the block's default input values. In the blockspecs, you can use %m.menuName for a non-editable menu, or %d.menuName for a menu with an editable number parameter.

Extension files should end in .s2e.


Communication
When an experimental extension is imported into Scratch, it attempts to connect to a server running at the extension's port on the local machine using HTTP.

Scratch uses HTTP connections for extensions which declare “useHTTP”: true in their manifests. Before sending any other requests, Flash sends an HTTP request to http://127.0.0.1:extensionPort/crossdomain.xml and expects a cross-domain policy file in response. For example, an extension could send back the following policy file:

Command blocks
When a command block is executed, Scratch sends a request to http://127.0.0.1:extensionPort/selector and ignores the result. Any block inputs are appended this URL, escape-encoded and preceded by a solidus. For example, running the block [log [Hello, world!]] from the example extension above would send a request to http://127.0.0.1:49001/log/Hello%2C%20world%21.

Reporters
Scratch gets reporter values by sending a request to http://127.0.0.1:extensionPort/poll, and expects a newline-separated list of (selector value) pairs. String values should be URL-encoded, but spaces don't seem to work. Scratch sends a poll request ~30 times per second.

Example poll response:

To send a message to Scratch that there is a problem with your extension (e.g. disconnected hardware), add a line to the poll response that starts with “_problem” , and then a problem to report to Scratch.
Example:

Commands that wait
When a “w” type command block is executed, Scratch adds a unique command_id parameter to the request before any other parameter.
Example:

For however long it takes to complete the command, add a _busy <commandID> line to your poll response (where <commandID> is the command id.

Reset command
When the stop sign in Scratch is pressed, Scratch sends a /reset_all command. When this is invoked, all hardware should be set to their original states.

Caveats
Projects with extensions are not to be uploaded to the Scratch website. The Scratch Team may host a small library of supported extensions, but these would have to fulfil very strict criteria.

@tb Really, you should copy n's entire post and update it.

blob8108 wrote:

@tb Really, you should copy n's entire post and update it.

Sure, tell me now.

technoboy10 wrote:

blob8108 wrote:

@tb Really, you should copy n's entire post and update it.

Sure, tell me now.

Well, if you don't tell us before, how are we supposed to know?

scimonster wrote:

Well, if you don't tell us before, how are we supposed to know?

Time machine.

@blob Updated post.

technoboy10 wrote:

@blob Updated post.

Don't forget to mention how reporters with menus work! It's a rather crucial point, as I'm not sure John mentions it anywhere.

Ooh, nice post. Looking forward to some interesting projects in the future.

Some observations: Is it empty string for command blocks, or space? It's hard to tell in the post. Also, you should link to n's gdocs list of %m.somethings.

Hardmath123 wrote:

Is it empty string for command blocks, or space? It's hard to tell in the post.

Space. That caught me out, too.

Also, you should link to n's gdocs list of %m.somethings.

And if you can't find that, it's on Scratch File Format.

Is there a way to connect to a remote server with extensions?

hm wrote:

Ooh, nice post

I totally didn't just edit n's post…

blob8108 wrote:

technoboy10 wrote:

@blob Updated post.

Don't forget to mention how reporters with menus work! It's a rather crucial point, as I'm not sure John mentions it anywhere.

I don't know how those work. Care to enlighten me?

@tb I sent you an email about that!

jji7skyline wrote:

Is there a way to connect to a remote server with extensions?

No, you can't specify hostname/IP. You could write a tunnelling program that ran on localhost and connected to the remote server, however.

Is there a reason for choosing HTTP?

The snag with HTTP is that it is a polling approach. On one of my older single core boxes Scratch consumes just under 20% CPU continuously when the extension is loaded. It would be much more efficient if an “event” orient approach could be used where scratch can push events/commands to the extension server and the server can push events / reports to Scratch as and when the event occurs. It is more efficient both in cases when events/reports occur infrequently and when events occur at a higher frequency like in gaming. Using a socket or websocket would provide a good basis for this. Using a WebSocket would still mean it is part of the HTTP family of protocols.

@jji7skyline Node-Red makes it simple to communicate with remote servers. I wrote a blog entry that describes how to get Scratch 2 to integrate with Node-Red here: http://davejlocke.wordpress.com/2013/10/14/14/

mqtt wrote:

Is there a reason for choosing HTTP?

The reason for choosing HTTP is that it's really really simple to implement across different platforms and languages.

I think the reason polling is chosen is that most hardware extensions are for things like sensors, where the value is changing continuously, and so the notion of an “event” is meaningless.

I'm not sure if Flash is allowed to listen on a port, which would be a requirement for implementing websockets.

I'm not sure if Flash is allowed to listen on a port, which would be a requirement for implementing websockets.

A socket or a websocket approach only requires that Scratch initiate the connection to the extension server, just like in the early implementation of the scratch 2.0 extension that supported sockets (and http). Once the connection is open they both provide a bi-directional communication pipe. One of the benefits of using WebSockets is, if the extension server is ever allowed to be remote to Scratch then a websocket can communicate through firewalls, proxies..

I think the reason polling is chosen is that most hardware extensions are for things like sensors, where the value is changing continuously, and so the notion of an “event” is meaningless.

There are just as many sensors where the sensor reading / measurement changes infrequently as there are those that change frequently. It is a simpler model to program to if Scratch only receives a measurement when the measurement has changed. An additional benefit is there will be no “overhead” like there is with an HTTP approach and the CPU will remain idle until an event occurs. (20% CPU for the current polling approach when the application is doing nothing is a lot of overhead - albeit on an old single core box).

Happy to contribute ideas on how this might work.

mqtt wrote:

I'm not sure if Flash is allowed to listen on a port, which would be a requirement for implementing websockets.

A socket or a websocket approach only requires that Scratch initiate the connection to the extension server

Whoops, I keep confusing WebSockets and WebHooks. Nevermind…

The websocket protocol is more complicated than plain HTTP, is it not?

It is a simpler model to program to if Scratch only receives a measurement when the measurement has changed.

I'm not sure that's true. As I see it, having Scratch make an HTTP request every time it encounters that stack/reporter block is definitely the simplest model. Can you explain how the sensor event-based model is simpler?

blob8108 wrote:

As I see it, having Scratch make an HTTP request every time it encounters that stack/reporter block is definitely the simplest model. Can you explain how the sensor event-based model is simpler?

That's somewhat impractical because every extension reporter would block its thread until the HTTP request returned. Polling gives you a (slightly old) value instantly, and while this definitely isn't appropriate for all cases it works (and feels more responsive) for a great number of them.

nXIII wrote:

every extension reporter would block its thread until the HTTP request returned.

Yeah, that's true. But there's a special “wait” block that pauses a thread while a stack block is executing – can't we have an equivalent version for reporters?

Otherwise it's impractical to implement eg. a "weather in " block.

blob8108 wrote:

nXIII wrote:

every extension reporter would block its thread until the HTTP request returned.

Yeah, that's true. But there's a special “wait” block that pauses a thread while a stack block is executing – can't we have an equivalent version for reporters?

Otherwise it's impractical to implement eg. a "weather in " block.

Yes. But the current interpreter evaluates reporters synchronously, so it would require some pretty hefty internal changes and might slow things down for everyone.