@scratch/scratch-vm 11.0.0-beta.1

package/src/sprites/sprite.js

@@ -0,0 +1,177 @@
+const RenderedTarget = require('./rendered-target');
+const Blocks = require('../engine/blocks');
+const {loadSoundFromAsset} = require('../import/load-sound');
+const {loadCostumeFromAsset} = require('../import/load-costume');
+const newBlockIds = require('../util/new-block-ids');
+const StringUtil = require('../util/string-util');
+const StageLayering = require('../engine/stage-layering');
+
+class Sprite {
+    /**
+     * Sprite to be used on the Scratch stage.
+     * All clones of a sprite have shared blocks, shared costumes, shared variables,
+     * shared sounds, etc.
+     * @param {?Blocks} blocks Shared blocks object for all clones of sprite.
+     * @param {Runtime} runtime Reference to the runtime.
+     * @constructor
+     */
+    constructor (blocks, runtime) {
+        this.runtime = runtime;
+        if (!blocks) {
+            // Shared set of blocks for all clones.
+            blocks = new Blocks(runtime);
+        }
+        this.blocks = blocks;
+        /**
+         * Human-readable name for this sprite (and all clones).
+         * @type {string}
+         */
+        this.name = '';
+        /**
+         * List of costumes for this sprite.
+         * Each entry is an object, e.g.,
+         * {
+         *      skinId: 1,
+         *      name: "Costume Name",
+         *      bitmapResolution: 2,
+         *      rotationCenterX: 0,
+         *      rotationCenterY: 0
+         * }
+         * @type {Array.<!Object>}
+         */
+        this.costumes_ = [];
+        /**
+         * List of sounds for this sprite.
+        */
+        this.sounds = [];
+        /**
+         * List of clones for this sprite, including the original.
+         * @type {Array.<!RenderedTarget>}
+         */
+        this.clones = [];
+
+        this.soundBank = null;
+        if (this.runtime && this.runtime.audioEngine) {
+            this.soundBank = this.runtime.audioEngine.createBank();
+        }
+    }
+
+    /**
+     * Add an array of costumes, taking care to avoid duplicate names.
+     * @param {!Array<object>} costumes Array of objects representing costumes.
+     */
+    set costumes (costumes) {
+        this.costumes_ = [];
+        for (const costume of costumes) {
+            this.addCostumeAt(costume, this.costumes_.length);
+        }
+    }
+
+    /**
+     * Get full costume list
+     * @return {object[]} list of costumes. Note that mutating the returned list will not
+     *     mutate the list on the sprite. The sprite list should be mutated by calling
+     *     addCostumeAt, deleteCostumeAt, or setting costumes.
+     */
+    get costumes () {
+        return this.costumes_;
+    }
+
+    /**
+     * Add a costume at the given index, taking care to avoid duplicate names.
+     * @param {!object} costumeObject Object representing the costume.
+     * @param {!int} index Index at which to add costume
+     */
+    addCostumeAt (costumeObject, index) {
+        if (!costumeObject.name) {
+            costumeObject.name = '';
+        }
+        const usedNames = this.costumes_.map(costume => costume.name);
+        costumeObject.name = StringUtil.unusedName(costumeObject.name, usedNames);
+        this.costumes_.splice(index, 0, costumeObject);
+    }
+
+    /**
+     * Delete a costume by index.
+     * @param {number} index Costume index to be deleted
+     * @return {?object} The deleted costume
+     */
+    deleteCostumeAt (index) {
+        return this.costumes.splice(index, 1)[0];
+    }
+
+    /**
+     * Create a clone of this sprite.
+     * @param {string=} optLayerGroup Optional layer group the clone's drawable should be added to
+     * Defaults to the sprite layer group
+     * @returns {!RenderedTarget} Newly created clone.
+     */
+    createClone (optLayerGroup) {
+        const newClone = new RenderedTarget(this, this.runtime);
+        newClone.isOriginal = this.clones.length === 0;
+        this.clones.push(newClone);
+        newClone.initAudio();
+        if (newClone.isOriginal) {
+            // Default to the sprite layer group if optLayerGroup is not provided
+            const layerGroup = typeof optLayerGroup === 'string' ? optLayerGroup : StageLayering.SPRITE_LAYER;
+            newClone.initDrawable(layerGroup);
+            this.runtime.fireTargetWasCreated(newClone);
+        } else {
+            this.runtime.fireTargetWasCreated(newClone, this.clones[0]);
+        }
+        return newClone;
+    }
+
+    /**
+     * Disconnect a clone from this sprite. The clone is unmodified.
+     * In particular, the clone's dispose() method is not called.
+     * @param {!RenderedTarget} clone - the clone to be removed.
+     */
+    removeClone (clone) {
+        this.runtime.fireTargetWasRemoved(clone);
+        const cloneIndex = this.clones.indexOf(clone);
+        if (cloneIndex >= 0) {
+            this.clones.splice(cloneIndex, 1);
+        }
+    }
+
+    duplicate () {
+        const newSprite = new Sprite(null, this.runtime);
+        const blocksContainer = this.blocks._blocks;
+        const originalBlocks = Object.keys(blocksContainer).map(key => blocksContainer[key]);
+        const copiedBlocks = JSON.parse(JSON.stringify(originalBlocks));
+        newBlockIds(copiedBlocks);
+        copiedBlocks.forEach(block => {
+            newSprite.blocks.createBlock(block);
+        });
+
+
+        const allNames = this.runtime.targets.map(t => t.sprite.name);
+        newSprite.name = StringUtil.unusedName(this.name, allNames);
+
+        const assetPromises = [];
+
+        newSprite.costumes = this.costumes_.map(costume => {
+            const newCostume = Object.assign({}, costume);
+            assetPromises.push(loadCostumeFromAsset(newCostume, this.runtime));
+            return newCostume;
+        });
+
+        newSprite.sounds = this.sounds.map(sound => {
+            const newSound = Object.assign({}, sound);
+            const soundAsset = sound.asset;
+            assetPromises.push(loadSoundFromAsset(newSound, soundAsset, this.runtime, newSprite.soundBank));
+            return newSound;
+        });
+
+        return Promise.all(assetPromises).then(() => newSprite);
+    }
+
+    dispose () {
+        if (this.soundBank) {
+            this.soundBank.dispose();
+        }
+    }
+}
+
+module.exports = Sprite;

package/src/util/base64-util.js

@@ -0,0 +1,48 @@
+const atob = require('atob');
+const btoa = require('btoa');
+
+class Base64Util {
+
+    /**
+     * Convert a base64 encoded string to a Uint8Array.
+     * @param {string} base64 - a base64 encoded string.
+     * @return {Uint8Array} - a decoded Uint8Array.
+     */
+    static base64ToUint8Array (base64) {
+        const binaryString = atob(base64);
+        const len = binaryString.length;
+        const array = new Uint8Array(len);
+        for (let i = 0; i < len; i++) {
+            array[i] = binaryString.charCodeAt(i);
+        }
+        return array;
+    }
+
+    /**
+     * Convert a Uint8Array to a base64 encoded string.
+     * @param {Uint8Array} array - the array to convert.
+     * @return {string} - the base64 encoded string.
+     */
+    static uint8ArrayToBase64 (array) {
+        const base64 = btoa(String.fromCharCode.apply(null, array));
+        return base64;
+    }
+
+    /**
+    * Convert an array buffer to a base64 encoded string.
+    * @param {array} buffer - an array buffer to convert.
+    * @return {string} - the base64 encoded string.
+    */
+    static arrayBufferToBase64 (buffer) {
+        let binary = '';
+        const bytes = new Uint8Array(buffer);
+        const len = bytes.byteLength;
+        for (let i = 0; i < len; i++) {
+            binary += String.fromCharCode(bytes[ i ]);
+        }
+        return btoa(binary);
+    }
+
+}
+
+module.exports = Base64Util;

package/src/util/cast.js

@@ -0,0 +1,218 @@
+const Color = require('../util/color');
+
+/**
+ * @fileoverview
+ * Utilities for casting and comparing Scratch data-types.
+ * Scratch behaves slightly differently from JavaScript in many respects,
+ * and these differences should be encapsulated below.
+ * For example, in Scratch, add(1, join("hello", world")) -> 1.
+ * This is because "hello world" is cast to 0.
+ * In JavaScript, 1 + Number("hello" + "world") would give you NaN.
+ * Use when coercing a value before computation.
+ */
+
+class Cast {
+    /**
+     * Scratch cast to number.
+     * Treats NaN as 0.
+     * In Scratch 2.0, this is captured by `interp.numArg.`
+     * @param {*} value Value to cast to number.
+     * @return {number} The Scratch-casted number value.
+     */
+    static toNumber (value) {
+        // If value is already a number we don't need to coerce it with
+        // Number().
+        if (typeof value === 'number') {
+            // Scratch treats NaN as 0, when needed as a number.
+            // E.g., 0 + NaN -> 0.
+            if (Number.isNaN(value)) {
+                return 0;
+            }
+            return value;
+        }
+        const n = Number(value);
+        if (Number.isNaN(n)) {
+            // Scratch treats NaN as 0, when needed as a number.
+            // E.g., 0 + NaN -> 0.
+            return 0;
+        }
+        return n;
+    }
+
+    /**
+     * Scratch cast to boolean.
+     * In Scratch 2.0, this is captured by `interp.boolArg.`
+     * Treats some string values differently from JavaScript.
+     * @param {*} value Value to cast to boolean.
+     * @return {boolean} The Scratch-casted boolean value.
+     */
+    static toBoolean (value) {
+        // Already a boolean?
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            // These specific strings are treated as false in Scratch.
+            if ((value === '') ||
+                (value === '0') ||
+                (value.toLowerCase() === 'false')) {
+                return false;
+            }
+            // All other strings treated as true.
+            return true;
+        }
+        // Coerce other values and numbers.
+        return Boolean(value);
+    }
+
+    /**
+     * Scratch cast to string.
+     * @param {*} value Value to cast to string.
+     * @return {string} The Scratch-casted string value.
+     */
+    static toString (value) {
+        return String(value);
+    }
+
+    /**
+     * Cast any Scratch argument to an RGB color array to be used for the renderer.
+     * @param {*} value Value to convert to RGB color array.
+     * @return {Array.<number>} [r,g,b], values between 0-255.
+     */
+    static toRgbColorList (value) {
+        const color = Cast.toRgbColorObject(value);
+        return [color.r, color.g, color.b];
+    }
+
+    /**
+     * Cast any Scratch argument to an RGB color object to be used for the renderer.
+     * @param {*} value Value to convert to RGB color object.
+     * @return {RGBOject} [r,g,b], values between 0-255.
+     */
+    static toRgbColorObject (value) {
+        let color;
+        if (typeof value === 'string' && value.substring(0, 1) === '#') {
+            color = Color.hexToRgb(value);
+
+            // If the color wasn't *actually* a hex color, cast to black
+            if (!color) color = {r: 0, g: 0, b: 0, a: 255};
+        } else {
+            color = Color.decimalToRgb(Cast.toNumber(value));
+        }
+        return color;
+    }
+
+    /**
+     * Determine if a Scratch argument is a white space string (or null / empty).
+     * @param {*} val value to check.
+     * @return {boolean} True if the argument is all white spaces or null / empty.
+     */
+    static isWhiteSpace (val) {
+        return val === null || (typeof val === 'string' && val.trim().length === 0);
+    }
+
+    /**
+     * Compare two values, using Scratch cast, case-insensitive string compare, etc.
+     * In Scratch 2.0, this is captured by `interp.compare.`
+     * @param {*} v1 First value to compare.
+     * @param {*} v2 Second value to compare.
+     * @returns {number} Negative number if v1 < v2; 0 if equal; positive otherwise.
+     */
+    static compare (v1, v2) {
+        let n1 = Number(v1);
+        let n2 = Number(v2);
+        if (n1 === 0 && Cast.isWhiteSpace(v1)) {
+            n1 = NaN;
+        } else if (n2 === 0 && Cast.isWhiteSpace(v2)) {
+            n2 = NaN;
+        }
+        if (isNaN(n1) || isNaN(n2)) {
+            // At least one argument can't be converted to a number.
+            // Scratch compares strings as case insensitive.
+            const s1 = String(v1).toLowerCase();
+            const s2 = String(v2).toLowerCase();
+            if (s1 < s2) {
+                return -1;
+            } else if (s1 > s2) {
+                return 1;
+            }
+            return 0;
+        }
+        // Handle the special case of Infinity
+        if (
+            (n1 === Infinity && n2 === Infinity) ||
+            (n1 === -Infinity && n2 === -Infinity)
+        ) {
+            return 0;
+        }
+        // Compare as numbers.
+        return n1 - n2;
+    }
+
+    /**
+     * Determine if a Scratch argument number represents a round integer.
+     * @param {*} val Value to check.
+     * @return {boolean} True if number looks like an integer.
+     */
+    static isInt (val) {
+        // Values that are already numbers.
+        if (typeof val === 'number') {
+            if (isNaN(val)) { // NaN is considered an integer.
+                return true;
+            }
+            // True if it's "round" (e.g., 2.0 and 2).
+            return val === parseInt(val, 10);
+        } else if (typeof val === 'boolean') {
+            // `True` and `false` always represent integer after Scratch cast.
+            return true;
+        } else if (typeof val === 'string') {
+            // If it contains a decimal point, don't consider it an int.
+            return val.indexOf('.') < 0;
+        }
+        return false;
+    }
+
+    static get LIST_INVALID () {
+        return 'INVALID';
+    }
+
+    static get LIST_ALL () {
+        return 'ALL';
+    }
+
+    /**
+     * Compute a 1-based index into a list, based on a Scratch argument.
+     * Two special cases may be returned:
+     * LIST_ALL: if the block is referring to all of the items in the list.
+     * LIST_INVALID: if the index was invalid in any way.
+     * @param {*} index Scratch arg, including 1-based numbers or special cases.
+     * @param {number} length Length of the list.
+     * @param {boolean} acceptAll Whether it should accept "all" or not.
+     * @return {(number|string)} 1-based index for list, LIST_ALL, or LIST_INVALID.
+     */
+    static toListIndex (index, length, acceptAll) {
+        if (typeof index !== 'number') {
+            if (index === 'all') {
+                return acceptAll ? Cast.LIST_ALL : Cast.LIST_INVALID;
+            }
+            if (index === 'last') {
+                if (length > 0) {
+                    return length;
+                }
+                return Cast.LIST_INVALID;
+            } else if (index === 'random' || index === 'any') {
+                if (length > 0) {
+                    return 1 + Math.floor(Math.random() * length);
+                }
+                return Cast.LIST_INVALID;
+            }
+        }
+        index = Math.floor(Cast.toNumber(index));
+        if (index < 1 || index > length) {
+            return Cast.LIST_INVALID;
+        }
+        return index;
+    }
+}
+
+module.exports = Cast;

package/src/util/clone.js

@@ -0,0 +1,17 @@
+/**
+ * Methods for cloning JavaScript objects.
+ * @type {object}
+ */
+class Clone {
+    /**
+     * Deep-clone a "simple" object: one which can be fully expressed with JSON.
+     * Non-JSON values, such as functions, will be stripped from the clone.
+     * @param {object} original - the object to be cloned.
+     * @returns {object} a deep clone of the original object.
+     */
+    static simple (original) {
+        return JSON.parse(JSON.stringify(original));
+    }
+}
+
+module.exports = Clone;

package/src/util/color.js

@@ -0,0 +1,204 @@
+class Color {
+    /**
+     * @typedef {object} RGBObject - An object representing a color in RGB format.
+     * @property {number} r - the red component, in the range [0, 255].
+     * @property {number} g - the green component, in the range [0, 255].
+     * @property {number} b - the blue component, in the range [0, 255].
+     */
+
+    /**
+     * @typedef {object} HSVObject - An object representing a color in HSV format.
+     * @property {number} h - hue, in the range [0-359).
+     * @property {number} s - saturation, in the range [0,1].
+     * @property {number} v - value, in the range [0,1].
+     */
+
+    /** @type {RGBObject} */
+    static get RGB_BLACK () {
+        return {r: 0, g: 0, b: 0};
+    }
+
+    /** @type {RGBObject} */
+    static get RGB_WHITE () {
+        return {r: 255, g: 255, b: 255};
+    }
+
+    /**
+     * Convert a Scratch decimal color to a hex string, #RRGGBB.
+     * @param {number} decimal RGB color as a decimal.
+     * @return {string} RGB color as #RRGGBB hex string.
+     */
+    static decimalToHex (decimal) {
+        if (decimal < 0) {
+            decimal += 0xFFFFFF + 1;
+        }
+        let hex = Number(decimal).toString(16);
+        hex = `#${'000000'.substr(0, 6 - hex.length)}${hex}`;
+        return hex;
+    }
+
+    /**
+     * Convert a Scratch decimal color to an RGB color object.
+     * @param {number} decimal RGB color as decimal.
+     * @return {RGBObject} rgb - {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     */
+    static decimalToRgb (decimal) {
+        const a = (decimal >> 24) & 0xFF;
+        const r = (decimal >> 16) & 0xFF;
+        const g = (decimal >> 8) & 0xFF;
+        const b = decimal & 0xFF;
+        return {r: r, g: g, b: b, a: a > 0 ? a : 255};
+    }
+
+    /**
+     * Convert a hex color (e.g., F00, #03F, #0033FF) to an RGB color object.
+     * CC-BY-SA Tim Down:
+     * https://stackoverflow.com/questions/5623838/rgb-to-hex-and-hex-to-rgb
+     * @param {!string} hex Hex representation of the color.
+     * @return {RGBObject} null on failure, or rgb: {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     */
+    static hexToRgb (hex) {
+        const shorthandRegex = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+        hex = hex.replace(shorthandRegex, (m, r, g, b) => r + r + g + g + b + b);
+        const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+        return result ? {
+            r: parseInt(result[1], 16),
+            g: parseInt(result[2], 16),
+            b: parseInt(result[3], 16)
+        } : null;
+    }
+
+    /**
+     * Convert an RGB color object to a hex color.
+     * @param {RGBObject} rgb - {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     * @return {!string} Hex representation of the color.
+     */
+    static rgbToHex (rgb) {
+        return Color.decimalToHex(Color.rgbToDecimal(rgb));
+    }
+
+    /**
+     * Convert an RGB color object to a Scratch decimal color.
+     * @param {RGBObject} rgb - {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     * @return {!number} Number representing the color.
+     */
+    static rgbToDecimal (rgb) {
+        return (rgb.r << 16) + (rgb.g << 8) + rgb.b;
+    }
+
+    /**
+    * Convert a hex color (e.g., F00, #03F, #0033FF) to a decimal color number.
+    * @param {!string} hex Hex representation of the color.
+    * @return {!number} Number representing the color.
+    */
+    static hexToDecimal (hex) {
+        return Color.rgbToDecimal(Color.hexToRgb(hex));
+    }
+
+    /**
+     * Convert an HSV color to RGB format.
+     * @param {HSVObject} hsv - {h: hue [0,360), s: saturation [0,1], v: value [0,1]}
+     * @return {RGBObject} rgb - {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     */
+    static hsvToRgb (hsv) {
+        let h = hsv.h % 360;
+        if (h < 0) h += 360;
+        const s = Math.max(0, Math.min(hsv.s, 1));
+        const v = Math.max(0, Math.min(hsv.v, 1));
+
+        const i = Math.floor(h / 60);
+        const f = (h / 60) - i;
+        const p = v * (1 - s);
+        const q = v * (1 - (s * f));
+        const t = v * (1 - (s * (1 - f)));
+
+        let r;
+        let g;
+        let b;
+
+        switch (i) {
+        default:
+        case 0:
+            r = v;
+            g = t;
+            b = p;
+            break;
+        case 1:
+            r = q;
+            g = v;
+            b = p;
+            break;
+        case 2:
+            r = p;
+            g = v;
+            b = t;
+            break;
+        case 3:
+            r = p;
+            g = q;
+            b = v;
+            break;
+        case 4:
+            r = t;
+            g = p;
+            b = v;
+            break;
+        case 5:
+            r = v;
+            g = p;
+            b = q;
+            break;
+        }
+
+        return {
+            r: Math.floor(r * 255),
+            g: Math.floor(g * 255),
+            b: Math.floor(b * 255)
+        };
+    }
+
+    /**
+     * Convert an RGB color to HSV format.
+     * @param {RGBObject} rgb - {r: red [0,255], g: green [0,255], b: blue [0,255]}.
+     * @return {HSVObject} hsv - {h: hue [0,360), s: saturation [0,1], v: value [0,1]}
+     */
+    static rgbToHsv (rgb) {
+        const r = rgb.r / 255;
+        const g = rgb.g / 255;
+        const b = rgb.b / 255;
+        const x = Math.min(Math.min(r, g), b);
+        const v = Math.max(Math.max(r, g), b);
+
+        // For grays, hue will be arbitrarily reported as zero. Otherwise, calculate
+        let h = 0;
+        let s = 0;
+        if (x !== v) {
+            const f = (r === x) ? g - b : ((g === x) ? b - r : r - g);
+            const i = (r === x) ? 3 : ((g === x) ? 5 : 1);
+            h = ((i - (f / (v - x))) * 60) % 360;
+            s = (v - x) / v;
+        }
+
+        return {h: h, s: s, v: v};
+    }
+
+    /**
+     * Linear interpolation between rgb0 and rgb1.
+     * @param {RGBObject} rgb0 - the color corresponding to fraction1 <= 0.
+     * @param {RGBObject} rgb1 - the color corresponding to fraction1 >= 1.
+     * @param {number} fraction1 - the interpolation parameter. If this is 0.5, for example, mix the two colors equally.
+     * @return {RGBObject} the interpolated color.
+     */
+    static mixRgb (rgb0, rgb1, fraction1) {
+        if (fraction1 <= 0) return rgb0;
+        if (fraction1 >= 1) return rgb1;
+        const fraction0 = 1 - fraction1;
+        return {
+            r: (fraction0 * rgb0.r) + (fraction1 * rgb1.r),
+            g: (fraction0 * rgb0.g) + (fraction1 * rgb1.g),
+            b: (fraction0 * rgb0.b) + (fraction1 * rgb1.b)
+        };
+    }
+}
+
+module.exports = Color;