Initial commit

Author: GarboMuffin

.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -0,0 +1,9 @@
+# TurboWarp Docs
+
+WIP
+
+```
+npm install
+npm start
+npm run build
+```

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/development/custom-extensions.md

@@ -0,0 +1,3 @@
+# Custom Extensions
+
+TODO

docs/development/getting-started.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 1
+---
+
+# Getting Started
+
+These are the instructions for setting up the TurboWarp development environment or making custom builds on your own computer.
+
+If you just want to use TurboWarp, visit https://turbowarp.org/. You don't need to follow these instructions.
+
+### Dependencies
+
+Make sure you have these installed:
+
+ - [Git](https://git-scm.com)
+ - [Node.js](https://nodejs.org/en/)
+
+You might have to restart your terminal or computer for them to be fully installed. We assume you have some familiarity with the command line. Note that TurboWarp is a large app that may take a lot of resources to build.
+
+### A note on how Scratch is organized
+
+Scratch 3 is organized into a bunch of different repositories. Each implements a part of the app. Here's the ones that TurboWarp cares enough about to fork:
+
+ - scratch-vm executes the project and is where the compiler lives
+ - scratch-render renders sprites and implements "touching" blocks and is where high quality pen lives
+ - scratch-blocks is the script editor
+ - scratch-gui implements the outer interface, connects everything together, and is where addons live
+ - scratch-paint is the costume editor
+ - scratch-l10n contains translations
+
+### Building the GUI
+
+The GUI is the minimum to build TurboWarp.
+
+```bash
+git clone https://github.com/TurboWarp/scratch-gui
+cd scratch-gui
+npm install
+npm start
+```
+
+http://localhost:8601/
+
+If you just want to build the GUI, you can stop here.
+
+### Build
+
+While `npm start` is useful for development, at some point you'll need to get HTML, JS, etc. out. To do this, run this in the scratch-gui folder:
+
+```
+npm run build
+```
+
+Output goes in the `build` folder.
+
+When deploying TurboWarp to a website, you should enable production mode. This will result in faster execution and a greatly reduced file size.
+
+```bash
+# mac, linux
+NODE_ENV=production npm run build
+
+# windows command prompt (untested)
+set NODE_ENV=production
+npm run build
+
+# windows powershell
+$env:NODE_ENV="production"
+npm run build
+```
+
+By default TurboWarp generates links like https://turbowarp.org/editor.html#123 However, by setting `ROOT=/` and `ROUTING_STYLE=wildcard` (in the same way that you set `NODE_ENV=production`), you can get routes like https://turbowarp.org/123/editor instead. Note that this requires a server that will setup the proper aliases. The webpack development server in scratch-gui is setup for this. For production you'd want something more like https://github.com/TurboWarp/turbowarp.org
+
+### Linking other packages
+
+If you're interested in changing parts of TurboWarp other than the GUI, you have to do extra steps. You do not need to do this if you are only interesting in scratch-gui.
+
+It's probably easiest to understand by example, so here's how you would link local instances of scratch-vm and scratch-render to your local scratch-gui:
+
+```bash
+git clone https://github.com/TurboWarp/scratch-vm
+git clone https://github.com/TurboWarp/scratch-render
+
+cd scratch-vm
+npm install
+npm link
+cd ..
+
+cd scratch-render
+npm install
+npm link
+cd ..
+
+cd scratch-gui
+npm link scratch-vm scratch-render
+```

docs/intro.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Intro
+
+TODO

docs/website/embedding.md

@@ -0,0 +1,33 @@
+# Embedding
+
+Embedding TurboWarp is very similar to how you embed Scratch 3:
+
+```html
+<iframe src="https://turbowarp.org/414716080/embed" width="499" height="416" allowtransparency="true" frameborder="0" scrolling="no" allowfullscreen></iframe>
+```
+
+Replace `414716080` with the ID of your project. The dimensions above of 499x416 will result in the stage itself being rendered without distortion at the default stage size (480x360), but you can change it to anything and the player will automatically resize to fit.
+
+## URL parameters
+
+All [standard URL Parameters](https://github.com/TurboWarp/scratch-gui/wiki/URL-Parameters) are still available. You can use these to control usernames and other things.
+
+There are also some special values only available in embeds:
+
+### Autoplay
+
+Embeds also support the `autoplay` parameter, which will automatically hit the green flag when the project is loaded. For example: https://turbowarp.org/15832807/embed?autoplay
+
+Note that audio may not work until the user interacts with the project (for example, clicking). This is a restriction imposed by browsers. There is nothing TurboWarp can do to work around this.
+
+## Security considerations
+
+If you use user-supplied information to generate embed links, please make sure to use encodeURIComponent or other sanitization to make sure that users cannot specify arbitrary parameters, as some parameters can cause **remote code execution** or other unexpected behaviors.
+
+## License
+
+TurboWarp is licensed under the [GPLv3.0](https://github.com/TurboWarp/scratch-gui/blob/develop/LICENSE). We believe that an `<iframe>` of a GPLv3.0 work doesn't create a derivative work under the GPLv3.0, rather, it creates an "aggregate work" (which is not subject to the same requirements as derivative works). However, we are not lawyers and this is not legal advice. Talk to a real lawyer for more information.
+
+## Need more control?
+
+Try the [TurboWarp Packager](https://packager.turbowarp.org/).

docs/website/how-to-copy-javascript.md

@@ -0,0 +1,14 @@
+# How to copy the JavaScript
+
+## Short Answer
+
+ * If you want to package/HTMLify TurboWarp, use https://packager.turbowarp.org/
+ * If you want to convert Scratch projects to readable JavaScript, use https://leopardjs.vercel.app/
+
+## Long Answer
+
+The code generated by TurboWarp is not designed to be read or edited by humans. Attempting to do so would be actively harmful to one's learning because of the many unusual things done to improve compatability or performance.
+
+For example, in regular JavaScript accessing a list item is as simple as `myList[myIndex]`, but TurboWarp does `(b1.value[(b0.value | 0) - 1] ?? "")` or `listGet(b0, b1.value)` depending on what assumptions it can make. `b0` and `b1` are real variable names that TurboWarp will use and `listGet` is a magic function that's part of the TurboWarp runtime. The code also lacks any formatting.
+
+If you want to convert Scratch projects to readable JavaScript, use https://leopardjs.vercel.app/

docs/website/translate.md

@@ -0,0 +1,37 @@
+# Help Translate TurboWarp
+
+We're looking for people to help translate TurboWarp into languages other than English. If that interests you, read on.
+
+Create a new discussion if you have questions following this guide: https://github.com/TurboWarp/scratch-gui/discussions
+
+## Joining the translation team
+
+### Requirements
+
+ - You are expected to read this entire document.
+ - You must be fluent in both English and another language.
+ - We want translations written by humans, not by machines. That means **NO Google Translate** or other machine translators.
+ - Requests to translate new languages that aren't already supported by Scratch will be rejected.
+ - The initial translation for new languages should take under an hour. Please check occasionally to translate any newly added strings. This isn't expected to be a large time commitment. Don't lose sleep over this. We're all unpaid volunteers.
+
+### Request to join
+ 
+ - Go to [our Transifex page](https://www.transifex.com/turbowarp/turbowarp/), and click on the blue "Help Translate TurboWarp" button.
+ - You'll probably have to create a Transifex account. Try to use the same username as your Scratch account so that we can add you to the [credits page](https://turbowarp.org/credits.html). Enter your email, a new password, then Sign Up.
+ - When asked for your name, enter your username as your name and surname instead of your real name. For "department" and "job title", select "localization" and "individual contributor".
+ - On then next step, select "join an existing project".
+ - Choose the language(s) you want to translate into.
+
+The request will be accepted within a few days.
+
+If the request is rejected, that most likely means that Scratch (and by extension, TurboWarp) does not support that language or that we already have enough translators for that language.
+
+## Writing translations
+
+Find your language on https://www.transifex.com/turbowarp/turbowarp/dashboard/ and click the Translate button.
+
+Read https://docs.transifex.com/translation/translating-with-the-web-editor to learn how to use the Transifex translator.
+
+Translations are periodically pulled from Transifex and put into the website.
+
+The most important resource to translate is `gui.json`. You should start with this one.

docs/website/unshared-projects.md

@@ -0,0 +1,33 @@
+# Unshared Projects
+
+You've probably noticed that TurboWarp, forkphorus, etc. can load unshared projects, and you might be concerned about that.
+
+### This is a problem with the Scratch API that's been around for at least seven years. It's not a TurboWarp bug.
+
+Even the Scratch GUI development builds (maintained and controlled by the Scratch Team) can view unshared projects (https://llk.github.io/scratch-gui/develop/#1) which implies that the Scratch Team does not consider this an issue. As TurboWarp uses the exact same project loading code as Scratch GUI, it's also able to load unshared projects.
+
+However, we want to make it clear that viewing unshared projects is not the intended use for TurboWarp. It only happens to be possible because of the Scratch API.
+
+## If you don't want people to see your unshared projects
+
+Don't share the project ID (the numbers in the project URL) with others. That includes links to your project and screenshots/videos that include your browser's URL bar.
+
+If the project ID has already been leaked, and you don't want people to see the project, then save a copy of the project (File > Save as a copy) and delete everything from the original project. **Deleting a project through the My Stuff page (even emptying the trash) is not enough.** You must manually clear everything from the original project. If someone already downloaded the project to their computer before you did this, there's not much you can directly do about that.
+
+This would be a good opportunity to download a backup of the project to your computer for safekeeping so that you don't have to learn the importance of backups the [hard way](https://ocular.jeffalo.net/search?q=project%20disappeared&sort=relevance).
+
+Another alternative to keep your project safe would be to use the offline editor. We recommend [TurboWarp Desktop](https://desktop.turbowarp.org/).
+
+## Couldn't TurboWarp fix it?
+
+Even if TurboWarp refused to load unshared projects, the root cause is the Scratch API. People would still be able to view unshared projects just as easily as before using the official Scratch GUI builds or [any other tool](https://www.google.com/search?hl=en&q=unshared%20project%20viewer%20scratch). Nothing would change.
+
+This is a problem that can only be fixed by the Scratch Team.
+
+## What is project ID 1?
+
+Curious people have visited https://turbowarp.org/1 or https://llk.github.io/scratch-gui/develop/#1 and found a strange project. That's just what the Scratch API returns when you ask for the project with ID 1. Some story applies to all the other low project IDs. We don't know why these projects are what they are.
+
+## The project is shared. Why am I seeing this link?
+
+This is normal if the project was shared very recently. It will probably fix itself within a few hours, otherwise let me know on [Scratch](https://scratch.mit.edu/users/GarboMuffin/#comments).

docusaurus.config.js

@@ -0,0 +1,58 @@
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+
+/** @type {import('@docusaurus/types').DocusaurusConfig} */
+module.exports = {
+  title: 'TurboWarp',
+  url: 'https://docs.turbowarp.org/',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.ico',
+  organizationName: 'TurboWarp',
+  projectName: 'docs',
+  themeConfig: {
+    navbar: {
+      title: 'TurboWarp',
+      items: [
+        {
+          type: 'doc',
+          docId: 'intro',
+          position: 'left',
+          label: 'Documentation',
+        },
+        {
+          href: 'https://github.com/TurboWarp/docs',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
+    prism: {
+      theme: lightCodeTheme,
+      darkTheme: darkCodeTheme,
+    },
+  },
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          routeBasePath: '/',
+          editUrl: 'https://github.com/TurboWarp/docs/edit/master/website/',
+        },
+        blog: {
+          showReadingTime: true,
+          editUrl: 'https://github.com/TurboWarp/docs/edit/master/website/blog/',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+};