Client exports

Dynamic Island

Client exports that put a music player, a live activity or a privacy dot in the island at the top of the phone.

A tray belongs to the resource that created it. Only that resource can change or remove it, and its trays are removed when it stops. How the island behaves for the player is described in Notifications and Dynamic Island.

#ShowMusicTray

Shows a music player in the island, on the lock screen and in the control centre.

lua---@class MusicTrayOptions
---@field id? string your own tray id, up to 40 characters; generated when left out
---@field title string up to 60 characters
---@field artist? string up to 60 characters (`subtitle` is accepted too)
---@field cover? string image link (https:// or nui://), up to 512 characters
---@field playing? boolean true while the track plays
---@field duration? number seconds, 0 to 86400; 0 hides the progress bar
---@field position? number seconds, 0 to 86400
---@field live? boolean marks a live stream
---@field volume? number 0 to 1
---@field like? boolean
---@field shuffle? boolean
---@field repeat? 'off'|'one'|'all'
---@field output? string name of the output device, up to 24 characters
---@field layout? 'compact'|'expanded'
---@field openApp? string app id opened when the tray is pressed
---@field color? string '#RRGGBB'
---@field disabled? string[] names of controls to disable
---@field handlers? table<string, function> play, pause, next, previous, seek(position), volume(value), like(value), shuffle(value), repeat(value), close

---@param opts MusicTrayOptions
---@return string|nil id
exports['fx-phone']:ShowMusicTray(opts)
lualocal tray = exports['fx-phone']:ShowMusicTray({
    title = 'Night Drive', artist = 'Synthwave FM', playing = true, duration = 214,
    handlers = { play = function() resume() end, pause = function() pause() end },
})
  • Returns nil when opts is not a table, or when the id already belongs to a tray of another resource.
  • When the player closes the tray, the close handler runs (or stop, or pause if there is none). The tray comes back when it is updated with playing = true.

#UpdateMusicTray

Changes a music tray: a new track, pause, the position, the handlers.

lua---@param id string
---@param patch table|string a table of fields, or one field name
---@param value? any the value when `patch` is a field name
---@return boolean ok
exports['fx-phone']:UpdateMusicTray(id, patch, value)
luaexports['fx-phone']:UpdateMusicTray(tray, { playing = false })
exports['fx-phone']:UpdateMusicTray(tray, 'position', 95)
  • Returns false when the tray does not exist, is not a music tray, or belongs to another resource.

#RemoveMusicTray

Removes a music tray. Without an id it removes every music tray of your resource.

Also available as: HideMusicTray

lua---@param id? string
---@return boolean ok always true
exports['fx-phone']:RemoveMusicTray(id)
luaexports['fx-phone']:RemoveMusicTray(tray)

#ShowLiveTray

Shows a live activity in the island: a delivery, a timer, a job in progress.

lua---@class LiveTrayButton
---@field id? string up to 20 characters
---@field label? string up to 24 characters (`title` is accepted too)
---@field icon? string icon name
---@field primary? boolean
---@field disabled? boolean
---@field onPress? function called when pressed (`cb` is accepted too)

---@class LiveTrayOptions
---@field id? string your own tray id, up to 40 characters
---@field title string up to 60 characters
---@field subtitle? string up to 60 characters
---@field icon? string icon name
---@field color? string '#RRGGBB'
---@field progress? number 0 to 1
---@field value? string short value text, up to 12 characters
---@field endsAt? number end time for a countdown
---@field waveform? boolean
---@field cover? string image link (https:// or nui://)
---@field layout? 'compact'|'expanded'
---@field openApp? string app id opened when the tray is pressed
---@field buttons? LiveTrayButton[] up to 4
---@field expanded? { lines?: string[], buttons?: LiveTrayButton[] } up to 4 lines of 60 characters and 4 buttons

---@param opts LiveTrayOptions
---@return string|nil id
exports['fx-phone']:ShowLiveTray(opts)
lualocal id = exports['fx-phone']:ShowLiveTray({
    title = 'Delivery', subtitle = '2.4 km to drop-off', icon = 'truck', color = '#30D158', progress = 0.35,
})

#UpdateLiveTray

Changes a live tray.

lua---@param id string
---@param patch table|string a table of fields, or one field name
---@param value? any the value when `patch` is a field name
---@return boolean ok
exports['fx-phone']:UpdateLiveTray(id, patch, value)
luaexports['fx-phone']:UpdateLiveTray(id, 'progress', 0.8)

#RemoveLiveTray

Removes a live tray. Without an id it removes every live tray of your resource.

lua---@param id? string
---@return boolean ok always true
exports['fx-phone']:RemoveLiveTray(id)
luaexports['fx-phone']:RemoveLiveTray(id)

#SetIslandIndicator

Switches a small privacy dot in the island on or off.

lua---@param kind 'mic'|'camera'|'location'|'custom'
---@param on boolean
---@return boolean ok false for an unknown kind
exports['fx-phone']:SetIslandIndicator(kind, on)
luaexports['fx-phone']:SetIslandIndicator('mic', true)