Player Data Service Reference #

Supported Data Types #

The following outlines the supported data types to use when defining Component, PlayerDataRequest, PlayerDataResponse, and PlayerDataContentSchema:

Supported:

String
Numeric Types: Int, UInt, Byte, UByte, Short, UShort, Long, ULong, Boolean, Float, and Double
UUID
Map and MutableMap
- Keys must be Int or String
List and MutableList
A class with properties using the above data types
All basic types and nested classes can be marked nullable.
- Example: Int?, String?, UUID?, MyCustomObject?
- Nullable markers are not supported with collection types. The protobuf generation does not support optional fields with map or repeated fields.

Not supported

Enums
Cycles. Example List<List<*>>
Generics types on classes
Inheritance/composition
Assigning default values. The protobuf generation will not respect the kotlin defaults.
Protobufs
Types defined in other libraries

Data Classes #

Entity #

Entity is a Player Data type that represents persisted data and holds Component(s).

Member	Description
`entityName: EntityName`	An identifier. `EntityName` contains a `id: String` property.
`instancedId: UUID`	A generated `UUID`.
`componentContainers: MutableList<ComponentContainer>`	The list of `ComponentContainer`(s).
`getComponents(): List<Component>`	Returns all `Components`
`addComponent(component: Component): ComponentId`	Creates a `ComponentContainer` with a generated componentId for the `Component` and adds it to the `componentContainers` list. Returns the componentId (`UUID`).
`removeComponent(componentId: ComponentId): Boolean`	Removes a `ComponentContainer` from the collection by the given `componentId: ComponentId`. Returns true if any elements were removed.
`removeComponent(component: Component): Boolean`	Removes all `ComponentContainer`(s) that contain a `Component` equal to the one passed in. Returns true if any elements were removed.
`getComponentsByType<reified T: Component>(): List<T>`	Returns a list of `Components` that are an instance of the generic parameter.
`getComponentById<reified T: Component>(componentId: ComponentId): T`	Returns a `Component` casted to the generic type. Throws a `NoSuchElementException` if no `ComponentContainer` is found with the given `ComponentId`.

ComponentContainer #

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

Member	Description
`componentId: ComponentId`	`ComponentId` is a Kotlin `typealias` for an `UUID`
`component: Component`	The user defined persisted data.

ContentRequest #

ContentRequest retrieves request endpoints and its associated Content Schema data.

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

Classes #

PlayerDataSubService #

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

Member	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.

Member	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 is used to identify PlayerDataOperation(s) and allows you to assign the allowed SessionType(s).

Member	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.

Member	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.

Member	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.

Member	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.

Member	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 data and functions in a PlayerDataOperation function.

Member	Description
`snapshot: PlayerDataSnapshot`	Access to the player’s persisted data. Modifying the snapshot will result in a single database transaction that will update the player’s data.
`playerId: PlayerId`	Access to the player’s game id. `PlayerId` is a type alais of `UUID`
`sessionType: SessionType`	Provides the session gateway used when calling the `PlayerDataOperation`.
`getSubService(clazz: KClass<T>): T`	A function that provides access to any `PlayerDataSubService`, allowing you to call operations on that sub service.
`doContentRequest(request: ContentRequest)`	A function that will facilate calling a `PlayerDataOperation` that is defined in content data.
`addOnSuccess(onSuccessBlock: OnSuccessType)`	Allows you to send notifications, call other services, track additional metrics or logging after the database has been succesfully updated.

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