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.addWebStore(
|
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.addWebStore(
|
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 | ## Committing
|
102 | This project uses [semantic release](https://github.com/semantic-release/semantic-release)
|
103 | to ensure version bumps follow semver so that projects using the config don't
|
104 | break unexpectedly.
|
105 |
|
106 | In order to automatically determine the type of version bump necessary, semantic
|
107 | release 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
|
118 | where you would include `BREAKING CHANGE` and `ISSUES FIXED` sections if
|
119 | applicable.
|
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 |
|
133 | Use the [commitizen CLI](https://github.com/commitizen/cz-cli) to make commits
|
134 | formatted in this way:
|
135 |
|
136 | ```bash
|
137 | npm install -g commitizen
|
138 | npm install
|
139 | ```
|
140 |
|
141 | Now you're ready to make commits using `git cz`.
|
142 |
|
143 | ## Breaking changes
|
144 | If you're committing a change that makes an API change, or will
|
145 | otherwise require changes to existing code, ensure your commit specifies a
|
146 | breaking change. In your commit body, prefix the changes with "BREAKING CHANGE: "
|
147 | This will cause a major version bump so downstream projects must choose to upgrade
|
148 | and will not break the build unexpectedly.
|
149 |
|
150 | ## Donate
|
151 | We 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,
|
153 | and resource development efforts. Donations of any size are appreciated. Thank you!
|