Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit cc7618f

Browse files
committedJul 12, 2021
Initial commit
0 parents  commit cc7618f

18 files changed

+11227
-0
lines changed
 

‎.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# TurboWarp Docs
2+
3+
WIP
4+
5+
```
6+
npm install
7+
npm start
8+
npm run build
9+
```

‎babel.config.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/development/custom-extensions.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Custom Extensions
2+
3+
TODO

‎docs/development/getting-started.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Getting Started
6+
7+
These are the instructions for setting up the TurboWarp development environment or making custom builds on your own computer.
8+
9+
If you just want to use TurboWarp, visit https://turbowarp.org/. You don't need to follow these instructions.
10+
11+
### Dependencies
12+
13+
Make sure you have these installed:
14+
15+
- [Git](https://git-scm.com)
16+
- [Node.js](https://nodejs.org/en/)
17+
18+
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.
19+
20+
### A note on how Scratch is organized
21+
22+
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:
23+
24+
- scratch-vm executes the project and is where the compiler lives
25+
- scratch-render renders sprites and implements "touching" blocks and is where high quality pen lives
26+
- scratch-blocks is the script editor
27+
- scratch-gui implements the outer interface, connects everything together, and is where addons live
28+
- scratch-paint is the costume editor
29+
- scratch-l10n contains translations
30+
31+
### Building the GUI
32+
33+
The GUI is the minimum to build TurboWarp.
34+
35+
```bash
36+
git clone https://github.com/TurboWarp/scratch-gui
37+
cd scratch-gui
38+
npm install
39+
npm start
40+
```
41+
42+
http://localhost:8601/
43+
44+
If you just want to build the GUI, you can stop here.
45+
46+
### Build
47+
48+
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:
49+
50+
```
51+
npm run build
52+
```
53+
54+
Output goes in the `build` folder.
55+
56+
When deploying TurboWarp to a website, you should enable production mode. This will result in faster execution and a greatly reduced file size.
57+
58+
```bash
59+
# mac, linux
60+
NODE_ENV=production npm run build
61+
62+
# windows command prompt (untested)
63+
set NODE_ENV=production
64+
npm run build
65+
66+
# windows powershell
67+
$env:NODE_ENV="production"
68+
npm run build
69+
```
70+
71+
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
72+
73+
### Linking other packages
74+
75+
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.
76+
77+
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:
78+
79+
```bash
80+
git clone https://github.com/TurboWarp/scratch-vm
81+
git clone https://github.com/TurboWarp/scratch-render
82+
83+
cd scratch-vm
84+
npm install
85+
npm link
86+
cd ..
87+
88+
cd scratch-render
89+
npm install
90+
npm link
91+
cd ..
92+
93+
cd scratch-gui
94+
npm link scratch-vm scratch-render
95+
```

‎docs/intro.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
sidebar_position: 1
3+
slug: /
4+
---
5+
6+
# Intro
7+
8+
TODO

‎docs/website/embedding.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Embedding
2+
3+
Embedding TurboWarp is very similar to how you embed Scratch 3:
4+
5+
```html
6+
<iframe src="https://turbowarp.org/414716080/embed" width="499" height="416" allowtransparency="true" frameborder="0" scrolling="no" allowfullscreen></iframe>
7+
```
8+
9+
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.
10+
11+
## URL parameters
12+
13+
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.
14+
15+
There are also some special values only available in embeds:
16+
17+
### Autoplay
18+
19+
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
20+
21+
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.
22+
23+
## Security considerations
24+
25+
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.
26+
27+
## License
28+
29+
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.
30+
31+
## Need more control?
32+
33+
Try the [TurboWarp Packager](https://packager.turbowarp.org/).
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# How to copy the JavaScript
2+
3+
## Short Answer
4+
5+
* If you want to package/HTMLify TurboWarp, use https://packager.turbowarp.org/
6+
* If you want to convert Scratch projects to readable JavaScript, use https://leopardjs.vercel.app/
7+
8+
## Long Answer
9+
10+
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.
11+
12+
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.
13+
14+
If you want to convert Scratch projects to readable JavaScript, use https://leopardjs.vercel.app/

‎docs/website/translate.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Help Translate TurboWarp
2+
3+
We're looking for people to help translate TurboWarp into languages other than English. If that interests you, read on.
4+
5+
Create a new discussion if you have questions following this guide: https://github.com/TurboWarp/scratch-gui/discussions
6+
7+
## Joining the translation team
8+
9+
### Requirements
10+
11+
- You are expected to read this entire document.
12+
- You must be fluent in both English and another language.
13+
- We want translations written by humans, not by machines. That means **NO Google Translate** or other machine translators.
14+
- Requests to translate new languages that aren't already supported by Scratch will be rejected.
15+
- 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.
16+
17+
### Request to join
18+
19+
- Go to [our Transifex page](https://www.transifex.com/turbowarp/turbowarp/), and click on the blue "Help Translate TurboWarp" button.
20+
- 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.
21+
- 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".
22+
- On then next step, select "join an existing project".
23+
- Choose the language(s) you want to translate into.
24+
25+
The request will be accepted within a few days.
26+
27+
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.
28+
29+
## Writing translations
30+
31+
Find your language on https://www.transifex.com/turbowarp/turbowarp/dashboard/ and click the Translate button.
32+
33+
Read https://docs.transifex.com/translation/translating-with-the-web-editor to learn how to use the Transifex translator.
34+
35+
Translations are periodically pulled from Transifex and put into the website.
36+
37+
The most important resource to translate is `gui.json`. You should start with this one.

‎docs/website/unshared-projects.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Unshared Projects
2+
3+
You've probably noticed that TurboWarp, forkphorus, etc. can load unshared projects, and you might be concerned about that.
4+
5+
### This is a problem with the Scratch API that's been around for at least seven years. It's not a TurboWarp bug.
6+
7+
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.
8+
9+
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.
10+
11+
## If you don't want people to see your unshared projects
12+
13+
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.
14+
15+
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.
16+
17+
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).
18+
19+
Another alternative to keep your project safe would be to use the offline editor. We recommend [TurboWarp Desktop](https://desktop.turbowarp.org/).
20+
21+
## Couldn't TurboWarp fix it?
22+
23+
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.
24+
25+
This is a problem that can only be fixed by the Scratch Team.
26+
27+
## What is project ID 1?
28+
29+
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.
30+
31+
## The project is shared. Why am I seeing this link?
32+
33+
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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
const lightCodeTheme = require('prism-react-renderer/themes/github');
2+
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
3+
4+
/** @type {import('@docusaurus/types').DocusaurusConfig} */
5+
module.exports = {
6+
title: 'TurboWarp',
7+
url: 'https://docs.turbowarp.org/',
8+
baseUrl: '/',
9+
onBrokenLinks: 'throw',
10+
onBrokenMarkdownLinks: 'warn',
11+
favicon: 'img/favicon.ico',
12+
organizationName: 'TurboWarp',
13+
projectName: 'docs',
14+
themeConfig: {
15+
navbar: {
16+
title: 'TurboWarp',
17+
items: [
18+
{
19+
type: 'doc',
20+
docId: 'intro',
21+
position: 'left',
22+
label: 'Documentation',
23+
},
24+
{
25+
href: 'https://github.com/TurboWarp/docs',
26+
label: 'GitHub',
27+
position: 'right',
28+
},
29+
],
30+
},
31+
colorMode: {
32+
respectPrefersColorScheme: true,
33+
},
34+
prism: {
35+
theme: lightCodeTheme,
36+
darkTheme: darkCodeTheme,
37+
},
38+
},
39+
presets: [
40+
[
41+
'@docusaurus/preset-classic',
42+
{
43+
docs: {
44+
sidebarPath: require.resolve('./sidebars.js'),
45+
routeBasePath: '/',
46+
editUrl: 'https://github.com/TurboWarp/docs/edit/master/website/',
47+
},
48+
blog: {
49+
showReadingTime: true,
50+
editUrl: 'https://github.com/TurboWarp/docs/edit/master/website/blog/',
51+
},
52+
theme: {
53+
customCss: require.resolve('./src/css/custom.css'),
54+
},
55+
},
56+
],
57+
],
58+
};

‎package-lock.json

Lines changed: 10824 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"name": "turbowarp-docs",
3+
"version": "0.0.0",
4+
"private": true,
5+
"scripts": {
6+
"docusaurus": "docusaurus",
7+
"start": "docusaurus start",
8+
"build": "docusaurus build",
9+
"swizzle": "docusaurus swizzle",
10+
"deploy": "docusaurus deploy",
11+
"clear": "docusaurus clear",
12+
"serve": "docusaurus serve",
13+
"write-translations": "docusaurus write-translations",
14+
"write-heading-ids": "docusaurus write-heading-ids"
15+
},
16+
"dependencies": {
17+
"@docusaurus/core": "2.0.0-beta.3",
18+
"@docusaurus/preset-classic": "2.0.0-beta.3",
19+
"@mdx-js/react": "^1.6.21",
20+
"@svgr/webpack": "^5.5.0",
21+
"clsx": "^1.1.1",
22+
"file-loader": "^6.2.0",
23+
"prism-react-renderer": "^1.2.1",
24+
"react": "^17.0.1",
25+
"react-dom": "^17.0.1",
26+
"url-loader": "^4.1.1"
27+
},
28+
"browserslist": {
29+
"production": [
30+
">0.5%",
31+
"not dead",
32+
"not op_mini all"
33+
],
34+
"development": [
35+
"last 1 chrome version",
36+
"last 1 firefox version",
37+
"last 1 safari version"
38+
]
39+
}
40+
}

‎sidebars.js

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
module.exports = {
2+
sidebar: [
3+
{
4+
type: "doc",
5+
id: "intro"
6+
},
7+
{
8+
type: "autogenerated",
9+
dirName: "website"
10+
},
11+
{
12+
type: "category",
13+
label: "Development",
14+
items: [
15+
{
16+
type: "autogenerated",
17+
dirName: "development"
18+
}
19+
]
20+
}
21+
]
22+
};

‎src/css/custom.css

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:root {
2+
--ifm-color-primary: #ff4c4c;
3+
--ifm-color-primary-dark: rgb(33, 175, 144);
4+
--ifm-color-primary-darker: rgb(31, 165, 136);
5+
--ifm-color-primary-darkest: rgb(26, 136, 112);
6+
--ifm-color-primary-light: rgb(70, 203, 174);
7+
--ifm-color-primary-lighter: rgb(102, 212, 189);
8+
--ifm-color-primary-lightest: rgb(146, 224, 208);
9+
--ifm-code-font-size: 95%;
10+
}
11+
12+
.docusaurus-highlight-code-line {
13+
background-color: rgba(0, 0, 0, 0.1);
14+
display: block;
15+
margin: 0 calc(-1 * var(--ifm-pre-padding));
16+
padding: 0 var(--ifm-pre-padding);
17+
}
18+
19+
html[data-theme='dark'] .docusaurus-highlight-code-line {
20+
background-color: rgba(0, 0, 0, 0.3);
21+
}

‎src/pages/markdown-page.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Markdown page example
3+
---
4+
5+
# Markdown page example
6+
7+
You don't need React to write simple standalone pages.

‎static/.nojekyll

Whitespace-only changes.

‎static/img/favicon.ico

4.19 KB
Binary file not shown.

0 commit comments

Comments
 (0)
Please sign in to comment.