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
QueueNotificationForOfflinewith 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-soundorxsound,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.AllowedHostsinconfig_server.lua). A link on another host is removed. - During the first-start setup screens the island stays empty, apart from calls.