scratch-mobile-app

scratch-mobile-app allows you to turn your Scratch projects into standalone mobile apps with ease! Experience your favorite Scratch creations on the go with offline functionality.

Features

• Turn Scratch projects into offline mobile apps.
• Tested on Android but should work on iOS too.

Getting Started

Follow these instructions to package your Scratch project in scratch-mobile-app, turning your .sb3 Scratch file into a mobile app (e.g., an .apk for Android) that you can install on your phone and use just like any other app.

The instructions are for Android built on Ununtu Linux. However, the project is expected to work on iOS too due to the multiplatform nature of Flutter. Contribution is welcome!

Using the Pre-Built Docker Container (Recommended)

Prerequisites

Install Docker

Generate APK from Your Own Scratch SB3 Project

1. Place your files to some directory, e.g. ~/my-cool-scratch-project

   • project.sb3: Scratch project
   • project.png: icon (optional)
   • project.yaml: configuration of app name (optional)

     name: "My Scratch App"

2. Change to the directory

cd ~/my-cool-scratch-project

3. Verify the project.sb3 file is there:

petr@petr:~/my-cool-scratch-project$ ls
project.sb3

4. Run the docker

docker run --rm -e UID=$(id -u) -e GID=$(id -g) -v $(pwd):/workspace ghcr.io/petrkaderabek/scratch-mobile-app:latest

5. Verify the project.apk and licence files were created:

petr@petr:~/my-cool-scratch-project$ ls
project.3rd_party_licenses.md  project.apk  project.sb3

6. Install project.apk on your mobile device.

Upload project.apk to your Android phone and install it. You are ready to run your own mobile app!

Generate Example APK

If you just want to try this tool on the default SB3 file included within, follow these steps to get the APK:

1. Change to a directory the results will be placed in

cd ~/Documents

2. Run the docker

docker run --rm -e "USE_DEFAULT_SB3=true" -e UID=$(id -u) -e GID=$(id -g) -v $(pwd):/workspace ghcr.io/petrkaderabek/scratch-mobile-app:latest

3. Verify the project.apk and licence files were created:

petr@petr:~/Documents$ ls project.*
project.3rd_party_licenses.md  project.apk

4. Install project.apk on your mobile device.

Upload project.apk to your Android phone and install it.

Local Installation

Local installation is needed, if you want to change code of the repo. If you just need to build APK file from your Scratch project, the above-mentioned Docker way is much simpler.

Prerequisites

• Node.js: Ensure you have Node.js v20 installed. NVM
• Flutter: Install Flutter with Android support. Flutter Installation Guide
• xmlstarlet: Command-line tool for reading/editing xml files (apt install xmlstarlet)

Installation

1. Clone this repository:

   git clone https://github.com/petrkaderabek/scratch-mobile-app.git

2. Navigate into the project directory:

   cd scratch-mobile-app

3. Replace default assets with your ones:

   • default_workspace/project.sb3: your own Scratch project,
   • default_workspace/project.png: icon of your new mobile app.
   • default_workspace/project.yaml: config of your new mobile app, currently contains app name only.

4. Build scratch-mobile-app.apk

   make all

5. Install scratch-mobile-app.apk on your mobile device.

Upload scratch-mobile-app.apk to your phone and install it. You can run your app!

Contributing

Contributions are welcome! Please submit a pull request or open an issue for any suggestions or bugs.

Steps for Contributing

1. Fork the repository.

2. Create your feature branch:

   git checkout -b feature/AmazingFeature

3. Commit your changes:

   git commit -m 'Add some AmazingFeature'

4. Push to the branch:

   git push origin feature/AmazingFeature

5. Open a pull request.

Debugging the React part

This app has two main components:

1. React.js app in the react-app dir.
2. Flutter wrapper running the javascript from point 1.

If you want to debug the React part separately, perform the following steps:

1. Ensure your project is already copied to react-app/public/project.sb3 (done by process_workspace.sh if run before).
2. Run the React HTTP server with the app by

   cd react-app
   npm start

3. Open the app in a browser at http://localhost:3000.