goboscript - Convert text code to Scratch blocks, Scratch compiler written in Rust.

aspizu

goboscript

Installation and documentation

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 uploaded to the Scratch website.

goboscript makes developing advanced Scratch projects FAST. Its syntax is
concise and easy to read. Use version control systems like git. Use VS Code
or your favorite text editor. Share code by copy-pasting. Use the standard library.
Refactor using search and replace. Write scripts in other languages
to generate goboscript code. goboscript allows you to integrate external tools and
workflows, such as generating costumes for a text renderer,
or loading images into lists. It features a powerful macro system like C’s.
The standard library includes macros for common patterns (e.g., RGB to int).
It optimizes, removes unused code, and detects mistakes.

goboscript is not just a 1:1 mapping of Scratch blocks to text. It offers:

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

All these abstractions compile down to standard Scratch code.

Try it out using the Online goboscript IDE

Sister Projects

std: The goboscript standard library
backpack: Package manager for goboscript
sb2gs: Decompile Scratch projects (.sb3) into goboscript projects (.gs)
goboscript.ide: Online IDE for goboscript, runs projects instantly in-browser

@retr0id first presented the demoscene server with his boiga project (1). boiga works by exporting Python data structures representing Scratch code.

(1): https://github.com/DavidBuchanan314/boiga

Soon after, I created gobomatic, a reimplementation of boiga, with more block support and features.
The Python version of goboscript used gobomatic to generate Scratch projects.
Now, gobomatic is abandoned, and goboscript is ported to Rust.

FOSS HACK 25

goboscript won first place at FOSS HACK 25, receiving a ₹50,000 prize.

FOSS HACK 25 was a 48-hour open-source hackathon by FOSS United, held on Feb 22–23, 2025.

During the event, I worked on goboscript issues and features.
Thanks to FOSS United for the opportunity!

Last edited by aspizu (May 26, 2025 17:43:39)

Mr_rudy

Cool!

ajskateboarder

I love the syntax, but it would be cool to know what the “error” function does

Also, would it be possible to implement type safety at compile time, so any parameters to a custom block are checked before the final project is made?

Last edited by ajskateboarder (March 14, 2024 01:50:18)

W1-F1

This looks really cool!

aspizu

ajskateboarder wrote:
I love the syntax, but it would be cool to know what the “error” function does

Also, would it be possible to implement type safety at compile time, so any parameters to a custom block are checked before the final project is made?

log, error, warn are sa debugger blocks.

type-safety for custom blocks is definitely possible and in-scope, could you describe what features you would like for type-safety?

aspizu

insert 100 + 200 at my_list[2];
insert 100 + 200 at 2 of my_list;

Which one would you guys prefer?

Redstone1080

aspizu wrote:
Which one would you guys prefer?

The first one looks nice and is consistent with the rest of the language's syntax, so you should definitely consider implementing it, rather than the second one.

MagicCrayon9342

now there just needs to be library support and implementations for modding.

a building toolset would be cool. a command line utility to compile for various platforms.

scratchusername40

aspizu wrote:
(#5)
type-safety for custom blocks is definitely possible and in-scope, could you describe what features you would like for type-safety?

You shouldn't be able to put a bool in a string input, and vice versa. Also, this shouldn't just be for custom blocks but for the whole language.

aspizu

scratchusername40 wrote:
(#9)
You shouldn't be able to put a bool in a string input, and vice versa. Also, this shouldn't just be for custom blocks but for the whole language.

I think type-safety for the entire language would be very difficult to implement. The least I am going to promise is -
hint the user of a procedure (custom block) that what types are expected as arguments (inputs) to the procedure.

The minimum amount of type-safety needed to produce valid Scratch projects include things like:

If you put a value in a boolean-input, then goboscript will use a boolean coercion macro, which can be configured to any expression.
The default would be something like:

variable = 1 < 2;
if variable { ... }

Which would get compiled into:

variable = 1 < 2;
if not(variable = 0) { ... }

Which is exactly what the Python version of the compiler did, but this functionality was not configurable. I will add a way to change
what macro will be used to convert values into booleans.

MagicCrayon9342

scratchusername40 wrote:
aspizu wrote:
(#5)
type-safety for custom blocks is definitely possible and in-scope, could you describe what features you would like for type-safety?
You shouldn't be able to put a bool in a string input, and vice versa. Also, this shouldn't just be for custom blocks but for the whole language.

who needs type safety?

ajskateboarder

aspizu wrote:
scratchusername40 wrote:
(#9)
You shouldn't be able to put a bool in a string input, and vice versa. Also, this shouldn't just be for custom blocks but for the whole language.
I think type-safety for the entire language would be very difficult to implement. The least I am going to promise is -
hint the user of a procedure (custom block) that what types are expected as arguments (inputs) to the procedure.

So like type annotations in Python? Yeah, this would also be fine as well - hints are almost as good as checks

aspizu

ajskateboarder wrote:
(#12)
So like type annotations in Python? Yeah, this would also be fine as well - hints are almost as good as checks

Some level of type-checking would be possible. Think constant expressions.

Mr_rudy

not sure if you did this, but in python i can make an arry by doing

x = [a,b,c ]

since lists are technically arrays, i think it would be nice to be able to do somerthing like what python does

aspizu

Mr_rudy wrote:
#14
not sure if you did this, but in python i can make an arry by doing
x = [a,b,c ]
since lists are technically arrays, i think it would be nice to be able to do somerthing like what python does

As you can save data in a list without having to use add blocks to create the list at runtime in Scratch by manually adding entries in a list
monitor then saving your project, goboscript will allow you to load lists from text files (python version already supports this), and also
define the default (initial) state of the list in code.

This is the idea of the syntax for defining a list with initial values:

# This goes outside of any hat-block definitions (Same level as costumes, sounds, etc)
my_list = [1, 2, 3];

But you would not be able to put any reporter block such as username in there.

The next thing is to generate add to list blocks from a single statement.

There are two ways I could go about doing this, even both at the same time would be fine:

onflag {
    my_list = [1, 2, username()];
}
# same as:
onflag {
  delete my_list;
  add 1 to my_list;
  add 2 to my_list;
  add username() to my_list;
}

The second idea is to let multiple arguments in the add statement:

# the above example would be:
delete my_list;
add 1, 2, username() to my_list;

aspizu

I'm adding a command to create a new goboscript project

Create a new goboscript project

Usage: goboscript new [OPTIONS]

Options:
  -n, --name <NAME>
          Name of directory to create new project, if not given, the current directory is used, if this is a path to an existing directory, it must be empty
  -f, --fps/--frame-rate <FRAME_RATE>
          Custom frame rate, used by TurboWarp
  -c, --clones/--max-clones <MAX_CLONES>
          Custom maximum number of clones allowed, used by TurboWarp
      --limitless/--no-miscellaneous-limits
          Disable miscellaneous limits, used by TurboWarp
      --offscreen/--no-sprite-fencing
          Disable sprite fencing, used by TurboWarp
      --interpolate/--frame-interpolation
          Enable frame interpolation, used by TurboWarp
      --hqpen/--high-quality-pen
          Enable high quality pen, used by TurboWarp
  -W, --stage-width <STAGE_WIDTH>
          Custom stage width, used by TurboWarp
  -H, --stage-height <STAGE_HEIGHT>
          Custom stage height, used by TurboWarp
  -h, --help
          Print help

If you use any of the turbowarp options then it will create a goboscript.toml file.

What features should I add to the new command?

Mahdir2111

nice

dumorando

aspizu wrote:
goboscript

goboscript is the Scratch compiler. It lets you write Scratch projects in a text-based programming language. It outputs .sb3 files which can be opened in Scratch or Turbowarp. It is written in Rust and is designed to have fast compile times.

goboscript is text-based, so you can use Visual Studio Code to write Scratch projects, you can even use Github Copilot to help you write Scratch projects. goboscript also performs optimizations, has a powerful macro system which lets you do meta-programming. It even finds errors in your Scratch projects before you run them.

GitHub Repository

You can install it if you have the Rust toolchain.
cargo install goboscript
Example

for me https://aspizu.github.io/goboscript doesnt work and thats where all the documentation is

Mr_rudy

wild idea, but you could probably recreate the turbowarp extension loader from the turbowarp vm to add support for extensions which would create more complex projects, maybe extensions could be loaded like this

import('https://extensions.turbowarp.org/lab/text.js');

or from a file like this

import('./extensions/extension.js');

but this would be a pretty difficult task
or you could support for writing extensions in rust, either way it would be really cool

aspizu

dumorando wrote:
#18
for me https://aspizu.github.io/goboscript doesnt work and thats where all the documentation is

Yeah, I have to write the documentation for the rust version. There is a lot of work to be done, so it will take some time. For now you can use the old python version, the docs for that are at https://aspizu.github.io/goboscript-docs/

Discuss Scratch