Skip to content

Rewrite README prose #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aspizu merged 1 commit into from
Oct 8, 2026
Merged

Rewrite README prose #396

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
113 changes: 58 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
<h1 align="center">
<img src="docs/assets/goboscript.svg">
<img alt="" src="docs/assets/goboscript.svg" />
goboscript
</h1>

<p align="center">
<strong><a href="https://aspiz.uk/goboscript/ide">Launch IDE</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://aspiz.uk/goboscript/ide">IDE</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://aspiz.uk/goboscript/docs">Documentation</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://github.com/aspizu/sb2gs">Decompiler</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://github.com/goboscript/std">Standard Library</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://github.com/aspizu/backpack">Package Manager</a></strong>&nbsp;&nbsp;•&nbsp;
<strong><a href="https://github.com/aspizu/sb2gs">Decompiler</a></strong></p>
<strong><a href="https://github.com/aspizu/backpack">Package Manager</a></strong>
</p>

<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/og-image-dark.webp" />
<source media="(prefers-color-scheme: light)" srcset="docs/assets/og-image-light.webp" />
Expand All @@ -18,79 +20,80 @@
![Matrix](https://img.shields.io/matrix/goboscript%3Amatrix.org?logo=matrix&label=goboscript%3Amatrix.org) [![Discord](https://img.shields.io/discord/1462182798210109505?style=flat&logo=discord&label=Discord)](https://discord.gg/mKQqsJ6UtK) ![GitHub License](https://img.shields.io/github/license/aspizu/goboscript)

goboscript is a text-based programming language that compiles to Scratch. Write
Scratch projects in text, and compile it into a `.sb3` file -- which can be opened
in the Scratch editor, TurboWarp or be uploaded to the Scratch website.

goboscript makes developing advanced Scratch projects FAST. goboscript syntax is
concise and easy to read. Use a version-control system such as git. Use VS Code
or your favourite text-editor. Share code by copy-pasting. Use the standard library.
Refactor code using search and replace. Write scripts in other programming languages
to generate goboscript code. goboscript allows you to integrate external tooling and
workflows, such as using a script to generate costumes for a text rendering engine,
or loading in images into lists. goboscript has a powerful macro system similar to C.
The standard library includes many macros for frequently used patterns, such as
converting R, G, B values into a single integer. goboscript performs optimization,
removes unused code, and detects problems & mistakes.

goboscript is more than just an 1:1 mapping of Scratch blocks to text, it has
abstractions such as:

- Custom data-types using Structs and Enums.
- Functions that return values
- Default parameters for Functions & Procedures
- Operators such as: `!=`, `>=`, `<=`, `//` (Floor division), `not in`
- Local variables (Function-scoped)
- and more...

All these abstractions are compiled down to regular Scratch code.
your project as plain text and compile it into a `.sb3` file that opens in the
Scratch editor, TurboWarp, or on the Scratch website.

goboscript makes developing advanced Scratch projects fast. The syntax is concise
and easy to read, and because projects are plain text, you get the full power of
modern tooling:

- 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 -- write scripts in other languages that emit goboscript.
- External tools and workflows, such as generating costumes for a text rendering
engine or loading images into lists.

A powerful macro system (similar to C's) eliminates repetition, and the
[standard library](https://github.com/goboscript/std) ships macros for frequently
used patterns, like converting R, G, B values into a single integer. The compiler
optimizes your project, removes unused code, and detects problems and mistakes.

goboscript goes beyond a 1:1 mapping of Scratch blocks to text with abstractions
such as:

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

All of these abstractions compile down to regular Scratch code.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/cheatsheet-dark.png" />
<source media="(prefers-color-scheme: light)" srcset="docs/assets/cheatsheet-light.png" />
<img alt="goboscript overview & reference" src="docs/assets/cheatsheet-light.png" />
</picture>

[**Scratch Forum topic**](https://scratch.mit.edu/discuss/topic/747370/)&nbsp;&nbsp;•&nbsp;&nbsp;[**Made With goboscript Studio**](https://scratch.mit.edu/studios/51262907/)&nbsp;&nbsp;•&nbsp;&nbsp;[**Hacker News Discussion (Reached Frontpage)**](https://news.ycombinator.com/item?id=44026799)

## Sister Projects

- [std](https://github.com/goboscript/std): The goboscript standard library.
- [backpack](https://github.com/aspizu/backpack): Package manager for goboscript.
- [sb2gs](https://github.com/aspizu/sb2gs): Decompile Scratch projects (.sb3) into goboscript projects (.gs)
- [IDE](https://github.com/aspizu/goboscript-ide): Online IDE for goboscript, runs projects instantly in the browser.
- [MCP Server](https://github.com/aspizu/goboscript-mcp): Connects AI coding agents to the compiler and Turbowarp Desktop.
[**Scratch Forum Topic**](https://scratch.mit.edu/discuss/topic/747370/)&nbsp;&nbsp;•&nbsp;&nbsp;[**Made With Goboscript Studio**](https://scratch.mit.edu/studios/51262907/)&nbsp;&nbsp;•&nbsp;&nbsp;[**Hacker News Discussion (Reached Frontpage)**](https://news.ycombinator.com/item?id=44026799)

## Prior Art

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restore the unintentionally removed Sister Projects section

This deletion removes the entire Sister Projects section even though the commit describes only removing its MCP Server entry while preserving the other links and polishing the section. In particular, the goboscript-ide source repository is no longer linked anywhere in the README—the remaining IDE link opens the hosted application—so readers lose the documented route to that sister project's source. Restore the section and omit only the intentionally removed MCP entry.

Useful? React with 👍 / 👎.


For a complete list of all text-based scratch projects, see <https://scratch.mit.edu/discuss/topic/792714/>
For a complete list of text-based Scratch languages, see
<https://scratch.mit.edu/discuss/topic/792714/>.

**@retr0id** first presented the demoscene discord with his
[**boiga**](https://github.com/DavidBuchanan314/boiga) project. boiga works by
exporting Python data structures which nicely represent Scratch code in the form of
Python code. Soon after, I created my own re-implementation of boiga called Gobomatic.
[@retr0id](https://scratch.mit.edu/users/retr0id/) first presented his
[boiga](https://github.com/DavidBuchanan314/boiga) project to the demoscene
Discord. boiga exports Python data structures that neatly represent Scratch code
as Python source. Soon after, I created my own re-implementation of boiga called
Gobomatic.

## Contributing

See the [**Contributing Guide**](https://aspiz.uk/goboscript/docs/contributing.html) for
instructions on setting up the development environment and submitting Pull Requests.
See the [**Contributing Guide**](https://aspiz.uk/goboscript/docs/contributing.html)
for instructions on setting up a development environment and submitting pull
requests.

See [**CHANGELOG**](./CHANGELOG.md) for a list of changes.

## FOSS HACK 25

goboscript was one of the
[first-place winners](https://forum.fossunited.org/t/foss-hack-2025-results/5541) of
FOSS HACK 25, and was awarded a ₹50,000 prize. FOSS HACK 25 was a open-source
hackathon conducted on 22nd - 23rd February 2025 by the FOSS United Foundation.
During the 48-hour hackathon, I had worked on several goboscript issues and feature
implementation. Thank you FOSS United for the platform and opportunity.
[first-place winners](https://forum.fossunited.org/t/foss-hack-2025-results/5541)
of FOSS HACK 25 and was awarded a ₹50,000 prize. FOSS HACK 25 was a 48-hour
open-source hackathon conducted on 22nd – 23rd February 2025 by the FOSS United
Foundation. Over the weekend, I worked on several goboscript issues and features.
Thank you FOSS United.

## Star History

<a href="https://star-history.dera.page/#aspizu/goboscript&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&legend=top-left" />
</picture>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=aspizu/goboscript&type=date&legend=top-left" />
</picture>
</a>
Loading