Player broadcasts #

Player broadcasts push a notification to every logged-in player session. Use them to alert players of upcoming maintenance, signal that new content is available, or relay any event that all connected clients should react to.

Broadcasts can be triggered from two places: a service can broadcast programmatically by calling notifyAllActiveSessionsServiceV1 via requestRpcV2, or an operator can broadcast directly via the notifyAllActiveSessionsOperatorV1 endpoint without writing any service code.

All examples on this page use the broadcastToPlayersV1 RPC from the DemoService reference service introduced in Custom services.

Define the notification #

A broadcast notification is a proto message with session type PLAYER and message type NOTIFICATION. It is defined alongside the RPC that triggers it:

demoServiceRpc.proto

package unicorn.demo;

message BroadcastToPlayersV1Request {
    option (pragma.pragma_session_type) = OPERATOR;
    option (pragma.pragma_message_type) = REQUEST;

    string message = 1;
}

message BroadcastToPlayersV1Response {
    option (pragma.pragma_session_type) = OPERATOR;
    option (pragma.pragma_message_type) = RESPONSE;
}

message BroadcastToPlayersV1Notification {
    option (pragma.pragma_session_type) = PLAYER;
    option (pragma.pragma_message_type) = NOTIFICATION;

    string message = 1;
}

The notification message name determines the generated SDK event name. BroadcastToPlayersV1Notification produces OnBroadcastToPlayersV1 in the Unreal SDK.

Broadcast from a service #

A service broadcasts by building the notification proto, wrapping it in an ExternalNotification, and forwarding it to the Player Session service via requestRpcV2:

DemoService.kt

package unicorn.demo

import pragma.ExternalNotification
import pragma.OperatorSession
import pragma.rpcs.JumpData
import pragma.rpcs.PragmaRPC
import pragma.rpcs.RoutingMethod
import pragma.rpcs.SessionType
import pragma.session.PlayerSessionRpc
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Notification
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Request
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Response

//...

@PragmaRPC(SessionType.OPERATOR, RoutingMethod.SESSION_PRAGMA_ID)
suspend fun broadcastToPlayersV1(session: OperatorSession, request: BroadcastToPlayersV1Request): BroadcastToPlayersV1Response {
    val notification = BroadcastToPlayersV1Notification.newBuilder()
        .setMessage(request.message)
        .build()

    val wrappedNotification = ExternalNotification.newBuilder()
        .setType(JumpData.getIntForRpcType(BroadcastToPlayersV1Notification::class.java))
        .setPayload(notification.toByteString())
        .build()

    val notifyAllRequest = PlayerSessionRpc.NotifyAllActiveSessionsServiceV1Request.newBuilder()
        .setNotification(wrappedNotification)
        .build()

    requestRpcV2(notifyAllRequest, PlayerSessionRpc.NotifyAllActiveSessionsServiceV1Response::parseFrom)

    return BroadcastToPlayersV1Response.getDefaultInstance()
}

The ExternalNotification wrapper carries the notification’s type Id (an integer derived from the proto class) and its serialized payload. The Player Session service unwraps it and delivers it to each connected player gateway.

Broadcast from an operator #

Operators can send broadcasts directly using notifyAllActiveSessionsOperatorV1 without writing service code:

curl --location 'http://localhost:10000/v1/rpc' \
--write-out '\nHTTP %{http_code}\n' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <operator-token>' \
--data '{
    "requestId": 1,
    "type": "PlayerSessionRpc.NotifyAllActiveSessionsOperatorV1Request",
    "payload": {
        "notification": {
            "type": "BroadcastToPlayersV1Notification",
            "payload": {
                "message": "Maintenance will start in one hour"
            }
        }
    }
}'

The type field inside notification is the proto message name. The payload contains the notification fields.

Handle notifications #

On the client, subscribe to the notification event on the generated raw service class. The SDK delivers the typed notification whenever the server broadcasts it:

RpcBasics.cpp

#include "Dto/UnicornDemoServiceRaw.h"

//...

Player->Api<UUnicornDemoServiceRaw>().OnBroadcastToPlayersV1.AddWeakLambda(this,
	[this](FPragma_Demo_BroadcastToPlayersV1Notification Notification, const FPragmaMessageMetadata&)
	{
		Handler->OnBroadcastReceived(Notification.Message);
	});

Subscribe during initialization (e.g., in BeginPlay) so the handler is in place before any broadcasts arrive. Use AddWeakLambda to tie the subscription to the subscribing object’s lifetime.

Configure notification settings #

The Player Session service batches broadcast delivery to avoid flooding gateways. Configure the batch size and interval through PlayerSessionConfig:

game:
  serviceConfigs:
    GamePlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000
social:
  serviceConfigs:
    SocialPlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000
SettingDefaultDescription
notifyAllActiveSessionsBatchSize500Number of notifications sent per gateway in each batch.
notifyAllActiveSessionsBatchIntervalMillis1000Time in milliseconds between each batch of notifications.

Persistence
Custom Errors