@scratch/scratch-vm 11.0.0-UEPR-176

package/src/engine/block-utility.js

@@ -0,0 +1,242 @@
+const Thread = require('./thread');
+const Timer = require('../util/timer');
+
+/**
+ * @fileoverview
+ * Interface provided to block primitive functions for interacting with the
+ * runtime, thread, target, and convenient methods.
+ */
+
+class BlockUtility {
+    constructor (sequencer = null, thread = null) {
+        /**
+         * A sequencer block primitives use to branch or start procedures with
+         * @type {?Sequencer}
+         */
+        this.sequencer = sequencer;
+
+        /**
+         * The block primitives thread with the block's target, stackFrame and
+         * modifiable status.
+         * @type {?Thread}
+         */
+        this.thread = thread;
+
+        this._nowObj = {
+            now: () => this.sequencer.runtime.currentMSecs
+        };
+    }
+
+    /**
+     * The target the primitive is working on.
+     * @type {Target}
+     */
+    get target () {
+        return this.thread.target;
+    }
+
+    /**
+     * The runtime the block primitive is running in.
+     * @type {Runtime}
+     */
+    get runtime () {
+        return this.sequencer.runtime;
+    }
+
+    /**
+     * Use the runtime's currentMSecs value as a timestamp value for now
+     * This is useful in some cases where we need compatibility with Scratch 2
+     * @type {function}
+     */
+    get nowObj () {
+        if (this.runtime) {
+            return this._nowObj;
+        }
+        return null;
+    }
+
+    /**
+     * The stack frame used by loop and other blocks to track internal state.
+     * @type {object}
+     */
+    get stackFrame () {
+        const frame = this.thread.peekStackFrame();
+        if (frame.executionContext === null) {
+            frame.executionContext = {};
+        }
+        return frame.executionContext;
+    }
+
+    /**
+     * Check the stack timer and return a boolean based on whether it has finished or not.
+     * @return {boolean} - true if the stack timer has finished.
+     */
+    stackTimerFinished () {
+        const timeElapsed = this.stackFrame.timer.timeElapsed();
+        if (timeElapsed < this.stackFrame.duration) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Check if the stack timer needs initialization.
+     * @return {boolean} - true if the stack timer needs to be initialized.
+     */
+    stackTimerNeedsInit () {
+        return !this.stackFrame.timer;
+    }
+
+    /**
+     * Create and start a stack timer
+     * @param {number} duration - a duration in milliseconds to set the timer for.
+     */
+    startStackTimer (duration) {
+        if (this.nowObj) {
+            this.stackFrame.timer = new Timer(this.nowObj);
+        } else {
+            this.stackFrame.timer = new Timer();
+        }
+        this.stackFrame.timer.start();
+        this.stackFrame.duration = duration;
+    }
+
+    /**
+     * Set the thread to yield.
+     */
+    yield () {
+        this.thread.status = Thread.STATUS_YIELD;
+    }
+
+    /**
+     * Set the thread to yield until the next tick of the runtime.
+     */
+    yieldTick () {
+        this.thread.status = Thread.STATUS_YIELD_TICK;
+    }
+
+    /**
+     * Start a branch in the current block.
+     * @param {number} branchNum Which branch to step to (i.e., 1, 2).
+     * @param {boolean} isLoop Whether this block is a loop.
+     */
+    startBranch (branchNum, isLoop) {
+        this.sequencer.stepToBranch(this.thread, branchNum, isLoop);
+    }
+
+    /**
+     * Stop all threads.
+     */
+    stopAll () {
+        this.sequencer.runtime.stopAll();
+    }
+
+    /**
+     * Stop threads other on this target other than the thread holding the
+     * executed block.
+     */
+    stopOtherTargetThreads () {
+        this.sequencer.runtime.stopForTarget(this.thread.target, this.thread);
+    }
+
+    /**
+     * Stop this thread.
+     */
+    stopThisScript () {
+        this.thread.stopThisScript();
+    }
+
+    /**
+     * Start a specified procedure on this thread.
+     * @param {string} procedureCode Procedure code for procedure to start.
+     */
+    startProcedure (procedureCode) {
+        this.sequencer.stepToProcedure(this.thread, procedureCode);
+    }
+
+    /**
+     * Get names and ids of parameters for the given procedure.
+     * @param {string} procedureCode Procedure code for procedure to query.
+     * @return {Array.<string>} List of param names for a procedure.
+     */
+    getProcedureParamNamesAndIds (procedureCode) {
+        return this.thread.target.blocks.getProcedureParamNamesAndIds(procedureCode);
+    }
+
+    /**
+     * Get names, ids, and defaults of parameters for the given procedure.
+     * @param {string} procedureCode Procedure code for procedure to query.
+     * @return {Array.<string>} List of param names for a procedure.
+     */
+    getProcedureParamNamesIdsAndDefaults (procedureCode) {
+        return this.thread.target.blocks.getProcedureParamNamesIdsAndDefaults(procedureCode);
+    }
+
+    /**
+     * Initialize procedure parameters in the thread before pushing parameters.
+     */
+    initParams () {
+        this.thread.initParams();
+    }
+
+    /**
+     * Store a procedure parameter value by its name.
+     * @param {string} paramName The procedure's parameter name.
+     * @param {*} paramValue The procedure's parameter value.
+     */
+    pushParam (paramName, paramValue) {
+        this.thread.pushParam(paramName, paramValue);
+    }
+
+    /**
+     * Retrieve the stored parameter value for a given parameter name.
+     * @param {string} paramName The procedure's parameter name.
+     * @return {*} The parameter's current stored value.
+     */
+    getParam (paramName) {
+        return this.thread.getParam(paramName);
+    }
+
+    /**
+     * Start all relevant hats.
+     * @param {!string} requestedHat Opcode of hats to start.
+     * @param {object=} optMatchFields Optionally, fields to match on the hat.
+     * @param {Target=} optTarget Optionally, a target to restrict to.
+     * @return {Array.<Thread>} List of threads started by this function.
+     */
+    startHats (requestedHat, optMatchFields, optTarget) {
+        // Store thread and sequencer to ensure we can return to the calling block's context.
+        // startHats may execute further blocks and dirty the BlockUtility's execution context
+        // and confuse the calling block when we return to it.
+        const callerThread = this.thread;
+        const callerSequencer = this.sequencer;
+        const result = this.sequencer.runtime.startHats(requestedHat, optMatchFields, optTarget);
+
+        // Restore thread and sequencer to prior values before we return to the calling block.
+        this.thread = callerThread;
+        this.sequencer = callerSequencer;
+
+        return result;
+    }
+
+    /**
+     * Query a named IO device.
+     * @param {string} device The name of like the device, like keyboard.
+     * @param {string} func The name of the device's function to query.
+     * @param {Array.<*>} args Arguments to pass to the device's function.
+     * @return {*} The expected output for the device's function.
+     */
+    ioQuery (device, func, args) {
+        // Find the I/O device and execute the query/function call.
+        if (
+            this.sequencer.runtime.ioDevices[device] &&
+            this.sequencer.runtime.ioDevices[device][func]) {
+            const devObject = this.sequencer.runtime.ioDevices[device];
+            // TODO: verify correct `this` after switching from apply to spread
+            // eslint-disable-next-line prefer-spread
+            return devObject[func].apply(devObject, args);
+        }
+    }
+}
+
+module.exports = BlockUtility;

package/src/engine/blocks-execute-cache.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview
+ * Access point for private method shared between blocks.js and execute.js for
+ * caching execute information.
+ */
+
+/**
+ * A private method shared with execute to build an object containing the block
+ * information execute needs and that is reset when other cached Blocks info is
+ * reset.
+ * @param {Blocks} blocks Blocks containing the expected blockId
+ * @param {string} blockId blockId for the desired execute cache
+ */
+exports.getCached = function () {
+    throw new Error('blocks.js has not initialized BlocksExecuteCache');
+};
+
+// Call after the default throwing getCached is assigned for Blocks to replace.
+require('./blocks');

package/src/engine/blocks-runtime-cache.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview
+ * The BlocksRuntimeCache caches data about the top block of scripts so that
+ * Runtime can iterate a targeted opcode and iterate the returned set faster.
+ * Many top blocks need to match fields as well as opcode, since that matching
+ * compares strings in uppercase we can go ahead and uppercase the cached value
+ * so we don't need to in the future.
+ */
+
+/**
+ * A set of cached data about the top block of a script.
+ * @param {Blocks} container - Container holding the block and related data
+ * @param {string} blockId - Id for whose block data is cached in this instance
+ */
+class RuntimeScriptCache {
+    constructor (container, blockId) {
+        /**
+         * Container with block data for blockId.
+         * @type {Blocks}
+         */
+        this.container = container;
+
+        /**
+         * ID for block this instance caches.
+         * @type {string}
+         */
+        this.blockId = blockId;
+
+        const block = container.getBlock(blockId);
+        const fields = container.getFields(block);
+
+        /**
+         * Formatted fields or fields of input blocks ready for comparison in
+         * runtime.
+         *
+         * This is a clone of parts of the targeted blocks. Changes to these
+         * clones are limited to copies under RuntimeScriptCache and will not
+         * appear in the original blocks in their container. This copy is
+         * modified changing the case of strings to uppercase. These uppercase
+         * values will be compared later by the VM.
+         * @type {object}
+         */
+        this.fieldsOfInputs = Object.assign({}, fields);
+        if (Object.keys(fields).length === 0) {
+            const inputs = container.getInputs(block);
+            for (const input in inputs) {
+                if (!Object.prototype.hasOwnProperty.call(inputs, input)) continue;
+                const id = inputs[input].block;
+                const inputBlock = container.getBlock(id);
+                const inputFields = container.getFields(inputBlock);
+                Object.assign(this.fieldsOfInputs, inputFields);
+            }
+        }
+        for (const key in this.fieldsOfInputs) {
+            const field = this.fieldsOfInputs[key] = Object.assign({}, this.fieldsOfInputs[key]);
+            if (field.value.toUpperCase) {
+                field.value = field.value.toUpperCase();
+            }
+        }
+    }
+}
+
+/**
+ * Get an array of scripts from a block container prefiltered to match opcode.
+ * @param {Blocks} container - Container of blocks
+ * @param {string} opcode - Opcode to filter top blocks by
+ */
+exports.getScripts = function () {
+    throw new Error('blocks.js has not initialized BlocksRuntimeCache');
+};
+
+/**
+ * Exposed RuntimeScriptCache class used by integration in blocks.js.
+ * @private
+ */
+exports._RuntimeScriptCache = RuntimeScriptCache;
+
+require('./blocks');