Scratch Modifications

https://docs.turbowarp.org
Admin
This project provides documentation and resources for various modifications and advanced features...
Tokens:32,376
Snippets:328
Trust Score:9.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start the Development Server

Source: https://docs.turbowarp.org/development/extensions/better-development-server

Run this command to start the local development server after cloning the repository and installing dependencies.

```bash
npm run dev  
```

--------------------------------

### Broadcasting and Starting Threads

Source: https://docs.turbowarp.org/development/extensions/hats

This example shows how to use `util.startHats` to trigger custom events and start new threads. The `broadcast` method returns a string indicating how many new threads were started.

```javascript
(function(Scratch) {  
  'use strict';  
  class Broadcast5 {  
    getInfo() {  
      return {  
        id: 'broadcast5example',  
        name: 'Broadcast Example 5',  
        blocks: [  
          {  
            opcode: 'whenReceived',  
            blockType: Scratch.BlockType.HAT,  
            text: 'when I receive [EVENT_OPTION]',  
            isEdgeActivated: false,  
            arguments: {  
              EVENT_OPTION: {  
                type: Scratch.ArgumentType.STRING,  
                menu: 'EVENT_FIELD'  
              }  
            }  
          },  
          {  
            opcode: 'broadcast',  
            blockType: Scratch.BlockType.REPORTER,  
            text: 'broadcast [EVENT]',  
            arguments: {  
              EVENT: {  
                type: Scratch.ArgumentType.STRING,  
                menu: 'EVENT_FIELD'  
              }  
            }  
          }  
        ],  
        menus: {  
          EVENT_FIELD: {  
            acceptReporters: false,  
            items: [  
              'Event 1',  
              'Event 2',  
              'Event 3'  
            ]  
          }  
        }  
      };  
    }  
    broadcast({EVENT, TARGET}, util) {  
      const threads = util.startHats('broadcast5example_whenReceived', {  
        EVENT_OPTION: EVENT  
      });  
      return `Started ${threads.length} new threads!`;  
    }  
  }  
  Scratch.extensions.register(new Broadcast5());  
}(Scratch));  
```

--------------------------------

### Clone and Install TurboWarp VM

Source: https://docs.turbowarp.org/development/getting-started

Clone the scratch-vm repository and install its dependencies. Then, link the package locally for use in other projects.

```bash
cd scratch-gui/..
git clone https://github.com/TurboWarp/scratch-vm

# install dependencies in the child package
cd scratch-vm
npm ci

# tell npm that this is your local copy of the package
npm link
```

--------------------------------

### Clone and Build TurboWarp GUI

Source: https://docs.turbowarp.org/development/getting-started

Clone the scratch-gui repository, install dependencies using npm ci, and start the development playground.

```bash
git clone https://github.com/TurboWarp/scratch-gui
cd scratch-gui
npm ci
npm start
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://docs.turbowarp.org/development/extensions/better-development-server

Use these commands to download the TurboWarp extensions repository and install the necessary Node.js dependencies.

```bash
git clone https://github.com/TurboWarp/extensions.git  
cd extensions  
npm ci  
```

--------------------------------

### Start Local HTTP Server with Python

Source: https://docs.turbowarp.org/development/custom-extensions

This command starts a local HTTP server using Python. It's recommended for developing extensions as it allows TurboWarp to fetch your extension from your computer, speeding up the development process.

```bash
cd path/to/where/you/will/store/your/extensions
python3 -m http.server 8080

```

--------------------------------

### Example of a simplified script using a custom reporter

Source: https://docs.turbowarp.org/return

This script shows how a custom reporter simplifies the same task as the previous example, making the code cleaner and more readable. It utilizes the 'return' block for a custom reporter.

```Scratch Blocks
repeat (10) {
  custom reporter "say hello and wait"
}
```

--------------------------------

### Setting Up Cloud Connection with Contact Information

Source: https://docs.turbowarp.org/cloud-variables

This example demonstrates how to initialize a cloud connection in a Node.js environment, emphasizing the mandatory 'contactInformation' field for constructing a valid User-Agent.

```javascript
const CloudConnection = require('...');  
  
const connection = new CloudConnection({
    username: '...',  
    projectId: '...',  
    // UPDATE THIS!  
    contactInformation: 'contact@example.com'
});  
  
connection.on('connected', () => { /* ... */ });  
connection.on('set', (name, value) => { /* ... */ });  

```

--------------------------------

### Turbo Mode Extension Example

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

An example of an unsandboxed extension that toggles turbo mode in Scratch. It requires the extension to run unsandboxed and uses the Scratch VM to set the turbo mode state.

```javascript
(function(Scratch) {
  'use strict';
  
  if (!Scratch.extensions.unsandboxed) {
    throw new Error('This Turbo Mode example must run unsandboxed');
  }
  const vm = Scratch.vm;
  
  class TurboMode {
    getInfo() {
      return {
        id: 'turbomodeunsandboxed',
        name: 'Turbo Mode',
        blocks: [
          {
            opcode: 'set',
            blockType: Scratch.BlockType.COMMAND,
            text: 'set turbo mode to [ENABLED]',
            arguments: {
              ENABLED: {
                type: Scratch.ArgumentType.STRING,
                menu: 'ENABLED_MENU'
              }
            }
          }
        ],
        menus: {
          ENABLED_MENU: {
            acceptReporters: true,
            items: ['on', 'off']
          }
        }
      };
    }
    set(args) {
      vm.setTurboMode(args.ENABLED === 'on');
    }
  }
  Scratch.extensions.register(new TurboMode());
})(Scratch);
```

--------------------------------

### Define Extension with Custom Icons

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

This example shows how to define an extension with custom icons for the menu and blocks. It demonstrates overriding the default block icon with a custom one.

```javascript
const colorIcon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABeCAYAAACq0qNuAAAAAXNSR0IArs4c6QAABTFJREFUeF7t3b2KFEEUBeAecBVkk8nERBSMBEGMTDcxN/IhfATDRdinMDSaV5gn8REEo40MlBqoobrmVtWtqvtzWnYzd3tmer46ffrOr7tlOz9/mbu6Y27nuhniTnKBe+Gg7ivKzmhhlxbH/X577UAT+smnD81EP3r9vLnN/d2huc2yLOYO1jdYBOdA54Ic+PwyjYUw87C6IRJ8BDuFHIFPL19ZBHUX9RtYluUCfRY84s3Cx+spLICqjeaVq4FLw3ssgAa8OrgWvOUCSMOv0KUqpTSWSFVN6fqJChLzEruivMu10QOWNny4DS18CXjTlEtONZwBv1I/U3ZTF/ZIuRe8dPpn4N2Srn1yrR0JUtUzCu+ObtXx1CJI4I/AQ6B7wkvUTi88DLo3/Cz+MLzFuNiaOizGydY+ZLXD9mRvmE4wCOgIiS+MmixT1kaI6EjwRO00XZsboKKjwffiP8C3Srzj7z1934I/TzEove75yJWzBlx8FjwiOmLVECfbom8N/pz26xfPlj/vX3IW3HQbhHGS8ciWNC7Br9DTK0daAET4xx/fnbh+33xN2S6cu+HDtaHgI8FH8Kg9Al9Me35YeS8AAnwOnhrV8KnEs+HjjXgtgCf8/d1htz/eVt+Y1QPfje6J7wVfS3neCiX8PPHD8B4LYA3fA97qehI+jI+zPxb1YwU/Al7o+rO3GrzF9GMBP4uejZYk/HTNlI4SrfRrwkuA1+omTfwJXqJmrBZAA14SvFY3pvDS9SMJrwVOpP5kHuHVakYz/VLw2ujUUwhu8BLj5yy8BXip51fwmv3eGk9HTsCj8JbgpZ6HgR/p/154L3Cq56Hge+unB94bPZ/nIeG5C8CBRwAvJd58omn1ffr3WvfX4JHAqRNsSDw0fC39FDwi+KbhqQXI4ZHR81l+M4mn6ifCo4P/F4lPF+Dq+5ee04X7tumLIptMfBC8un663Pz4dsI8/vrpjsrZgU3DB/D4E+Hjv9EXYJPwKXgJHj39m4On0ANynvj0cEdM/2bgS+C1xOddi7QAOXzYV/VXnzgnn9XEknR56bK1xCOmP4HfwT1X00p5CsqFRzn5QsL3gPdUDXW0eNUPHPwIeuvk2qo2D/wifNhZy1ehRsFnE+/R//lb+Vxec50Fl4S36v8SvNlkI4U+WzXW3Z/WTLhts/fVSIJrJF67fprw0j2vAa4NL10/1Fu1Vd+0qomuUTVa9ZOnPa8asZ7XBrdKvFT9sOFH68YK3AN+tH7UPxFijW5VNbP1w4U/1w039R7gnonvqZ+eD5+x4T3BUeBb9dML38RHQPesGqp+wu/S539S9P3xNnzSezVBdn2yGwUcLfFU/Yx8sjtez+odZmjoiImPcIe3n89rQaWdmuPzo+iEv3/zqnR0uf6+94UQq51N4E+f/s5rhg2Pio8In6a99n+PtL4oaHWiRUs+GjwXnZP4B/iOfpKGh8VHSnwPOjfxF1MOSuWgwPei98LDJR8BfgR9Ch5h0vGGz9C7PDlTDTnbx1961o4n/Ax61wpl+quvhPLC94KfRZ+BX/W9V+14wEugz8K741vDS6FLwLviW8JLokvBX8z5VtVjAS8NHrFGpprag2jTk642vBa6dOLJ5GumXwueABe3kk58ejRcfAup9NgpDW8BrlU1VA2pLYAUvCW4JfzF5CP1qHcWvgAuXitUGjWrhpX+mUUYga9gm4BbJ776fA+1QpzzAQe+Ae3mYJ340iha/Trw2vw6+Df3++2+AwSc1iJA3VeonWmkl7sgm7hP/wDwgcxktVR5CQAAAABJRU5ErkJggg==
```

```javascript
class IconsExample {
  getInfo() {
    return {
      id: 'iconsexample',
      name: 'Icons Example',
      menuIconURI: blocksIcon, 
      blockIconURI: dangoIcon, 
      blocks: [
        {
          opcode: 'defaultIcon',
          blockType: Scratch.BlockType.REPORTER,
          text: 'reporter with default icon [INPUT]',
          arguments: {
            INPUT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '0'
            }
          }
        },
        {
          opcode: 'overriddenIcon',
          blockType: Scratch.BlockType.COMMAND,
          text: 'command with overridden icon [INPUT]',
          blockIconURI: colorIcon,
          arguments: {
            INPUT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '0'
            }
          }
        }
      ]
    };
  }

  defaultIcon() {
    return 0;
  }
  overriddenIcon() {

  }
}

Scratch.extensions.register(new IconsExample());
```

--------------------------------

### Old Plugin Mechanism Example

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

An example of the older 'plugin' mechanism for extensions, which is now deprecated.

```javascript
class MyExtension {
  getInfo () {
    return { /* ... */ };
  }
}
(function() {
  var extensionInstance = new MyExtension(window.vm.extensionManager.runtime)
  var serviceName = window.vm.extensionManager._registerInternalExtension(extensionInstance)
  window.vm.extensionManager._loadedExtensions.set(extensionInstance.getInfo().id, serviceName)
})();
```

--------------------------------

### Enable Rich Presence for Chat App Snap (Linux Flatpak)

Source: https://docs.turbowarp.org/desktop/rich-presence

Execute this command in a terminal to allow TurboWarp Desktop (Flatpak) to interact with a Snap installation of Chat App for Rich Presence. A restart of TurboWarp Desktop is required.

```bash
# For Chat App Snap
flatpak override org.turbowarp.TurboWarp --user --filesystem=xdg-run/snap.$(printf "\x64\x69\x73\x63\x6f\x72\x64")":create
```

--------------------------------

### Unsandboxed Extension Block Utility Example

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

This example demonstrates how to use `util.target` to get the current sprite's name and check if a variable of a specific type exists.

```javascript
(function(Scratch) {
  'use strict';

  if (!Scratch.extensions.unsandboxed) {
    throw new Error('This Block Utility example must run unsandboxed');
  }

  class BlockUtilityExamples {
    getInfo() {
      return {
        id: 'blockutilityexamples',
        name: 'BlockUtility Examples',
        blocks: [
          {
            opcode: 'getSpriteName',
            text: 'sprite name',
            blockType: Scratch.BlockType.REPORTER,
          },
          {
            opcode: 'doesVariableExist',
            text: 'is there a [TYPE] named [NAME]?',
            blockType: Scratch.BlockType.BOOLEAN,
            arguments: {
              NAME: {
                type: Scratch.ArgumentType.STRING,
                defaultValue: 'my variable'
              },
              TYPE: {
                type: Scratch.ArgumentType.STRING,
                menu: 'TYPE_MENU',
                defaultValue: 'list'
              }
            }
          }
        ],
        menus: {
          TYPE_MENU: {
            acceptReporters: true,
            items: [
              // Value here corresponds to the internal types of the variables
              // in scratch-vm. And yes, broadcasts are actually variables.
              // https://github.com/TurboWarp/scratch-vm/blob/20c60193c1c567a65cca87b16d22c51963565a43/src/engine/variable.js#L43-L67
              {
                text: 'variable',
                value: ''
              },
              'list',
              {
                text: 'broadcast',
                value: 'broadcast_msg'
              }
            ]
          }
        }
      };
    }
    getSpriteName(args, util) {
      return util.target.getName();
    }
    doesVariableExist(args, util) {
      const variable = util.target.lookupVariableByNameAndType(args.NAME.toString(), args.TYPE);
      // Remember: Boolean blocks need to explicitly return a boolean on their own
      return !!variable;
    }
  }
  Scratch.extensions.register(new BlockUtilityExamples());
})(Scratch);
```

--------------------------------

### Accessing the Scratch VM Instance

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

This snippet shows how to get a reference to the Scratch VM object, which is necessary for interacting with Scratch internals in an unsandboxed extension.

```javascript
const vm = Scratch.vm;
```

--------------------------------

### Embed with Multiple Addons Enabled

Source: https://docs.turbowarp.org/embedding

Enable specific addons by listing their IDs in the 'addons' parameter, separated by commas. This example enables pause, gamepad, and mute-project addons.

```html
https://turbowarp.org/15832807/embed?addons=pause,gamepad,mute-project
```

--------------------------------

### Embed with Autoplay Enabled

Source: https://docs.turbowarp.org/embedding

Enable the 'autoplay' parameter to automatically start the project when it loads. Note that sound may require user interaction due to browser restrictions.

```html
https://turbowarp.org/15832807/embed?autoplay
```

--------------------------------

### Define VM, Runtime, and Cast APIs

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

Common practice to define frequently used APIs like `vm`, `runtime`, and `Cast` at the start of an extension to save time.

```javascript
const vm = Scratch.vm;
const runtime = vm.runtime;
const Cast = Scratch.Cast; // Discussed later.
```

--------------------------------

### Registering an Inline Images Extension Example

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

This snippet shows how to register a custom extension that utilizes inline images. Ensure all necessary methods like reporter() and command() are defined.

```javascript
}
      ]
    };
  }

  reporter() {
    return 'Example block';
  }
  command() {

  }
}

Scratch.extensions.register(new InlineImagesExample());
```

--------------------------------

### Hide Block from Palette (Initially Visible)

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

This example demonstrates a block that is initially visible in the extension flyout. It serves as a baseline before applying the hideFromPalette property.

```javascript
class HideFromPaletteExample {
  getInfo() {
    return {
      id: 'hidefrompaletteexample',
      name: 'hideFromPalette Example',
      blocks: [
        {
          opcode: 'hidden',
          blockType: Scratch.BlockType.REPORTER,
          text: 'example block (visible)'
        },
      ]
    };
  }

  hidden() {
    return 'The block is still visible';
  }
}

Scratch.extensions.register(new HideFromPaletteExample());
```

--------------------------------

### Scratch Interpreter AST Example

Source: https://docs.turbowarp.org/how

This JSON represents the abstract syntax tree (AST) that Scratch's interpreter walks at runtime. It details the structure of a simple script including event triggers, loops, and motion blocks.

```json
{
  "va[U{Cbi_NZpSOSx_kVA": {
    "opcode": "event_whenflagclicked",
    "inputs": {},
    "fields": {},
    "next": "tzXnZ{8G!xK|t^WAWF{m",
    "topLevel": true
  },
  "tzXnZ{8G!xK|t^WAWF{m": {
    "opcode": "control_forever",
    "inputs": {
      "SUBSTACK": {
        "name": "SUBSTACK",
        "block": "$xf$bq|xl(}RhT-K,taS"
      }
    },
    "fields": {},
    "next": null,
    "topLevel": false
  },
  "$xf$bq|xl(}RhT-K,taS": {
    "opcode": "motion_movesteps",
    "inputs": {
      "STEPS": {
        "name": "STEPS",
        "block": "cw__.I:g}Y~`:5KmO00q"
      }
    },
    "fields": {},
    "next": null,
    "topLevel": false
  },
  "cw__.I:g}Y~`:5KmO00q": {
    "opcode": "data_variable",
    "inputs": {},
    "fields": {
      "VARIABLE": {
        "name": "VARIABLE",
        "id": "`jEk@4|i[#Fk?(8x)AV.-my variable"
      }
    },
    "next": null,
    "topLevel": false
  }
}

```

--------------------------------

### Async Extension with Wait and Fetch Blocks

Source: https://docs.turbowarp.org/development/extensions/async

This example demonstrates how to create an extension with blocks that handle asynchronous operations. The 'wait' block uses a Promise with setTimeout for timed delays, and the 'fetch' block uses the native fetch API to retrieve data from a URL.

```javascript
class AsyncExtension {
  getInfo() {
    return {
      id: 'asyncexample',
      name: 'Async Blocks',
      blocks: [
        {
          opcode: 'wait',
          text: 'wait [TIME] seconds',
          blockType: Scratch.BlockType.COMMAND,
          arguments: {
            TIME: {
              type: Scratch.ArgumentType.NUMBER,
              defaultValue: 1
            }
          }
        },
        {
          opcode: 'fetch',
          text: 'fetch [URL]',
          blockType: Scratch.BlockType.REPORTER,
          arguments: {
            URL: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: 'https://extensions.turbowarp.org/hello.txt'
            }
          }
        }
      ]
    };
  }

  wait (args) {
    return new Promise((resolve, reject) => {
      const timeInMilliseconds = args.TIME * 1000;
      setTimeout(() => {
        resolve();
      }, timeInMilliseconds);
    });
  }

  fetch (args) {
    return fetch(args.URL)
      .then((response) => {
        return response.text();
      })
      .catch((error) => {
        console.error(error);
        return 'Uh oh! Something went wrong.';
      });
  }
}
Scratch.extensions.register(new AsyncExtension());

```

--------------------------------

### Example of a complex script without custom reporters

Source: https://docs.turbowarp.org/return

This script demonstrates a repetitive task that becomes cumbersome without custom reporters. It is less readable and harder to maintain.

```Scratch Blocks
repeat (10) {
  say "hello"
  wait (1) secs
}
```

--------------------------------

### Recursive custom reporter for repeating a task

Source: https://docs.turbowarp.org/return

This example demonstrates recursion by rewriting the repeat block to use no variables. It breaks down a problem into smaller, similar subproblems until a base case is reached.

```Scratch Blocks
define repeat (times) {
  if <(times) = [0]> then {
    stop this script
  }
  say "hello"
  wait (1) secs
  repeat ((times) - (1))
}
```

--------------------------------

### Enable Rich Presence for Chat App Native (Linux Flatpak)

Source: https://docs.turbowarp.org/desktop/rich-presence

Run this command in a terminal to grant TurboWarp Desktop (Flatpak) necessary permissions to communicate with a native installation of Chat App for Rich Presence functionality. Restart TurboWarp Desktop after execution.

```bash
# For Chat App Native
flatpak override org.turbowarp.TurboWarp --user --filesystem=xdg-run/$(printf "\x64\x69\x73\x63\x6f\x72\x64")-ipc-{0..9}
```

--------------------------------

### Short-circuiting example in TurboWarp compiler

Source: https://docs.turbowarp.org/return

This script illustrates the 'short circuiting' behavior in the TurboWarp compiler. It shows how the compiler can skip evaluating parts of a boolean expression if the result is already determined, which can lead to different behavior than the interpreter if blocks have side effects.

```Scratch Blocks
< (1) = (2) and (move (10) steps)>
```

--------------------------------

### Setting Custom Headers for WebSocket Connection

Source: https://docs.turbowarp.org/cloud-variables

This Node.js example shows how to set a custom 'user-agent' header when establishing a WebSocket connection to the TurboWarp cloud variable server, using the 'ws' library.

```javascript
const WebSocket = require('ws');
const ws = new WebSocket("wss://clouddata.turbowarp.org", {
  headers: {
    "user-agent": userAgentGoesHere
  }
});  

```

--------------------------------

### Hide Block from Palette (Initially Hidden)

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

This example shows how to use the hideFromPalette: true property to hide a block from the extension flyout. Blocks hidden this way will not appear in the toolbox but will continue to function if already present in a project.

```javascript
class HideFromPaletteExample {
  getInfo() {
    return {
      id: 'hidefrompaletteexample',
      name: 'hideFromPalette Example',
      blocks: [
        {
          opcode: 'hidden',
          blockType: Scratch.BlockType.REPORTER,
          text: 'example block (hidden)',
          hideFromPalette: true
        },
      ]
    };
  }

  hidden() {
    return 'The block is hidden from the palette but still works';
  }
}

Scratch.extensions.register(new HideFromPaletteExample());
```

--------------------------------

### Enable Debug Logging in TurboWarp JavaScript

Source: https://docs.turbowarp.org/javascript

Run this command in the JavaScript console before starting a project to log compiled JavaScript to the console. This is useful for debugging but requires understanding of JavaScript consoles.

```javascript
vm.enableDebug();  

```

--------------------------------

### Console Output for Edge-Activated Hat Example

Source: https://docs.turbowarp.org/development/extensions/hats

This log output shows the behavior of the edge-activated 'when timer > X' block. It logs the current timer value and a boolean indicating if the condition is met. Observe how the 'true' values appear only after the timer crosses the threshold, and then stop until the condition potentially becomes false and true again.

```log
2.719 false
2.753 false
2.785 false
2.818 false
2.851 false
2.885 false
2.918 false
2.951 false
2.985 false
3.017 true
4.113 true
4.148 true
4.181 true
4.214 true
4.248 true
4.281 true
4.314 true
4.347 true
4.381 true
...
```

--------------------------------

### Restarting Threads on Key Press

Source: https://docs.turbowarp.org/development/extensions/hats

This example demonstrates how to set `shouldRestartExistingThreads: true` for a 'when key pressed' block. This ensures that if the key is pressed again while the script is running, the existing thread is restarted, resetting any timers like 'wait' blocks.

```javascript
(function(Scratch) {  
  'use strict';  
  
  if (!Scratch.extensions.unsandboxed) {  
    throw new Error('This example must run unsandboxed');  
  }  
  
  class WhenKeyPressed {  
    getInfo() {  
      return {  
        id: 'restartexampleunsandboxed',  
        name: 'Restart Threads Example',  
        blocks: [  
          {  
            blockType: Scratch.BlockType.EVENT,  
            opcode: 'whenPressed',  
            text: 'when [KEY] key pressed',  
            isEdgeActivated: false,  
            shouldRestartExistingThreads: true,  
            arguments: {  
              KEY: {  
                type: Scratch.ArgumentType.STRING,  
                menu: 'key'  
              }  
            }  
          }  
        ],  
        menus: {  
          key: {  
            acceptReporters: false,  
            items: [  
              {  
                text: 'space',  
                value: ' '  
              },  
              'a',  
              'b',  
              'c',  
              // ...  
            ]  
          }  
        }  
      };  
    }  
  }  
  
  document.addEventListener('keydown', (e) => {  
    Scratch.vm.runtime.startHats('restartexampleunsandboxed_whenPressed', {  
      KEY: e.key  
    });  
  });  
  
  Scratch.extensions.register(new WhenKeyPressed());  
})(Scratch);
```

--------------------------------

### TurboWarp Runtime List Get and Replace Functions

Source: https://docs.turbowarp.org/how

These functions provide the core list manipulation capabilities within the TurboWarp runtime. `listGet` retrieves an item at a specified index, while `listReplace` modifies an item, ensuring compatibility with Scratch's list behaviors and performance optimizations.

```javascript
const listGet = (list, idx) => {
  const index = listIndex(idx, list.length);
  if (index === -1) {
    return '';
  }
  return list[index];
};

const listReplace = (list, idx, value) => {
  const index = listIndex(idx, list.value.length);
  if (index === -1) {
    return;
  }
  list.value[index] = value;
  list._monitorUpToDate = false;
};
```

--------------------------------

### Custom 'When Key Pressed' Event Block Targeting the Stage

Source: https://docs.turbowarp.org/development/extensions/hats

This snippet extends the previous example to ensure the custom 'when key pressed' event block only triggers when the event originates from the stage. It uses the third argument of startHats to specify the target.

```javascript
(function(Scratch) {
  'use strict';
  
  if (!Scratch.extensions.unsandboxed) {
    throw new Error('This example must run unsandboxed');
  }
  
  class WhenKeyPressedInStage {
    getInfo() {
      return {
        id: 'eventexample3unsandboxed',
        name: 'Event Block Example 3',
        blocks: [
          {
            blockType: Scratch.BlockType.EVENT,
            opcode: 'whenPressed',
            text: 'when [KEY] key pressed',
            isEdgeActivated: false,
            arguments: {
              KEY: {
                type: Scratch.ArgumentType.STRING,
                menu: 'key'
              }
            }
          }
        ],
        menus: {
          key: {
            acceptReporters: false,
            items: [
              {
                text: 'space',
                value: ' '
              },
              'a',
              'b',
              'c',
              // ...
            ]
          }
        }
      };
    }
  }
  
  document.addEventListener('keydown', (e) => {
    Scratch.vm.runtime.startHats('eventexample3unsandboxed_whenPressed', {
      KEY: e.key
    }, Scratch.vm.runtime.getTargetForStage());
  });
  
  Scratch.extensions.register(new WhenKeyPressedInStage());
})(Scratch);

```

--------------------------------

### Link Local VM to Scratch GUI

Source: https://docs.turbowarp.org/development/getting-started

After setting up your local scratch-vm, link it to the scratch-gui project to test your modifications within the GUI.

```bash
# tell scratch-gui to use your local copy of the package
cd ../scratch-gui
npm link scratch-vm
```

--------------------------------

### Build TurboWarp GUI with Production Mode (Windows Command Prompt)

Source: https://docs.turbowarp.org/development/getting-started

Build the TurboWarp GUI with production mode enabled on Windows using the Command Prompt.

```bash
set NODE_ENV=production
npm run build
```

--------------------------------

### Enforce Unsandboxed Execution

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

This snippet should be added at the start of an extension if it absolutely requires unsandboxed execution.

```javascript
if (!Scratch.extensions.unsandboxed) {
  throw new Error('Extension Name must run unsandboxed');
}
```

--------------------------------

### Get Redux Store State

Source: https://docs.turbowarp.org/development/globals

Access the internal Redux store state. This is useful for inspecting the application's current state.

```javascript
ReduxStore.getState()
```

--------------------------------

### Build VM Packages

Source: https://docs.turbowarp.org/development/getting-started

For certain packages within scratch-vm, such as storage or svg-renderer, a build step is necessary for your changes to take effect.

```bash
# for some packages (eg. storage, svg-renderer), you may need to build for your changes to apply
npm run build
```

--------------------------------

### Build TurboWarp GUI with Production Mode (Linux/macOS)

Source: https://docs.turbowarp.org/development/getting-started

Build the TurboWarp GUI with production mode enabled on Linux or macOS systems.

```bash
NODE_ENV=production npm run build
```

--------------------------------

### Build TurboWarp GUI for Production

Source: https://docs.turbowarp.org/development/getting-started

Build the TurboWarp GUI for production use, which optimizes for faster execution and reduced file size.

```bash
npm run build
```

--------------------------------

### Add Documentation Link to Extension

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

Use the docsURI property to provide a URL that opens a documentation page for your extension. This adds a button to the block list.

```javascript
class HelloDocs {
  getInfo() {
    return {
      id: 'hellodocs',
      name: 'Hello Docs!',
      docsURI: 'https://docs.turbowarp.org/development/extensions/docsURI-demo',
      blocks: [
        {
          opcode: 'hello',
          blockType: Scratch.BlockType.REPORTER,
          text: 'Hello!'
        }
      ]
    };
  }

  hello() {
    return Math.random();
  }
}

Scratch.extensions.register(new HelloDocs());

```

--------------------------------

### Opening New Windows with Scratch.openWindow

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

Use Scratch.openWindow to open new tabs or windows. If Scratch.openWindow is not suitable, verify with Scratch.canOpenWindow before using window.open.

```javascript
// Do not do this:  
const win = window.open(url);  
// Do this instead:  
const win = await Scratch.openWindow(url);  
  
// Do not do this:  
const win = window.open(url, '_blank', 'width=400,height=400')  
// Do this instead:  
const win = await Scratch.openWindow(url, 'width=400,height=400');  
```

--------------------------------

### Build TurboWarp GUI with Production Mode (Windows PowerShell)

Source: https://docs.turbowarp.org/development/getting-started

Build the TurboWarp GUI with production mode enabled on Windows using PowerShell.

```powershell
$env:NODE_ENV="production"
npm run build
```

--------------------------------

### Link Local Packages for Development

Source: https://docs.turbowarp.org/development/getting-started

Clone the package you want to develop in the same folder as scratch-gui to enable linking local package versions.

```bash
# clone the package you want to develop in the same folder as scratch-gui  
```

--------------------------------

### Block Implementation

Source: https://docs.turbowarp.org/development/extensions/hello-world

The hello() function is the implementation for the block with the opcode 'hello'. REPORTER blocks are expected to return a string, number, or boolean.

```javascript
hello() {
    return 'Hello, world!';
  }
```

--------------------------------

### Download Scratch Project Data

Source: https://docs.turbowarp.org/unshared-projects

This JavaScript code demonstrates how to fetch project metadata and then download the project data. It includes error handling for non-existent projects and network issues. Use `trampoline.turbowarp.org` for browser environments and `api.scratch.mit.edu` for server-side environments.

```javascript
const getProjectMetadata = async (projectId) => {
    // IF IN A WEB BROWSER, you need to use a service like trampoline.turbowarp.org to access the Scratch API.
    // IF IN NODE.JS, you should use https://api.scratch.mit.edu/projects/${projectId} directly instead.
    const response = await fetch(`https://trampoline.turbowarp.org/api/projects/${projectId}`);
    if (response.status === 404) {
        throw new Error('The project is unshared or does not exist');
    }
    if (!response.ok) {
        throw new Error(`HTTP error ${response.status} fetching project metadata`);
    }
    const json = await response.json();
    return json;
};

const getProjectData = async (projectId) => {
    const metadata = await getProjectMetadata(projectId);
    const token = metadata.project_token;
    const response = await fetch(`https://projects.scratch.mit.edu/${projectId}?token=${token}`);
    if (!response.ok) {
        throw new Error(`HTTP error ${response.status} fetching project data`);
    }
    const data = await response.arrayBuffer();
    return data;
};

getProjectData('60917032').then((data) => {
    console.log(data);
}).catch((error) => {
    console.error(error);
});

```

--------------------------------

### Filter Blocks by Target Type

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

This example demonstrates how to use the 'filter' property to make blocks available only in sprites, only on the stage, or in all targets. Note that blocks filtered to a specific target type must still include runtime checks for the target type.

```javascript
class FilterExample {
  getInfo() {
    return {
      id: 'filterexample',
      name: 'Filter Example',
      blocks: [
        {
          opcode: 'all',
          blockType: Scratch.BlockType.COMMAND,
          text: 'available in ALL targets',
        },
        {
          opcode: 'sprites',
          blockType: Scratch.BlockType.COMMAND,
          text: 'available in ONLY sprites',
          filter: [Scratch.TargetType.SPRITE]
        },
        {
          opcode: 'stage',
          blockType: Scratch.BlockType.COMMAND,
          text: 'available in ONLY the stage',
          filter: [Scratch.TargetType.STAGE]
        },
        {
          opcode: 'none',
          blockType: Scratch.BlockType.COMMAND,
          text: 'available in NEITHER sprites or the stage',
          // NOTE: Use hideFromPalette instead of filter: []
          filter: []
        }
      ]
    };
  }

  all() {
    return 0;
  }
  sprites() {
    return 0;
  }
  stage() {
    return 0;
  }
  none() {
    return 0;
  }
}

Scratch.extensions.register(new FilterExample());

```

--------------------------------

### Hello, world! Extension Code

Source: https://docs.turbowarp.org/development/extensions/hello-world

This is the main JavaScript code for the 'Hello, world!' extension. It defines a class with a getInfo() method to describe the extension's blocks and a method to return the 'World!' string.

```javascript
class HelloWorld {
  getInfo() {
    return {
      id: 'helloworld',
      name: 'It works!',
      blocks: [
        {
          opcode: 'hello',
          blockType: Scratch.BlockType.REPORTER,
          text: 'Hello!'
        }
      ]
    };
  }

  hello() {
    return 'World!';
  }
}

Scratch.extensions.register(new HelloWorld());

```

--------------------------------

### Scratch.Cast Type Conversion and Comparison

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

Demonstrates how to use Scratch.Cast.toNumber, Scratch.Cast.toString, Scratch.Cast.toBoolean, and Scratch.Cast.compare for handling type conversions and comparisons in Scratch extensions. Note the specific comparison logic required for Scratch.Cast.compare.

```javascript
class CastingExample {
  getInfo() {
    return {
      id: 'castexample',
      name: 'Casting Example',
      blocks: [
        {
          opcode: 'toNumber',
          blockType: Scratch.BlockType.REPORTER,
          text: 'convert [INPUT] to number',
          arguments: {
            INPUT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '3.0'
            }
          }
        },
        {
          // The opcode "toString" should work but given it's special
          // treatment in JS, it seems a bit dangerous to use
          opcode: 'castToString',
          blockType: Scratch.BlockType.REPORTER,
          text: 'convert [INPUT] to string',
          arguments: {
            INPUT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: 'Hello'
            }
          }
        },
        {
          opcode: 'toBoolean',
          blockType: Scratch.BlockType.BOOLEAN,
          text: 'convert [INPUT] to boolean',
          arguments: {
            INPUT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '1'
            }
          }
        },
        {
          opcode: 'compare',
          blockType: Scratch.BlockType.REPORTER,
          text: 'compare [A] to [B]',
          arguments: {
            A: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '3'
            },
            B: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: '5'
            }
          }
        }
      ]
    };
  }

  toNumber({INPUT}) {
    return Scratch.Cast.toNumber(INPUT);
  }

  castToString({INPUT}) {
    return Scratch.Cast.toString(INPUT);
  }

  toBoolean({INPUT}) {
    return Scratch.Cast.toBoolean(INPUT);
  }

  compare({A, B}) {
    const comparison = Scratch.Cast.compare(A, B);
    // You need to use < 0, > 0, or === 0 here.
    // Do not use === 1 or === -1! That will not work in some cases.
    if (comparison === 0) {
      return 'Equal';
    } else if (comparison > 0) {
      return 'A is greater';
    } else if (comparison < 0) {
      return 'B is greater';
    }
  }
}

Scratch.extensions.register(new CastingExample());
```

--------------------------------

### Using Block Icons

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

Shows how to set a custom icon for a block using `blockIconURI`. This icon will appear next to the block's text.

```JavaScript
blockIconURI: colorIcon
```

--------------------------------

### Define a Static Menu with String Items

Source: https://docs.turbowarp.org/development/extensions/inputs

This snippet demonstrates how to define a static menu where menu items are simple strings. The `FORMAT_MENU` is used for the `FORMAT` argument, allowing selection between 'uppercase' and 'lowercase'.

```javascript
class Strings1 {
  getInfo() {
    return {
      id: 'strings1example',
      name: 'Encoding',
      blocks: [
        {
          opcode: 'convert',
          blockType: Scratch.BlockType.REPORTER,
          text: 'convert [TEXT] to [FORMAT]',
          arguments: {
            TEXT: {
              type: Scratch.ArgumentType.STRING,
              defaultValue: 'Apple'
            },
            FORMAT: {
              type: Scratch.ArgumentType.STRING,
              menu: 'FORMAT_MENU'
            }
          }
        }
      ],
      menus: {
        FORMAT_MENU: {
          acceptReporters: true,
          items: ['uppercase', 'lowercase']
        }
      }
    };
  }

  convert (args) {
    if (args.FORMAT === 'uppercase') {
      // Notice the toString() call: TEXT might be a number or boolean,
      // so we have to make sure to convert it to a string first so that
      // it has a toUpperCase() function, otherwise we will get an error!
      // Remember: the argument's "type" is just a suggestion for the
      // editor; it's never enforced.
      return args.TEXT.toString().toUpperCase();
    } else {
      return args.TEXT.toString().toLowerCase();
    }
  }
}
Scratch.extensions.register(new Strings1());

```

--------------------------------

### Basic TurboWarp Embed Iframe

Source: https://docs.turbowarp.org/embedding

Use this template to embed a Scratch project. Adjust the 'src', 'width', and 'height' attributes to match your project and desired dimensions.

```html
<iframe src="https://turbowarp.org/414716080/embed" width="482" height="412" allowtransparency="true" frameborder="0" scrolling="no" allowfullscreen="" style="color-scheme: auto"></iframe>  

```

--------------------------------

### Create New Extension for Breaking Changes

Source: https://docs.turbowarp.org/development/extensions/compatibility

When backward compatibility must be broken, create a completely new extension with a distinct ID. Leave the old extension untouched.

```javascript
getInfo() {
    return {
      // For a completely new redesign, use a new ID
      id: 'fetch2'
      // ...
    };
  }
```

--------------------------------

### Embedding a Packaged Project with an iframe

Source: https://docs.turbowarp.org/packager/embedding

Use this iframe code to embed your packaged Scratch project into a website. Adjust the 'src' attribute to point to your project's HTML file and modify 'width' and 'height' as needed. If controls are enabled, increase the 'height' by 48.

```html
<iframe src="path_to_project.html" width="480" height="360" allowtransparency="true" frameborder="0" scrolling="no" allowfullscreen></iframe>
```

--------------------------------

### Extension Metadata

Source: https://docs.turbowarp.org/development/extensions/hello-world

The getInfo() function provides metadata for the extension, including its ID, name, and a list of blocks it defines. This is called by Scratch when the extension is registered.

```javascript
getInfo() {
    return {
      id: 'helloworld',
      name: 'It works!',
      blocks: [
        {
          opcode: 'hello',
          blockType: Scratch.BlockType.REPORTER,
          text: 'Hello, world!'
        }
      ]
    };
  }
```

--------------------------------

### Log Window Origin in Sandboxed Extension

Source: https://docs.turbowarp.org/development/extensions/sandbox

Use console.log to output the value of `window.origin` within a custom extension to understand its execution context. Compare this to the origin in the main browser console.

```javascript
console.log(window.origin);
```

--------------------------------

### Making Network Requests with Scratch.fetch

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

Use Scratch.fetch for network requests instead of the global fetch. Always check Scratch.canFetch before using other network-dependent APIs like WebSockets, images, or audio.

```javascript
// Do not do this:  
const response = await fetch(url);  
// Do this instead:  
const response = await Scratch.fetch(url);  
  
// Do not do this:  
const ws = new WebSocket(url);  
// Do this instead:  
if (await Scratch.canFetch(url)) {  
  const ws = new WebSocket(url);  
}  
  
// Do not do this:  
const image = new Image();  
image.src = src;  
// Do this instead:  
if (await Scratch.canFetch(src)) {  
  const image = new Image();  
  image.src = src;  
}  
  
// Do not do this:  
const audio = new Audio(url);  
// Do this instead:  
if (await Scratch.canFetch(url)) {  
  const audio = new Audio(url);  
}
```

--------------------------------

### Registering the Extension

Source: https://docs.turbowarp.org/development/extensions/hello-world

Registers the extension class with the Scratch API. This function must be called exactly once for the extension to load correctly.

```javascript
Scratch.extensions.register(new HelloWorld());

```

--------------------------------

### Flipping Images in RTL

Source: https://docs.turbowarp.org/development/extensions/assorted-apis

Illustrates how to horizontally flip an inline image when the interface is in a right-to-left language by setting `flipRTL` to true.

```JavaScript
flipRTL: true
```

--------------------------------

### Create a Custom 'When Space Key Pressed' Event Block

Source: https://docs.turbowarp.org/development/extensions/hats

This snippet demonstrates how to define a custom event block for 'when space key pressed' in an unsandboxed TurboWarp extension. It requires the extension to be unsandboxed and uses `Scratch.BlockType.EVENT` to define the block. The actual script execution is triggered by a global keydown event listener.

```javascript
(function(Scratch) {
  'use strict';

  if (!Scratch.extensions.unsandboxed) {
    throw new Error('This example must run unsandboxed');
  }

  class WhenSpaceKeyPressed {
    getInfo() {
      return {
        id: 'eventexampleunsandboxed',
        name: 'Event Block Example',
        blocks: [
          {
            blockType: Scratch.BlockType.EVENT,
            opcode: 'whenSpacePressed',
            text: 'when space key pressed',
            isEdgeActivated: false // required boilerplate
          }
        ]
      };
    }
    // Notice: whenSpacePressed does not have a function defined!
  }

  document.addEventListener('keydown', (e) => {
    if (e.key === ' ') {
      Scratch.vm.runtime.startHats('eventexampleunsandboxed_whenSpacePressed');
    }
  });

  Scratch.extensions.register(new WhenSpaceKeyPressed());
})(Scratch);
```

--------------------------------

### Redirecting Current Page with Scratch.redirect

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

Use Scratch.redirect for page redirection. If Scratch.redirect is unavailable, check Scratch.canRedirect before using location.href.

```javascript
// Do not do this:  
location.href = url;  
// Do this instead:  
await Scratch.redirect(url);  
```

--------------------------------

### Correct IIFE Structure for Unsandboxed Extensions

Source: https://docs.turbowarp.org/development/extensions/unsandboxed

Demonstrates the correct Immediately Invoked Function Expression (IIFE) structure for unsandboxed extensions, ensuring that variable declarations are scoped within the IIFE. This prevents potential conflicts and ensures proper extension loading.

```javascript
(function(Scratch) {
  const vm = Scratch.vm;
  // ...
}(Scratch));
```

```javascript
const vm = Scratch.vm;
(function(Scratch) {
  // ...
}(Scratch));
```

--------------------------------

### Embed with Settings Button

Source: https://docs.turbowarp.org/embedding

Add the 'settings-button' parameter to include a settings button in the embed, providing access to advanced options.

```html
https://turbowarp.org/15832807/embed?autoplay&settings-button
```

--------------------------------

### Inefficiently Fetching Cloud Variable

Source: https://docs.turbowarp.org/cloud-variables

This code demonstrates an inefficient pattern of rapidly opening and closing connections to fetch a cloud variable. Libraries should use event-driven APIs instead.

```python
while True:
    value = cloudlibrary.get_var(project_id, username, user_agent, variable_name)
    print(f"{variable_name} is {value}")
```
Tokens:
Raw