Load an .sb3 file from disk into memory for editing.

Write the open project back to an .sb3 file (defaults to the path it was opened from). If the TurboWarp Desktop userscript is installed, the editor reloads the file automatically.

Summarize the open project: targets, extensions, monitors and meta.

Authenticate with a scratch.mit.edu account so the server can open your projects from the website and (with your confirmation) save edits back and publish them. Credentials default to the SCRATCH_USER / SCRATCH_PASS environment variables if omitted. The session is kept in memory for this server process only.

Download a project from scratch.mit.edu by id and hold it open in memory for editing — the same in-memory project the other editing tools act on. Shared projects open without login; your own unshared projects need scratch_login first. Use push_to_scratch to save edits back.

Save the open project back to scratch.mit.edu, overwriting the online project's contents (uploads its costumes/sounds, then writes project.json). Requires login and ownership of the project. This edits the live project, so it always asks the user to confirm first (set confirm: true only after the user has agreed).

Publish a project on scratch.mit.edu so it becomes publicly visible (PUT /proxy/projects//share). Requires login and ownership. Publishing is public and outward-facing, so it always asks the user to confirm first (set confirm: true only after the user has agreed).

List every sprite with its position, size and media.

Full details for one target (a sprite or the stage), including variables and lists.

A target's complete raw project.json entry — blocks (scripts), costumes, sounds, variables, lists and properties — exactly as stored. Read this first to author a patch_target edit, since the patch paths are JSON Pointers into this object. Pass pointer to fetch just a subtree (e.g. "/blocks" or "/blocks/abc123") and keep the response small.

The catalog of standard Scratch block opcodes you can use in a target's blocks map — each with its category, shape (hat / stack / c-block / cap / reporter / boolean) and the names of its inputs and fields. Use this to discover opcodes, then get_block_schema for how to fill one in. With no category, lists core blocks; pass a core category (motion, looks, sound, event, control, sensing, operator, data, procedures) or a built-in extension id (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor) to filter.

The full schema for one block opcode: its shape, every input (with the sb3 shadow encoding to use, e.g. a text input is [1, [10, "hi"]]), every field (with enumerated dropdown options where applicable), and a ready-to-adapt example block JSON. Read this before writing a block with patch_target. In the example, <…> placeholders (block ids, variable ids) must be replaced with real ones; menu inputs also need a matching shadow block (opcode menuOpcode, a field named menuField, shadow: true). Dynamic menu options (sprites, sounds, costumes, …) are filled from the open project; pass target to enumerate that sprite's own costumes and sounds.

Register an extension on the project so its blocks load and show in the palette — required before using any <id>_… extension block. For a built-in extension pass just its id (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor). For a custom/third-party (TurboWarp) extension, also pass the loader url so the editor can fetch it. Adds the id to the project's extensions and, with a url, records it in extensionURLs.

Apply an RFC 6902 JSON Patch to a target's raw JSON — the way to edit a sprite's scripts (blocks) or any field a higher-level tool does not cover, on a sprite you just made or an existing one. Paths are JSON Pointers into the object returned by get_target_json; read that first. To write blocks, discover opcodes with list_blocks and get the exact input/field shapes from get_block_schema — the result reports advisory warnings for unknown opcodes or inputs. The patch is applied atomically: if any operation fails the target is left unchanged. Notes: patching the costumes/sounds arrays does not touch stored asset bytes (use add_costume/remove_costume for those), and you are responsible for keeping blocks internally consistent (ids, next/parent links).

Update one or more properties of a sprite (position, size, direction, visibility, …).

Add a new, empty sprite. Add at least one costume before opening it in the editor.

Delete a sprite and any assets only it used.

Rename a sprite (or the stage).

Update stage-level properties: tempo, video state/transparency, volume.

Create or update a variable on a target by name.

Delete a variable from a target by name.

Create or replace a list on a target by name.

Delete a list from a target by name.

Add a broadcast message to the project (no-op if it already exists).

List a target's workspace comments — the yellow sticky notes shown in the editor. Each has an id, its text, and either a blockId (when attached to a block) or null (when floating free on the canvas).

Add a workspace comment to a target. With no blockId the comment floats free on the canvas; pass a blockId (a key in the target's blocks map — see get_target_json) to attach it to that block, which also sets the block's comment back-reference so the editor anchors it.

Update an existing comment on a target by id: its text, position, size, minimized state, or the blockId it is attached to (pass an empty string or null to detach it). Only the fields you pass change.

Delete a workspace comment from a target by id. If it was attached to a block, the block's comment back-reference is cleared too.

Add a costume to a sprite (or the stage) from an image file on disk.

Remove a costume from a target by name.

Add a sound to a sprite (or the stage) from an audio file on disk.

Remove a sound from a target by name.

Tell connected TurboWarp Desktop userscripts to load an .sb3 from disk (defaults to the open project). Use after editing on disk without going through save_project.

Press the green flag in connected TurboWarp Desktop userscripts.

Stop running in connected TurboWarp Desktop userscripts.

Load the open project into a headless Scratch VM (TurboWarp, JIT) for running and testing — no browser needed. Reflects the current in-memory edits; call again after editing to pick up changes. Returns a state snapshot.

Press the green flag in the headless runtime (clears bubbles, the pending question and errors, then starts scripts). Does not advance time on its own — call vm_run to step the VM. Run vm_load first.

Advance the headless VM, then return a state snapshot. By default it runs in real time until every script finishes (so waits, timers and glides behave) or the budget elapses. Returns sprite positions, variables, lists, monitors, say/think bubbles, any pending question, running-thread count and errors. Also returns events: the ordered timeline of what happened since the previous vm_run (say/think, broadcasts, question/answer, errors), so you can assert on sequence, not just final state.

Stop every running script in the headless VM.

A structured snapshot of the headless VM right now: every target with its position/size/direction/costume/visibility, variables and lists, visible monitors, say/think bubbles, the pending question, running-thread count and errors. Assert against these rather than a screenshot.

Feed input into the headless VM the way the editor would: key presses, mouse position/clicks, and answers to ask and wait. Stage coordinates run -240..240 (x) and -180..180 (y).

Capture a PNG of the live stage from a connected TurboWarp Desktop editor (via the live-reload bridge + userscript). This is the real renderer, so load and run the project there first (save_project/run_project). For logic checks prefer vm_state — pixels are a poor substitute for values. For a much smaller payload use screenshot_jpeg.

Same capture as screenshot, but re-encoded as JPEG (via sharp) for a much smaller payload. Prefer this version unless you need pixel fidelity — JPEG is lossy, so fine UI detail and flat color edges may soften. Optional quality (1-100, default 80).