Skip to content
Merged
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
17 changes: 15 additions & 2 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
name: Validate

on: pull_request
on:
pull_request:
push:
branches: [master]

jobs:
build:
Expand All @@ -10,6 +13,16 @@ jobs:
- name: Install Node.js
uses: actions/setup-node@v4
with:
node-version: 20
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- name: Check out scratch-gui for its docs links
uses: actions/checkout@v4
with:
repository: MistWarp/scratch-gui
path: scratch-gui
sparse-checkout: src
- run: npm run check
env:
SCRATCH_GUI_DIR: scratch-gui
59 changes: 59 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# MistWarp docs

The documentation site for MistWarp, built with Docusaurus. It is served at
https://mistwarp.org/docs/ (`baseUrl: '/docs/'`, `trailingSlash: true`) and also
inside the editor's Help window, which loads it in a same-origin iframe.

## How it ships

- Cloudflare Pages builds `master` with `npm run build`. `scripts/pack-build.mjs`
then writes `docs-build.tar.gz` (the build with `index.html` at its root) and
`docs-build.json` (`{commit, branch}`), which scratch-gui's Cloudflare build
downloads from docs.warp.mistium.com. Keep both names and that layout.
- `plugins/search-index.js` writes the Pagefind index into `build/pagefind/`
after `docusaurus build`. Search only works in a build, not in `npm start`.

## Structure

- Pages live in `docs/<section>/<page>.md`. The folder sets the URL, so
`docs/editor/stage.md` is `/docs/editor/stage/`.
- `sidebars.js` lists every page explicitly, in five sidebars: `using`,
`extensions`, `packager`, `contributing`, `backend`. A page that is not
listed there does not appear in navigation, so add new pages to it.
- Each section starts with an overview page that links into it.
- `src/theme/SearchBar/` is the search UI, `src/pages/index.js` the landing page.

## Embedded in the editor

`scratch-gui/src/components/mw-help-modal/help-modal.jsx` sets
`localStorage.theme`, `data-theme` and the editor's CSS custom properties on
the iframe's `<html>`. `src/css/custom.css` maps Infima variables onto those
(`--ui-modal-background`, `--text-primary`, `--looks-secondary`, ...), with
standalone fallbacks. `html[data-embedded]` hides the colour mode switch, and
`src/clientModules/spotlight-key.js` hands Ctrl or Cmd+K to the editor.

## URL contract

The editor and other sites deep-link into the docs. Never remove or rename a
page without adding its old path to `redirects.js`.
`scripts/check-inbound-links.mjs` checks every path in
`scripts/inbound-links.json` and every docs link in a sibling `scratch-gui`
checkout against the build. Run `npm run check -- --write` to add new
scratch-gui links to the committed list.

## Writing

- Plain, direct, second person. Sentence case titles and headings, one
heading per section with no eyebrow label above it, no ALL CAPS headings.
- No em dashes anywhere. Use commas, parentheses or "to".
- No code comments.
- Link to other pages with root paths such as `/advanced/cloud-variables`.
Broken links and anchors fail the build.
- Admonitions are tinted backgrounds with an icon. Never add a left border or
stripe to anything with rounded corners.
- READMEs are short overviews, never documentation.

## Commands

- `npm run build` builds the site and the search index.
- `npm run check` checks inbound links. Run it after a build.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
See https://github.com/MistWarp/docs#writing-content
Read [AGENTS.md](AGENTS.md) for where pages go, the writing rules and the URL contract, then open a pull request against `master`.
39 changes: 11 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,16 @@
# MistWarp Docs
# MistWarp docs

https://mistwarp.org/docs/
The documentation for [MistWarp](https://mistwarp.org/), published at
https://mistwarp.org/docs/ and in the editor's Help window.

This repository contains documentation for MistWarp.

## Writing content

If you found a typo or have a suggestion to improve the pages, the easiest way to get it resolved is to post about it on the Scratch profile https://scratch.mit.edu/users/M1stium/#comments or in GitHub issues https://github.com/MistWarp/docs/issues/new. Minor fixes get resolved very quickly usually.

Alternatively, you can submit a pull request yourself containing a fix. The easiest way to edit a page is:

1. Open the website, https://mistwarp.org/docs/
2. Find the page you want to edit
3. Click "Edit this page" at the bottom
4. Sign in with a GitHub account
5. Fork the repository
6. Use the GitHub editor to modify the file. It uses [Markdown syntax](https://www.markdownguide.org/basic-syntax/).
7. Click "Propose Changes"

If you'd like to write a new page, we'd prefer that you ask us first before you spend much time writing.

## Local Development

This website is built with [Docusaurus](https://docusaurus.io/). Documentation is inside the `docs` folder, generally that is all you will have to touch. We accept pull requests.
Found a mistake? Use "Edit this page" at the bottom of any page, or
[open an issue](https://github.com/MistWarp/docs/issues/new).

```bash
npm install
# For development:
npm start
# For production:
npm run build
npm ci
npm start # dev server, without search
npm run build # full build with the search index
npm run check # check that inbound links still resolve
```

See [AGENTS.md](AGENTS.md) for how the site is structured and deployed.
5 changes: 0 additions & 5 deletions docs/advanced/_category_.json

This file was deleted.

5 changes: 2 additions & 3 deletions docs/advanced/cloud-variables.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Cloud Variables
sidebar_position: 1
title: Cloud variables
---

# Cloud Variables
# Cloud variables

Cloud variables are variables whose value is shared, in real time, between everyone who has the same project open. A variable is a cloud variable when its name starts with a cloud symbol (`☁`). You create one by checking "Cloud variable" in the "Make a Variable" dialog, exactly like in Scratch.

Expand Down
1 change: 0 additions & 1 deletion docs/advanced/cors.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: CORS
sidebar_position: 6
---

# CORS: why your fetch block does not work
Expand Down
1 change: 0 additions & 1 deletion docs/advanced/custom-fps.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Custom FPS
sidebar_position: 7
---

# Custom FPS
Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/custom-stage-size.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Custom Stage Size
sidebar_position: 8
title: Custom stage size
---

# Custom Stage Size
# Custom stage size

MistWarp can change the stage from Scratch's default 480x360 (4:3) to any other size, from the [editor settings](/editor/settings) or the [`size` URL parameter](/advanced/url-parameters) (`size=640x360`).

Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/disable-compiler.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Disable Compiler
sidebar_position: 15
title: Disable compiler
---

# Disable Compiler
# Disable compiler

MistWarp's [compiler](/advanced/javascript) turns your blocks into JavaScript so they run much faster than in vanilla Scratch. This option turns it off, falling back to interpreting blocks one at a time like Scratch does. Toggle it in the [editor settings](/editor/settings) or with the [`nocompile` URL parameter](/advanced/url-parameters).

Expand Down
1 change: 0 additions & 1 deletion docs/advanced/embedding.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Embedding
sidebar_position: 4
---

# Embedding
Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/high-quality-pen.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: High Quality Pen
sidebar_position: 9
title: High quality pen
---

# High Quality Pen
# High quality pen

By default the pen layer is drawn at 480x360 and stretched to fit the stage, so pen art can look blocky when the stage is larger. High Quality Pen renders the pen layer at the stage's real resolution instead, and disables some coordinate rounding so pen lines land where you expect. Enable it in the [editor settings](/editor/settings) or with the [`hqpen` URL parameter](/advanced/url-parameters).

Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/infinite-clones.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Infinite Clones
sidebar_position: 13
title: Infinite clones
---

# Infinite Clones
# Infinite clones

Scratch limits a project to 300 clones at once. This option removes that cap so you can create as many clones as you like. Enable it in the [editor settings](/editor/settings), or set an explicit maximum with the [`clones` URL parameter](/advanced/url-parameters) (`clones=1000`).

Expand Down
1 change: 0 additions & 1 deletion docs/advanced/interpolation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Interpolation
sidebar_position: 10
---

# Interpolation
Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/javascript.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: JavaScript and the Compiler
sidebar_position: 2
title: JavaScript and the compiler
---

# JavaScript and the Compiler
# JavaScript and the compiler

JavaScript shows up in MistWarp in three ways: a **compiler** that turns your blocks into JavaScript automatically for speed, the **Patching extension** that gives you `js (...)` blocks to run your own JavaScript from inside a project, and the **extension system** for writing full blocks of your own in JavaScript. This page covers all three.

Expand Down
34 changes: 34 additions & 0 deletions docs/advanced/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Advanced features
sidebar_label: Overview
description: The compiler, cloud variables, URL parameters, embedding, and the runtime options that lift Scratch's limits.
---

# Advanced features

These pages cover what MistWarp does beyond the Scratch editor: how projects are compiled, how to share data between players, how to control a project from its URL or an embed, and the runtime options that remove Scratch's limits.

## Projects and the web

- [JavaScript and the compiler](/advanced/javascript) explains how blocks become JavaScript, and how to run your own code.
- [Cloud variables](/advanced/cloud-variables) share values between everyone playing the same project.
- [URL parameters](/advanced/url-parameters) set options such as FPS, stage size or username from the link.
- [Embedding](/advanced/embedding) puts a project on another website with an iframe.
- [Unshared projects](/advanced/unshared-projects) explains why unshared Scratch projects cannot be opened.
- [CORS](/advanced/cors) explains why a fetch or networking block can fail even after you allow it.

## Runtime options

Each of these is a setting in the [editor settings](/editor/settings), and most also have a [URL parameter](/advanced/url-parameters). The [packager](/packager/overview) offers the same options.

| Option | What it changes |
| --- | --- |
| [Custom FPS](/advanced/custom-fps) | How many times per second scripts run (Scratch uses 30). |
| [Interpolation](/advanced/interpolation) | Smooths motion by drawing in-between frames, without speeding scripts up. |
| [Custom stage size](/advanced/custom-stage-size) | The stage dimensions, instead of 480x360. |
| [High quality pen](/advanced/high-quality-pen) | Draws the pen layer at the stage's real resolution. |
| [Warp timer](/advanced/warp-timer) | Stops long loops in warp mode from freezing the project. |
| [Infinite clones](/advanced/infinite-clones) | Removes the 300 clone limit. |
| [Remove fencing](/advanced/remove-fencing) | Lets sprites leave the stage and grow or shrink without limit. |
| [Remove miscellaneous limits](/advanced/remove-limits) | Lifts smaller limits, such as the pitch effect range and pen size. |
| [Disable compiler](/advanced/disable-compiler) | Interprets blocks one at a time, like Scratch. |
5 changes: 2 additions & 3 deletions docs/advanced/remove-fencing.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Remove Fencing
sidebar_position: 14
title: Remove fencing
---

# Remove Fencing
# Remove fencing

"Fencing" is Scratch's rule that keeps sprites partly on the stage, caps how large or small they can get, and stops "touching" checks from working past the stage edge. Removing fencing lets sprites move fully offscreen, grow or shrink without limit, and detect touching offscreen. Enable it in the [editor settings](/editor/settings) or with the [`offscreen` URL parameter](/advanced/url-parameters).

Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/remove-limits.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Remove Miscellaneous Limits
sidebar_position: 11
title: Remove miscellaneous limits
---

# Remove Miscellaneous Limits
# Remove miscellaneous limits

This option lifts a handful of small Scratch limits that are not big enough to each get their own setting. Enable it in the [editor settings](/editor/settings) or with the [`limitless` URL parameter](/advanced/url-parameters).

Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/unshared-projects.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Unshared Projects
sidebar_position: 5
title: Unshared projects
---

# Unshared Projects
# Unshared projects

Unshared projects on Scratch cannot be opened in MistWarp, the packager, or any other third-party site. This is a Scratch restriction, not a MistWarp one, and there is no way around it that keeps your account safe.

Expand Down
7 changes: 3 additions & 4 deletions docs/advanced/url-parameters.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: URL Parameters
sidebar_position: 3
title: URL parameters
---

# URL Parameters
# URL parameters

You can control how MistWarp loads and runs a project by adding parameters to the URL. This is useful for sharing a reproducible setup, embedding a project with specific options, or automating tests.

Expand Down Expand Up @@ -36,7 +35,7 @@ https://mistwarp.org/?project_url=https://example.com/project.sb3
| Parameter | Value | What it does |
|-----------|-------|--------------|
| `fps` | number | Sets the [frame rate](/advanced/custom-fps). `0` runs at the display's refresh rate. |
| `turbo` | switch | Enables [turbo mode](/advanced/warp-timer) (no per-frame throttling). |
| `turbo` | switch | Enables [turbo mode](/editor/stage#turbo-mode) (no per-frame throttling). |
| `interpolate` | switch | Enables [interpolation](/advanced/interpolation) for smoother motion. |
| `hqpen` | switch | Enables [high quality pen](/advanced/high-quality-pen). |
| `limitless` | switch | Removes [miscellaneous limits](/advanced/remove-limits). |
Expand Down
5 changes: 2 additions & 3 deletions docs/advanced/warp-timer.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
title: Warp Timer
sidebar_position: 12
title: Warp timer
---

# Warp Timer
# Warp timer

The Warp Timer makes scripts check whether they are stuck in a long or infinite loop and drop to a low frame rate instead of freezing the whole project until the loop finishes. This prevents most "the project hung" crashes, but it has a real performance cost, so it is only on by default in the editor, not in the player. Toggle it in the [editor settings](/editor/settings) or with the [`stuck` URL parameter](/advanced/url-parameters) (also accepted as `warp_timer`).

Expand Down
5 changes: 0 additions & 5 deletions docs/api-reference/_category_.json

This file was deleted.

1 change: 0 additions & 1 deletion docs/api-reference/addon-api.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Addon API
sidebar_position: 7
---

Addons are userscripts and userstyles that modify the editor and player. Each addon is a folder
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Audio API
sidebar_position: 4
---

# Audio API
Expand Down Expand Up @@ -101,5 +100,5 @@ getMic(args, util) {

## See also

- [VM API](/building-extensions/apis/vm-api)
- [Scratch object API](/building-extensions/apis/scratch-api)
- [VM API](/api-reference/vm-api)
- [Scratch object API](/api-reference/extension-api)
1 change: 0 additions & 1 deletion docs/api-reference/block-registration.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Block registration
sidebar_position: 5
---

Blocks reach the palette in two ways: the built-in categories are registered as internal block
Expand Down
1 change: 0 additions & 1 deletion docs/api-reference/events.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Events
sidebar_position: 8
---

`VirtualMachine` extends Node's `EventEmitter`. The editor and player listen to these events to
Expand Down
Loading
Loading