@m2c2kit/core 0.3.25 → 0.3.27

package/dist/index.d.ts

@@ -1254,6 +1254,7 @@ interface M2Sound {
     soundName: string;
     data: ArrayBuffer | undefined;
     audioBuffer: AudioBuffer | undefined;
+    audioBufferSource: AudioBufferSourceNode | undefined;
     url: string;
     status: M2SoundStatus;
 }
@@ -4633,6 +4634,37 @@ declare class SoundPlayer extends M2Node implements SoundPlayerOptions {
      */
     constructor(options: SoundPlayerOptions);
     initialize(): void;
+    /**
+     * Remove an action from this node. If the action is running, it will be
+     * stopped.
+     *
+     * @privateRemarks This methods overrides the `removeAction` method from the
+     * `M2Node` class. It is necessary to override this method because the
+     * `SoundPlayer` class has a special case for removing actions that play
+     * sounds.
+     *
+     * @param key - key (string identifier) of the action to remove
+     */
+    removeAction(key: string): void;
+    /**
+     * Remove all actions from this node. If actions are running, they will be
+     * stopped.
+     *
+     * @privateRemarks This methods overrides the `removeAllActions` method from
+     * the `M2Node` class. It is necessary to override this method because the
+     * `SoundPlayer` class has a special case for removing actions that play
+     * sounds.
+     */
+    removeAllActions(): void;
+    /**
+     * Stops the audio source node for a sound play action.
+     *
+     * @remarks When a SoundPlayer play action is removed, the audio source node
+     * must be stopped and disconnected.
+     *
+     * @param playAction - the play action of the sound to stop
+     */
+    private stopSoundActionAudio;
     dispose(): void;
     /**
      * Duplicates a node using deep copy.
@@ -4707,10 +4739,49 @@ declare class SoundRecorder extends M2Node implements Omit<SoundRecorderOptions,
      */
     constructor(options?: SoundRecorderOptions);
     initialize(): void;
+    /**
+     * Starts recording audio from the microphone.
+     *
+     * @remarks If the `SoundRecorder` is already recording, an error will be
+     * thrown. If permission to use the microphone has not been granted, the
+     * browser will prompt the user to allow or deny access. Denial of access
+     * will result in an error being thrown. To avoid this, use the
+     * `queryPermission()` and `requestPermission()` methods to check and request
+     * permission, respectively, and handle the results accordingly.
+     */
     start(): Promise<void>;
+    /**
+     * Stops recording audio from the microphone.
+     *
+     * @remarks If the `stop()` method is not awaited, the method returns a
+     * Promise and the useable data will be lost.
+     *
+     * @returns A promise that resolves to a {@link SoundRecorderResults} object.
+     * The `audioBase64` property of the object contains the recorded audio as a
+     * base64 string.
+     */
     stop(): Promise<SoundRecorderResults>;
     pause(): void;
     resume(): void;
+    /**
+     * Checks if the microphone permission is granted.
+     *
+     * @remarks This does not request permission from the user. It only queries
+     * the current microphone permission state.
+     *
+     * @returns The `state` property ("granted", "denied", or "prompt") of
+     * `PermissionStatus` or undefined if the browser does not support the
+     * "microphone" permission.
+     * See https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state
+     */
+    queryPermission(): Promise<string | undefined>;
+    /**
+     * Requests permission to use the microphone, and possibly prompts the user
+     * to allow or deny access.
+     *
+     * @returns true if the microphone permission is granted, false if denied.
+     */
+    requestPermission(): Promise<boolean>;
     /** Is the `SoundRecorder` currently recording? */
     get isRecording(): boolean;
     /** Is the `SoundRecorder` currently paused? */

package/dist/index.js

@@ -1892,16 +1892,18 @@ class Action {
     if (!playAction.started) {
       const m2Sound = soundManager.getSound(soundPlayer.soundName);
       if (m2Sound.audioBuffer) {
-        const source = soundManager.audioContext.createBufferSource();
-        source.buffer = m2Sound.audioBuffer;
-        source.onended = () => {
+        m2Sound.audioBufferSource = soundManager.audioContext.createBufferSource();
+        m2Sound.audioBufferSource.buffer = m2Sound.audioBuffer;
+        m2Sound.audioBufferSource.onended = () => {
           playAction.running = false;
           playAction.completed = true;
           const knownDuration = performance.now() - (action.runStartTime + action.startOffset.value);
           action.duration.assign(knownDuration);
         };
-        source.connect(soundManager.audioContext.destination);
-        source.start();
+        m2Sound.audioBufferSource.connect(
+          soundManager.audioContext.destination
+        );
+        m2Sound.audioBufferSource.start();
         playAction.started = true;
       } else {
         if (m2Sound.status === M2SoundStatus.Error) {
@@ -8032,6 +8034,7 @@ class SoundManager {
         soundName: sound.soundName,
         data: void 0,
         audioBuffer: void 0,
+        audioBufferSource: void 0,
         url,
         status: sound.lazy ? M2SoundStatus.Deferred : M2SoundStatus.WillFetch
       };
@@ -10981,9 +10984,13 @@ class Game {
       this.raiseTapDownEvent(node, nodeEvent, domPointerEvent);
     }
     if (node.children) {
-      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort(
-        (a, b) => b.zPosition - a.zPosition
-      ).forEach(
+      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort((a, b) => {
+        const zDiff = b.zPosition - a.zPosition;
+        if (zDiff !== 0) {
+          return zDiff;
+        }
+        return node.children.indexOf(b) - node.children.indexOf(a);
+      }).forEach(
         (node2) => this.processDomPointerDown(node2, nodeEvent, domPointerEvent)
       );
     }
@@ -10997,7 +11004,6 @@ class Game {
       node.pressed = false;
       node.pressedAndWithinHitArea = false;
       this.raiseM2DragEndEvent(node, nodeEvent, domPointerEvent);
-      nodeEvent.handled = true;
       return;
     }
     if (node.isUserInteractionEnabled && node.pressed && node.pressedAndWithinHitArea) {
@@ -11020,9 +11026,13 @@ class Game {
       this.raiseM2PointerUpEvent(node, nodeEvent, domPointerEvent);
     }
     if (node.children) {
-      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort(
-        (a, b) => b.zPosition - a.zPosition
-      ).forEach(
+      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort((a, b) => {
+        const zDiff = b.zPosition - a.zPosition;
+        if (zDiff !== 0) {
+          return zDiff;
+        }
+        return node.children.indexOf(b) - node.children.indexOf(a);
+      }).forEach(
         (node2) => this.processDomPointerUp(node2, nodeEvent, domPointerEvent)
       );
     }
@@ -11050,7 +11060,6 @@ class Game {
         x: domPointerEvent.offsetX,
         y: domPointerEvent.offsetY
       };
-      nodeEvent.handled = true;
       if (firstMoveOfDrag) {
         this.raiseM2DragStartEvent(node, nodeEvent, domPointerEvent);
       } else {
@@ -11083,9 +11092,13 @@ class Game {
       this.raiseM2PointerLeaveEvent(node, nodeEvent, domPointerEvent);
     }
     if (node.children) {
-      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort(
-        (a, b) => b.zPosition - a.zPosition
-      ).forEach(
+      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort((a, b) => {
+        const zDiff = b.zPosition - a.zPosition;
+        if (zDiff !== 0) {
+          return zDiff;
+        }
+        return node.children.indexOf(b) - node.children.indexOf(a);
+      }).forEach(
         (node2) => this.processDomPointerMove(node2, nodeEvent, domPointerEvent)
       );
     }
@@ -11124,9 +11137,13 @@ class Game {
       this.raiseM2PointerLeaveEvent(node, nodeEvent, domPointerEvent);
     }
     if (node.children) {
-      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort(
-        (a, b) => b.zPosition - a.zPosition
-      ).forEach(
+      node.children.filter((node2) => !node2.hidden).filter((node2) => node2.isDrawable).sort((a, b) => {
+        const zDiff = b.zPosition - a.zPosition;
+        if (zDiff !== 0) {
+          return zDiff;
+        }
+        return node.children.indexOf(b) - node.children.indexOf(a);
+      }).forEach(
         (node2) => this.processDomPointerLeave(node2, nodeEvent, domPointerEvent)
       );
     }
@@ -11728,6 +11745,56 @@ class SoundPlayer extends M2Node {
   }
   initialize() {
   }
+  /**
+   * Remove an action from this node. If the action is running, it will be
+   * stopped.
+   *
+   * @privateRemarks This methods overrides the `removeAction` method from the
+   * `M2Node` class. It is necessary to override this method because the
+   * `SoundPlayer` class has a special case for removing actions that play
+   * sounds.
+   *
+   * @param key - key (string identifier) of the action to remove
+   */
+  removeAction(key) {
+    const actionToRemove = this.actions.find((action) => action.key === key);
+    if (actionToRemove?.type === ActionType.Play) {
+      this.stopSoundActionAudio(actionToRemove);
+    }
+    this.actions = this.actions.filter((action) => action.key !== key);
+  }
+  /**
+   * Remove all actions from this node. If actions are running, they will be
+   * stopped.
+   *
+   * @privateRemarks This methods overrides the `removeAllActions` method from
+   * the `M2Node` class. It is necessary to override this method because the
+   * `SoundPlayer` class has a special case for removing actions that play
+   * sounds.
+   */
+  removeAllActions() {
+    while (this.actions.length) {
+      const removedAction = this.actions.pop();
+      if (removedAction?.type === ActionType.Play) {
+        this.stopSoundActionAudio(removedAction);
+      }
+    }
+  }
+  /**
+   * Stops the audio source node for a sound play action.
+   *
+   * @remarks When a SoundPlayer play action is removed, the audio source node
+   * must be stopped and disconnected.
+   *
+   * @param playAction - the play action of the sound to stop
+   */
+  stopSoundActionAudio(playAction) {
+    if (playAction.running) {
+      const m2Sound = this.game.soundManager.getSound(this.soundName);
+      m2Sound.audioBufferSource?.stop();
+      m2Sound.audioBufferSource?.disconnect();
+    }
+  }
   dispose() {
   }
   /**
@@ -11788,12 +11855,24 @@ class SoundRecorder extends M2Node {
   }
   initialize() {
   }
+  /**
+   * Starts recording audio from the microphone.
+   *
+   * @remarks If the `SoundRecorder` is already recording, an error will be
+   * thrown. If permission to use the microphone has not been granted, the
+   * browser will prompt the user to allow or deny access. Denial of access
+   * will result in an error being thrown. To avoid this, use the
+   * `queryPermission()` and `requestPermission()` methods to check and request
+   * permission, respectively, and handle the results accordingly.
+   */
   async start() {
     if (this.isRecording) {
       throw new Error(
         "cannot start SoundRecorder because it is already started."
       );
     }
+    this.audioChunks = [];
+    this.endIso8601Timestamp = void 0;
     const supportedMimeTypes = this.getMediaRecorderSupportedAudioMimeTypes();
     if (supportedMimeTypes.length === 0) {
       throw new Error(
@@ -11810,7 +11889,7 @@ class SoundRecorder extends M2Node {
         audio: this.audioTrackConstraints ? this.audioTrackConstraints : true
       });
     } catch (error) {
-      throw new Error("Error getting user media.");
+      throw new Error(`Error getting user media: ${error}.`);
     }
     if (!stream) {
       throw new Error("no stream.");
@@ -11833,6 +11912,16 @@ class SoundRecorder extends M2Node {
     this._isRecording = true;
     this._isPaused = false;
   }
+  /**
+   * Stops recording audio from the microphone.
+   *
+   * @remarks If the `stop()` method is not awaited, the method returns a
+   * Promise and the useable data will be lost.
+   *
+   * @returns A promise that resolves to a {@link SoundRecorderResults} object.
+   * The `audioBase64` property of the object contains the recorded audio as a
+   * base64 string.
+   */
   async stop() {
     if (!this.isRecording) {
       throw new Error("cannot stop SoundRecorder because it has not started.");
@@ -11892,6 +11981,52 @@ class SoundRecorder extends M2Node {
     this._isPaused = false;
     Timer.start(this.timerUuid);
   }
+  /**
+   * Checks if the microphone permission is granted.
+   *
+   * @remarks This does not request permission from the user. It only queries
+   * the current microphone permission state.
+   *
+   * @returns The `state` property ("granted", "denied", or "prompt") of
+   * `PermissionStatus` or undefined if the browser does not support the
+   * "microphone" permission.
+   * See https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state
+   */
+  async queryPermission() {
+    try {
+      const status = await navigator.permissions.query({
+        /**
+         * We use a type assertion here because the PermissionName type
+         * does not include "microphone" in the TypeScript type definitions.
+         */
+        name: "microphone"
+      });
+      return status.state;
+    } catch (error) {
+      console.warn(
+        `Error calling navigator.permissions.query({ name: "microphone" }): ${error}.`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Requests permission to use the microphone, and possibly prompts the user
+   * to allow or deny access.
+   *
+   * @returns true if the microphone permission is granted, false if denied.
+   */
+  async requestPermission() {
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.audioTrackConstraints ? this.audioTrackConstraints : true
+      });
+      stream.getTracks().forEach((track) => track.stop());
+      return true;
+    } catch (error) {
+      console.warn(`Microphone access denied: ${error}`);
+      return false;
+    }
+  }
   /** Is the `SoundRecorder` currently recording? */
   get isRecording() {
     return this._isRecording;
@@ -12045,7 +12180,7 @@ class Story {
   }
 }
 
-console.log("\u26AA @m2c2kit/core version 0.3.25 (af00d1f0)");
+console.log("\u26AA @m2c2kit/core version 0.3.27 (1ed4ac2a)");
 
 export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
 //# sourceMappingURL=index.js.map