Live Activities

Show live content from your resource on the phone, like a music player or a delivery ETA. Pick a template, fill in its fields, and Yseries draws it on both phone types. Button presses come back to you as a client event.

All exports are client-side. Activities only show on that player's phone.

YOS phone home screen. The Dynamic Island shows album artwork and red level bars, with a small round bubble holding a green app-grid glyph next to it. — YOS: the music example in the Dynamic Island, the delivery example in the bubble.

YOS uses the Dynamic Island. The oldest activity takes the island and the second one shows as a bubble next to it. Tap the island to expand it. Calls and system alerts take priority, and nothing shows while the phone is locked.

Humanoid shows activities in three places, using the same payload:

a chip in the status bar (opens the shade)
a card in the notification shade
a bar on the lock screen, with controls that work without unlocking

Humanoid Y26 notification shade with a media card for Midnight City by M83 and a Food delivery card with Set waypoint and Cancel buttons. — Humanoid notification shade.

Humanoid Y26 lock screen with an expanded Midnight City bar under the clock, showing a progress bar and playback controls. — Humanoid lock screen.

3 activities per resource, 8 per phone.
Ids are per resource, so two resources can both use player.
Activities are removed when your resource stops or yseries restarts.

lua

-- Create or replace an activity. Fields you leave out are removed.
local ok, reason = exports.yseries:SetLiveActivity(id, data)

-- Change only the fields you pass. Can't remove a field, use SetLiveActivity for that.
local ok, reason = exports.yseries:UpdateLiveActivity(id, patch)

-- Remove one activity.
local ok, reason = exports.yseries:RemoveLiveActivity(id)

-- Remove all activities from your resource. Returns how many were removed.
local removed = exports.yseries:ClearLiveActivities()

id is 1-32 letters, digits, _ or -. When ok is false, reason says why and nothing changes:

Reason	Cause
`invalid_id`	Bad id format.
`invalid_payload`	`data` is not a table, or `isPlaying` is not a boolean.
`invalid_<field>`	That field is missing or wrong, e.g. `invalid_title`, `invalid_accent`. See the tables below.
`limit_reached`	Over 3 per resource or 8 per phone.
`not_found`	No activity with that id (Update and Remove).

Field	Type	Notes
`template`	`"media"` or `"status"`	Required.
`title`	string, max 64	Required.
`subtitle`	string, max 64
`artwork`	URL	Square image. See Artwork.
`accent`	`#RRGGBB`	Color of bars, text and the Humanoid chip.
`appKey`	string	Opens this custom app when tapped.

Field	Type	Notes
`isPlaying`	boolean	Animates the bars and moves the progress bar.
`duration`	seconds	Shows a progress bar.
`position`	seconds	Needs `duration`. The phone keeps counting while playing, so only resend on seek or track change.
`controls`	list	Any of `"previous"`, `"playPause"`, `"next"`.

Field	Type	Notes
`trailing`	string, max 12	Short text on the right, like `"4 min"`.
`progress`	0 to 1	Progress bar.
`actions`	max 2	`{ id = "waypoint", label = "Set waypoint" }`, label max 20 characters.

lua

AddEventHandler(('yseries:live-activity-action:%s'):format(GetCurrentResourceName()), function(id, action)
    -- media: "previous", "play", "pause" or "next"
    -- status: the id of the pressed action
end)

The phone doesn't change anything on its own. Update the activity yourself, for example flip isPlaying. Any client resource can trigger this event, so check on the server before giving out money or items.

https:// URLs, or nui://your_resource/path.png for files in your resource (list them in files).
Max 512 characters. Without artwork, a music note or app grid shows instead.

lua

local tracks = {
    { title = 'Midnight City', artist = 'M83', duration = 244, cover = 'https://cdn.example.com/covers/midnight-city.jpg' },
    { title = 'Nightcall', artist = 'Kavinsky', duration = 258, cover = 'https://cdn.example.com/covers/nightcall.jpg' },
}
local current = 1

local function showTrack()
    local track = tracks[current]
    exports.yseries:SetLiveActivity('player', {
        template = 'media',
        title = track.title,
        subtitle = track.artist,
        artwork = track.cover,
        accent = '#ff2d55',
        isPlaying = true,
        position = 0,
        duration = track.duration,
        controls = { 'previous', 'playPause', 'next' },
    })
end

AddEventHandler(('yseries:live-activity-action:%s'):format(GetCurrentResourceName()), function(id, action)
    if id ~= 'player' then return end

    if action == 'play' or action == 'pause' then
        exports.yseries:UpdateLiveActivity('player', { isPlaying = action == 'play' })
    elseif action == 'next' or action == 'previous' then
        current = (current - 1 + (action == 'next' and 1 or -1)) % #tracks + 1
        showTrack()
    end
end)

RegisterCommand('music', showTrack, false)
RegisterCommand('musicstop', function() exports.yseries:RemoveLiveActivity('player') end, false)

YOS phone with the Dynamic Island expanded, showing Midnight City by M83 with a red progress bar and previous, pause and next buttons. — Expanded island. The cover is a placeholder image.

lua

exports.yseries:SetLiveActivity('route', {
    template = 'status',
    title = 'Food delivery',
    subtitle = 'Courier is 1.2 km away',
    accent = '#34c759',
    trailing = '4 min',
    progress = 0.6,
    actions = {
        { id = 'waypoint', label = 'Set waypoint' },
        { id = 'cancel', label = 'Cancel' },
    },
})

AddEventHandler(('yseries:live-activity-action:%s'):format(GetCurrentResourceName()), function(id, action)
    if id ~= 'route' then return end
    if action == 'waypoint' then
        SetNewWaypoint(215.8, -810.1)
    elseif action == 'cancel' then
        TriggerServerEvent('my_delivery:cancel')
        exports.yseries:RemoveLiveActivity('route')
    end
end)

-- Later, as the courier gets closer:
exports.yseries:UpdateLiveActivity('route', { trailing = '2 min', progress = 0.8 })

Live Activities

Where it shows

Limits

Exports

Templates

Shared fields

media

status

Button presses

Artwork

Example: music player

Example: delivery status

On this page