feat(overlay-widgets): add ability for overlay widgets to send messages back to firebot from overlay

ebiggz · ebiggz · commit 17b5004318fd · 2025-11-22T17:42:46.000-07:00
diff --git a/src/backend/events/builtin/firebot-event-source.ts b/src/backend/events/builtin/firebot-event-source.ts
@@ -182,6 +182,20 @@ export const FirebotEventSource: EventSource = {
                 dynamicCountdownWidgetId: "testCountdownId",
                 dynamicCountdownWidgetName: "Test Countdown"
             }
+        },
+        {
+            id: "custom-widget-message-received",
+            name: "Custom Overlay Widget Message Received",
+            description: "When a message is received from a custom overlay widget.",
+            cached: false,
+            manualMetadata: {
+                customWidgetId: "testCountdownId",
+                customWidgetName: "Test Countdown",
+                messageName: "testMessage",
+                messageData: {
+                    foo: "bar"
+                }
+            }
         }
     ]
 };
diff --git a/src/backend/events/filters/builtin/firebot/custom-widget-message-name.ts b/src/backend/events/filters/builtin/firebot/custom-widget-message-name.ts
@@ -0,0 +1,13 @@
+import { createTextFilter } from "../../filter-factory";
+
+const filter = createTextFilter({
+    id: "firebot:custom-widget-message-name",
+    name: "Message Name",
+    description: "Filter to specific message name",
+    events: [
+        { eventSourceId: "firebot", eventId: "custom-widget-message-received" }
+    ],
+    eventMetaKey: "customWidgetMessageName"
+});
+
+export default filter;
diff --git a/src/backend/events/filters/builtin/firebot/custom-widget.ts b/src/backend/events/filters/builtin/firebot/custom-widget.ts
@@ -0,0 +1,22 @@
+import { createPresetFilter } from "../../filter-factory";
+
+const filter = createPresetFilter({
+    id: "firebot:custom-widget",
+    name: "Custom Widget",
+    description: "Filter to a Custom overlay widget (both Basic and Advanced types)",
+    events: [
+        { eventSourceId: "firebot", eventId: "custom-widget-message-received" }
+    ],
+    eventMetaKey: "customWidgetId",
+    allowIsNot: true,
+    presetValues: (overlayWidgetsService: any) => {
+        return overlayWidgetsService.getOverlayWidgetConfigsByTypes(["firebot:custom", "firebot:custom-advanced"])
+            .map(c => ({ value: c.id, display: c.name }));
+    },
+    valueIsStillValid: (filterSettings, overlayWidgetsService: any) => {
+        return overlayWidgetsService.getOverlayWidgetConfigsByTypes(["firebot:custom", "firebot:custom-advanced"])
+            .some(c => c.id === filterSettings.value);
+    }
+});
+
+export default filter;
diff --git a/src/backend/events/filters/builtin/firebot/index.ts b/src/backend/events/filters/builtin/firebot/index.ts
@@ -1,6 +1,8 @@
 import countdownDynamic from "./countdown-dynamic";
 import currency from "./currency";
 import customVariableName from "./custom-variable-name";
+import customWidget from "./custom-widget";
+import customWidgetMessageName from "./custom-widget-message-name";
 import effectQueue from "./effect-queue";
 import metadataKey from "./metadata-key";
 import metadataValue from "./metadata-value";
@@ -21,6 +23,8 @@ export default [
     countdownDynamic,
     currency,
     customVariableName,
+    customWidgetMessageName,
+    customWidget,
     effectQueue,
     metadataKey,
     metadataValue,
diff --git a/src/backend/overlay-widgets/builtin-types/custom/custom-advanced.ts b/src/backend/overlay-widgets/builtin-types/custom/custom-advanced.ts
@@ -1,4 +1,5 @@
 import { OverlayWidgetType, IOverlayWidgetEventUtils, WidgetOverlayEvent } from "../../../../types/overlay-widgets";
+import { EventManager } from "../../../events/event-manager";
 
 type Settings = {
     onEventJs: string;
@@ -36,7 +37,16 @@ if (eventName === "show") {
   document
     .getElementById(widgetId)?.remove();
 }`,
-            tip: "The following variables are available:\n- `eventName` (the name of the received event: `show`, `settings-update`, `state-update`, `message`, `remove`)\n- `widgetId` (this widget's unique ID)\n- `widgetState` (the current state of the widget, if any)\n- `messageName` (the name of the received message, if event is 'message')\n- `messageData` (the data sent with the message, if any and if event is 'message')\n- `overlayWrapperElement` (the official root element of the overlay, it's recommended to use this for DOM manipulations)\n- `utils.stylesToString(styles)` (utility function to convert a styles object to an inline css string)",
+            tip:
+`The following variables are available:
+- \`eventName\` (the name of the received event: \`show\`, \`settings-update\`, \`state-update\`, \`message\`, \`remove\`)
+- \`widgetId\` (this widget's unique ID)
+- \`widgetState\` (the current state of the widget, if any)
+- \`messageName\` (the name of the received message, if event is 'message')
+- \`messageData\` (the data sent with the message, if any and if event is 'message')
+- \`overlayWrapperElement\` (the official root element of the overlay, it's recommended to use this for DOM manipulations)
+- \`utils.stylesToString(styles)\` (utility function to convert a styles object to an inline css string)
+- \`utils.sendMessageToFirebot(messageName: string, messageData?: any)\` (utility function to send a message back to Firebot)`,
             settings: {
                 mode: { name: "javascript" },
                 lineNumbers: true,
@@ -57,6 +67,14 @@ if (eventName === "show") {
     },
     supportsLivePreview: false,
     livePreviewState: {},
+    onOverlayMessage(config, messageName, messageData) {
+        void EventManager.triggerEvent("firebot", "custom-widget-message-received", {
+            customWidgetId: config.id,
+            customWidgetName: config.name,
+            customWidgetMessageName: messageName,
+            customWidgetMessageData: messageData
+        });
+    },
     overlayExtension: {
         eventHandler: async (event: WidgetOverlayEvent<Settings, State>, utils: IOverlayWidgetEventUtils) => {
             if (!event.data.widgetConfig.settings.onEventJs) {
@@ -96,7 +114,8 @@ if (eventName === "show") {
                 messageData: event.data.messageData,
                 overlayWrapperElement: document.body.querySelector(".wrapper"),
                 utils: {
-                    stylesToString: utils.stylesToString
+                    ...utils,
+                    sendMessageToFirebot: utils.sendMessageToFirebot.bind(utils)
                 }
             });
         }
diff --git a/src/backend/overlay-widgets/builtin-types/custom/custom.ts b/src/backend/overlay-widgets/builtin-types/custom/custom.ts
@@ -1,4 +1,5 @@
 import { OverlayWidgetType, IOverlayWidgetEventUtils, WidgetOverlayEvent } from "../../../../types/overlay-widgets";
+import { EventManager } from "../../../events/event-manager";
 
 type Settings = {
     html: string;
@@ -34,8 +35,13 @@ export const custom: OverlayWidgetType<Settings, State> = {
             type: "codemirror",
             title: "onShow JS",
             description: "Optional code that runs when the widget is shown. Ran in an async function (await is supported).",
-            default: `// Example: Change the text color of the widget's\n// content to red\ncontainerElement\n.   .querySelector('#my-widget')\n.   .style.color = 'red';`,
-            tip: "The following variables are available:\n- `containerElement` (the root HTML element of the widget)\n- `widgetId` (this widget's unique ID)\n- `widgetState` (the current state of the widget, if any)",
+            default: `// Example: Change the text color of the widget's\n// content to red\ncontainerElement\n   .querySelector('#my-widget')\n   .style.color = 'red';`,
+            tip:
+`The following variables are available:
+- \`containerElement\` (the root HTML element of the widget)
+- \`widgetId\` (this widget's unique ID)
+- \`widgetState\` (the current state of the widget, if any)
+- \`utils.sendMessageToFirebot(messageName: string, messageData?: any)\` (utility function to send a message back to Firebot)`,
             settings: {
                 mode: { name: "javascript" },
                 lineNumbers: true,
@@ -50,7 +56,12 @@ export const custom: OverlayWidgetType<Settings, State> = {
             title: "onStateUpdate JS",
             description: "Optional code that runs when the widget's state is updated via the Update Custom Widget State effect. Ran in an async function (await is supported).",
             default: ``,
-            tip: "The following variables are available:\n- `containerElement` (the root HTML element of the widget)\n- `widgetId` (this widget's unique ID)\n- `widgetState` (the current state of the widget, if any)",
+            tip:
+`The following variables are available:
+- \`containerElement\` (the root HTML element of the widget)
+- \`widgetId\` (this widget's unique ID)
+- \`widgetState\` (the current state of the widget, if any)
+- \`utils.sendMessageToFirebot(messageName: string, messageData?: any)\` (utility function to send a message back to Firebot)`,
             settings: {
                 mode: { name: "javascript" },
                 lineNumbers: true,
@@ -65,7 +76,14 @@ export const custom: OverlayWidgetType<Settings, State> = {
             title: "onMessage JS",
             description: "Optional code that runs when the widget receives a message from the Send Message To Custom Widget effect. Ran in an async function (await is supported).",
             default: ``,
-            tip: "The following variables are available:\n- `containerElement` (the root HTML element of the widget)\n- `widgetId` (this widget's unique ID)\n- `widgetState` (the current state of the widget, if any)\n- `messageName` (the name of the received message)\n- `messageData` (the data sent with the message, if any)",
+            tip:
+`The following variables are available:
+- \`containerElement\` (the root HTML element of the widget)
+- \`widgetId\` (this widget's unique ID)
+- \`widgetState\` (the current state of the widget, if any)
+- \`messageName\` (the name of the received message)
+- \`messageData\` (the data sent with the message, if any)
+- \`utils.sendMessageToFirebot(messageName: string, messageData?: any)\` (utility function to send a message back to Firebot)`,
             settings: {
                 mode: { name: "javascript" },
                 lineNumbers: true,
@@ -78,6 +96,14 @@ export const custom: OverlayWidgetType<Settings, State> = {
     initialState: {},
     supportsLivePreview: true,
     livePreviewState: {},
+    onOverlayMessage(config, messageName, messageData) {
+        void EventManager.triggerEvent("firebot", "custom-widget-message-received", {
+            customWidgetId: config.id,
+            customWidgetName: config.name,
+            customWidgetMessageName: messageName,
+            customWidgetMessageData: messageData
+        });
+    },
     overlayExtension: {
         eventHandler: async (event: WidgetOverlayEvent<Settings, State>, utils: IOverlayWidgetEventUtils) => {
             utils.handleOverlayEvent((config) => {
@@ -112,15 +138,23 @@ export const custom: OverlayWidgetType<Settings, State> = {
                 await runRawJs(event.data.widgetConfig.settings.onShowJs, {
                     containerElement: utils.getWidgetContainerElement(),
                     widgetId: event.data.widgetConfig.id,
-                    widgetState: event.data.widgetConfig.state
+                    widgetState: event.data.widgetConfig.state,
+                    utils: {
+                        ...utils,
+                        sendMessageToFirebot: utils.sendMessageToFirebot.bind(utils)
+                    }
                 });
             }
 
             if (event.name === "state-update" && event.data.widgetConfig.settings.onStateUpdateJs) {
                 await runRawJs(event.data.widgetConfig.settings.onStateUpdateJs, {
                     containerElement: utils.getWidgetContainerElement(),
                     widgetId: event.data.widgetConfig.id,
-                    widgetState: event.data.widgetConfig.state
+                    widgetState: event.data.widgetConfig.state,
+                    utils: {
+                        ...utils,
+                        sendMessageToFirebot: utils.sendMessageToFirebot.bind(utils)
+                    }
                 });
             }
 
@@ -130,7 +164,11 @@ export const custom: OverlayWidgetType<Settings, State> = {
                     widgetId: event.data.widgetConfig.id,
                     widgetState: event.data.widgetConfig.state,
                     messageName: event.data.messageName,
-                    messageData: event.data.messageData
+                    messageData: event.data.messageData,
+                    utils: {
+                        ...utils,
+                        sendMessageToFirebot: utils.sendMessageToFirebot.bind(utils)
+                    }
                 });
             }
         }
diff --git a/src/backend/overlay-widgets/overlay-widgets-manager.ts b/src/backend/overlay-widgets/overlay-widgets-manager.ts
@@ -319,5 +319,25 @@ websocketServerManager.on("overlay-connected", (instanceName: string = "Default"
     }
 });
 
+websocketServerManager.on("overlay-event", (event: { name: string, data: unknown }) => {
+    if (event.name !== "overlay-widget-message") {
+        return;
+    }
+    const data = event.data as { widgetConfigId: string, messageName: string, messageData?: unknown };
+    const config = overlayWidgetConfigManager.getItem(data.widgetConfigId);
+    if (!config) {
+        logger.warn(`Overlay widget config with ID '${data.widgetConfigId}' not found for overlay message.`);
+        return;
+    }
+    const type = manager.getOverlayWidgetType(config.type);
+    if (!type) {
+        logger.warn(`Overlay widget type with ID '${config.type}' not found for overlay message on widget ID '${data.widgetConfigId}'.`);
+        return;
+    }
+    if (type.onOverlayMessage) {
+        void type.onOverlayMessage(config, data.messageName, data.messageData);
+    }
+});
+
 
 export = manager;
diff --git a/src/backend/variables/builtin/overlay-widgets/custom-widget-id.ts b/src/backend/variables/builtin/overlay-widgets/custom-widget-id.ts
@@ -0,0 +1,9 @@
+import { createEventDataVariable } from "../../variable-factory";
+
+export default createEventDataVariable({
+    handle: "customWidgetId",
+    description: "The ID of the custom widget",
+    events: ["firebot:custom-widget-message-received"],
+    type: "text",
+    eventMetaKey: "customWidgetId"
+});
diff --git a/src/backend/variables/builtin/overlay-widgets/custom-widget-message-data.ts b/src/backend/variables/builtin/overlay-widgets/custom-widget-message-data.ts
@@ -0,0 +1,9 @@
+import { createEventDataVariable } from "../../variable-factory";
+
+export default createEventDataVariable({
+    handle: "customWidgetMessageData",
+    description: "The data of the custom widget message",
+    events: ["firebot:custom-widget-message-received"],
+    type: "ALL",
+    eventMetaKey: "customWidgetMessageData"
+});
diff --git a/src/backend/variables/builtin/overlay-widgets/custom-widget-message-name.ts b/src/backend/variables/builtin/overlay-widgets/custom-widget-message-name.ts
@@ -0,0 +1,9 @@
+import { createEventDataVariable } from "../../variable-factory";
+
+export default createEventDataVariable({
+    handle: "customWidgetMessageName",
+    description: "The name of the custom widget message",
+    events: ["firebot:custom-widget-message-received"],
+    type: "text",
+    eventMetaKey: "customWidgetMessageName"
+});
diff --git a/src/backend/variables/builtin/overlay-widgets/custom-widget-name.ts b/src/backend/variables/builtin/overlay-widgets/custom-widget-name.ts
@@ -0,0 +1,9 @@
+import { createEventDataVariable } from "../../variable-factory";
+
+export default createEventDataVariable({
+    handle: "customWidgetName",
+    description: "The name of the custom widget",
+    events: ["firebot:custom-widget-message-received"],
+    type: "text",
+    eventMetaKey: "customWidgetName"
+});
diff --git a/src/backend/variables/builtin/overlay-widgets/index.ts b/src/backend/variables/builtin/overlay-widgets/index.ts
@@ -1,9 +1,17 @@
+import customWidgetId from "./custom-widget-id";
+import customWidgetMessageData from "./custom-widget-message-data";
+import customWidgetMessageName from "./custom-widget-message-name";
+import customWidgetName from "./custom-widget-name";
 import dynamicCountdownId from "./dynamic-countdown-id";
 import dynamicCountdownName from "./dynamic-countdown-name";
 import overlayWidgetState from "./overlay-widget-state";
 
 export default [
     dynamicCountdownId,
     dynamicCountdownName,
-    overlayWidgetState
+    overlayWidgetState,
+    customWidgetId,
+    customWidgetName,
+    customWidgetMessageName,
+    customWidgetMessageData
 ];
diff --git a/src/resources/overlay/js/overlay-widgets.ts b/src/resources/overlay/js/overlay-widgets.ts
@@ -218,6 +218,13 @@ class OverlayWidgetEventUtils implements IOverlayWidgetEventUtils {
             "color": fontOptions?.color || '#FFFFFF',
         };
     }
+    sendMessageToFirebot(messageName: string, messageData?: unknown): void {
+        sendWebsocketEvent("overlay-widget-message", {
+            widgetConfigId: this.widgetId,
+            messageName,
+            messageData
+        });
+    }
 }
 
 function handleOverlayEvent(event: WidgetOverlayEvent) {
diff --git a/src/types/overlay-widgets.d.ts b/src/types/overlay-widgets.d.ts
@@ -138,6 +138,10 @@ export type OverlayWidgetType<
      * Called before the widget is removed from the overlay. You can modify state here.
      */
     onRemove?: WidgetEventHandler<Settings, State>;
+    /**
+     * Called when the widget sends a message from the overlay.
+     */
+    onOverlayMessage?: (config: OverlayWidgetConfig<Settings, State>, messageName: string, messageData?: unknown) => Awaitable<void>;
     /**
      * This code is injected into the overlay. Do not reference any variables outside this scope.
      */
@@ -218,6 +222,7 @@ export interface IOverlayWidgetEventUtils {
     removeWidget(): void;
     stylesToString(styles: Record<string, string | number | undefined>): string;
     getFontOptionsStyles(fontOptions?: FontOptions): Record<string, string | number | undefined>;
+    sendMessageToFirebot(messageName: string, messageData?: unknown): void;
 }
 
 export interface IOverlayWidgetInitUtils {
