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

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 or `null` if no component is found. If cast fails throws a `java.lang.ClassCastException`.

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.

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 facilitates retrieving, creating, modifying, and deleting entities and their components.

Is constructed with a copy of all the player’s data stored in the cache/database.
Each player data operation is provided a PlayerDataSnapshot instance through Context.
The snapshot is used to construct a single database transaction to update the player’s data. Changes are identified by the Pragma Engine through byte comparison of the components in the snapshot vs the cached state.

Member	Description
`getEntityById(instanceId: UUID): Entity?`	Returns an `Entity` by its associated `instanceId` or `null` if no Entity found.
`createEntity(entityName: String, components: List<Component> = emptyList()): Entity`	Adds a new `Entity`. Generates and assigns a `UUID` for the `Entity` and each `Component`.
`getEntitiesByName(name: String): List<Entity>`	Returns all entities with the provided name.
`getOrCreateUniqueEntity(name: String, getComponents: () -> List<Component> = ::emptyList): Entity`	Checks for an `Entity` by the provided name and creates one if not found. The snapshot does not prevent you from accidentally adding other entities with the same name through `createEntity`. Throws an `ApplicationErrorException` if: there are multiple entities with the provided name. the underlying `EntityData` has become corrupted by manually modifying it.
`getUniqueEntity(name: String): Entity?`	Returns an `Entity` with the provided name or `null` if no Entity found. Throws an `ApplicationErrorException` if: there are multiple entities with the provided name.
`deleteEntity(entity: Entity)`	Deletes the `Entity`. No ops if there is no `Entity` found by its `EntityId`.
`deleteEntity(entityId: EntityId)`	Deletes the `Entity` associated with the provided `EntityId`. No ops if there is no `Entity` with the provided `EntityId`
`getEntities(): List<Entity>`	Returns all entities.
`<reified T: Component>getEntitiesWithComponent(): List<Entity>`	Returns all entities that contain a `Component` of the generic type `T`.

PlayerDataOperation #

PlayerDataOperation is an annotation used to identify player data operation functions, and allows you to assign the allowed SessionType types.

Member	Description
`sessionTypes: Array<SessionType>`	Assign which Pragma Engine session types can access the 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