web: Change onFSCommand to addFSCommandHandler in V1 API

web/packages/core/src/internal/player/impl_v1.ts

@@ -10,14 +10,8 @@ export class PlayerV1Impl implements PlayerV1 {
         this.#inner = inner;
     }
 
-    get onFSCommand(): ((command: string, args: string) => boolean) | null {
-        return this.#inner.onFSCommand;
-    }
-
-    set onFSCommand(
-        value: ((command: string, args: string) => boolean) | null,
-    ) {
-        this.#inner.onFSCommand = value;
+    addFSCommandHandler(handler: (command: string, args: string) => void) {
+        this.#inner.addFSCommandHandler(handler);
     }
 
     get readyState(): ReadyState {

web/packages/core/src/internal/player/inner.tsx

@@ -191,6 +191,8 @@ export class InnerPlayer {
     private volumeSettings: VolumeControls;
     private readonly debugPlayerInfo: () => string;
     protected readonly onCallbackAvailable: (name: string) => void;
+    private readonly onFSCommand: ((command: string, args: string) => void)[] =
+        [];
 
     public constructor(
         element: HTMLElement,
@@ -201,7 +203,10 @@ export class InnerPlayer {
         this.debugPlayerInfo = debugPlayerInfo;
         this.onCallbackAvailable = onCallbackAvailable;
 
-        this.shadow = this.element.attachShadow({ mode: "open", delegatesFocus: true });
+        this.shadow = this.element.attachShadow({
+            mode: "open",
+            delegatesFocus: true,
+        });
         this.shadow.appendChild(ruffleShadowTemplate.content.cloneNode(true));
 
         this.dynamicStyles = this.shadow.getElementById(
@@ -309,7 +314,6 @@ export class InnerPlayer {
 
         this.instance = null;
         this.newZipWriter = null;
-        this.onFSCommand = null;
 
         this._readyState = ReadyState.HaveNothing;
         this.metadata = null;
@@ -318,15 +322,19 @@ export class InnerPlayer {
         this.setupPauseOnTabHidden();
     }
 
-    /**
-     * A movie can communicate with the hosting page using fscommand
-     * as long as script access is allowed.
-     *
-     * @param command A string passed to the host application for any use.
-     * @param args A string passed to the host application for any use.
-     * @returns True if the command was handled.
-     */
-    onFSCommand: ((command: string, args: string) => boolean) | null;
+    addFSCommandHandler(handler: (command: string, args: string) => void) {
+        this.onFSCommand.push(handler);
+    }
+
+    public callFSCommand(command: string, args: string): boolean {
+        if (this.onFSCommand.length == 0) {
+            return false;
+        }
+        for (const handler of this.onFSCommand) {
+            handler(command, args);
+        }
+        return true;
+    }
 
     /**
      * Any configuration that should apply to this specific player.

web/packages/core/src/internal/player/ruffle-player-element.tsx

@@ -11,15 +11,15 @@ import { PlayerV1Impl } from "./impl_v1";
  */
 export class RufflePlayerElement extends HTMLElement implements PlayerElement {
     #inner: InnerPlayer;
+    #legacyFSCommandHandler: ((command: string, args: string) => void) | null =
+        null;
 
-    get onFSCommand(): ((command: string, args: string) => boolean) | null {
-        return this.#inner.onFSCommand;
+    get onFSCommand(): ((command: string, args: string) => void) | null {
+        return this.#legacyFSCommandHandler;
     }
 
-    set onFSCommand(
-        value: ((command: string, args: string) => boolean) | null,
-    ) {
-        this.#inner.onFSCommand = value;
+    set onFSCommand(value: ((command: string, args: string) => void) | null) {
+        this.#legacyFSCommandHandler = value;
     }
 
     get readyState(): ReadyState {
@@ -54,6 +54,9 @@ export class RufflePlayerElement extends HTMLElement implements PlayerElement {
                 }
             },
         );
+        this.#inner.addFSCommandHandler((command, args) => {
+            this.#legacyFSCommandHandler?.(command, args);
+        });
     }
 
     ruffle<V extends keyof APIVersions = 1>(version?: V): APIVersions[V] {

web/packages/core/src/public/player/legacy.ts

@@ -10,17 +10,25 @@ import { ReadyState } from "../../internal/player/inner";
  */
 export interface LegacyRuffleAPI {
     /**
-     * A movie can communicate with the hosting page using fscommand
-     * as long as script access is allowed.
+     * Adds a handler for arbitrary "fs commands" from a movie in this player.
+     *
+     * @remarks
+     * If script access is allowed, a movie may communicate to the page through the ActionScript method `fscommand(name, args)`.
+     *
+     * The exact commands and their arguments are more or less arbitrary and up to the movie.
+     * This is an incredibly deprecated way of communicating between Flash and JavaScript,
+     * and was deprecated in favor of `ExternalInterface` in Flash Player 8 (2005).
      *
-     * @param command A string passed to the host application for any use.
-     * @param args A string passed to the host application for any use.
-     * @returns True if the command was handled.
      * @deprecated Please use {@link PlayerElement.ruffle | ruffle()} to access a versioned API.
      * This method may be replaced by Flash and is not guaranteed to exist.
-     * A direct replacement is {@link PlayerV1.onFSCommand}
+     * A direct replacement is {@link PlayerV1.addFSCommandHandler}, which supports multiple handlers.
      */
-    onFSCommand: ((command: string, args: string) => boolean) | null;
+    onFSCommand:
+        | ((
+              /** An arbitrary name of a command. */ command: string,
+              /** An arbitrary argument to the command. */ args: string,
+          ) => void)
+        | null;
 
     /**
      * Any configuration that should apply to this specific player.

web/packages/core/src/public/player/v1.ts

@@ -4,14 +4,24 @@ import { ReadyState } from "../../internal/player/inner";
 
 export interface PlayerV1 {
     /**
-     * A movie can communicate with the hosting page using fscommand
-     * as long as script access is allowed.
-     *
-     * @param command A string passed to the host application for any use.
-     * @param args A string passed to the host application for any use.
-     * @returns True if the command was handled.
-     */
-    onFSCommand: ((command: string, args: string) => boolean) | null;
+     * Adds a handler for arbitrary "fs commands" from a movie in this player.
+     *
+     * @remarks
+     * If script access is allowed, a movie may communicate to the page through the ActionScript method `fscommand(name, args)`.
+     *
+     * The exact commands and their arguments are more or less arbitrary and up to the movie.
+     * This is an incredibly deprecated way of communicating between Flash and JavaScript,
+     * and was deprecated in favor of `ExternalInterface` in Flash Player 8 (2005).
+     */
+    addFSCommandHandler(
+        /**
+         * A command handler to receive `fscommand`s.
+         *
+         * @param command An arbitrary name of a command.
+         * @param args An arbitrary argument to the command.
+         */
+        handler: (command: string, args: string) => void,
+    ): void;
 
     /**
      * Any configuration that should apply to this specific player.

web/src/external_interface.rs

@@ -71,7 +71,7 @@ impl ExternalInterfaceProvider for JavascriptInterface {
 impl FsCommandProvider for JavascriptInterface {
     fn on_fs_command(&self, command: &str, args: &str) -> bool {
         self.js_player
-            .on_fs_command(command, args)
+            .call_fs_command(command, args)
             .unwrap_or_default()
     }
 }

web/src/lib.rs

@@ -153,8 +153,9 @@ extern "C" {
     #[wasm_bindgen(method, js_name = "getObjectId")]
     fn get_object_id(this: &JavascriptPlayer) -> Option<String>;
 
-    #[wasm_bindgen(method, catch, js_name = "onFSCommand")]
-    fn on_fs_command(this: &JavascriptPlayer, command: &str, args: &str) -> Result<bool, JsValue>;
+    #[wasm_bindgen(method, catch, js_name = "callFSCommand")]
+    fn call_fs_command(this: &JavascriptPlayer, command: &str, args: &str)
+        -> Result<bool, JsValue>;
 
     #[wasm_bindgen(method)]
     fn panic(this: &JavascriptPlayer, error: &JsError);