Operations Reference #

Operation Function #

An Operation’s business logic is written inside a Sub Service’s class using a specific Operation function. Operation functions should always have a unique name and return the Operation’s respective PlayerDataResponse type. Below are the following properties that must be included for an Operation’s function to work properly:

PropertyDescription
@PlayerDataOperation(sessionTypes)An annotation that allows you to limit and assign which Pragma Engine gateway session types can call this Operation, which is either PLAYER, PARTNER, SERVICE, or OPERATOR.
requestA parameter for the instance of the Operation’s Request class inheriting the PlayerDataRequest structure.
contextA parameter that provides access to other objects and helper functions useful for implementing Operation logic.

Context #

Below are the properties of the Context interface and their use cases:

PropertyDescription
snapshotA parameter used for retrieving the PlayerDataSnapshot class, which contains helper functions for interacting with live data.
playerIdA parameter for using playerId when modifying live data in an Operation.
getSubService(clazz: KClass<T>)A function that allows an Operation to call another Sub Service’s Operation function.
doContentRequest(request: ContentRequest)A function that allows an Operation to define content using ContentRequests from a Content Schema. See the Content Overview page for more information.
addOnSuccess(onSuccessBlock: OnSuccessType)A function for adding business logic after live data has been successfully updated in the database, cache, and before the response data has returned.

This function is useful for performing additional actions after any successful player data changes. Some additional actions using this function include sending out a notification to a player, additional metrics and telemetry data, as well as any additional logs.

Snapshot #

Below are all of the functions and objects in Snapshot and their use cases.

FunctionDescription
getEntityById(instanceId: UUID)Fetches one specific Entity by its associated instanceId.
createEntity(entityName: String, components: List<Component> = emptyList())Creates an Entity that is non-specific by not enforcing the Entity’s name to be unique.

This function is useful for creating Entities which you expect players to have multiples of that use the same structure of Components.
getEntitiesByName(name: String)Fetches an Entity by its name as a string. Returns a list of entities that contain the specific string name, but does not provide type-safety when fetching the Entity.

This function is useful for fetching unique Entities when you know its exact name.
getUniqueEntity(name: String)Fetches one specific Entity solely by its name as a string. Returns only one Entity, and if there are multiple Entities with the same name the function will throw an error to indicate there are multiple Entities with the same name.
getOrCreateUniqueEntity(name: String, getComponents: () -> List<Component>)Creates a unique Entity that the player should only have one of. If the player already has the Entity, the function will return that pre-existing Entity and will not create another.

This function fulfills most use cases when creating Entities, as it is always safe to author Entity creation with this function without accidentally creating unnecessary data.
deleteEntity(entity: Entity)Deletes an Entity permanently from the database and the Entity can no longer be retrieved.

This function typically shouldn’t be used for an Entity that stores any type of player progression data, like MMR or experience points.
getEntities()Returns a list of all of a player’s entities.
getEntitiesWithComponent<ComponentClass>()Returns all entities that contain a Component of the generic type.

Player Data Service SDK #

Below are all of the accessor methods available in the Unreal SDK’s FPlayerDataCache which is accessed through UPragmaPlayerDataService.GetCache().

MethodDescription
GetEntityByInstanceId(const FString& InstanceId)Fetches one specific Entity by its associated instanceId or string.
GetEntitiesByName(const FString& Name)Fetches a list of Entities by a shared name.
GetUniqueEntityByName(const FString& Name)Fetches one specific Entity solely by its name.

Use to fetch an Entity that is known to have a unique name.
AllInstanceIds()Fetches all InstanceIds.

Use in combination with GetEntityByInstanceId to loop through all of a player’s entities

Operations Tasks
Live Data