goboscript: a text language that compiles to Scratch projects

Scratch projects as text files

goboscript is described as a text-based programming language that compiles to Scratch. You write your project as plain text and compile it into a.sb3 file that opens in the Scratch editor, in TurboWarp, or on the Scratch website.

That output target is the point. A.sb3 file is the normal Scratch project format, so the compiled result is not a special artefact that only this toolchain can run. It is the file you would have got from the editor, which means a project can be developed in text and still be opened, shared and extended by anyone using Scratch as usual.

The reason to do that at all is scale and workflow. The README lists what plain text buys you. Version control with git. Any editor you like, VS Code or your favourite text editor. Sharing code by copy-pasting. Refactoring with search and replace. Code generation, meaning you can write scripts in other languages that emit goboscript. And external tools and workflows, such as generating costumes for a text rendering engine or loading images into lists.

Those items are not compiler features, they are editor features, and they only exist because the source is text. The primary language is Rust, the licence is MIT, the homepage is aspiz.uk/goboscript/docs, and the repository is on the main branch with the last push on 2026-10-21.

The abstractions that the block editor has no room for

The README is explicit that goboscript goes beyond a 1:1 mapping of Scratch blocks to text, and it lists what that buys.

Custom data types using Structs and Enums. Functions that return values. Default parameters for functions and procedures. Operators such as !=, >=, <=, // for floor division, and not in. And local variables that are function-scoped.

Then the sentence that keeps the whole thing honest: all of these abstractions compile down to regular Scratch code. There is no runtime, no virtual machine and no interpreter in the .sb3 file. The output is the same kind of Scratch project the editor produces, with the extra features compiled into blocks and variables.

That is what makes the tool compatible with the wider Scratch ecosystem rather than a separate thing. A TurboWarp project, a Scratch website upload and a project opened by a teacher in the editor all behave the same way, because there is nothing in the file that only goboscript understands.

The compiler does more than translate. The README says it optimizes your project, removes unused code, and detects problems and mistakes, so a project that compiles is also a project with its dead code stripped and its errors found before anyone opens it in Scratch.

Macros do the work the copy-paste would otherwise do

The macro system is the feature the README leads with after the workflow list, and it describes it as similar to C's. The stated purpose is that it eliminates repetition, and the standard library in its own repository ships macros for frequently used patterns, with converting R, G, B values into a single integer given as the example.

That example is more instructive than it looks. Scratch has no bitwise operators and no way to write a function that returns a value, so anything that looks like arithmetic on a colour has to be inlined as a block sequence, copy-pasted, every time. A macro solves exactly that: the source says what it means, and the compiler expands it into the blocks.

The standard library is a separate repository, goboscript/std, rather than part of the compiler, and the README links it alongside the other parts of the toolchain. That separation is the same idea as a package manager rather than a built-in library, and it means the compiler itself stays small.

The wider toolchain follows the same pattern. The README's header links an IDE at aspiz.uk/goboscript/ide, the documentation, a decompiler in the sb2gs repository, the standard library, and a package manager at aspizu/backpack. A decompiler alongside a compiler is the useful pairing here, because it is what lets you recover something like source from an existing .sb3 file.

A Rust compiler with a generated parser and a web build

The Cargo.toml describes the implementation, and the dependency list is a good map of how a compiler is put together.

The parsing side is lalrpop-util, with lalrpop as a build dependency, which means the grammar is generated at build time from a parser generator rather than hand-written as a recursive descent parser, and logos handles the lexer. The output side uses serde and serde_json, with serde_json configured to preserve order, which matters when the output has to keep the layout a Scratch project expects. The zip crate with deflate is what writes the .sb3 archive.

The command line is clap with derive, and the error reporting uses annotate-snippets, which is the crate that renders compiler errors as a source snippet with a caret under the offending token. That choice shows up directly in the experience of using the compiler.

The library target is named libgoboscript and is built as both a cdylib and an rlib. That pairing is the web IDE's reason to exist: wasm-bindgen, tsify and js-sys are in the dependency list, and there is a separate target section for wasm32, so the compiler can be compiled to WebAssembly and run in the browser rather than on a server.

The rest of the list is ordinary compiler infrastructure with a few entries that reveal the scope. csscolorparser handles colour literals, semver is there for version handling, md-5 for checksums, reqwest with blocking and json for network calls, glob and walkdir for file traversal, directories for platform-specific config paths, and suggestions, which is a crate for producing editor suggestions, so the compiler can report completions to an editor that asks for them.

Building, testing and shipping the documentation

The repository uses a justfile for the developer tasks, and the two targets are short enough to read at a glance:

gdsl:
    python gdsl.py
    cargo +nightly fmt
    cargo fix --allow-dirty

test:
    uv run tools/run.py tests/*

The gdsl target regenerates something from the gdsl.py script and then runs nightly rustfmt plus cargo fix with --allow-dirty, so the generated code and the fixups happen in one step. The test target is a Python driver that takes the tests directory, run through uv.

The documentation has its own toolchain, and it is a different one from the compiler's. The Python project is named goboscript-docs and requires Python 3.10 or newer, with mkdocs at a pinned 1.6.1 and the Material theme, plus plugins for git authors, git committers and localized revision dates. The JavaScript side is a pnpm workspace, and the scripts in package.json build the docs with mkdocs in strict mode, then move the generated redirects into place:

    "build:docs": "pnpm --dir docs/javascripts run build && rm -rf site && MKDOCS_GIT_COMMITTERS_APIKEY=\"${MKDOCS_GIT_COMMITTERS_APIKEY:-${GITHUB_TOKEN:-$(gh auth token 2>/dev/null)}}\" NO_MKDOCS_2_WARNING=1 uv run --locked mkdocs build --strict --site-dir site/goboscript/docs && mv site/goboscript/docs/_redirects site/_redirects",
    "dev:docs": "pnpm run build:docs && wrangler dev",
    "deploy:docs": "pnpm run build:docs && wrangler deploy",

The dev and deploy scripts both go through wrangler, which is the Cloudflare Workers command line, and wrangler.jsonc sits at the repository root. So the documentation site is served from Cloudflare rather than from a static host, which fits a project whose main product is a browser IDE.

The repository also carries flake.nix and default.nix for a reproducible development environment, a .goreleaser.yaml for the release binaries, editors/ for editor support, a cheatsheet/ directory, and examples including an Advent of Code 2024 project and a font_engine example.

The lineage runs through boiga and the Scratch forum

The Prior Art section is short and it explains where the idea came from.

@retr0id first presented his boiga project to the demoscene Discord. boiga exports Python data structures that neatly represent Scratch code as Python source. Soon after, the author of goboscript created his own re-implementation of boiga called Gobomatic.

That is the whole prior art story, and it is also the clearest statement of how goboscript differs from its ancestor. boiga is a Python library that emits Scratch code as Python data structures, so you stay in Python and use a library. goboscript is a separate text language with its own grammar, its own macro system, its own standard library and its own compiler, and the macros are expanded by the compiler rather than by a Python function.

The README also points to a Scratch forum topic with a complete list of text-based Scratch languages, which is the reference for anyone comparing the options, and to a discussion thread on Hacker News that reached the frontpage.

The project has been recognised outside its own community as well. goboscript was one of the first-place winners of FOSS HACK 25, a 48-hour open-source hackathon held on 22 and 23 February 2025 by the FOSS United Foundation, and it was awarded a prize of ₹50,000.

MIT, and a manifest version ahead of the last tag

The licence is MIT and the crate metadata names Priyanshu Dangare as the author, with the category compilers. The manifest version is 3.3.0, while the most recent GitHub release is v3.2.1 from 2025-05-22, before v3.2.0 from 2025-05-20 and v3.1.1 from 2025-03-16.

So the crate version and the last tagged release do not agree, and the gap is more than a patch. That is worth understanding before you pin a dependency, because a Cargo dependency resolves to a published crate version, while the git tags track the releases that the README's links and the web IDE are built from. The CHANGELOG.md at the repository root is where the project records what changed, and the README points at it for a list of changes.

The repository layout shows the pieces of the project separated by purpose rather than folded together. There is src for the compiler, tests for the suite, docs for the documentation site sources, tools for the test driver, examples for the sample projects, editors for editor integrations, and cheatsheet for the reference sheet. The gdsl.py and gdsl.txt files sit at the root next to the justfile, which is the generator and its output.

The documentation is published at aspiz.uk/goboscript/docs and the Contributing Guide is linked from the README, with instructions on setting up a development environment and submitting pull requests.

Editorial conclusion

goboscript fits a Scratch project that has outgrown the block editor, especially one that is version controlled, shared with a team or generated by another tool, since a text source with macros and functions is what makes those workflows possible. It is the wrong choice for a two-script classroom project, where the setup cost exceeds the benefit, and the wrong choice if you need to keep working in the block editor with other people who will not move. Verify first which Scratch runtime you are targeting, since the output opens in the Scratch editor, in TurboWarp or on the Scratch website, and read the CHANGELOG before upgrading, because the manifest version and the last tagged release in this repository do not match.

Frequently asked questions

Official sources

1. aspizu/goboscript on GitHub
2. License: MIT
3. Project website
4. README
5. Releases