Merge pull request #34 from paulcheeba/v13.2.1.0

V13.2.1.0

Author: paulcheeba

.gitignore

@@ -0,0 +1,2 @@
+# Development documentation
+dev-docs/

README.md

@@ -1,6 +1,8 @@
 <!-- Latest release (semantic version) -->
 ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/paulcheeba/about-time-next?sort=semver) <!-- Total downloads across all releases -->![Downloads](https://img.shields.io/github/downloads/paulcheeba/about-time-next/total) <!-- Downloads of latest release only -->![Downloads (latest)](https://img.shields.io/github/downloads/paulcheeba/about-time-next/latest/total)
 
+<img width="512" height="512" alt="ATN Logo" src="https://github.com/paulcheeba/about-time-next/blob/v13.2.1.0/assets/images/about-time-next_cartoon_logo_w-ATN.png?raw=true" />
+
 
 # About Time Next (v13.1.3.2)
 
@@ -9,7 +11,7 @@ It works with **Simple Calendar** (*see installation note 3*) or falls back to F
 
 ---
 
-## 📦 Installation
+## Installation
 
 1. Download and install via Foundry’s module browser  
 
@@ -28,9 +30,9 @@ It works with **Simple Calendar** (*see installation note 3*) or falls back to F
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-- **EM (Event Manager V2):** Open from the **Journal/Notes** toolbar sub-button **“Event Manager”** (GM-only).  
+- **Event Manager (applicationV2):** Open from the **Journal/Notes** toolbar sub-button **“Event Manager”** (GM-only).  
   Use it to create one-shots or repeating events, stop items by name/UID, view the queue, or flush all.
 
 - **Mini Time Manager (optional):** Enable in **Configure Settings → About-Time** to show a compact panel with **Play/Pause**, current time, and tiny toggles for realtime behavior (GM sees controls; players see time).
@@ -40,11 +42,11 @@ It works with **Simple Calendar** (*see installation note 3*) or falls back to F
 
 ---
 
-## 🧰 Toolbars
+### Toolbar Buttons
 
 <img width="281" height="200" alt="image" src="https://github.com/user-attachments/assets/8f3c06f8-d511-4e0c-9528-9c2b67d1c8a3" />
 
-### Event Manager (V2, ApplicationV2)
+### Event Manager (ApplicationV2)
 
 <img width="923" height="437" alt="image" src="https://github.com/user-attachments/assets/6e72b4b3-477a-417e-bb5b-789698696a46" />
 
@@ -57,7 +59,7 @@ Opened via the **Journal/Notes** toolbar sub-button (GM-only).
 - **Stop all Events**: Flush the queue.  
 - **Stop all + 1h reminder**: Flush and schedule a “Resume in 1h” reminder.
 
-The V2 view auto-updates countdowns and refreshes itself if an event fires or is rescheduled, keeping “Remaining” correct for repeating items.
+The Event Manager auto-updates countdowns and refreshes itself if an event fires or is rescheduled, keeping “Remaining” correct for repeating items.
 
 ### Mini Time Manager (optional, client setting)
 Enable **“Enable AT Time Manager”** to show a compact panel:
@@ -73,7 +75,7 @@ Enable **“Enable AT Time Manager”** to show a compact panel:
 
 ---
 
-## ⌛ Realtime & Clock
+## Realtime & Clock
 
 About-Time provides a simple **realtime worldTime runner** (GM-only, single-owner) with:
 - **Rate** (default 1.0×) and **Tick Hz** settings (safe minimums enforced)
@@ -82,7 +84,7 @@ About-Time provides a simple **realtime worldTime runner** (GM-only, single-owne
 
 ---
 
-## 💬 Chat Commands (GM-only output)
+## Chat Commands (GM-only output)
 
 All commands are handled by `/at` (see `module/ATChat.js`).  
 Durations accept mixed units: days (**d**), hours (**h**), minutes (**m**), seconds (**s**).  
@@ -113,9 +115,9 @@ Examples: `1h30m`, `2d 4h`, `45m10s`, or `5400` (seconds).
 
 ---
 
-## 🗓 Event Manager (details)
+## Event Manager (details)
 
-The EM V2 lists every queued item with:
+The Event Manager lists every queued item with:
 
 - **Name** (friendly name you provided when scheduling)
 - **UID** (unique identifier; safe to copy)
@@ -132,11 +134,34 @@ Actions (top buttons):
 - **Send Queue to Chat** (GM-whisper)  
 - **Stop all Events** / **Stop all + 1h reminder**
 
-> With **Simple Calendar** installed, About-Time uses SC’s formatting/conversion where appropriate. Without SC, it falls back to core Foundry world time.
+> With **Simple Calendar** installed, About-Time uses SC's formatting/conversion where appropriate. Without SC, it falls back to core Foundry world time.
+
+### Event Notification Cards (v13.2.1.0)
+When events trigger, they display standardized notification cards with detailed information:
+
+<img width="293" height="365" alt="image" src="https://github.com/user-attachments/assets/0bbc2efb-e1a4-408c-9b54-1865c1e4d457" />
+
+
+```
+[about-time-next]
+Event Name: <name or NA>
+Message: <message or NA>
+Duration: DD:HH:MM:SS (or NA)
+Repeating: Yes/No
+Macro: <macro name or NA>
+Event UID: <unique identifier>
+```
+
+- **Consistent Format**: All Event Manager events use the same card layout
+- **Persistence**: Format maintained through Foundry reloads
+- **Macro Integration**: Events with macros show the event card *and* executes the macro
+- **Sound Support**: `[about-time-next]` prefix ensures notification sounds trigger correctly
+
+_Note: `/at` chat commands currently use legacy format. Standardization planned for future release._
 
 ---
 
-## 🧩 Macros
+## Macros
 
 **Advance by 30 seconds (core FVTT v13):**
 ```js
@@ -172,7 +197,7 @@ game.abouttime.notifyIn({ seconds: 30 }, "myCustomEvent", "arg1", "arg2");
 
 ---
 
-## 🧪 Example Scenarios
+## Example Scenarios
 
 - **Short Rest timer (one-shot):**  
   “Wake the party in 1 hour.”  
@@ -191,17 +216,36 @@ game.abouttime.notifyIn({ seconds: 30 }, "myCustomEvent", "arg1", "arg2");
 
 ---
 
-## ⚙ Settings (high-level)
+## Settings (high-level)
 
 - **Enable AT Time Manager (client)** — Shows the mini panel for this user.  
 - **Realtime Rate / Tick Hz (world)** — Controls the realtime runner (GM-only; safe ranges enforced).  
 - **Link Pause / Auto-Pause Combat (client)** — How the mini panel reacts to world/game state.
 
+### Event Notification Sounds (client, v13.2.0.0)
+
+Configure audible alerts when events trigger (GM-only feature):
+
+- **Enable Event Notification Sound** — Toggle notification sounds on/off
+- **Sound Source** — Choose between built-in sound or custom audio file
+- **Custom Sound Path** — File picker to select your own audio (defaults to module's sounds folder)
+- **Notification Volume** — Adjust volume from 0-100% (affects only ATN notifications)
+- **Test Sound** — Preview button to hear current selection before saving
+
+Event notifications play automatically when scheduled events fire, helping GMs track timers without constantly watching the Event Manager. Settings apply immediately after saving, so you can adjust volume mid-session without reloading. Included are 3 royalty free notification sounds.
+- Supported file types:
+  - MP3 (.mp3) - Most widely supported, best compatibility
+  - OGG (.ogg) - Good compression, well-supported
+  - WAV (.wav) - Uncompressed, larger files
+  - WebM (.webm) - Modern format with good compression
+  - M4A (.m4a) - AAC audio, good quality
+Best practice: MP3 is the safest choice for maximum browser compatibility across all platforms (which is why we used it for the notification sounds in v13.2.0.0+).
+
 > Where SC is present, date/time formatting in the mini panel and EM uses SC helpers.
 
 ---
 
-## ❗ Notes & Limitations
+## Notes & Limitations
 
 - The module **does not** override combat round/initiative time.  
 - Complex SC calendars (non-365-day years, custom months) are supported via SC’s own conversions, while raw seconds math remains conservative in fallback mode.  
@@ -210,10 +254,12 @@ game.abouttime.notifyIn({ seconds: 30 }, "myCustomEvent", "arg1", "arg2");
 
 ---
 
-## 📝 Credits
+## Credits
 
 Originally created by **Tim Posney**, updated and maintained for FVTT v13+ by **paulcheeba** with community input and ChatGPT-assisted refactoring.
 
-## 📝 License
+**Event notification sound effects** by [Notification_Message](https://pixabay.com/users/notification_message-47259947/) from [Pixabay](https://pixabay.com/sound-effects/).
+
+## License
 
 MIT — see LICENSE file.

about-time.js

@@ -1,5 +1,5 @@
 // about-time.js — Entry point
-// v13.1.1.1  (Hotfix: use active-combat signal and reconcile on updateCombat)
+// v13.2.0.0 — Added event notification sound system
 
 import { registerSettings, MODULE_ID } from './module/settings.js';
 import { preloadTemplates } from './module/preloadTemplates.js';
@@ -13,6 +13,7 @@ import { registerMiniSettings } from './module/ATMiniSettings.js';
 import { showMiniPanel, hideMiniPanel, toggleMiniPanel } from './module/ATMiniPanel.js';
 import { startRealtime, stopRealtime, isRealtimeRunning, setRealtimeRate } from './module/ATRealtimeClock.js';
 import './module/ATMiniToolbar.js'; // only adds tool when enabled & GM
+import { ATNotificationSound } from './module/ATNotificationSound.js'; // v13.2.0.0 - event notifications
 
 // Side-effect imports (existing)
 import './module/ATChat.js'; // /at chat command
@@ -145,6 +146,9 @@ Hooks.once('ready', () => {
   PseudoClock.init();
   ElapsedTime.init();
 
+  // Initialize event notification sound system (v13.2.0.0)
+  ATNotificationSound.init();
+
   // Auto-open the mini panel per user setting
   try {
     if (game.settings.get(MODULE_ID, "enableMiniPanel")) {

assets/images/about-time-next_cartoon_logo_w-ATN.png

@@ -1,17 +1,52 @@
+# Changelog (v13.2.1.0)
+
+- **Standardized Event Chat Cards**  
+  All Event Manager events now display detailed, consistently formatted notification cards with clear visual styling. Cards include event name, message, duration (DD:HH:MM:SS), repeating status, macro name, and event UID. Format persists through Foundry reloads with all metadata intact.
+
+- **Event Card Persistence Fix**  
+  Fixed critical bug where event metadata was lost after Foundry reload, causing empty or malformed chat messages. Implemented deep cloning for proper serialization through Foundry's settings system, ensuring all event details survive reload cycles.
+
+- **[about-time-next] Prefix Integration**  
+  Event cards now always include the `[about-time-next]` prefix, ensuring notification sounds trigger correctly for both fresh events and after reload. Both fresh handlers and reconstructed handlers use the same standardized format for consistency.
+
+- **Macro Integration Enhancement**  
+  Events with macros now display the event notification card *before* executing the macro, providing clear context about what triggered the macro execution. Both card and macro output appear in sequence.
+
+- **UID Display Fix**  
+  Corrected issue where event UID displayed as "null" in fresh event cards. UIDs now display correctly in both pre-reload and post-reload scenarios.
+
+---
+
+# Changelog (v13.2.0.0)
+
+- **Event Notification Sounds**  
+  Added audible alerts when scheduled events trigger (GM-only). Configure sound source, volume, and preview selections via module settings. Includes 3 built-in notification sounds with file picker support for custom audio.
+
+- **Settings Enhancements**  
+  Added 5 new client settings for notification sound system: enable/disable toggle, sound source selector, custom sound path with file picker, volume slider (0-100%), and test button for previewing sounds before saving.
+
+- **Hook-Based Detection**  
+  Implemented ATNotificationSound.js with pattern-matching detection for ATN event chat messages, ensuring notifications play only for actual event triggers without modifying existing event handling code.
+
+- **Localization**  
+  Added 11 new translation keys for notification settings and test button (English only; other languages use fallback).
+
+---
+
 # Changelog (v13.1.1.1)
 
 - **Fixed pause/link bug**  
   Replaced all combat-state checks from `game.combats?.size` to `!!game.combat`, ensuring realtime is gated only by active combat, not dormant combat documents.
 
 - **Realtime runner reconciliation**  
-  Added `Hooks.on("updateCombat", ...)` to catch combat start/stop transitions that don’t create or delete combat documents (e.g., starting an encounter from an existing record, scene changes).
+  Added `Hooks.on("updateCombat", ...)` to catch combat start/stop transitions that don't create or delete combat documents (e.g., starting an encounter from an existing record, scene changes).
 
 - **Pause/unpause logic corrected**  
   Updated the `pauseGame` hook to resume realtime only when the game is unpaused *and* no active combat exists.
 
 - **Setting `rtLinkPause` fixed**  
-  Adjusted its `onChange` handler to also use `!!game.combat`, eliminating sticky mismatches where toggling wouldn’t update the runner state.
+  Adjusted its `onChange` handler to also use `!!game.combat`, eliminating sticky mismatches where toggling wouldn't update the runner state.
 
 - **UI text clarification**  
   Updated hover text for `rtAutoPauseCombat` to:  
-  *“Auto Pause at Combat Start/End”* for clearer user intent.
+  *"Auto Pause at Combat Start/End"* for clearer user intent.

assets/sounds/notification-9-270134.mp3

@@ -37,5 +37,19 @@
   "about-time.display.advanceMidDay": "Advance to mid day",
   "about-time.display.advanceMidnight": "Advance to midnight",
 
-  "about-time.countDown.startStop": "Start/Stop pseudoclock."
+  "about-time.countDown.startStop": "Start/Stop pseudoclock.",
+
+  "ATN.SETTINGS.EnableEventNotificationSound": "Enable Event Notification Sounds",
+  "ATN.SETTINGS.EnableEventNotificationSoundHint": "Play a sound when an event fires and sends a chat message.",
+  "ATN.SETTINGS.EventNotificationSoundSource": "Notification Sound Source",
+  "ATN.SETTINGS.EventNotificationSoundSourceHint": "Choose between the built-in notification sound or a custom audio file.",
+  "ATN.SETTINGS.SoundSourceBuiltin": "Built-in notification sound",
+  "ATN.SETTINGS.SoundSourceCustom": "Custom file path",
+  "ATN.SETTINGS.EventNotificationSoundPath": "Custom Sound File Path",
+  "ATN.SETTINGS.EventNotificationSoundPathHint": "Path to a custom notification sound (only used when 'Custom file path' is selected). Defaults to ATN's included sounds.",
+  "ATN.SETTINGS.EventNotificationVolume": "Notification Volume",
+  "ATN.SETTINGS.EventNotificationVolumeHint": "Volume level for event notification sounds (0-100%).",
+  "ATN.SETTINGS.TestNotificationSound": "Test Notification Sound",
+  "ATN.SETTINGS.TestNotificationSoundButton": "Test Sound",
+  "ATN.SETTINGS.TestNotificationSoundHint": "Play a test notification sound using your current settings."
 }