Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/development/extensions/assorted-apis.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ hide_table_of_contents: true

import {ExtensionCode} from './utils.js';

Now that you are familiar with writing custom extensions, we will share some more APIs. These APIs are available in **both** sandboxed and unsandboxed extensions. They can all be used together.
Now that you are familiar with writing custom extensions, we will share some more APIs. They can all be used together.

## color1, color2, color3

Expand Down
2 changes: 1 addition & 1 deletion docs/development/extensions/async.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@ This also demonstrates error handling. Whenever your promises can reject, fail,

## Next steps

You may have realized that even your blocks that don't return a Promise don't actually run instantly and your extension can't access many APIs. To determine why, we need to [discuss what the "sandbox" really is, and what it means for your extensions](./sandbox.md).
If you've read older guides about custom extensions, you may have seen them talk about a "sandbox". Next, we will [discuss what the sandbox was, and why it no longer matters for your extensions](./sandbox.md).
14 changes: 1 addition & 13 deletions docs/development/extensions/hats.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,6 @@ Event blocks and hat blocks are two types of blocks that allow you to control wh

Event blocks are for running scripts in response to an external event. An example of this is "when flag clicked" - the event is when the user clicks on the flag button. "when this sprite clicked" similarly is run in response to a click event, though Scratch does a bit more work to figure out which sprite the event happened on. Event blocks can be used for any external event that lets you run a callback.

:::warning
Event blocks are only supported in unsandboxed extensions.
:::

Event blocks never get executed; they just mark which scripts to run. For example, consider this block you're familiar with:

![when space key pressed](./assets/when-space-key-pressed.svg)
Expand Down Expand Up @@ -91,10 +87,6 @@ Finally, startHats returns an array of the Thread objects that it started. You c

## Predicate-based hat blocks

:::info
Predicate-based hats are only supported in unsandboxed extensions.
:::

Predicate-based hat blocks let you create something similar to:

![](./assets/forever-if-something-then.svg)
Expand Down Expand Up @@ -125,10 +117,6 @@ This is a subtle but important difference. Consider these two scripts:

While the blocks may look similar, they have a significant difference. The top one will only run *once* when the timer *becomes* 5 while the bottom one will run repeatedly after the timer reaches 5.

:::info
Edge-activated hats can be used in any extension, even sandboxed ones
:::

Let's think about how you would implement this using normal Scratch blocks. You could try something like this:

![](./assets/wait-until-something-true.svg)
Expand All @@ -149,7 +137,7 @@ To demonstrate this, we can write an extension similar to Scratch's "when timer

<ExtensionCode title="timer-reimplementation">{require("!raw-loader!@site/static/example-extensions/timer-reimplementation.js")}</ExtensionCode>

Notice that we don't have to run startHats -- Scratch automatically runs startHats for each edge activated hat at the beginning of a frame. This lets you use edge activated hats in sandboxed extensions. You also should not use `shouldRestartExistingThreads: true` for edge-activated hats.
Notice that we don't have to run startHats -- Scratch automatically runs startHats for each edge activated hat at the beginning of a frame. You also should not use `shouldRestartExistingThreads: true` for edge-activated hats.

To test this use a script like this:

Expand Down
2 changes: 1 addition & 1 deletion docs/development/extensions/hello-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The above is a standard component we will use for showing extension code. Make n

If you're just using simple files to develop extensions, save this code into a file called "hello-world.js". If you're using a local HTTP server, save the code in a file called "hello-world.js" that the server will let you access.

Now, go to the TurboWarp editor, click on the add extension button (a + next to 2 blocks), scroll to the bottom of the Scratch section, and choose the "Custom Extension" option. Either enter the full URL to your local HTTP server or use one of the other tabs to select your file or paste in code. For now, **do not** check the "Run extension without sandbox" box.
Now, go to the TurboWarp editor, click on the add extension button (a + next to 2 blocks), scroll to the bottom of the Scratch section, and choose the "Custom Extension" option. Either enter the full URL to your local HTTP server or use one of the other tabs to select your file or paste in code. The menu will warn you to only load extensions from authors you trust. You wrote this one yourself, so it's fine.

After a second, an extension named "It works!" should appear in the sidebar. If it doesn't appear, open up your developer tools and look for any warnings in the console. Some of the most common errors are:

Expand Down
7 changes: 3 additions & 4 deletions docs/development/extensions/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,11 @@ When people refer to "extensions", there are a few things they could be referrin
| |Can access Scratch internals|Can be loaded by URL|
|:-:|:-:|:-:|
|Core extensions (pen, translate, etc.)|✅|❌|
|Sandboxed custom extensions|❌|✅|
|Unsandboxed custom extensions|✅|✅|
|Custom extensions|✅|✅|

The documentation in these segments refers only to custom extensions. While core extensions share many fundamentals, the process of developing them is significantly different. See [getting started](../getting-started) as a starting point for building core extensions.

We will discuss the difference between sandboxed and unsandboxed extensions at [a later time](./unsandboxed).
In TurboWarp, custom extensions run directly on the page, with the same access to the page as TurboWarp itself. We will discuss what this means for your extensions at [a later time](./unsandboxed).

## Compatibility

Expand Down Expand Up @@ -65,7 +64,7 @@ This starts a local HTTP server on http://localhost:8080/ in whatever folder you

We will [eventually](./better-development-server) introduce the official development server, but we recommend starting with the most primitive setup possible for now.

For now, you should use a port **other than 8000**. We will talk more about this later, but currently we want the extensions you write to run in the sandbox. Extensions that run outside of the sandbox have some extra responsibilities that we will discuss [later](./unsandboxed).
Any port will work. We use 8080 in this tutorial because the [official development server](./better-development-server) we introduce later uses port 8000.

To test that your server works, create a file called `hello-world.js` and put any text in it. Make sure you're able to read the contents of the file in your browser by visiting a link like [http://localhost:8080/hello-world.js](http://localhost:8080/hello-world.js).

Expand Down
45 changes: 11 additions & 34 deletions docs/development/extensions/sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,54 +2,31 @@
hide_table_of_contents: true
---

# What is the sandbox anyways?
# What happened to the sandbox?

There are two types of custom extensions:
Older versions of TurboWarp had two types of custom extensions:

- Sandboxed extensions
- Unsandboxed extensions
- Sandboxed extensions, which ran in an isolated `<iframe>` that couldn't directly access the editor or the VM
- Unsandboxed extensions, which ran in the same context as Scratch itself as `<script>` tags

This difference has a significant impact on your extensions. So far we've primarily focused on creating sandboxed extensions, but what does that mean?
Sandboxed extensions couldn't access Scratch internals, couldn't access any part of the project that wasn't passed in as an argument, and couldn't directly interact with sprites. Every time one of their blocks ran, the script would also pause for at least 1 frame, no matter how simple the block was. Very few useful extensions could work within those limits, and the sandbox kept causing problems, so it has been removed.

## The sandbox
**All custom extensions in TurboWarp now run unsandboxed.** Every extension, whether it is loaded from a URL, a file, or pasted code, runs directly on the page with full access to it. That includes the extensions you've written so far in this tutorial.

The sandbox is actually an `<iframe>`. Sandboxed extensions are run in a sandboxed cross-origin iframe that can't directly access the main page with the editor and the VM; it's stuck in its own isolated world.

For this reason, sandboxed extensions:

- Can not access Scratch internals
- Can not access any part of the project that was not passed in as an argument, including variables
- Can not directly interact with sprites at all

They can, however:

- Access most public APIs, as long as [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) allows it
- Access some JavaScript Web APIs, such as the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API)

It is worthwhile to note that in other Scratch mods, the extension sandbox may be a `Worker` instead of an `<iframe>`. We use an `<iframe>` instead as it is more secure (cross origin vs. same origin) and allows access to more Web APIs.

And perhaps the biggest limitation of all is that *every* time a block runs, the script will pause for at least 1 frame, regardless of how simple the script is. It doesn't matter whether "run without screen refresh" or turbo mode is enabled. It will always wait.

This is a very significant limitation and it makes custom extensions almost useless, which is why we introduced support for...

## Unsandboxed extensions

As the name implies, unsandboxed extensions do not run in an iframe. They run in the same context as Scratch itself as `<script>` tags.

This means that unsandboxed extensions:
This means that extensions:

- CAN access Scratch internals
- CAN access parts of the project that were not passed in as an argument, such as variables
- CAN directly interact with any sprite
- Run their blocks instantly, without a forced 1 frame delay

And perhaps most importantly, running a block from an unsandboxed extension is actually instantaneous -- no forced 1 frame delay.
Some older guides and other Scratch mods still talk about sandboxed extensions, which in other mods may run in a `Worker` instead of an `<iframe>`. In TurboWarp, you can ignore that distinction.

## Exercises

1. Create a sandboxed extension (same as we've been building so far) with a COMMAND block that does nothing. Create a new empty project and create a repeat (10) loop that runs this block 4 times. Observe that, even though the blocks don't do anything, it takes more than a second for the loop to complete.
1. In the repeat loop, replace the block from the extension with a "set my variable to 0" block instead. Observe that the loop completes instantly. This is how blocks from unsandboxed extensions will behave.
1. Create an extension with a COMMAND block that does nothing. Create a new empty project and create a repeat (10) loop that runs this block 4 times. Observe that the loop completes instantly, just like it would with a built-in block such as "set my variable to 0".
1. Inside a custom extension, use console.log to output the value of `window.origin`. Compare this to running `window.origin` in your browser's developer console on turbowarp.org.

## Next steps

Unsandboxed extensions are clearly better, so [let's write one](./unsandboxed).
Full access to the page brings new powers and new responsibilities, so [let's learn about them](./unsandboxed).
16 changes: 10 additions & 6 deletions docs/development/extensions/share.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,21 @@ hide_table_of_contents: true

If you want to share your extension with the broader world, you'll have to find a place to put it.

Note that, if you only care about using your own extensions in your own projects and will use the packager to share your project with others, you don't need to submit your extension anywhere as the packager always runs extensions without the sandbox.
Note that, if you only care about using your own extensions in your own projects and will use the packager to share your project with others, you don't need to submit your extension anywhere.

## Sandboxed extensions
## The extension gallery

Sandboxed extensions can be hosted anywhere that offers static file hosting and HTTPS.
The best way to share your extension is to submit it to extensions.turbowarp.org: https://github.com/TurboWarp/extensions/blob/master/CONTRIBUTING.md

A common choice is [GitHub Pages](https://pages.github.com/). Note that GitHub's "raw" links (raw.githubusercontent.com) do not work; you must use GitHub Pages instead.
Extensions on extensions.turbowarp.org are loaded automatically, without showing users a permission prompt.

## Hosting it yourself

## Unsandboxed extensions
Extensions can also be hosted anywhere that offers static file hosting and HTTPS.

A common choice is [GitHub Pages](https://pages.github.com/). Note that GitHub's "raw" links (raw.githubusercontent.com) do not work; you must use GitHub Pages instead.

The best way to share your unsandboxed extension is to submit it to extensions.turbowarp.org: https://github.com/TurboWarp/extensions/blob/master/CONTRIBUTING.md
Users will need to trust you to use extensions hosted elsewhere: projects that use them will show a [permission prompt](./unsandboxed#loading-extensions-and-permission-prompts) before loading.

## Exercises

Expand Down
Loading
Loading