Notifications

A reply arrives while the player is across town; a plan is in an hour; one was missed overnight. Notify tells them: a short toast under the clock, and a row in the notification centre behind the bell on the map's left rail, which keeps an unread count. Both exist on the city map and inside rooms.

lua-- Lua/ynl_clock.lua
local M = "ynl_Nightlife"

Events:handler(M, "doorOpens", function(payload)
	Notify:send(M, "doors_" .. payload.night, {
		title = "The club opens in an hour",
		message = "Guest list closes at midnight.",
		icon = "Nightlife/club.png",   -- a mod image, or a Map/Icons/UI glyph such as "calendar"
		priority = "high",
		target = { page = true },       -- opens your Mods page
	})
end)

Notify exists from the moment your library loads, like Events. Every method takes your mod's folder name first.

#Options

#What to rely on

• One key, one alert. The key is the event's stable id. A key that was already delivered is ignored, also after saving and loading, so a handler that runs again or a page that checks the same overdue plan twice cannot alert twice. Build keys from what makes the event unique: "missed_" .. slot .. "_" .. due, not just "missed".
• Never during a scene. Toasts wait while a scene, the character creator or the city picker holds the game. Sending from inside a scene is fine; the toast shows when it ends.
• No floods. One toast at a time. When three or more are waiting (a night's sleep, a long trip), they become one toast, "5 new notifications", that names the first two and opens the bell.
• Loading does not replay. Read state and delivered keys are saved; the toast queue is not.
• The player decides. Under the bell, each module can be set to everything, list only, or off. Off drops new notifications (send returns false). Read it with Notify:preference(M) if you want to fall back to something else.
• Links are checked. A person who was blocked or removed since, or a page of a module that is turned off, is shown as "No longer available" and does not open. A link never starts a scene.
• Turned off is not deleted. Your notifications stay in the save while your mod is turned off, but are not listed or counted until it comes back.
• Not a history or an inbox. Keep your messages in your own state and significant events in the life history (Actor:record); a notification points at them.

#The phone

For a message from someone (a friend, a parent, a bank), send a text rather than a bare notification: it is kept in that sender's conversation on the map's phone page (the phone button on the rail), and the bell announces it with a link straight to the conversation.

lualocal M = "ul_OldFriends"

Game:SendPhoneMessage(friend, "Long time! Are you still in London?", { mod = M })      -- a person
Game:SendPhoneMessage("Mum", "Call me when you get this.", { mod = M })                -- a name
Game:SendPhoneMessage("Unknown number", "", { mod = M, call = true })                  -- a missed call
Game:SendPhoneMessage(friend, "Yes! Drinks Friday?", { mod = M, fromPlayer = true })   -- the player's reply

local unread = Game:getPhoneUnread()
for _, m in ipairs(Game:getPhoneMessages(friend)) do
	-- m.from ("You" for the player's own), m.text, m.hours, m.read, m.call
end

• A person's conversation is keyed by their id, so it survives a rename; a sender who is not a person (a bank, a newsletter) is keyed by the name.
• Texts folded on the bell: five messages from one person are one row, "Sara (5)", until read.
• silent = true keeps it off the bell, for a mod that already sends its own notification (ul_Phone does).
• The newest 300 messages are kept. Sending never starts a scene: to wait for a reply, schedule it with Events.
• A notification can also open a conversation: target kind phone, which SendPhoneMessage sets for you.