Add support for system notifications when game and tab are unfocused

danthedaniel · danthedaniel · commit 95d068bb34c5 · 2025-07-06T19:26:13.000-07:00
diff --git a/src/client/java/dev/creesch/config/ModConfig.java b/src/client/java/dev/creesch/config/ModConfig.java
@@ -33,6 +33,9 @@ public class ModConfig {
     @SerialEntry(comment = "Enable ping on username")
     public boolean pingOnUsername = true;
 
+    @SerialEntry(comment = "Enable system notifications")
+    public boolean systemNotifications = false;
+
     @SerialEntry(comment = "Extra ping keywords")
     public List<String> pingKeywords = Arrays.asList();
 
diff --git a/src/client/java/dev/creesch/config/ModConfigScreen.java b/src/client/java/dev/creesch/config/ModConfigScreen.java
@@ -45,6 +45,30 @@ public static Screen createScreen(Screen parent) {
                                 .controller(BooleanControllerBuilder::create)
                                 .build()
                         )
+                        .option(
+                            Option.<Boolean>createBuilder()
+                                .name(Text.literal("System Notifications"))
+                                .description(
+                                    OptionDescription.of(
+                                        Text.literal(
+                                            "Send system notifications when pinged.\n" +
+                                            "Notifications are only sent when the game and chat browser tab are unfocused."
+                                        )
+                                    )
+                                )
+                                .binding(
+                                    ModConfig.HANDLER.defaults()
+                                        .systemNotifications,
+                                    () ->
+                                        ModConfig.HANDLER.instance()
+                                            .systemNotifications,
+                                    val ->
+                                        ModConfig.HANDLER.instance()
+                                            .systemNotifications = val
+                                )
+                                .controller(BooleanControllerBuilder::create)
+                                .build()
+                        )
                         .build()
                 )
                 .group(
diff --git a/src/client/java/dev/creesch/model/ChatMessagePayload.java b/src/client/java/dev/creesch/model/ChatMessagePayload.java
@@ -14,4 +14,5 @@ public class ChatMessagePayload {
     private JsonObject component;
     private Map<String, String> translations;
     private boolean isPing;
+    private boolean notify;
 }
diff --git a/src/client/java/dev/creesch/model/WebsocketMessageBuilder.java b/src/client/java/dev/creesch/model/WebsocketMessageBuilder.java
@@ -79,6 +79,8 @@ public static WebsocketJsonMessage createLiveChatMessage(
             (timestamp + minecraftChatJson).getBytes()
         ).toString();
 
+        boolean ping = !fromSelf && isPing(message, client);
+        boolean notify = ping && doNotify(client);
         // Back to objects we go
         JsonObject jsonObject = gson.fromJson(
             minecraftChatJson,
@@ -88,7 +90,8 @@ public static WebsocketJsonMessage createLiveChatMessage(
             .history(false)
             .uuid(messageUUID)
             .component(jsonObject)
-            .isPing(!fromSelf && isPing(message, client))
+            .isPing(ping)
+            .notify(notify)
             .translations(translations)
             .build();
 
@@ -163,6 +166,17 @@ private static Pattern pingPattern(String pingKeyword) {
         );
     }
 
+    /**
+     * Whether the web clients should send a system notification.
+     */
+    private static boolean doNotify(MinecraftClient client) {
+        if (client.isWindowFocused()) {
+            return false;
+        }
+
+        return ModConfig.HANDLER.instance().systemNotifications;
+    }
+
     /**
      * Processes both chat and game messages, converting them to the appropriate format.
      */
diff --git a/src/client/resources/web/js/chat.mjs b/src/client/resources/web/js/chat.mjs
@@ -14,6 +14,7 @@ import { directMessageManager } from './managers/direct_message.mjs';
 import { parseModServerMessage } from './messages/message_types.mjs';
 import { faviconManager } from './managers/favicon_manager.mjs';
 import { tabListManager } from './managers/tab_list_manager.mjs';
+import { notificationManager } from './managers/notification_manager.mjs';
 
 /**
  * Import all types we might need
@@ -162,6 +163,19 @@ loadMoreButtonElement.addEventListener('click', () => {
     }
 });
 
+async function enableNotificationsOnClick() {
+    if (await notificationManager.enableNotifications()) {
+        console.log('Notifications enabled');
+    } else {
+        console.log('Notifications not enabled');
+    }
+
+    document.body.removeEventListener('click', enableNotificationsOnClick);
+}
+if (!notificationManager.isEnabled()) {
+    document.body.addEventListener('click', enableNotificationsOnClick);
+}
+
 /**
  * ======================
  *  Chat related functions
@@ -210,79 +224,76 @@ function handleChatMessage(message) {
         faviconManager.handleNewMessage(message.payload.isPing);
     }
 
-    requestAnimationFrame(() => {
-        const messageElement = document.createElement('article');
-        messageElement.classList.add('message');
+    const messageElement = document.createElement('article');
+    messageElement.classList.add('message');
 
-        if (message.payload.isPing) {
-            messageElement.classList.add('ping');
-        }
-
-        // Create timestamp outside of try block. That way errors can be timestamped as well for the moment they did happen.
-        const { timeString, fullDateTime } = formatTimestamp(message.timestamp);
-        const timeElement = document.createElement('time');
-        timeElement.dateTime = new Date(message.timestamp).toISOString();
-        timeElement.textContent = timeString;
-        timeElement.title = fullDateTime;
-        timeElement.className = 'message-time';
-        messageElement.appendChild(timeElement);
+    if (message.payload.isPing) {
+        messageElement.classList.add('ping');
+    }
 
-        try {
-            // Format the chat message - this uses the Component format from message_parsing
-            assertIsComponent(message.payload.component);
-            const chatContent = formatChatMessage(
-                message.payload.component,
-                message.payload.translations,
-            );
-            messageElement.appendChild(chatContent);
-        } catch (e) {
-            console.error(message);
-            if (e instanceof ComponentError) {
-                console.error('Invalid component:', e.toString());
-                messageElement.appendChild(
-                    formatChatMessage(
-                        {
-                            text: 'Invalid message received from server',
-                            color: 'red',
-                        },
-                        {},
-                    ),
-                );
-            } else {
-                console.error('Error parsing message:', e);
-                messageElement.appendChild(
-                    formatChatMessage(
-                        {
-                            text: 'Error parsing message',
-                            color: 'red',
-                        },
-                        {},
-                    ),
-                );
-            }
+    // Create timestamp outside of try block. That way errors can be timestamped as well for the moment they did happen.
+    const { timeString, fullDateTime } = formatTimestamp(message.timestamp);
+    const timeElement = document.createElement('time');
+    timeElement.dateTime = new Date(message.timestamp).toISOString();
+    timeElement.textContent = timeString;
+    timeElement.title = fullDateTime;
+    timeElement.className = 'message-time';
+    messageElement.appendChild(timeElement);
+
+    try {
+        // Format the chat message - this uses the Component format from message_parsing
+        assertIsComponent(message.payload.component);
+        const chatContent = formatChatMessage(
+            message.payload.component,
+            message.payload.translations,
+        );
+
+        if (message.payload.notify && chatContent.textContent) {
+            notificationManager.sendNotification(chatContent.textContent);
         }
 
-        // Storing raw scroll value. To be used to fix the scroll position down the line.
-        const scrolledFromTop = messagesElement.scrollTop;
-
-        if (message.payload.history) {
-            // Insert the message after the load-more button
-            loadMoreContainerElement.before(messageElement);
+        messageElement.appendChild(chatContent);
+    } catch (e) {
+        console.error(message);
+        if (e instanceof ComponentError) {
+            console.error('Invalid component:', e.toString());
+            messageElement.appendChild(
+                formatChatMessage({
+                    text: 'Invalid message received from server',
+                    color: 'red',
+                }),
+            );
         } else {
-            // For new messages, insert at the start
-            messagesElement.insertBefore(
-                messageElement,
-                messagesElement.firstChild,
+            console.error('Error parsing message:', e);
+            messageElement.appendChild(
+                formatChatMessage({
+                    text: 'Error parsing message',
+                    color: 'red',
+                }),
             );
         }
+    }
 
-        // If it is due to the flex column reverse or something else, once the user has scrolled it doesn't "lock" at the bottom.
-        // Let's fix that, if the user was near the bottom when a message was inserted we put them back there.
-        // Note: the values appear negative due to the flex column shenanigans.
-        if (scrolledFromTop <= 1 && scrolledFromTop >= -35) {
-            messagesElement.scrollTop = 0;
-        }
-    });
+    // Storing raw scroll value. To be used to fix the scroll position down the line.
+    const scrolledFromTop = messagesElement.scrollTop;
+
+    if (message.payload.history) {
+        // Insert the message after the load-more button
+        loadMoreContainerElement.before(messageElement);
+    } else {
+        // For new messages, insert at the start
+        messagesElement.insertBefore(
+            messageElement,
+            messagesElement.firstChild,
+        );
+    }
+
+    // If it is due to the flex column reverse or something else, once the user has scrolled it doesn't "lock" at the bottom.
+    // Let's fix that, if the user was near the bottom when a message was inserted we put them back there.
+    // Note: the values appear negative due to the flex column shenanigans.
+    if (scrolledFromTop <= 1 && scrolledFromTop >= -35) {
+        messagesElement.scrollTop = 0;
+    }
 }
 
 function clearMessageHistory() {
diff --git a/src/client/resources/web/js/managers/notification_manager.mjs b/src/client/resources/web/js/managers/notification_manager.mjs
@@ -0,0 +1,77 @@
+// @ts-check
+'use strict';
+
+/**
+ * Manages browser notifications for new messages
+ */
+class NotificationManager {
+    /**
+     * @type {boolean}
+     */
+    #notificationsEnabled = false;
+
+    constructor() {
+        // Check if notifications are supported
+        if (!('Notification' in window)) {
+            console.warn('This browser does not support notifications');
+            return;
+        }
+
+        // Check if we already have permission
+        if (Notification.permission === 'granted') {
+            this.#notificationsEnabled = true;
+        }
+    }
+
+    /**
+     * Enable notifications by requesting permission from the user
+     * @returns {Promise<boolean>} Whether notifications were successfully enabled
+     */
+    async enableNotifications() {
+        if (!('Notification' in window)) {
+            return false;
+        }
+
+        if (Notification.permission === 'granted') {
+            this.#notificationsEnabled = true;
+            return true;
+        }
+
+        if (Notification.permission !== 'denied') {
+            const permission = await Notification.requestPermission();
+            this.#notificationsEnabled = permission === 'granted';
+            return this.#notificationsEnabled;
+        }
+
+        return false;
+    }
+
+    /**
+     * Send a notification if notifications are enabled and the page is not visible
+     * @param {string} text - The text to display in the notification
+     */
+    sendNotification(text) {
+        if (!this.#notificationsEnabled) {
+            return;
+        }
+        if (document.visibilityState === 'visible') {
+            return;
+        }
+
+        new Notification('Minecraft WebChat', {
+            body: text,
+            icon: '/img/icon_32.png',
+        });
+    }
+
+    /**
+     * Get whether notifications are currently enabled
+     * @returns {boolean}
+     */
+    isEnabled() {
+        return this.#notificationsEnabled;
+    }
+}
+
+// Export a singleton instance since we only need one notification manager
+export const notificationManager = new NotificationManager();
diff --git a/src/client/resources/web/js/messages/message_parsing.mjs b/src/client/resources/web/js/messages/message_parsing.mjs
@@ -1337,10 +1337,10 @@ export function formatPlainText(element) {
 /**
  * Transforms a Minecraft component into HTML.
  * @param {Component} component
- * @param {Record<string, string>} translations Translation key-value pairs
+ * @param {Record<string, string>} [translations] Translation key-value pairs
  * @returns {Element | Text}
  */
-export function formatChatMessage(component, translations) {
+export function formatChatMessage(component, translations = {}) {
     // Message payload should come with translations included. If not it likely is a legacy 1.21.1 message and the fallback translation file is used.
     const usedTranslations = Object.keys(translations).length
         ? translations
diff --git a/src/client/resources/web/js/messages/message_types.mjs b/src/client/resources/web/js/messages/message_types.mjs
@@ -30,6 +30,7 @@
  *     translations: Record<string, string>,
  *     uuid: string,
  *     isPing: boolean,
+ *     notify: boolean,
  *   }
  * }} ChatMessage
  */

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,5 @@ public class ChatMessagePayload {`
`14`	`14`	`private JsonObject component;`
`15`	`15`	`private Map<String, String> translations;`
`16`	`16`	`private boolean isPing;`
	`17`	`+ private boolean notify;`
`17`	`18`	`}`