Although basic emits are great for command output, notifications are more broadly used to alert players to things happening in the game.
Table of Contents
There are many different kinds of notifications, which each serve a different purpose.
Emits are specific notifications to players on a MU client. They are not sent to the web portal.
Personal notifications are persistent alerts targeted to individual characters. They’re saved to the database, so folks won’t miss anything. You can view personal notifications by clicking the ‘bell’ icon on the web portal or using the notices command in-game.
These notifications are associated with a specific kind of object - a mail message or a scene, for example. They are marked as ‘read’ when you view the mail/scene/forum/etc. that it’s notifying you about.
Browser alerts are transient messages that appear in the bottom-right corner of the web portal. Depending on the player’s browser and computer settings, they may also appear in the computer’s notification center.
For a player to see these notifications in their computer’s notification center:
Low-priority messages are sent to the game announcements channel rather than directly to players. This allows players to mute/leave the channel when they don’t want to be bothered. This channel is named “Game” by default, though individual games can configure which channel is used.
Finally, you can send raw data to the web portal to update a page. For example, if someone poses in a scene, the game updates the scene live with the new pose data.
Web data updates are not visible to the player, but rather contain raw data that is parsed and handled by the web portal.
There are several notification utilities available in the code.
Emits are sent to a specific player. If you’re in a command handler, you might already have a client or room reference:
client.emit message
enactor.room.emit message
Otherwise you can find a character by name and then notify them with this utility:
Login.emit_if_logged_in(char, message)
Commonly you’ll want to notify BOTH characters on the web portal and those on a MU client. The global notifier class can help.
To notify all characters, you would do:
Global.notifier.notify_ooc(:shutdown, message) do |char|
true
end
:shutdown), is just a symbol identifying the notification. This allows the web portal to act differently for different types of notifications. Here it’s not important because the notification is just a raw message, so the web portal’s default handling will suffice.
You can put conditions into the block to limit the notification to only certain characters. Here the notification is limited to those characters who can read a forum category:
Global.notifier.notify_ooc(type, message) do |char|
char & Forum.can_read_category?(char, category)
end
You can create a personal notification (aka login notice) for a character using this utility:
Login.notify(recipient, :mail, message, message.id)
The type (:mail) and the reference ID (message.id) help the portal direct the player to the proper page to read the item.
:mail. However, if you want the web portal to show the ‘View’ button and let you navigate to a specific page, you’ll need to modify notifications.hbs to add the navigation code.
Ideally, you will mark notifications as read when they’re no longer relevant. For example, you’d mark the mail notification as read once they’ve read the mail message.
Login.mark_notices_read(message.character, :mail, message.id)
Use the same type (:mail) and reference ID (message.id) that you used when creating the notification.
Web data notifications are used to update info on the web portal without emitting to the game, like adding a pose to a scene or a chat message to a channel.
new_combat_activity in both the plugin and portal code for an example you can follow.
As with the global notifier, we can limit the notification to only certain characters. Here we’re only sending it to characters on a channel:
web_message = "#{channel.name.downcase}|#{channel.name}|#{Website.format_markdown_for_html(formatted_msg)}"
Global.client_monitor.notify_web_clients(:new_chat, web_message) do |char|
char && Channels.is_on_channel?(char, channel)
end
The type (:new_chat) tells the web portal how to interpret the data.
notify_web_clients always expects its message parameter to be a string, even when sending data. Typically you will either use a pipe-delimited string of content (as illustrated above) or use to_json on a more complex object. Either way, you’ll need to ensure that the receiver on the web side knows how to handle that data appropriately.
data = {
id: channel.id,
...
is_page: false
}
Global.client_monitor.notify_web_clients(:new_chat, data.to_json, true) do |char|
General game events are sent to the Game channel by default (though you can configure which channel). This includes miscellaneous updates like the who record being broken, and event starting, and so on. Using a channel versus a global emit lets people mute these notifications when they’re RPing and catch up on them later.
Channels.announce_notification(message)