joshlory / scratch-storage

Load and store project and asset files for Scratch 3.0

scratch-storage

Scratch Storage is a library for loading and storing project and asset files for Scratch 3.0

Installation

This requires you to have Node.js installed.

In your own Node.js environment/application:

npm install https://github.com/LLK/scratch-storage.git

If you want to edit/play yourself (requires Git):

git clone https://github.com/LLK/scratch-storage.git
cd scratch-storage
npm install

Using scratch-storage

From HTML

<script src="scratch-storage/dist/web/scratch-storage.js"></script>
<script>
    var storage = new Scratch.Storage();
    // continue to "Storage API Quick Start" section below
</script>

From Node.js / Webpack

var storage = require('scratch-storage');
// continue to "Storage API Quick Start" section below

Storage API Quick Start

Once you have an instance of scratch-storage, add some web sources. For each source you'll need to provide a function to generate a URL for a supported type of asset:

/**
 * @param {Asset} asset - calculate a URL for this asset.
 * @returns {string} a URL to download a project asset (PNG, WAV, etc.)
 */
var getAssetUrl = function (asset) {
    var assetUrlParts = [
        'https://assets.example.com/path/to/assets/',
        asset.assetId,
        '.',
        asset.dataFormat,
        '/get/'
    ];
    return assetUrlParts.join('');
};

Then, let the storage module know about your source:

storage.addWebSource(
    [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
    getAssetUrl);

If you're using ES6 you may be able to simplify all of the above quite a bit:

storage.addWebSource(
    [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
    asset => `https://assets.example.com/path/to/assets/${asset.assetId}.${asset.dataFormat}/get/`);

Once the storage module is aware of the sources you need, you can start loading assets:

storage.load(AssetType.Sound, soundId).then(function (soundAsset) {
    // `soundAsset` is an `Asset` object. File contents are stored in `soundAsset.data`.
});

If you'd like to use scratch-storage with scratch-vm you must "attach" the storage module to the VM:

vm.attachStorage(storage);

Testing

To run all tests:

npm test

To show test coverage:

npm run coverage

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!