Scratch++

Scratch++ is a Scratch mod that adds new blocks which can compile to normal Scratch. This allows for easily building advanced Scratch projects, which you can share normally.

How to use

Example: In the editor, write a script with a new block (like the power operator).

when 🏳️ clicked
say ( 5 ^ 3 )

Then, click on File > Compile to Scratch (.sb3). It should download an sb3 file that is fully compatible with normal Scratch.

Installation

1. Go to the releases tab, and download the zip file from the assets section.
2. Create a new folder on your computer, naming it whatever you want.
3. Extract the zip file to this folder.
4. Open index.html in Chrome or your preferred browser!

Building

This requires you to have Git and Node.js installed.

cd scratchplusplus #Folder dedicated to Scratch++

git clone --depth=1 https://github.com/ZXMushroom63/scratch-gui.git
cd scratch-gui
npm install

cd ..
git clone --depth=1 https://github.com/ZXMushroom63/scratch-vm.git
cd scratch-vm
npm install

cd ..
git clone --depth=1 https://github.com/ZXMushroom63/scratch-blocks.git
cd scratch-blocks
npm install
npm run translate
sudo npm run prepublish #Requires python 2 and Java installed!!!

cd ../scratch-gui
npm link ../scratch-blocks ../scratch-vm #Might also need sudo

# Now, to run it in localhost:
npm start

# Or, to make a build:
npm run build
# Outputs to the build folder

Current feature list

• fencing control blocks
• power operator
• previous costume & previous backdrop
• force set size
• point to X Y
• min operator
• max operator
• if operator
• replace x with y in z operator
• newline reporter
• decimal to hexadecimal operator
• color at my position reporter
• set list to x split by y
• Network extension
• fastpower
• letters x to y of string
• starts with
• ends with
• Physics extension

Testing

Documentation

You may want to review the documentation for Jest and Enzyme as you write your tests.

See jest cli docs for more options.

Running tests

NOTE: If you're a Windows user, please run these scripts in Windows cmd.exe instead of Git Bash/MINGW64.

Before running any tests, make sure you have run npm install from this (scratch-gui) repository's top level.

Main testing command

To run linter, unit tests, build, and integration tests, all at once:

npm test

Running unit tests

To run unit tests in isolation:

npm run test:unit

To run unit tests in watch mode (watches for code changes and continuously runs tests):

npm run test:unit -- --watch

You can run a single file of integration tests (in this example, the button tests):

$(npm bin)/jest --runInBand test/unit/components/button.test.jsx

Running integration tests

Integration tests use a headless browser to manipulate the actual HTML and javascript that the repo produces. You will not see this activity (though you can hear it when sounds are played!).

Note that integration tests require you to first create a build that can be loaded in a browser:

npm run build

Then, you can run all integration tests:

npm run test:integration

Or, you can run a single file of integration tests (in this example, the backpack tests):

$(npm bin)/jest --runInBand test/integration/backpack.test.js

If you want to watch the browser as it runs the test, rather than running headless, use:

USE_HEADLESS=no $(npm bin)/jest --runInBand test/integration/backpack.test.js

Note: If you are seeing failed tests related to chromedriver being incompatible with your version of Chrome, you may need to update chromedriver with:

npm install chromedriver@{version}

Troubleshooting

Ignoring optional dependencies

When running npm install, you can get warnings about optional dependencies:

npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]

You can suppress them by adding the no-optional switch:

npm install --no-optional

Further reading: Stack Overflow

Resolving dependencies

When installing for the first time, you can get warnings that need to be resolved:

npm WARN [email protected] requires a peer of babel-eslint@^8.0.1 but none was installed.
npm WARN [email protected] requires a peer of eslint@^4.0 but none was installed.
npm WARN [email protected] requires a peer of react-intl-redux@^0.7 but none was installed.
npm WARN [email protected] requires a peer of react-responsive@^4 but none was installed.

You can check which versions are available:

npm view react-intl-redux@0.* version

You will need to install the required version:

npm install  --no-optional --save-dev react-intl-redux@^0.7

The dependency itself might have more missing dependencies, which will show up like this:

user@machine:~/sources/scratch/scratch-gui (491-translatable-library-objects)$ npm install  --no-optional --save-dev react-intl-redux@^0.7
[email protected] /media/cuideigin/Linux/sources/scratch/scratch-gui
├── [email protected]
└── UNMET PEER DEPENDENCY [email protected]

You will need to install those as well:

npm install  --no-optional --save-dev react-responsive@^5.0.0

Further reading: Stack Overflow

Troubleshooting

If you run into npm install errors, try these steps:

1. run npm cache clean --force
2. Delete the node_modules directory
3. Delete package-lock.json
4. run npm install again

Publishing to GitHub Pages

You can publish the GUI to github.io so that others on the Internet can view it. Read the wiki for a step-by-step guide.

Understanding the project state machine

Since so much code throughout scratch-gui depends on the state of the project, which goes through many different phases of loading, displaying and saving, we created a "finite state machine" to make it clear which state it is in at any moment. This is contained in the file src/reducers/project-state.js .

It can be hard to understand the code in src/reducers/project-state.js . There are several types of data and functions used, which relate to each other:

Loading states

These include state constant strings like:

• NOT_LOADED (the default state),
• ERROR,
• FETCHING_WITH_ID,
• LOADING_VM_WITH_ID,
• REMIXING,
• SHOWING_WITH_ID,
• SHOWING_WITHOUT_ID,
• etc.

Transitions

These are names for the action which causes a state change. Some examples are:

• START_FETCHING_NEW,
• DONE_FETCHING_WITH_ID,
• DONE_LOADING_VM_WITH_ID,
• SET_PROJECT_ID,
• START_AUTO_UPDATING,

How transitions relate to loading states

Like this diagram of the project state machine shows, various transition actions can move us from one loading state to another:

Note: for clarity, the diagram above excludes states and transitions relating to error handling.

Example

Here's an example of how states transition.

Suppose a user clicks on a project, and the page starts to load with URL https://scratch.mit.edu/projects/123456 .

Here's what will happen in the project state machine:

1. When the app first mounts, the project state is NOT_LOADED.
2. The SET_PROJECT_ID redux action is dispatched (from src/lib/project-fetcher-hoc.jsx), with projectId set to 123456. This transitions the state from NOT_LOADED to FETCHING_WITH_ID.
3. The FETCHING_WITH_ID state. In src/lib/project-fetcher-hoc.jsx, the projectId value 123456 is used to request the data for that project from the server.
4. When the server responds with the data, src/lib/project-fetcher-hoc.jsx dispatches the DONE_FETCHING_WITH_ID action, with projectData set. This transitions the state from FETCHING_WITH_ID to LOADING_VM_WITH_ID.
5. The LOADING_VM_WITH_ID state. In src/lib/vm-manager-hoc.jsx, we load the projectData into Scratch's virtual machine ("the vm").
6. When loading is done, src/lib/vm-manager-hoc.jsx dispatches the DONE_LOADING_VM_WITH_ID action. This transitions the state from LOADING_VM_WITH_ID to SHOWING_WITH_ID
7. The SHOWING_WITH_ID state. Now the project appears normally and is playable and editable.

Donate

We provide Scratch free of charge, and want to keep it that way! Please consider making a donation to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!