This article was written on Pragma Engine version 0.0.94.

The Content Data System: Part 1 #

In the first Content Data series article, we’ll go over Pragma Engine’s Content Data system and the many different services and features it supports. Jump ahead to the next article if you want to learn how to create and interact with your own content data in Pragma Engine.

For some hands-on examples and implementations of our Content Data system, check out our previous tech blog articles from the Stackables and Instanced Items series.

Understanding Content Data #

Whether the content data is new in-game items, missions, or battlepasses, live service games need to patch and create new content constantly. Managing this content and making sure all the content data is correct and ready to go to a player-base requires data versioning and data migration. Doing so across many platforms and game client versions necessitates structured, versioned content management via your backend platform.

Pragma Engine’s Content Data system is designed to manage such structured, versioned content. It enables live update scenarios when patching and generating new content for your game, and supports more complex schema migration scenarios in conjunction with our Player Data service. You can use the Content Data system to rebalance in-game items and plugin logic without game client or server patches, as well as revamp how an entire feature or item works without scrapping and replacing all the content data you’ve previously designed.

Overview of Pragma Engine’s Content Data system infrastructure.

The services and features that are supported by our Content Data system include player inventory services, item exchanges through stores, player loadouts for matches, and player progression artifacts like missions, quests, battlepasses, and more! These are all provided content data paths, and the Content Data system allows you to construct and refine your own custom services and content data paths as well.

When creating or editing any type of data in Pragma Engine, all content must be written and defined in the platform’s 5-ext folder. This folder contains all “ext” content for Pragma Engine, and ext content is purely customer-defined data that interacts with the engine. Creating and editing content anywhere else in Pragma Engine will create an unstable version of the Pragma Engine, which can cause broken builds when updating to the newest release.

In the next two sections, we’ll take a look at Pragma Engine’s two different types of supported content and the file architecture associated with the Content Data system.

Provided vs Custom Content #

There are two supported categories of content definitions within the Content Data system–all of which reside in the platform’s 5-ext folder: content that is provided, and content that is custom.

Provided content is used by already existing services within Pragma Engine–most notably the Inventory service. Instanced and stackable items belong under this category, as well as stores, rewards, crafting, and much more. These services can be customized by editing items’ extension (ext) fields from files in the 5-ext folder.

Provided content is “out of the box” and readily available in Pragma Engine.

When using any type of provided content, like an instanced or stackable item, you’ll use provided content paths in protos and JSON to define the item’s specs. Because there’s many different types of content that are provided in the Content Data system, you’ll need to know the specific data types and fields required to define your specific content.

Custom content, on the other hand, is completely built by the user. This includes user-defined custom services, as well as custom item specifications and ext logic via JSON and Proto definitions.

Create custom content by using Pragma Engine’s “toolbox” of interfaces in JSON, protobufs, and Kotlin plugins.

To customize content data with your own particular code logic, you can create Kotlin plugins that utilize your content in specific, user-defined ways. You can also create entirely customized services that work in tandem with provided content, such as an attribute system for instanced and stackable items.

Even though these two types of content are categorized separately, they can (and usually do) work in tandem with one another. For instance, if you’re designing a store to sell instanced items like player gear, the store can be defined using entirely provided content, and the instanced items defined using custom content via ext data.

File Architecture for Content #

Whether you’re creating provided or custom content, you’re going to be defining such content using two distinct file structures that work in tandem with one another: Protocol Buffers and JSON.

Protocol Buffers #

Pragma Engine uses Protocol Buffers (protobufs) to define templates for many different types of content data. All protobuf data is defined using a message: an interface for templating different data fields and types in an easily accessible and modifiable way. This data is defined as ext templates for customizing provided content–like ExtInstancedItem or ExtPartySelections–and can also be used to define entirely new custom content.

The “ext book” of protobuf template definitions used to design data.

All field types in a protobuf template are written in binary and are given actual readable values (integers, strings, maps, etc.) in JSON catalogs or Pragma Engine plugins. A message in protos only represents the template for housing data objects, so to create a readable and modifiable object of your protobufs (like an ext object for provided content), you’ll need to use generated method functions compiled by your protobuf data in your own content-building plugin logic. This is often performed by specific builder() functions.

To learn more about how protobuf messages work and how you can read, edit, and write data using proto structures, check out Google’s documentation on Protocol Buffers in Javascript and Kotlin.

JSON Catalogs #

Since protobufs are used to write custom templatess for content data, JSON files are used to catalog and define the content data themselves. In JSON, content almost always contains some type of id parameter for identifying the specific data in the catalog, and a set of unique content parameters specific to the type of data defined. For instance, stackable items have a catalogId parameter for service calls to use, a name purely for display information, and other specific data parameters unique just to stackables (like a limit parameter for capping the total amount of a stackable item in an inventory).

The many “JSON books” used to catalog and define content data.

JSON catalogs have the option to contain an additional ext field using user-defined protobuf templates, though it is not required. It’s important to note that customizing JSON data using ext fields allows for a plethora of unique ways you can define, utilize, and manage your data. For example, instanced items are purely unique due to how their ext data is defined and utilized using protobuf templates.

For more information, check out the rest of the articles in this series:

Content Data System Part I (this article)
Content Data System Part II