Features

Notifications and Dynamic Island

How notifications are shown and saved, and what the Dynamic Island displays.

Two parts of the phone tell the player that something happened.

Part What it is
Notifications Banners at the top of the screen, a list on the Lock Screen and in the Notification Center, and a sound
Dynamic Island The black pill over the camera. It shows what is going on right now: a call, a timer, a track, a delivery

#1. Notifications

#What the player sees

A notification has an app icon, a title, a text and sometimes a picture. Where it shows depends on the phone:

Phone What happens
Put away The top of the phone rises into view for a moment with the banner on it
Open and unlocked A banner slides in at the top. Up to 3 banners stack
Open and locked No banner. It goes into the list on the Lock Screen
Do Not Disturb on No banner and no sound. It still goes into the list

A banner stays for its timeout (5 seconds by default), at least 2 and at most 10 seconds. Tapping it opens the app it belongs to. Every notification also lands in the Notification Center (pull down from the top) and on the Lock Screen, grouped by app, until the player opens or clears it.

#Saved and shown-only notifications

Some notifications are saved in the database, some are only shown. This decides whether an offline player ever sees them.

Sent to Saved Offline player sees it later
A server id (player online) No No
A phone number or an identifier Yes Yes, the next time the phone loads
Everyone, with 'all' Yes Yes
Everyone, with 'online' No No

When the phone loads, it fetches the newest 50 saved notifications. Saved notifications are deleted after Config.Retention.notifications days (default 7) by the daily clean-up.

The phone's own features (missed calls, messages, mail, bank, invoices, Wallet, health records and so on) send saved notifications, so a player who was offline finds them when they come back.

The exports are on Server exports: notifications (SendNotification, NotifyEveryone, QueueNotificationForOffline, EmergencyNotification) and Client exports: notifications.

#The player's settings

Setting Where What it does
Allow Notifications Settings > Notifications Off: nothing appears, no banner, no list entry, no sound
Per app switch Settings > Notifications Off for one app: that app's notifications are dropped
Do Not Disturb Settings > Focus No banners and no sound; notifications still go into the list
Silent Mode Settings > Sounds No notification sound
Airplane mode Settings No notification sound
Text Tone Settings > Sounds Which sound plays, from Config.NotificationSounds
3D Sounds Settings > Sounds Players nearby hear the sound too

The switches are saved on the server, so a notification sent while the player is offline follows them too.

#Sounds

The notification sound plays on the player's own game. With 3D Sounds on, players within Config.Sound.Range metres hear it as well. That needs a sound resource (fx-sound or xsound) and Config.Sound.Enable3D = true. Without one, the owner alone hears it.

A player without the phone item hears no notification sound, even when the notification arrives.

The sounds to choose from are Config.NotificationSounds. Each entry plays html/assets/sounds/<id>.wav, or your own <id>.ogg when its id is listed in html/assets/sounds/overrides.json.

luaConfig.NotificationSounds = {
    { id = 'note',    label = 'Note' },
    { id = 'tri-tone', label = 'Tri-tone' },
    ...
}

#Options

Option Default What it does
Config.NotificationSounds note, tri-tone, chord, bloom, aurora, glass Sounds a player can pick as the text tone
Config.Sound.Resource 'auto' 'auto', 'fx-sound', 'xsound' or 'none': what plays sounds other players hear
Config.Sound.Enable3D true Nearby players can hear notification sounds and ringtones
Config.Sound.Range 12.0 Metres within which they hear them
Config.Retention.notifications 7 Days a saved notification is kept

#2. Dynamic Island

The island shows one activity in the pill. A second activity shows as a small circle on its right; any more add a +N badge on that circle. Tapping the pill opens the activity's app. A long press, a pull down, or resting the mouse on it opens a larger card with controls. The card folds away again after a few seconds without use.

#Activities

Activity Where it comes from What it shows
Incoming call Phone, video calls Caller with Accept and Decline. Full screen instead when the phone is locked or the caller has a Contact Poster; see Calls
Call Phone Who it is and the call time; the card has mute (not with SaltyChat), speaker and hang up. A notice saying how the call ended ("Call Ended · 1:24", "No Answer", "Line Busy") shows for a moment after
Alarm Clock A ringing alarm
Timer Clock The time left, with a ring that empties
Music ShowMusicTray, used by fx-musicapp Track, cover and controls. A paused track leaves the island after 8 seconds and stays on the Lock Screen and in the Control Center
Live activity ShowLiveTray, from any resource A title, a line of text, a progress bar or countdown, up to 3 buttons
AirDrop AirDrop A file being sent or offered
Pet Settings > Display > Island Pet One of the player's Pets app pets when it is hungry, thirsty, dirty, tired, bored or sick. Tapping it opens Pets
Notice The phone Short messages: "Call ended", charging, low battery

When several are going on, the one higher in the table wins the pill: a ringing call first, then a call, an alarm, a timer, music, live activities, AirDrop and notices.

While a call rings, goes on, or an alarm or finished timer rings with the phone put away, the top of the phone stays raised so the player sees the island.

#Privacy dots

Small coloured dots in the island show what the phone is using:

Dot Colour On while
Microphone Green A call is active or dialling, a voice memo or a voicemail is being recorded
Camera Orange The Camera app is open, or the camera is on in a video call
Location Blue A script switches it on with SetIslandIndicator
Live Purple A live activity is in the island

#Low battery and charging

When the battery drops to one of the levels in Config.Battery.WarnAt (default { 20, 10 }), a red "Battery 20%" notice shows in the island for a few seconds. Each level warns once; it warns again only after the battery climbed more than 2 % above that level. No warning shows while the phone charges.

When charging starts, a green "Charging" notice with the level shows in the island for a moment, and the lock screen shows a green battery with the level under the clock for as long as it charges. How the battery drains and charges is on Battery and signal.

#Adding your own activity

Other resources can put a music player or a live activity (a delivery, a heist timer, a taxi ride) in the island, and switch the privacy dots. See Client exports: island: ShowMusicTray, UpdateMusicTray, RemoveMusicTray, ShowLiveTray, UpdateLiveTray, RemoveLiveTray, SetIslandIndicator.

Only the resource that created a tray can change or remove it, and every tray of a resource goes away when that resource stops.

#Good to know

  • A script's notification never reaches an offline player. It was sent to a server id. Send it to the phone number, or use QueueNotificationForOffline with the identifier.
  • A player gets no notifications from one app. They switched that app off in Settings > Notifications, or switched Allow Notifications off.
  • Notifications appear but make no sound. Silent Mode, Do Not Disturb or airplane mode is on, or the player has no phone item.
  • Nearby players do not hear the sound. No fx-sound or xsound, Config.Sound.Enable3D = false, or the player switched 3D Sounds off.
  • Pictures in a notification do not show. Icons and thumbnails follow the same host list as player media (ServerConfig.Upload.AllowedHosts in config_server.lua). A link on another host is removed.
  • During the first-start setup screens the island stays empty, apart from calls.