1 | ## scratch-storage
|
2 | #### Scratch Storage is a library for loading and storing project and asset files for Scratch 3.0
|
3 |
|
4 | [![Build Status](https://travis-ci.org/LLK/scratch-storage.svg?branch=develop)](https://travis-ci.org/LLK/scratch-storage)
|
5 | [![Coverage Status](https://coveralls.io/repos/github/LLK/scratch-storage/badge.svg?branch=develop)](https://coveralls.io/github/LLK/scratch-storage?branch=develop)
|
6 | [![Greenkeeper badge](https://badges.greenkeeper.io/LLK/scratch-storage.svg)](https://greenkeeper.io/)
|
7 |
|
8 | ## Installation
|
9 | This requires you to have Node.js installed.
|
10 |
|
11 | In your own Node.js environment/application:
|
12 | ```bash
|
13 | npm install https://github.com/LLK/scratch-storage.git
|
14 | ```
|
15 |
|
16 | If you want to edit/play yourself (requires Git):
|
17 | ```bash
|
18 | git clone https://github.com/LLK/scratch-storage.git
|
19 | cd scratch-storage
|
20 | npm install
|
21 | ```
|
22 |
|
23 | ## Using scratch-storage
|
24 |
|
25 | ### From HTML
|
26 |
|
27 | ```html
|
28 | <script src="scratch-storage/dist/web/scratch-storage.js"></script>
|
29 | <script>
|
30 | var storage = new Scratch.Storage();
|
31 | // continue to "Storage API Quick Start" section below
|
32 | </script>
|
33 | ```
|
34 |
|
35 | ### From Node.js / Webpack
|
36 |
|
37 | ```js
|
38 | var storage = require('scratch-storage');
|
39 | // continue to "Storage API Quick Start" section below
|
40 | ```
|
41 |
|
42 | ### Storage API Quick Start
|
43 |
|
44 | Once you have an instance of `scratch-storage`, add some web sources. For each source you'll need to provide a function
|
45 | to generate a URL for a supported type of asset:
|
46 | ```js
|
47 | /**
|
48 | * @param {Asset} asset - calculate a URL for this asset.
|
49 | * @returns {string} a URL to download a project asset (PNG, WAV, etc.)
|
50 | */
|
51 | var getAssetUrl = function (asset) {
|
52 | var assetUrlParts = [
|
53 | 'https://assets.example.com/path/to/assets/',
|
54 | asset.assetId,
|
55 | '.',
|
56 | asset.dataFormat,
|
57 | '/get/'
|
58 | ];
|
59 | return assetUrlParts.join('');
|
60 | };
|
61 | ```
|
62 |
|
63 | Then, let the storage module know about your source:
|
64 | ```js
|
65 | storage.addWebSource(
|
66 | [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
|
67 | getAssetUrl);
|
68 | ```
|
69 |
|
70 | If you're using ES6 you may be able to simplify all of the above quite a bit:
|
71 | ```js
|
72 | storage.addWebSource(
|
73 | [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
|
74 | asset => `https://assets.example.com/path/to/assets/${asset.assetId}.${asset.dataFormat}/get/`);
|
75 | ```
|
76 |
|
77 | Once the storage module is aware of the sources you need, you can start loading assets:
|
78 | ```js
|
79 | storage.load(AssetType.Sound, soundId).then(function (soundAsset) {
|
80 | // `soundAsset` is an `Asset` object. File contents are stored in `soundAsset.data`.
|
81 | });
|
82 | ```
|
83 |
|
84 | If you'd like to use `scratch-storage` with `scratch-vm` you must "attach" the storage module to the VM:
|
85 | ```js
|
86 | vm.attachStorage(storage);
|
87 | ```
|
88 |
|
89 | ## Testing
|
90 |
|
91 | To run all tests:
|
92 | ```bash
|
93 | npm test
|
94 | ```
|
95 |
|
96 | To show test coverage:
|
97 | ```bash
|
98 | npm run coverage
|
99 | ```
|
100 |
|
101 | ## Donate
|
102 | We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a
|
103 | [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community,
|
104 | and resource development efforts. Donations of any size are appreciated. Thank you!
|