ScratchScript

Convert natural language descriptions into working Scratch 3.0 .sb3 files using a two-stage architecture: an LLM generates ScratchScript DSL code, then a deterministic compiler converts it to .sb3. Includes both a web UI and a CLI.

How To

Web UI

Launch the web interface with:

scratchscript-gui

Type out your prompt in natural language in the bottom left corner. Requires an API key or Ollama running locally in order to start. The "Import .sb3" button also enables users to import preexisting projects into the editor.

The LLM output is then checked for errors by the reviewer agent, as seen below. This is necessary to catch any logical errors that would prevent the program from working, or stylistic issues with the code output that would cause compiler errors.

The code is finally written in ScratchScript, which is a domain-specific language and a textual representation of Scratch's block-based coding language, shown in the image below. ScratchScript is an indentation-based language that maps 1:1 to Scratch blocks. You can also manually edit the generated code in the right panel before compiling.

Download the newly created .sb3 file by clicking the blue text.

Open up scratch.mit.edu, click "Create" to make a new project. Then, click "File" and "Load from your computer" to import the .sb3 file you just downloaded.

Test that the game works. (It does!)

Install

pip install -e .

# With LLM provider support:
pip install -e ".[claude]"    # Anthropic Claude
pip install -e ".[openai]"    # OpenAI
pip install -e ".[gemini]"    # Google Gemini
pip install -e ".[gui]"       # Web UI (Flask)
pip install -e ".[all]"       # All providers + web UI

Usage

Web UI

scratchscript-gui

Opens a browser-based editor with a chat panel for prompts and a code panel with syntax highlighting. Supports real-time streaming with Ollama, manual code editing, and .sb3 import/export.

Generate from natural language (requires an LLM provider)

scratchscript generate "make a cat that chases the mouse pointer"
scratchscript generate --provider ollama "make a platformer"
scratchscript generate --provider claude -o game.sb3 "make a pong game"
scratchscript generate --fast "make a pong game"  # skip the reviewer stage

Compile a .scratchscript file directly

scratchscript compile game.scratchscript
scratchscript compile game.scratchscript -o output.sb3

Import and decompile an existing .sb3 file

scratchscript import game.sb3
scratchscript import game.sb3 -o game.scratchscript
scratchscript import game.sb3 --modify "add a score counter" --provider ollama

ScratchScript DSL

ScratchScript is an indentation-based language that maps to Scratch blocks. It supports 150+ block types across motion, looks, sound, events, control, sensing, operators, data, pen, and music categories.

project
  backdrops "Blue Sky"
  variable score = 0

  sprite Cat
    costumes "cat-a", "cat-b"
    sounds "Meow"
    position 0, 0
    size 100

    script
      when flag clicked
        forever
          move 10
          if on edge bounce
          next costume
          wait 0.2

    script
      when this sprite clicked
        play sound until done "Meow"
        change score by 1

See examples/ for complete game examples (Flappy Bird, Pong, platformer).

LLM Providers

ScratchScript auto-detects available providers in this order:

1. Ollama (if running locally) — ollama serve — no API key needed
2. Claude — set ANTHROPIC_API_KEY — default model: claude-sonnet-4-6
3. OpenAI — set OPENAI_API_KEY — default model: gpt-4o
4. Gemini — set GEMINI_API_KEY — default model: gemini-2.0-flash

Override with --provider and --model:

scratchscript generate --provider claude --model claude-sonnet-4-6 "make a game"

Architecture

User prompt -> LLM Provider -> ScratchScript DSL -> Reviewer -> Compiler -> .sb3 file
                                                       ^                |
                                                       |   (retry on    |
                                                       +--- error) -----+

Compiler pipeline:

• Lexer (compiler/lexer.py): indentation-aware tokenizer with support for keywords, strings, numbers, and color literals
• Parser (compiler/parser.py): recursive descent parser producing an AST
• Code Generator (compiler/codegen.py): AST to Scratch 3.0 project.json
• Bundler (compiler/bundler.py): project.json + downloaded assets into .sb3 ZIP
• Validator (compiler/validator.py): error checking with fuzzy match suggestions
• Decompiler (compiler/decompiler.py): reverse compilation from .sb3 back to ScratchScript

Other components:

• Reviewer (reviewer.py): LLM-based code review agent that catches logical and stylistic errors before compilation
• Providers (providers/): pluggable LLM backends (Ollama, Claude, OpenAI, Gemini)
• Asset Library (assets/library.py): downloads and caches Scratch costumes, sounds, and backdrops from the Scratch CDN
• CLI (cli.py): Click-based command-line interface
• Web UI (gui.py): Flask-based browser interface with real-time streaming and syntax highlighting

Development

pip install -e ".[dev]"
pytest tests/
ruff check src/

License

MIT