sb-edit

sb-edit is a javascript library for manipulating Scratch project files.

🚧 Warning!

sb-edit is still a work-in-progress. Not everything will work, and the API will probably change drastically. Don't get too comfortable the way things are. ;)

Importing and exporting

sb-edit allows importing and exporting a variety of Scratch project file types:

| File Format | Import | Export | | ------------------------------------------------------ | ---------- | -------------- | | Scratch 3.0 (.sb3) | ✅ Yes | ✅ Yes | | Scratch 2.0 (.sb2) | 🕒 Planned | 🕒 Planned | | Leopard | ❌ No | ✅ Yes | | scratchblocks | 👻 Maybe! | 🚧 In progress |

Editing

sb-edit can also be used to modify Scratch projects. A few things you can/will be able to do with sb-edit:

| | Add | Edit | Delete | | ------------------- | ---------- | ---------- | ---------- | | Sprites | 🕒 Planned | ✅ Yes | ✅ Yes | | Stage | ❌ No | ✅ Yes | ❌ No | | Scripts | 🕒 Planned | 🕒 Planned | 🕒 Planned | | Costumes and sounds | 🕒 Planned | 🕒 Planned | 🕒 Planned |

CLI Examples

To use the sb-edit CLI, first install it globally using the following command:

$ npm i -g sb-edit

Convert .sb3 project to Leopard

$ sb-edit --input path/to/project.sb3 --output path/to/output-folder

Convert .sb3 project to Leopard .zip

$ sb-edit --input path/to/project.sb3 --output path/to/output-folder.zip

Code Examples

Import an .sb3 file in Node

const { Project } = require("sb-edit");
const fs = require("fs");
const path = require("path");

const file = fs.readFileSync(path.join(__dirname, "myProject.sb3"));
const project = await Project.fromSb3(file);

console.log(project);

Export an .sb3 file in Node

const { Project } = require("sb-edit");
const fs = require("fs");
const path = require("path");

const project = /* Get yourself a `Project`... */;

const saveLocation = path.join(__dirname, "myProject.sb3");
fs.writeFileSync(saveLocation, Buffer.from(await project.toSb3()));

// `project` is now saved at ./myProject.sb3

Get Leopard code for project

const project = /* Get yourself a `Project`... */;

console.log(project.toLeopard({ printWidth: 100 })); // Optionally pass a Prettier config object!

Development

If you want to help develop the sb-edit package, you'll need to follow these steps:

Step 1: Download sb-edit and prepare to use

> git clone https://github.com/PullJosh/sb-edit.git
> cd sb-edit
> npm link # Allow using sb-edit in another local project

Step 2: Add sb-edit as dependency in another project

> cd my-cool-project
> npm init # This should be a node project
> npm link sb-edit # Similar to `npm install` but uses local version

Step 3: Modify sb-edit

If you make any changes to the sb-edit source code, you'll have to rebuild the package. Here's how:

> cd sb-edit # Cloned from Github and then edited
> npm run build # Build the new version!
> npm run watch # Watch files and rebuild automatically when code is changed

You can also run the Jest tests to make sure you didn't break anything:

> cd sb-edit # You're probably already here ;)
> npm test # Run Jest tests
> npm run lint # Check code for style problems

And finally, make sure everything is pretty:

> cd sb-edit
> npm run format # Format code to look nice with Prettier