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> = ::emptyList)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 APIs #

Below are the available Player Data service APIs that can be made within Pragma Engine.

APIRequest PropertiesResponse PropertiesDescription
doOperationServiceV1Fixed128 playerId,

PlayerDataRequestProto ext,

and String oneTimeKey		PlayerDataResponseProto extCalls a single Player Data Operation. Successful responses will return PragmaResult containing the expected response proto, and a failed response will return PragmaFailure with either a ServiceError or application error.
doBatchOperationsServiceV1Fixed128 playerId,

Repeated PlayerDataRequestProto operations,

and String oneTimeKey		repeated PlayerDataResponseProto operationResponsesCalls multiple Player Data Operations
getServiceV1Fixed128 playerIdPlayerData playerDataReturns all of a player’s Entities. This endpoint is particularly useful for making service to service calls to fetch all of a player’s data.
deleteServiceV1Fixed128 playerId~ empty payloadDeletes all of a player’s Entities, Components, and one time transaction records

Player Data Service SDK #

See the Live Data reference page for information on cache data accessor methods available to Operations in the SDK.


Operations Tasks
Live Data