Content Tasks #

Content can be authored for various different purposes, but you’ll be authoring the same classes, running the same code gen processes, and authoring the same format of JSON no matter that feature or Content Schema data. This page describes how to create a Content Schema class and author its JSON content utilizing the Content Schema, as well as helpful tips when data modeling your static data scenarios.

Common tasks when modeling content data include:

Author a Player Data Content Schema #

A ContentSchema class is created in Kotlin using the provided ContentSchema interface.

Before you can define your content data in JSON, you need to author the structure of your content using a ContentSchema class.

Author the Player Data Content Schema class by giving it a unique name and inheriting the PlayerDataContentSchema structure. Every PlayerDataContentSchema data class must include a parameter field for id: String in order for the engine layer to interact with it. Then, you can define the rest of the content’s properties for the rest of the content.

Below is an example of custom defined content for a Sub Service:

data class ExampleContentSchema(
    override val id: String,
    val exampleData: Int
): PlayerDataContentSchema

After a new PlayerDataContentSchema data class is defined, the content needs to be generated via a make ext build command so Pragma Engine can use it. Without running this command, the generated code for the Content Schema can’t be used for defining data in JSON catalogs.

Define the files associated with a Content Schema #

Data using a Content Schema structure requires a JSON file for cataloging data, and a metadata file for handling Content Schema information.

All content using a Content Schema structure requires its own JSON and metadata file in the 5-ext/content/src directory. The metadata file handles the engine layer information associated with the Content Schema, and the JSON file catalogs the data that uses your Content Schema structure.

The file name for these two files must be the same. For example, a PlayerDataContentSchema called ExampleContentSchema would have the following two files for defining content:

  • ExampleContentSchema.metadata

  • ExampleContentSchema.json

First, create the metadata file for assigning the appropriate content schema metadata information. The file must contain a field for applyTriggers and versionsToRetain.

The applyTriggers field must also contain an additional field for contentHandler. Every PlayerDataContentSchema has its own generated ContentHandler class, which must be imputed into the applyTriggers’s contentHandler field. A generated ContentHandler for a PlayerDataContentSchema follows this pattern: <Class-Name-Of-Your-PlayerDataContentSchema>ContentHandler.

Then input how many different versions you want for this type of content to be stored in the database in the versionsToRetain field.

An example of a metadata file for a PlayerDataContentSchema called ExampleContentSchema can be seen below:

{
  "applyTriggers": {
    "contentHandler": "ExampleContentSchemaContentHandler"
  },
  "versionsToRetain": 1
}

Second, create the JSON file for containing the content data that will use your specific Content Schema structure. There are no unique fields that need to be assigned to this file.

Define content data using a Content Schema #

Data using a Content Schema structure is authored in the Content Schema’s associated JSON Catalog file.

Once you’ve run the code generation process for a Content Schema class and created the metadata file and JSON file associated with the Content Schema, you can then define the data that will use your Content Schema structure.

Every JSON catalog entry will always have at least an id field for the content’s id information, alongside any fields defined in the PlayerDataContentSchema’s class.

Below is an example of a JSON file for a content catalog that follows the previously defined PlayerDataContentSchema called ExampleContentSchema:

[
  {
    "id": "custom-content-item-1",
    "exampleData": 100
  }
]

Once you’re finished making content data changes, you must validate the package, and apply the changes by running the contentdata apply command. Pragma Engine will not run unless all content data changes are applied and validated via this command.

Access and utilize Content Schema data #

Content Schema data can be accessed in an Operation for assigning data to an Entity or a Component. To learn more, see the Access Content Schema data in an Operation task.

Author content endpoints using a Content Schema #

API Endpoints and their respective data can be defined using a Content Schema interface and defined data entries in a JSON Catalog.

If you want to define Endpoints that are batch requests, extensible, and do not need to interact with Entities and their respective Components, you can use the PlayerDataContentSchema interface to author content oriented endpoints. The endpoint’s business logic is written in JSON instead of Kotlin, but the structure of the data is still written using a PlayerDataContentSchema class.

Just like a regular Content Schema, author a Content Endpoint by defining a class that includes a value for id: String and inherits the PlayerDataContentSchema interface. You get to define the endpoint Requests as properties within this class, so all properties in the endpoint that makes a ContentRequest must have the property ContentRequest. Lists and Maps for a ContentRequest are supported.

Below is an example of a ContentRequest data class containing three separate ContentRequests.

data class ExampleContentRequest(
    override val id: String,
    val exampleListRequest: List<ContentRequest>,
    val exampleRequest: ContentRequest,
    val exampleMapRequest: Map<String, ContentRequest>
): PlayerDataContentSchema

Once the Content Schema is defined, the content needs to be generated via a make ext build command so Pragma Engine can use it.

Define API endpoints in JSON using a Content Schema #

API Endpoints using a Content Schema structure are authored in the Content Schema’s associated JSON Catalog file.

Before you define your API Endpoints using a Content Schema, make sure you’ve already defined the PlayerDataContentSchema class, generated the code, and created the JSON and metadata files associated with the Content Schema. See the previous Tasks for further information.

API Endpoints using a Content Schema structure must be authored in the JSON file respective to the Content Schema. The structure for authoring these endpoints is the same as regular content data in the Player Data service, so make sure you always include an id field for the endpoint Request’s id information. The JSON fields for each endpoint will differ depending on the properties defined by the developer in the ContentRequest data class.

Below is an example of a ContentRequest catalog with three different API Requests authored in JSON:

[
  {
    "id": "exampleContentRequest1",
    "exampleRequest": {
      "addNumber": {
        "number": 5
      }
    },
    "exampleMapRequest": {
      "anEndpoint": {
        "addNumber": {
          "number": 7
        }
      }
    },
    "exampleListRequest": [
      {
        "addNumber": {
          "number": 2
        }
      },
      {
        "echo": {
          "message": "Hello World!"
        }
      }
    ]
  }
]

Perform a Content Request #

ContentRequests are performed in an Operation function’s business logic, and the data within each Request can be used for a player’s Entity and Component data. To learn more, see the Perform a Content Request task.


Content Overview
Reference