Skip to content

Commit dbdbf6f

Browse files
CrispStrobeCrispStrobe
authored
Update README.md
1 parent f0e3b1f commit dbdbf6f

1 file changed

Lines changed: 129 additions & 89 deletions

File tree

‎README.md‎

Lines changed: 129 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,162 +1,202 @@
1-
# **Scratch GUI with LEGO BOOST and Xcratch Integration**
1+
# Scratch GUI with LEGO BOOST and Xcratch Integration
2+
3+
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.
24

3-
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.
45
**Live Demo:** [https://crispstrobe.github.io/scratch-gui/](https://crispstrobe.github.io/scratch-gui/)
56

6-
## **Features**
7+
## Features
78

8-
* All the features of the Xcratch project.
9-
* Fix for the LEGO BOOST Distance Sensor.
10-
* Support for the LEGO BOOST LED Light (88005).
11-
* Custom German (de) translations for new hardware blocks.
9+
- All the features of the Xcratch project
10+
- Fix for the LEGO BOOST Distance Sensor
11+
- Support for the LEGO BOOST LED Light (88005)
12+
- Custom German (de) translations for new hardware blocks
1213

13-
## **Acknowledgments**
14+
## Acknowledgments
1415

15-
* **Scratch Team** for the original Scratch and the Scratch Foundation for maintaining Scratch 3.0.
16-
* **Xcratch/yokobond** for the extensible Scratch mod.
17-
* **afpeuti** for the initial LEGO BOOST distance sensor implementation.
16+
- **Scratch Team** for the original Scratch and the Scratch Foundation for maintaining Scratch 3.0
17+
- **Xcratch/yokobond** for the extensible Scratch mod
18+
- **afpeuti** for the initial LEGO BOOST distance sensor implementation
1819

19-
## **Development & Deployment Guide**
20+
## Development & Deployment Guide
2021

21-
### **Prerequisites**
22+
### Prerequisites
2223

23-
* [Git](https://git-scm.com/)
24-
* [Node.js](https://nodejs.org/) (recommended using a Long-Term Support (LTS) version)
25-
* [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) (recommended for managing Node.js versions)
24+
- [Git](https://git-scm.com/)
25+
- [Node.js](https://nodejs.org/) (recommended using a Long-Term Support (LTS) version)
26+
- [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) (recommended for managing Node.js versions)
2627

27-
### **Local Development Setup**
28+
### Local Development Setup
2829

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

31-
#### **Step 1: Clone All Three Repositories**
32+
#### Step 1: Clone All Three Repositories
33+
34+
Create a parent directory (e.g., `~/code/`) and clone your forks of all three projects into it.
3235

33-
Create a parent directory (e.g., \~/code/) and clone your forks of all three projects into it.
34-
\# Create a development directory
35-
mkdir \-p \~/code
36-
cd \~/code
36+
```bash
37+
# Create a development directory
38+
mkdir -p ~/code
39+
cd ~/code
3740

38-
\# Clone the required repositories
39-
git clone https://github.com/CrispStrobe/scratch-l10n.git
40-
git clone https://github.com/CrispStrobe/scratch-vm.git
41+
# Clone the required repositories
42+
git clone https://github.com/CrispStrobe/scratch-l10n.git
43+
git clone https://github.com/CrispStrobe/scratch-vm.git
4144
git clone https://github.com/CrispStrobe/scratch-gui.git
45+
```
46+
47+
#### Step 2: Set Up the Node.js Environment
4248

43-
#### **Step 2: Set Up the Node.js Environment**
49+
Use nvm to switch to the Node.js version specified in the projects' `.nvmrc` files. This ensures a stable and compatible environment.
4450

45-
Use nvm to switch to the Node.js version specified in the projects' .nvmrc files. This ensures a stable and compatible environment.
46-
\# Navigate into any of the project directories
47-
cd \~/code/scratch-gui
51+
```bash
52+
# Navigate into any of the project directories
53+
cd ~/code/scratch-gui
4854

49-
\# Let nvm read the .nvmrc file and switch to the correct Node.js version
50-
\# If the version isn't installed, nvm will provide the command to install it.
55+
# Let nvm read the .nvmrc file and switch to the correct Node.js version
56+
# If the version isn't installed, nvm will provide the command to install it
5157
nvm use
58+
```
5259

53-
#### **Step 3: Build and Link scratch-l10n**
60+
#### Step 3: Build and Link scratch-l10n
5461

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

57-
1. **(Optional) Add Custom Translations:** If you are adding or modifying translations, make the changes to the JSON files inside the scratch-l10n directory now.
58-
2. **Build and Link:**
59-
\# Navigate to your l10n fork
60-
cd \~/code/scratch-l10n
64+
1. **(Optional) Add Custom Translations:** If you are adding or modifying translations, make the changes to the JSON files inside the scratch-l10n directory now.
65+
66+
2. **Build and Link:**
67+
68+
```bash
69+
# Navigate to your l10n fork
70+
cd ~/code/scratch-l10n
6171

62-
\# Install dependencies and build the project
63-
\# This generates the necessary locale files.
64-
npm install
65-
npm run build
72+
# Install dependencies and build the project
73+
# This generates the necessary locale files
74+
npm install
75+
npm run build
76+
77+
# Create a global symlink to this local package
78+
npm link
79+
```
6680

67-
\# Create a global symlink to this local package
68-
npm link
81+
This makes your custom scratch-l10n package available to other local projects.
6982

70-
This makes your custom scratch-l10n package available to other local projects.
83+
#### Step 4: Build and Link scratch-vm
7184

72-
#### **Step 4: Build and Link scratch-vm**
85+
The Virtual Machine depends on the translations from scratch-l10n.
7386

74-
The Virtual Machine depends on the translations from scratch-l10n.
75-
\# Navigate to your vm fork
76-
cd \~/code/scratch-vm
87+
```bash
88+
# Navigate to your vm fork
89+
cd ~/code/scratch-vm
7790

78-
\# Install its dependencies
91+
# Install its dependencies
7992
npm install
8093

81-
\# Link it to your custom-built scratch-l10n package
94+
# Link it to your custom-built scratch-l10n package
8295
npm link scratch-l10n
8396

84-
\# Build the VM project
97+
# Build the VM project
8598
npm run build
8699

87-
\# Create a global symlink to this local VM package
100+
# Create a global symlink to this local VM package
88101
npm link
102+
```
89103

90-
#### **Step 5: Build and Run scratch-gui**
104+
#### Step 5: Build and Run scratch-gui
91105

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

94-
1. **Install Dependencies and Link:**
95-
\# Navigate to your gui project
96-
cd \~/code/scratch-gui
108+
1. **Install Dependencies and Link:**
97109

98-
\# Clean install using the legacy peer dependency flag to resolve conflicts
99-
rm \-rf node\_modules package-lock.json
100-
npm install \--legacy-peer-deps
110+
```bash
111+
# Navigate to your gui project
112+
cd ~/code/scratch-gui
101113

102-
\# Link it to your custom-built scratch-vm package
103-
npm link scratch-vm
114+
# Clean install using the legacy peer dependency flag to resolve conflicts
115+
rm -rf node_modules package-lock.json
116+
npm install --legacy-peer-deps
104117

105-
2. **Run the Local Development Server:**
106-
npm start
118+
# Link it to your custom-built scratch-vm package
119+
npm link scratch-vm
120+
```
107121

108-
You can now access your fully custom build at **http://localhost:8601/**.
122+
2. **Run the Local Development Server:**
109123

110-
### **Deployment to GitHub Pages**
124+
```bash
125+
npm start
126+
```
127+
128+
You can now access your fully custom build at **http://localhost:8601/**.
129+
130+
### Deployment to GitHub Pages
111131

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

114-
1. **Run the Deploy Script:** The package.json is pre-configured to handle the build and deployment process.
115-
\# From within the scratch-gui directory
116-
npm run deploy
134+
1. **Run the Deploy Script:** The package.json is pre-configured to handle the build and deployment process.
135+
136+
```bash
137+
# From within the scratch-gui directory
138+
npm run deploy
139+
```
140+
141+
This script will automatically build the project and push the contents of the build/ folder to the gh-pages branch of your repository.
117142

118-
This script will automatically build the project and push the contents of the build/ folder to the gh-pages branch of your repository.
119-
2. **Verify Deployment:**
120-
* Wait a few minutes for GitHub Pages to update.
121-
* Open your site: https://crispstrobe.github.io/scratch-gui/
122-
* 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.
143+
2. **Verify Deployment:**
144+
- Wait a few minutes for GitHub Pages to update
145+
- Open your site: https://crispstrobe.github.io/scratch-gui/
146+
- 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
123147

124-
## **Original Scratch GUI Documentation**
148+
## Original Scratch GUI Documentation
149+
150+
*The original README from scratchfoundation/scratch-gui follows for general information on testing and contribution.*
125151

126-
*(The original README from scratchfoundation/scratch-gui follows for general information on testing and contribution.)*
127152
Scratch GUI is a set of React components that comprise the interface for creating and running Scratch 3.0 projects.
128153

129-
### **Installation**
154+
### Installation
155+
156+
This requires you to have Git and Node.js installed. To use this in your own application:
130157

131-
This requires you to have Git and Node.js installed. To use this in your own application:
158+
```bash
132159
npm install https://github.com/scratchfoundation/scratch-gui.git
160+
```
133161

134-
To develop scratch-gui itself:
135-
git clone https://github.com/scratchfoundation/scratch-gui.git
136-
cd scratch-gui
162+
To develop scratch-gui itself:
163+
164+
```bash
165+
git clone https://github.com/scratchfoundation/scratch-gui.git
166+
cd scratch-gui
137167
npm install
168+
```
169+
170+
### Running
138171

139-
### **Running**
172+
Open a terminal in the repository and run:
140173

141-
Open a terminal in the repository and run:
174+
```bash
142175
npm start
176+
```
143177

144178
Then go to [http://localhost:8601/](http://localhost:8601/).
145179

146-
### **Testing**
180+
### Testing
147181

148-
Before running any tests, make sure you have run npm install.
182+
Before running any tests, make sure you have run `npm install`.
149183

150-
* **Run all tests (lint, unit, integration):**
184+
- **Run all tests (lint, unit, integration):**
185+
```bash
151186
npm test
187+
```
152188

153-
* **Run unit tests:**
189+
- **Run unit tests:**
190+
```bash
154191
npm run test:unit
192+
```
155193

156-
* **Run integration tests:**
157-
npm run build
194+
- **Run integration tests:**
195+
```bash
196+
npm run build
158197
npm run test:integration
198+
```
159199

160-
### **Donate**
200+
### Donate
161201

162-
We provide Scratch free of charge, and want to keep it that way\! Please consider making a [donation](https://www.scratchfoundation.org/donate) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you\!
202+
We provide Scratch free of charge, and want to keep it that way! Please consider making a [donation](https://www.scratchfoundation.org/donate) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!

0 commit comments

Comments
 (0)