@scratch/scratch-vm 11.0.0-beta.1

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@scratch/scratch-vm",
+  "version": "11.0.0-beta.1",
+  "description": "Virtual Machine for Scratch 3.0",
+  "author": "Massachusetts Institute of Technology",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/scratchfoundation/scratch-vm#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scratchfoundation/scratch-editor.git"
+  },
+  "main": "./dist/node/scratch-vm.js",
+  "browser": "./dist/web/scratch-vm.js",
+  "exports": {
+    "webpack": "./src/index.js",
+    "browser": "./dist/web/scratch-vm.js",
+    "node": "./dist/node/scratch-vm.js",
+    "default": "./src/index.js"
+  },
+  "scripts": {
+    "build": "npm run docs && webpack --progress",
+    "coverage": "tap ./test/{unit,integration}/*.js --coverage --coverage-report=lcov",
+    "docs": "jsdoc -c .jsdoc.json",
+    "i18n:src": "mkdirp translations/core && format-message extract --out-file translations/core/en.json src/extensions/**/index.js",
+    "i18n:push": "tx-push-src scratch-editor extensions translations/core/en.json",
+    "lint": "eslint . && format-message lint src/**/*.js",
+    "prepublish": "in-publish && npm run build || not-in-publish",
+    "start": "webpack serve",
+    "tap": "tap ./test/{unit,integration}/*.js",
+    "tap:unit": "tap ./test/unit/*.js",
+    "tap:integration": "tap ./test/integration/*.js",
+    "test": "npm run lint && npm run tap",
+    "watch": "webpack --progress --watch"
+  },
+  "browserslist": [
+    "Chrome >= 63",
+    "Edge >= 15",
+    "Firefox >= 57",
+    "Safari >= 11"
+  ],
+  "tap": {
+    "branches": 60,
+    "functions": 70,
+    "lines": 70,
+    "statements": 70
+  },
+  "dependencies": {
+    "@scratch/scratch-render": "11.0.0-beta.1",
+    "@scratch/scratch-svg-renderer": "11.0.0-beta.1",
+    "@vernier/godirect": "^1.5.0",
+    "arraybuffer-loader": "^1.0.6",
+    "atob": "^2.1.2",
+    "btoa": "^1.2.1",
+    "canvas-toBlob": "^1.0.0",
+    "decode-html": "^2.0.0",
+    "diff-match-patch": "^1.0.4",
+    "format-message": "^6.2.1",
+    "htmlparser2": "^3.10.0",
+    "immutable": "^3.8.1",
+    "jszip": "^3.1.5",
+    "minilog": "^3.1.0",
+    "scratch-audio": "^1.0.6",
+    "scratch-parser": "^5.1.1",
+    "scratch-sb1-converter": "^1.0.0",
+    "scratch-storage": "^4.0.24",
+    "scratch-translate-extension-languages": "^1.0.0",
+    "text-encoding": "^0.7.0",
+    "uuid": "^8.3.2",
+    "web-worker": "^1.3.0"
+  },
+  "devDependencies": {
+    "@babel/core": "7.25.2",
+    "@babel/eslint-parser": "7.25.1",
+    "@babel/preset-env": "7.25.4",
+    "adm-zip": "0.4.11",
+    "babel-loader": "9.1.3",
+    "callsite": "1.0.0",
+    "copy-webpack-plugin": "4.6.0",
+    "docdash": "1.2.0",
+    "eslint": "8.57.0",
+    "eslint-config-scratch": "9.0.8",
+    "expose-loader": "1.0.3",
+    "file-loader": "6.2.0",
+    "format-message-cli": "6.2.4",
+    "in-publish": "2.0.1",
+    "js-md5": "0.7.3",
+    "jsdoc": "3.6.11",
+    "json": "^9.0.4",
+    "pngjs": "3.4.0",
+    "scratch-blocks": "1.1.206",
+    "scratch-l10n": "3.18.286",
+    "scratch-render-fonts": "1.0.92",
+    "scratch-semantic-release-config": "1.0.14",
+    "scratch-webpack-configuration": "1.6.0",
+    "script-loader": "0.7.2",
+    "semantic-release": "19.0.5",
+    "stats.js": "0.17.0",
+    "tap": "16.3.10",
+    "webpack": "5.94.0",
+    "webpack-cli": "4.10.0",
+    "webpack-dev-server": "3.11.3"
+  }
+}

package/release.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+    extends: 'scratch-semantic-release-config',
+    branches: [
+        {
+            name: 'develop'
+            // default channel
+        },
+        {
+            name: 'hotfix/*',
+            channel: 'hotfix'
+        }
+    ]
+};

package/src/blocks/scratch3_control.js

@@ -0,0 +1,206 @@
+const Cast = require('../util/cast');
+
+class Scratch3ControlBlocks {
+    constructor (runtime) {
+        /**
+         * The runtime instantiating this block package.
+         * @type {Runtime}
+         */
+        this.runtime = runtime;
+
+        /**
+         * The "counter" block value. For compatibility with 2.0.
+         * @type {number}
+         */
+        this._counter = 0;
+
+        this.runtime.on('RUNTIME_DISPOSED', this.clearCounter.bind(this));
+    }
+
+    /**
+     * Retrieve the block primitives implemented by this package.
+     * @return {object.<string, Function>} Mapping of opcode to Function.
+     */
+    getPrimitives () {
+        return {
+            control_repeat: this.repeat,
+            control_repeat_until: this.repeatUntil,
+            control_while: this.repeatWhile,
+            control_for_each: this.forEach,
+            control_forever: this.forever,
+            control_wait: this.wait,
+            control_wait_until: this.waitUntil,
+            control_if: this.if,
+            control_if_else: this.ifElse,
+            control_stop: this.stop,
+            control_create_clone_of: this.createClone,
+            control_delete_this_clone: this.deleteClone,
+            control_get_counter: this.getCounter,
+            control_incr_counter: this.incrCounter,
+            control_clear_counter: this.clearCounter,
+            control_all_at_once: this.allAtOnce
+        };
+    }
+
+    getHats () {
+        return {
+            control_start_as_clone: {
+                restartExistingThreads: false
+            }
+        };
+    }
+
+    repeat (args, util) {
+        const times = Math.round(Cast.toNumber(args.TIMES));
+        // Initialize loop
+        if (typeof util.stackFrame.loopCounter === 'undefined') {
+            util.stackFrame.loopCounter = times;
+        }
+        // Only execute once per frame.
+        // When the branch finishes, `repeat` will be executed again and
+        // the second branch will be taken, yielding for the rest of the frame.
+        // Decrease counter
+        util.stackFrame.loopCounter--;
+        // If we still have some left, start the branch.
+        if (util.stackFrame.loopCounter >= 0) {
+            util.startBranch(1, true);
+        }
+    }
+
+    repeatUntil (args, util) {
+        const condition = Cast.toBoolean(args.CONDITION);
+        // If the condition is false (repeat UNTIL), start the branch.
+        if (!condition) {
+            util.startBranch(1, true);
+        }
+    }
+
+    repeatWhile (args, util) {
+        const condition = Cast.toBoolean(args.CONDITION);
+        // If the condition is true (repeat WHILE), start the branch.
+        if (condition) {
+            util.startBranch(1, true);
+        }
+    }
+
+    forEach (args, util) {
+        const variable = util.target.lookupOrCreateVariable(
+            args.VARIABLE.id, args.VARIABLE.name);
+
+        if (typeof util.stackFrame.index === 'undefined') {
+            util.stackFrame.index = 0;
+        }
+
+        if (util.stackFrame.index < Number(args.VALUE)) {
+            util.stackFrame.index++;
+            variable.value = util.stackFrame.index;
+            util.startBranch(1, true);
+        }
+    }
+
+    waitUntil (args, util) {
+        const condition = Cast.toBoolean(args.CONDITION);
+        if (!condition) {
+            util.yield();
+        }
+    }
+
+    forever (args, util) {
+        util.startBranch(1, true);
+    }
+
+    wait (args, util) {
+        if (util.stackTimerNeedsInit()) {
+            const duration = Math.max(0, 1000 * Cast.toNumber(args.DURATION));
+
+            util.startStackTimer(duration);
+            this.runtime.requestRedraw();
+            util.yield();
+        } else if (!util.stackTimerFinished()) {
+            util.yield();
+        }
+    }
+
+    if (args, util) {
+        const condition = Cast.toBoolean(args.CONDITION);
+        if (condition) {
+            util.startBranch(1, false);
+        }
+    }
+
+    ifElse (args, util) {
+        const condition = Cast.toBoolean(args.CONDITION);
+        if (condition) {
+            util.startBranch(1, false);
+        } else {
+            util.startBranch(2, false);
+        }
+    }
+
+    stop (args, util) {
+        const option = args.STOP_OPTION;
+        if (option === 'all') {
+            util.stopAll();
+        } else if (option === 'other scripts in sprite' ||
+            option === 'other scripts in stage') {
+            util.stopOtherTargetThreads();
+        } else if (option === 'this script') {
+            util.stopThisScript();
+        }
+    }
+
+    createClone (args, util) {
+        // Cast argument to string
+        args.CLONE_OPTION = Cast.toString(args.CLONE_OPTION);
+
+        // Set clone target
+        let cloneTarget;
+        if (args.CLONE_OPTION === '_myself_') {
+            cloneTarget = util.target;
+        } else {
+            cloneTarget = this.runtime.getSpriteTargetByName(args.CLONE_OPTION);
+        }
+
+        // If clone target is not found, return
+        if (!cloneTarget) return;
+
+        // Create clone
+        const newClone = cloneTarget.makeClone();
+        if (newClone) {
+            this.runtime.addTarget(newClone);
+
+            // Place behind the original target.
+            newClone.goBehindOther(cloneTarget);
+        }
+    }
+
+    deleteClone (args, util) {
+        if (util.target.isOriginal) return;
+        this.runtime.disposeTarget(util.target);
+        this.runtime.stopForTarget(util.target);
+    }
+
+    getCounter () {
+        return this._counter;
+    }
+
+    clearCounter () {
+        this._counter = 0;
+    }
+
+    incrCounter () {
+        this._counter++;
+    }
+
+    allAtOnce (args, util) {
+        // Since the "all at once" block is implemented for compatiblity with
+        // Scratch 2.0 projects, it behaves the same way it did in 2.0, which
+        // is to simply run the contained script (like "if 1 = 1").
+        // (In early versions of Scratch 2.0, it would work the same way as
+        // "run without screen refresh" custom blocks do now, but this was
+        // removed before the release of 2.0.)
+        util.startBranch(1, false);
+    }
+}
+
+module.exports = Scratch3ControlBlocks;

package/src/blocks/scratch3_core_example.js

@@ -0,0 +1,69 @@
+const BlockType = require('../extension-support/block-type');
+const ArgumentType = require('../extension-support/argument-type');
+
+/* eslint-disable-next-line max-len */
+const blockIconURI = 'data:image/svg+xml,%3Csvg id="rotate-counter-clockwise" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"%3E%3Cdefs%3E%3Cstyle%3E.cls-1%7Bfill:%233d79cc;%7D.cls-2%7Bfill:%23fff;%7D%3C/style%3E%3C/defs%3E%3Ctitle%3Erotate-counter-clockwise%3C/title%3E%3Cpath class="cls-1" d="M22.68,12.2a1.6,1.6,0,0,1-1.27.63H13.72a1.59,1.59,0,0,1-1.16-2.58l1.12-1.41a4.82,4.82,0,0,0-3.14-.77,4.31,4.31,0,0,0-2,.8,4.25,4.25,0,0,0-1.34,1.73,5.06,5.06,0,0,0,.54,4.62A5.58,5.58,0,0,0,12,17.74h0a2.26,2.26,0,0,1-.16,4.52A10.25,10.25,0,0,1,3.74,18,10.14,10.14,0,0,1,2.25,8.78,9.7,9.7,0,0,1,5.08,4.64,9.92,9.92,0,0,1,9.66,2.5a10.66,10.66,0,0,1,7.72,1.68l1.08-1.35a1.57,1.57,0,0,1,1.24-.6,1.6,1.6,0,0,1,1.54,1.21l1.7,7.37A1.57,1.57,0,0,1,22.68,12.2Z"/%3E%3Cpath class="cls-2" d="M21.38,11.83H13.77a.59.59,0,0,1-.43-1l1.75-2.19a5.9,5.9,0,0,0-4.7-1.58,5.07,5.07,0,0,0-4.11,3.17A6,6,0,0,0,7,15.77a6.51,6.51,0,0,0,5,2.92,1.31,1.31,0,0,1-.08,2.62,9.3,9.3,0,0,1-7.35-3.82A9.16,9.16,0,0,1,3.17,9.12,8.51,8.51,0,0,1,5.71,5.4,8.76,8.76,0,0,1,9.82,3.48a9.71,9.71,0,0,1,7.75,2.07l1.67-2.1a.59.59,0,0,1,1,.21L22,11.08A.59.59,0,0,1,21.38,11.83Z"/%3E%3C/svg%3E';
+
+/**
+ * An example core block implemented using the extension spec.
+ * This is not loaded as part of the core blocks in the VM but it is provided
+ * and used as part of tests.
+ */
+class Scratch3CoreExample {
+    constructor (runtime) {
+        /**
+         * The runtime instantiating this block package.
+         * @type {Runtime}
+         */
+        this.runtime = runtime;
+    }
+
+    /**
+     * @returns {object} metadata for this extension and its blocks.
+     */
+    getInfo () {
+        return {
+            id: 'coreExample',
+            name: 'CoreEx', // This string does not need to be translated as this extension is only used as an example.
+            blocks: [
+                {
+                    func: 'MAKE_A_VARIABLE',
+                    blockType: BlockType.BUTTON,
+                    text: 'make a variable (CoreEx)'
+                },
+                {
+                    opcode: 'exampleOpcode',
+                    blockType: BlockType.REPORTER,
+                    text: 'example block'
+                },
+                {
+                    opcode: 'exampleWithInlineImage',
+                    blockType: BlockType.COMMAND,
+                    text: 'block with image [CLOCKWISE] inline',
+                    arguments: {
+                        CLOCKWISE: {
+                            type: ArgumentType.IMAGE,
+                            dataURI: blockIconURI
+                        }
+                    }
+                }
+            ]
+        };
+    }
+
+    /**
+     * Example opcode just returns the name of the stage target.
+     * @returns {string} The name of the first target in the project.
+     */
+    exampleOpcode () {
+        const stage = this.runtime.getTargetForStage();
+        return stage ? stage.getName() : 'no stage yet';
+    }
+
+    exampleWithInlineImage () {
+        return;
+    }
+
+}
+
+module.exports = Scratch3CoreExample;

package/src/blocks/scratch3_data.js

@@ -0,0 +1,257 @@
+const Cast = require('../util/cast');
+
+class Scratch3DataBlocks {
+    constructor (runtime) {
+        /**
+         * The runtime instantiating this block package.
+         * @type {Runtime}
+         */
+        this.runtime = runtime;
+    }
+
+    /**
+     * Retrieve the block primitives implemented by this package.
+     * @return {object.<string, Function>} Mapping of opcode to Function.
+     */
+    getPrimitives () {
+        return {
+            data_variable: this.getVariable,
+            data_setvariableto: this.setVariableTo,
+            data_changevariableby: this.changeVariableBy,
+            data_hidevariable: this.hideVariable,
+            data_showvariable: this.showVariable,
+            data_listcontents: this.getListContents,
+            data_addtolist: this.addToList,
+            data_deleteoflist: this.deleteOfList,
+            data_deletealloflist: this.deleteAllOfList,
+            data_insertatlist: this.insertAtList,
+            data_replaceitemoflist: this.replaceItemOfList,
+            data_itemoflist: this.getItemOfList,
+            data_itemnumoflist: this.getItemNumOfList,
+            data_lengthoflist: this.lengthOfList,
+            data_listcontainsitem: this.listContainsItem,
+            data_hidelist: this.hideList,
+            data_showlist: this.showList
+        };
+    }
+
+    getVariable (args, util) {
+        const variable = util.target.lookupOrCreateVariable(
+            args.VARIABLE.id, args.VARIABLE.name);
+        return variable.value;
+    }
+
+    setVariableTo (args, util) {
+        const variable = util.target.lookupOrCreateVariable(
+            args.VARIABLE.id, args.VARIABLE.name);
+        variable.value = args.VALUE;
+
+        if (variable.isCloud) {
+            util.ioQuery('cloud', 'requestUpdateVariable', [variable.name, args.VALUE]);
+        }
+    }
+
+    changeVariableBy (args, util) {
+        const variable = util.target.lookupOrCreateVariable(
+            args.VARIABLE.id, args.VARIABLE.name);
+        const castedValue = Cast.toNumber(variable.value);
+        const dValue = Cast.toNumber(args.VALUE);
+        const newValue = castedValue + dValue;
+        variable.value = newValue;
+
+        if (variable.isCloud) {
+            util.ioQuery('cloud', 'requestUpdateVariable', [variable.name, newValue]);
+        }
+    }
+
+    changeMonitorVisibility (id, visible) {
+        // Send the monitor blocks an event like the flyout checkbox event.
+        // This both updates the monitor state and changes the isMonitored block flag.
+        this.runtime.monitorBlocks.changeBlock({
+            id: id, // Monitor blocks for variables are the variable ID.
+            element: 'checkbox', // Mimic checkbox event from flyout.
+            value: visible
+        }, this.runtime);
+    }
+
+    showVariable (args) {
+        this.changeMonitorVisibility(args.VARIABLE.id, true);
+    }
+
+    hideVariable (args) {
+        this.changeMonitorVisibility(args.VARIABLE.id, false);
+    }
+
+    showList (args) {
+        this.changeMonitorVisibility(args.LIST.id, true);
+    }
+
+    hideList (args) {
+        this.changeMonitorVisibility(args.LIST.id, false);
+    }
+
+    getListContents (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+
+        // If block is running for monitors, return copy of list as an array if changed.
+        if (util.thread.updateMonitor) {
+            // Return original list value if up-to-date, which doesn't trigger monitor update.
+            if (list._monitorUpToDate) return list.value;
+            // If value changed, reset the flag and return a copy to trigger monitor update.
+            // Because monitors use Immutable data structures, only new objects trigger updates.
+            list._monitorUpToDate = true;
+            return list.value.slice();
+        }
+
+        // Determine if the list is all single letters.
+        // If it is, report contents joined together with no separator.
+        // If it's not, report contents joined together with a space.
+        let allSingleLetters = true;
+        for (let i = 0; i < list.value.length; i++) {
+            const listItem = list.value[i];
+            if (!((typeof listItem === 'string') &&
+                  (listItem.length === 1))) {
+                allSingleLetters = false;
+                break;
+            }
+        }
+        if (allSingleLetters) {
+            return list.value.join('');
+        }
+        return list.value.join(' ');
+
+    }
+
+    addToList (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        if (list.value.length < Scratch3DataBlocks.LIST_ITEM_LIMIT) {
+            list.value.push(args.ITEM);
+            list._monitorUpToDate = false;
+        }
+    }
+
+    deleteOfList (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        const index = Cast.toListIndex(args.INDEX, list.value.length, true);
+        if (index === Cast.LIST_INVALID) {
+            return;
+        } else if (index === Cast.LIST_ALL) {
+            list.value = [];
+            return;
+        }
+        list.value.splice(index - 1, 1);
+        list._monitorUpToDate = false;
+    }
+
+    deleteAllOfList (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        list.value = [];
+        return;
+    }
+
+    insertAtList (args, util) {
+        const item = args.ITEM;
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        const index = Cast.toListIndex(args.INDEX, list.value.length + 1, false);
+        if (index === Cast.LIST_INVALID) {
+            return;
+        }
+        const listLimit = Scratch3DataBlocks.LIST_ITEM_LIMIT;
+        if (index > listLimit) return;
+        list.value.splice(index - 1, 0, item);
+        if (list.value.length > listLimit) {
+            // If inserting caused the list to grow larger than the limit,
+            // remove the last element in the list
+            list.value.pop();
+        }
+        list._monitorUpToDate = false;
+    }
+
+    replaceItemOfList (args, util) {
+        const item = args.ITEM;
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        const index = Cast.toListIndex(args.INDEX, list.value.length, false);
+        if (index === Cast.LIST_INVALID) {
+            return;
+        }
+        list.value[index - 1] = item;
+        list._monitorUpToDate = false;
+    }
+
+    getItemOfList (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        const index = Cast.toListIndex(args.INDEX, list.value.length, false);
+        if (index === Cast.LIST_INVALID) {
+            return '';
+        }
+        return list.value[index - 1];
+    }
+
+    getItemNumOfList (args, util) {
+        const item = args.ITEM;
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+
+        // Go through the list items one-by-one using Cast.compare. This is for
+        // cases like checking if 123 is contained in a list [4, 7, '123'] --
+        // Scratch considers 123 and '123' to be equal.
+        for (let i = 0; i < list.value.length; i++) {
+            if (Cast.compare(list.value[i], item) === 0) {
+                return i + 1;
+            }
+        }
+
+        // We don't bother using .indexOf() at all, because it would end up with
+        // edge cases such as the index of '123' in [4, 7, 123, '123', 9].
+        // If we use indexOf(), this block would return 4 instead of 3, because
+        // indexOf() sees the first occurence of the string 123 as the fourth
+        // item in the list. With Scratch, this would be confusing -- after all,
+        // '123' and 123 look the same, so one would expect the block to say
+        // that the first occurrence of '123' (or 123) to be the third item.
+
+        // Default to 0 if there's no match. Since Scratch lists are 1-indexed,
+        // we don't have to worry about this conflicting with the "this item is
+        // the first value" number (in JS that is 0, but in Scratch it's 1).
+        return 0;
+    }
+
+    lengthOfList (args, util) {
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        return list.value.length;
+    }
+
+    listContainsItem (args, util) {
+        const item = args.ITEM;
+        const list = util.target.lookupOrCreateList(
+            args.LIST.id, args.LIST.name);
+        if (list.value.indexOf(item) >= 0) {
+            return true;
+        }
+        // Try using Scratch comparison operator on each item.
+        // (Scratch considers the string '123' equal to the number 123).
+        for (let i = 0; i < list.value.length; i++) {
+            if (Cast.compare(list.value[i], item) === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Type representation for list variables.
+     * @const {number}
+     */
+    static get LIST_ITEM_LIMIT () {
+        return 200000;
+    }
+}
+
+module.exports = Scratch3DataBlocks;