Understanding Pragma Engine #

Pragma Engine is a platform that powers online features for live-service games. This includes services such as accounts, social, parties, matchmaking, game allocation, player data, and content management. The platform has built-in live ops features such as metrics, monitoring, and telemetry.

The engine is built on the JVM and written in Kotlin. It is designed as an async, RPC-style server. It supports WebSockets and HTTP with messages sent as protobuf or JSON payloads.

Pragma Engine runs in two modes: the Social backend provides account and social features, while the Game backend provides the game loop, player data, game allocation, and related services. Each backend shares the same engine capabilities in terms of metrics, operability, authentication and authorization, and service-to-service calls.

Multi-Game Support #

The Social backend can manage multiple game titles. Each game title can support multiple game shards, allowing publishers to build a single social graph across games and regions. This allows players to create an account and build their social graph once. This feature is available in a white-label capacity for enterprise customers, giving studios full ownership of their data.

API Gateways #

The engine hosts multiple API gateways serving different clients, including Players, Operators, and Partner services. Each gateway is hosted on its own port, ensuring secure access to trusted gateways.

The Engine #

Connecting to the engine #

Pragma Engine provides engine-native SDKs for Unreal and Unity.

The SDKs expose the following APIs:

  • a raw API that can be used directly
  • a rich API with sophisticated features such as caching patterns, notification queues, and friendlier APIs for handling specific workflows like invites and party flow for getting players into a game

The Social and Game gateways are designed to accept WebSocket and HTTP traffic with requests formatted either as JSON or protobuf. This allows for a full socket, binary protocol for production contexts, and HTTP + JSON for tooling and testing. Both protocols share the same session support and the HTTP protocol includes a distinct payload for accepting async notifications, allowing users to build a rich async client if needed.

Running the engine #

Pragma Engine utilizes a microservices configuration to operate a production shard. To support development and internal test environments, the engine can also run all services within a single artifact. This drastically reduces the complexity of configuring and maintaining dev and internal environments, making it practical to run local dev environments and inexpensive test environments.

Pragma Engine includes a Makefile with various utilities for building and running the platform. These targets are used in local development, and also serve as the primitives for implementing a CI / CD pipeline.

The included dev scripts include setup scripts for Windows, Mac, and Linux that install prerequisites through standard package managers. These include the JVM, Maven, Make, and a few other utilities used by our toolchain.

After installing prerequisites, running the platform is as simple as make build run. The platform will run locally with a default configuration that includes an in-memory database. It will run both Social and Game modes side-by-side within a single running process, and it’s also packaged with our built-in web portal.

We maintain a Postman collection that provides example API calls over HTTP + JSON that can be used to test, experiment, and learn the platform APIs.

Viewing older versions of the documentation #

To access documentation for older versions of Pragma Engine, you can view the docs site locally directly from the pragma-engine repo. Note that following these steps will generate the site based on the engine release version you have downloaded.

Prerequisites:

  • Pragma Engine must be installed on your machine.
  • The site generator tool Hugo must be installed. See install instructions if you don’t already have the latest hugo-extended version installed.

To view the docs site locally:

  1. Navigate to pragma-engine/documentation.
  2. Compile and run the site using the make run command.
  3. If a message about true conditional values pops up, select y to continue.
  4. Access the docs site at localhost:1313.
If you need to update your Hugo version, you’ll get a warning and the site will fail to start.

Custom Services #

Studios can author custom microservices within the Pragma stack. Custom services are authored identically to engine services, taking full advantage of the security, networking, communication, and authorship tools available within the engine. This gives studios full control of their platform and means they’re never blocked on a missing feature or capability.

Many Pragma-provided services support plugins. This allows studios to customize workflows within the engine, for example defining custom matchmaking rules, or authoring custom game data within the inventory and player data services.

Content Management #

Pragma Engine provides a sophisticated content data system. Developers can define an unlimited number of in-game currencies, consumables, skins, and gear. Game assets continue to be managed within the game client, while the engine provides platform-authoritative content ownership, grants, purchases and crafting. Additionally, metadata that cannot be safely controlled by game clients, such as randomly rolled attributes on weapons, can be managed by the Pragma Engine content system.

The platform supports real-time content enablement and scheduling. This includes supporting data migrations to make live game balance changes and evolve game content rapidly in production.


Overview
Customizing Pragma Engine