Global notification manager with achievement/exp support
[heading: "Description"]NotificationSystem is the global toast manager that displays queued notifications in a bordered window at the top of the screen. It supports regular text as well as achievement, error, success, and unlock types, each with its own color scheme and sound. Notifications survive state transitions and are restored once an allowed state loads.
[heading: "Key Features"] [list] * Queues and shows text, error, success, unlock, and achievement notifications * Preserves and restores notifications across state changes * Tinted windows with cycling color animation * Restricted states where notifications stay hidden [/list] [heading: "Properties"] [table header] [ Property | Type | Description ] [ queue | Array | Pending notifications waiting to be shown ] [ isShowing | boolean | Whether a notification is currently on screen ] [ currentNotification | object | The notification currently being displayed ] [ duration | number | Default display duration in milliseconds ] [ lineHeight | number | Line height used to layout notification text ] [ padding | number | Padding around the notification text ] [ maxLineWidth | number | Maximum text width before wrapping in pixels ] [ charWidth | number | Width of a single character in pixels ] [ notificationWindow | Window|null | The window displaying the current notification ] [ notificationTint | Array | Cycling tint colors for the notification window ] [ notificationTexts | Array|null | Text sprites inside the notification window ] [ restrictedStates | Set | State names in which notifications are suppressed ] [ tintAnimationLoop | ?Phaser.TimerEvent | Timer cycling the notification window tint ] [ preservedNotification | ?Object | Copy of the current notification saved across state changes ] [/table] [heading: "Methods"] [table header] [ Method | Parameters | Description ] [ setupStateChangeHandling | () | Patches game.state.start and subscribes to the state change signal. ] [ onStateChange | (newState) | Processes pending notifications and restores preserved ones after a state change. ] [ show | (text, duration=2000, type="normal") | Queues and shows a regular text notification of the given type. ] [ showAchievement | (achievement, expGain=0) | Queues an achievement banner showing the unlocked achievement details. ] [ processPendingNotifications | () | Processes the next queued notification when none is currently showing. ] [ processNext | () | Shows the next queued notification and schedules its hide. ] [ animateNotificationTint | (notification) | Cycles the notification window tint through its configured colors. ] [ stopNotificationTintAnimation | () | Stops the cycling tint animation loop. ] [ playNotificationSound | (notification) | Plays the sound corresponding to the notification type. ] [ displayTextNotification | (text, type="normal") | Builds the notification window and its text lines, fading it in. ] [ wrapText | (text) | Wraps text into lines that fit the maximum notification width. ] [ breakLongWord | (word) | Breaks a word that is longer than the maximum line width into chunks. ] [ getTextWidth | (text) | Estimates the rendered width of a string at the configured char width. ] [ preserveCurrentNotification | () | Saves the current notification with remaining time and clears the UI so it can be restored later, surviving a state change. ] [ restorePreservedNotification | () | Re-displays a preserved notification for its remaining duration. ] [ hideCurrent | () | Fades out and cleans up the current notification, then shows the next one. ] [ cleanupUI | () | Destroys the notification window and all of its text sprites. ] [ isStateAllowed | (stateName) | Returns whether notifications are allowed in the given state name. ] [ clear | () | Clears the queue, current notification, tint animation, and any preserved one. ] [ destroy | () | Clears all notifications and unsubscribes from the state change signal. ] [/table] [heading: "Example Usage (Modding)"] [codeblock javascript] // Modding usage example notifications.show('Song downloaded!', 2000, 'success'); notifications.showAchievement( { name: 'First Steps', description: { achieved: 'Play 1 song' } }, 50 ); [/codeblock] [footer: "© Retora 2026"]