Player Data Service Reference #

Supported Code Generation Types #

Pragma Engine’s code generation for any class inheriting a Player Data service interface must be defined with only the supported field types:

Supported:

Primitive types: Ints, Strings, Longs, Bytes, Floats, and Doubles
Maps with keys that are Ints, Strings, and vals of primitive types or Kotlin classes
Mutable Maps
Lists containing values of primitive types or Kotlin classes
Mutable Lists
Kotlin types defined with only supported types

Not supported
Generics types on any classes or fields
Lists of Lists
Maps that have keys that are not Ints, or Strings,
Cycles in types
Kotlin collection classes that are NOT: Lists, Maps, MutableLists, MutableMaps
Inheritance/composition. For example, in class Shape: Component and class Square: Shape, the Component named Square can not inherit the Shape class.
Properties with default values, since the generated protobuf will not align with the default value
Nullable Properties
Properties that are a protobuf message
Enums
Types defined in by other libraries

Data Classes #

Entity #

Entity wraps and contains player data in Components.

Entity data classes cannot be authored through inheriting an interface. Entities must be defined using functions from the context.snapshot object.

Property	Description
`entityName: EntityName`	The name for a type of data in your player data feature. This name does not have to be unique, but it must be different compared to other `Component` declarations.
`instancedId: UUID`	TThe unique ID for the instance of the `Entity`.
`componentContainers: MutableList<ComponentContainer>`	The list of `Components` belonging to the specific `Entity`.
`getComponents()`	Returns a list of `Components`
`addComponent()`	Fetches a `Component`, creates a `ComponentContainer` for said component, and then adds the newly created `ComponentContainer` to the `componentContainers` collection.
`removeComponent(componentId: UUID)`	Removes a component from the `ComponentsContainers` collection by its `componentId`.
`removeComponent(component: Component)`	Removes `component`(s) from the `componentsContainers` collection.
`getComponentsByType<reified T: Component>()`	Returns a list of `Components` that are an instance of the generic parameter.

ComponentContainer #

ComponentContainer contains the Entity’s MutableList of Components and is automatically authored in every Entity.

Property	Description
`componentId: UUID`	The unique ID that identifies the `Component` and helps with data persistence.
`component: Component`	Utilized by the engine layer to contain the `Component`.

ContentRequest #

ContentRequest retrieves request endpoints and its associated Content Schema data.

Property	Description
`request`	A defined `PlayerDataRequest` class.

Classes #

PlayerDataSubService #

PlayerDataSubService houses and organizes Operations and allows Operations to use content data.

Property	Description
`contentLibrary`	Accesses `PlayerDataContentLibrary` to allow `Operations` to interact with and utilize content data.

PlayerDataSnapshot #

PlayerDataSnapshot contains functions for retrieving, creating, modifying, and deleting Entities and their Components.

Function	Description
`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`. 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.

PlayerDataOperation annotation #

PlayerDataOperation annotation classes assign a Pragma Engine gateway session to an Operation and are required for the service’s code generation.

Property	Description
`sessionTypes: Array<SessionType> = []`	Assign which Pragma Engine gateway session types can call this `Operation`: `PLAYER`, `PARTNER`, `SERVICE`, or `OPERATOR`.

PlayerDataClient #

PlayerDataClient contains two functions for calling Operations from other services and plugins.

The property oneTimeKey contains a string for only calling an Operation once. Any future requests that have an already used key will result in a PragmaResult.Failure containing a PlayerDataOneTimeKeyError application error.

Property	Description
`doOperation(request: PlayerDataRequest, playerId: PlayerId, oneTimeKey: String? = null): PragmaResult<PlayerDataResponse, PragmaFailure>`	Calls a single Player Data `Operation`.
`doBatchOperation(operationRequests: List<PlayerDataRequest>, playerId: PlayerId, oneTimeKey: String? = null, ): PragmaResult<List<PlayerDataResponse>, PragmaFailure>`	Utilized by the engine layer to contain the `Component`.

Interfaces #

Classes can inherit the following interfaces for specific Player Data functionality.

PlayerDataRequest #

PlayerDataRequest handles an Operation’s Request and its associated data. These classes don’t have any additional properties aside from what the user defines in the class’s parameters.

PlayerDataResponse #

PlayerDataResponse handles an Operation’s Response and its associated data. These classes don’t have any additional properties aside from what the user defines in the class’s parameters.

Component #

Components store user-defined player data and belong to an Entity.

Property	Description
`hiddenFromPlayer: Boolean get() = false`	A defined `PlayerDataRequest` class.

HiddenComponent #

HiddenComponents store user-defined player data, belong to an Entity, and are hidden from the player and client.

Property	Description
`hiddenFromPlayer: Boolean get() = true`	Data stored within this Component class is not visible to the player and will be filtered out of a `PlayerDataServiceRpc.GetV1Response`.

PlayerDataContentSchema #

PlayerDataContentSchemas template data and API endpoints written in JSON Catalogs.

Property	Description
`id`	The ID for the instance of the `PlayerDataContentSchema`.

PlayerDataContentLibrary #

PlayerDataContentLibrary is included in every Sub Service’s parameters and is responsible for receiving content data.

Function	Description
`getCatalog(resourcePath: String, clazz: KClass<T>): Map<String, T>`	Returns content defined using the `PlayerDataContentSchema` interface.
`getContentData(resourcePath: String): ContentData<ContentProto>`	Returns content defined solely in protobuf form, such as custom content.

Context #

Context provides useful data, objects, and helper functions for writing business logic in an Operation function.

Property	Description
`snapshot`	A parameter used for retrieving the `PlayerDataSnapshot` class, which contains helper functions for interacting with live data.
`playerId`	A 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.
`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.

Player Data service SDK #

Unreal #

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

Method	Definition
`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

Errors #

PlayerDataService_InvalidOperation
PlayerDataService_InvalidUniqueEntity
playerdata.PlayerDataOuterClass.PlayerDataOneTimeKeyError
PragmaError.UNKNOWN_ERROR