Scratch GUI with LEGO BOOST and Xcratch Integration

This repository contains a fork of Scratch GUI, integrating custom extensions for LEGO BOOST hardware and features from the Xcratch project. It includes a patched scratch-vm to support additional sensor functionality.

Live Demo: https://crispstrobe.github.io/scratch-gui/

Features

All the features of the Xcratch project
Fix for the LEGO BOOST Distance Sensor
Support for the LEGO BOOST LED Light (88005)
Custom German (de) translations for new hardware blocks

Acknowledgments

Scratch Team for the original Scratch and the Scratch Foundation for maintaining Scratch 3.0
Xcratch/yokobond for the extensible Scratch mod
afpeuti for the initial LEGO BOOST distance sensor implementation

Development & Deployment Guide

Prerequisites

Git
Node.js (recommended using a Long-Term Support (LTS) version)
nvm (Node Version Manager) (recommended for managing Node.js versions)

Local Development Setup

This project depends on two other repositories: scratch-vm and scratch-l10n. The complete setup involves cloning all three and linking them locally.

Step 1: Clone All Three Repositories

Create a parent directory (e.g., ~/code/) and clone your forks of all three projects into it.

# Create a development directory
mkdir -p ~/code
cd ~/code

# Clone the required repositories
git clone https://github.com/CrispStrobe/scratch-l10n.git
git clone https://github.com/CrispStrobe/scratch-vm.git
git clone https://github.com/CrispStrobe/scratch-gui.git

Step 2: Set Up the Node.js Environment

Use nvm to switch to the Node.js version specified in the projects' .nvmrc files. This ensures a stable and compatible environment.

# Navigate into any of the project directories
cd ~/code/scratch-gui

# Let nvm read the .nvmrc file and switch to the correct Node.js version
# If the version isn't installed, nvm will provide the command to install it
nvm use

Step 3: Build and Link scratch-l10n

This project contains the text and translations for the Scratch interface. It must be built first.

(Optional) Add Custom Translations: If you are adding or modifying translations, make the changes to the JSON files inside the scratch-l10n directory now.
Build and Link:

# Navigate to your l10n fork
cd ~/code/scratch-l10n

# Install dependencies and build the project
# This generates the necessary locale files
npm install
npm run build

# Create a global symlink to this local package
npm link

This makes your custom scratch-l10n package available to other local projects.

Step 4: Build and Link scratch-vm

The Virtual Machine depends on the translations from scratch-l10n.

# Navigate to your vm fork
cd ~/code/scratch-vm

# Install its dependencies
npm install

# Link it to your custom-built scratch-l10n package
npm link scratch-l10n

# Build the VM project
npm run build

# Create a global symlink to this local VM package
npm link

Step 5: Build and Run scratch-gui

Finally, set up the GUI to use your custom-built VM.

Install Dependencies and Link:

# Navigate to your gui project
cd ~/code/scratch-gui

# Clean install using the legacy peer dependency flag to resolve conflicts
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

# Link it to your custom-built scratch-vm package
npm link scratch-vm

Run the Local Development Server:

npm start

You can now access your fully custom build at http://localhost:8601/.

Deployment to GitHub Pages

After you've tested your changes locally, you can deploy the application to your live GitHub Pages site.

Run the Deploy Script: The package.json is pre-configured to handle the build and deployment process.

# From within the scratch-gui directory
npm run deploy

This script will automatically build the project and push the contents of the build/ folder to the gh-pages branch of your repository.

Verify Deployment:
- Wait a few minutes for GitHub Pages to update
- Open your site: https://crispstrobe.github.io/scratch-gui/
- Perform a hard refresh in your browser (e.g., Cmd+Shift+R or Ctrl+Shift+R) to clear the cache and see the latest changes

Original Scratch GUI Documentation

The original README from scratchfoundation/scratch-gui follows for general information on testing and contribution.

Scratch GUI is a set of React components that comprise the interface for creating and running Scratch 3.0 projects.

Installation

This requires you to have Git and Node.js installed. To use this in your own application:

npm install https://github.com/scratchfoundation/scratch-gui.git

To develop scratch-gui itself:

git clone https://github.com/scratchfoundation/scratch-gui.git
cd scratch-gui
npm install

Running

Open a terminal in the repository and run:

npm start

Then go to http://localhost:8601/.

Testing

Before running any tests, make sure you have run npm install.

Run all tests (lint, unit, integration):
```
npm test
```
Run unit tests:
```
npm run test:unit
```
Run integration tests:
```
npm run build
npm run test:integration
```

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!