search

Mittagskogel / Sulfurous

MIT License
40 stars 22 forks source link

readme

Sulfurous

Research report - Institute of Networked and Embedded Systems Alpen-Adria-University

Alexander Pichler 03.10.2023 Version 1.2

1 Abstract

This research report serves as a final summary of my work at the Institute of Networked and Embedded Systems of the Alpen-Adria University regarding scratch and the Sulfurous player. Furthermore it will be shown why an external scratch player is still a useful alternative to the original scratch environment provided by the MIT.

The main part of my work at the NES was the development of additional features and a conversion system that works with the new sb3 standard for the sulfurous player. All of this development was done in Java Script.

Sulfurous has many features that are missing in the original scratch player that can be used to extend the projects you build. They are easy to use and implement and do not interfere with players who run the games in the normal scratch player.

2 Scratch

Untitled

Scratch is a programming language for children that was developed by the Massachusetts Institute of Technology (MIT) Media Lab Lifelong Kindergarten Group. It was first released in 2007 and has since become popular worldwide. Scratch allows children to create their own interactive stories, games, and animations using a visual programming language that is easy to learn. The platform also provides an online community where users can share their creations with others. In addition, Scratch has been used in schools and educational settings to teach children programming concepts and encourage creativity.

Why should you use Scratch?

Pros:

Cons:

2.1 How does Scratch work?

Scratch is single threaded by design.

The first thing to understand is that Scratch doesn’t run separate blocks of code at the same time. It takes turns between blocks (or threads as the Scratch source code refers to them). Before you execute any code in Scratch no threads are running. If you click the green flag then any block of code attached to a green flag hat block will be added to the active threads.

The green flag clicked block is not the only one that is able to add blocks to the active thread list.

Untitled

Hat blocks are unique because they are added to the active thread list in response to events whether that event is the green flag being pressed, the volume reaching a certain level or a broadcast message being received. These are the hat blocks that can be used in Scratch

Clones

If a clone is created it gets added to the active thread list.

It is worth noting that when a clone is created, the data for that clone is initialized when the block is encountered and not when the queued thread is executed.

That means it could be a problem if data changed between adding the block to the active threads and executing the block

Threads and yield points

To make the program look like it runs multithreaded so called yield points are used. Yield points are points in the program where the active thread is changed. This is necessary for the multithreaded look an feel of Scratch.

This process continues from thread to thread (and then back to the first) until all threads have completed execution. Now, the points at which execution will yield are -

  • At the end of any loop (forever, repeat, repeat until)
  • Each time a wait until block is false (as this is effectively a loop)
  • At a stop all (for obvious reasons)
  • After a broadcast and wait
  • At a wait block (again on every iteration until the required time has elapsed)

Why custom blocks are so useful

Custom blocks have the ability to ignore the yield points if the “Run without screen refresh” checkbox is ticked.

If this box is ticked the whole code of the custom block is executed without switching the active thread which means it runs in a blocking state.

All Quotes from: https://rokcoder.com/tips/inner-workings.html (accessed 2023-06-20)

Scratch as a game platform

Scratch allows you to share your game projects and build communities. The main page and the explore page makes it easy to find new games to play. On the explore site you can use filters to tailor the results to your liking. If you found a game you want to play the experience is seamless. You have the possibility to interact with other players and the creator via the commands feature.

As you can see the end user experience is really good. The one weak factor is that there is no way for a creator to get paid for their games. This is where platforms like Itch.io come in.

3 Itch.io

Itch.io is a video game distribution platform for indie games.

The platform allows you to upload and host games for all platforms. It is also allows to upload assets and tool for others to use.

It is a really easy process to upload and monetize your games the pricing options include:

The community experience on Itch.io is also way better than on scratch. Itch.io hosts game jams and you can write devlogs to keep your community updated.

4 Sulfurous

Sulfurous is a JavaScript player for Scratch. It allows to run Scratch projects faster and with more features.

Why?

Scratch used to work with Adobe Flash Player which is slow compared to JavaScript execution. We wanted to improve the overall performance of Scratch and add additional features to it. To do so we needed to either extend the original Scratch player or implement a new one. The second option was the better one. There were some projects that had the same goal in mind. We used Phosphorus as a starting point for our player.

4.1 Additional Features

Name the block “sulf.script” add a input of type “number or text” you can call it however you want

Name the block “sulf.script” add a input of type “number or text” you can call it however you want

Now you can use custom JS executions in your scratch projects

Now you can use custom JS executions in your scratch projects

You can try this example here:

Scratch: https://scratch.mit.edu/projects/237120625

Sulfurous: https://sulfurous.aau.at/#237120625

On Scratch you will see that nothing is happening when you press the Space Bar. If you run this project on sulfurous the color of the list background will change to red and a alert will show in the browser.

4.2 Inner workings

Sulfurous consists of 4 main components depending on which components are running certain features may not be available

FRONTEND BACKEND CONVERTER
Sulfurous SB2 ✔️ ✔️ ✖️
Sulfurous Cloud ✔️ ✔️ ✖️
Sulfurous SB3 ✔️ ✔️ ✔️
Sulfurous SB3+ Cloud ✔️ ✔️ ✔️

Frontend

The frontend is written in plain HTML CSS and JavaScript. All the inner workings of the sulfurous player that are needed to play the scratch game are on the frontend so no backend is needed to play sb2 projects. All new sb3 projects need to be converted back to sb2 via the backend to be played

This was true until 05/23 from now on the sulfurous player needs the backend to load Scratch projects from their servers

Player Program structure

Backend

The backend contains some of the logic for the conversion form the new sb3 format to the sb2 format that is used by the sulfurous player. Furthermore the cloudsave and some basic Admin tools are also in the backend

Converter

The converter receives the projects that need to be converted from the backend. This works via a bash script that looks for new work in a folder. The conversion is done with a modified version of the python converter script from RexScratch.

4.3 Naming

Why is Sulfurous called Sulfurous? Our predecessor was the Phosphorus player it used the Element phosphorus as its name we thought we should continue this and use the next element Sulfur. To stay more true to the original name we added the sufix “ous”.

Untitled

5 Alternative projects and feature comparison

5.1 Phosphorus

The Phosphorus player is the basis of our Sulfurous and was one of the best SB2 Players. It hast no SB3 support. Is was developed by Nathen on Github. The repository not available anymore. The player is still online but does not work since the change in the Scratch backend that also forced us to change to a mandatory backend for the sulfurous.

Link: https://phosphorus.github.io/ Repo:

https://github.com/nathan/phosphorus

5.2 Turbowarp

Turbowarp consists of three parts:

Repo:

TurboWarp

5.3 Forkphorus

Forkphorus is based on Phosphorus and Sulfurous it can play SB1 SB2 and SB3 projects.

It supports everything but JS execution. Forkphorus uses turbowarp in the backend to work with the new Scratch API changes.

It has additional settings that can be applied on the fly.

Untitled

Link: https://forkphorus.github.io/

Repo:

https://github.com/forkphorus/forkphorus

5.4 Leopardjs

Leopardjs converts scratch projects to JavaScript in a way that the code is well formatted and human readable that allows a developer to port their game to JavaScript with ease.

In my testing leopard did not work as well as expected most projects I wanted to try did not even load at all. Also SB2 projects are not supported by leopard it has now conversion to SB3. To use it with old projects you first have to convert them on your one to the new SB3 format.

Link: https://leopardjs.com/

Repo:

Leopard

5.5 Capabilities of different Scratch Players

Scratch Sulfurous Phosphorous Forkphorus Turbowarp Leopardjs
SB2 ✔️ ✔️ ❌ ✔️ ✔️ ❌
SB3 ✔️ ✔️ ❌ ✔️ ✔️ ✔️ / ❌
Cloud Variables ✔️ ✔️ ❌ ✔️ ✔️ ❌
JS execution ❌ ✔️ ❌ ❌ ❌ ✔️
Packaging for external use ❌ ✔️ ❌ ✔️ ✔️ ✔️
Self hosting ❌ ✔️ ✔️ ✔️ ✔️ ✔️

5.6 Benchmarks

Disclaimer:

Leopardjs does only support SB3 project but none of the benchmarks did load on it even after conversion to SB3

Scratch Sulfurous Phosphorous Forkphorus Turbowarp Leopardjs
BM1 301 / 23fps 302 / 170fps ❌ 302 / 100fps 301 / 30fps ❌
BM2 80.8 519.6 ❌ 229.6 749.1 ❌

6 Sulfurous on Itch.io

With sulfurous you are able to host your Scratch games on Itch.io.

You just need to load your project in Sulfurous and use the “Package ZIP” option. This will build a standalone version of sulfurous that automatically loads your project in package mode.

Untitled

To use the package version you just need to unzip the “OUTPUT.zip” file in the root of your webserver or upload the zip to Itch.io.

Itch.io will automatically do the unzipping and hosting for you if you set your kind of project to HTML

Untitled

7 Self hosting

Since sulfurous is completely open source your can host it yourself.

7.1 Requirements

7.2 How to

Replace TYPE with the appropriate version you want to run.

SB2: only old SB2 projects will work

SB3: old and new projects will work

Linux:

git clone https://github.com/Mittagskogel/Sulfurous
cd ./Sulfurous
./startSulfurous[TYPE].sh

Windows:

git clone https://github.com/Mittagskogel/Sulfurous
cd .\Sulfurous
.\startSulfurous[TYPE].bat

After the docker containers are up you can access sulfurous on http://localhost:3000