UNPKG

5.09 kBMarkdownView Raw
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
9This requires you to have Node.js installed.
10
11In your own Node.js environment/application:
12```bash
13npm install https://github.com/LLK/scratch-storage.git
14```
15
16If you want to edit/play yourself (requires Git):
17```bash
18git clone https://github.com/LLK/scratch-storage.git
19cd scratch-storage
20npm 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
38var storage = require('scratch-storage');
39// continue to "Storage API Quick Start" section below
40```
41
42### Storage API Quick Start
43
44Once you have an instance of `scratch-storage`, add some web sources. For each source you'll need to provide a function
45to 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 */
51var 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
63Then, let the storage module know about your source:
64```js
65storage.addWebStore(
66 [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
67 getAssetUrl);
68```
69
70If you're using ES6 you may be able to simplify all of the above quite a bit:
71```js
72storage.addWebStore(
73 [AssetType.ImageVector, AssetType.ImageBitmap, AssetType.Sound],
74 asset => `https://assets.example.com/path/to/assets/${asset.assetId}.${asset.dataFormat}/get/`);
75```
76
77Once the storage module is aware of the sources you need, you can start loading assets:
78```js
79storage.load(AssetType.Sound, soundId).then(function (soundAsset) {
80 // `soundAsset` is an `Asset` object. File contents are stored in `soundAsset.data`.
81});
82```
83
84If you'd like to use `scratch-storage` with `scratch-vm` you must "attach" the storage module to the VM:
85```js
86vm.attachStorage(storage);
87```
88
89## Testing
90
91To run all tests:
92```bash
93npm test
94```
95
96To show test coverage:
97```bash
98npm run coverage
99```
100
101## Committing
102This project uses [semantic release](https://github.com/semantic-release/semantic-release)
103to ensure version bumps follow semver so that projects using the config don't
104break unexpectedly.
105
106In order to automatically determine the type of version bump necessary, semantic
107release expects commit messages to be formatted following
108[conventional-changelog](https://github.com/bcoe/conventional-changelog-standard/blob/master/convention.md).
109```
110<type>(<scope>): <subject>
111<BLANK LINE>
112<body>
113<BLANK LINE>
114<footer>
115```
116
117`subject` and `body` are your familiar commit subject and body. `footer` is
118where you would include `BREAKING CHANGE` and `ISSUES FIXED` sections if
119applicable.
120
121`type` is one of:
122* `fix`: A bug fix **Causes a patch release (0.0.x)**
123* `feat`: A new feature **Causes a minor release (0.x.0)**
124* `docs`: Documentation only changes
125* `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
126* `refactor`: A code change that neither fixes a bug nor adds a feature
127* `perf`: A code change that improves performance **May or may not cause a minor release. It's not clear.**
128* `test`: Adding missing tests or correcting existing tests
129* `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
130* `chore`: Other changes that don't modify src or test files
131* `revert`: Reverts a previous commit
132
133Use the [commitizen CLI](https://github.com/commitizen/cz-cli) to make commits
134formatted in this way:
135
136```bash
137npm install -g commitizen
138npm install
139```
140
141Now you're ready to make commits using `git cz`.
142
143## Breaking changes
144If you're committing a change that makes an API change, or will
145otherwise require changes to existing code, ensure your commit specifies a
146breaking change. In your commit body, prefix the changes with "BREAKING CHANGE: "
147This will cause a major version bump so downstream projects must choose to upgrade
148and will not break the build unexpectedly.
149
150## Donate
151We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a
152[donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community,
153and resource development efforts. Donations of any size are appreciated. Thank you!