Initial Setup #

Pragma Engine is a platform that supports cross platform accounts, game loop, matchmaking, player data, metrics, and more. Pragma enables studios to build and operate rich live service games.

Throughout this guide, you will:

  • set up a development environment with all dependencies
  • create a Pragma git repository locally in your organization’s GitHub account
  • build and run Pragma running locally

Developer Setup #

Setting up your development environment #

You must have several dependencies installed in order to use all features provided by Pragma Engine. We recommend using our automated setup script to install the development dependencies and set up Git.

  • Git, Make, Maven, and Corretto JDK are required to build Pragma Engine
  • IntelliJ is the recommended IDE for Pragma Engine development
  • Docker is recommended for running Pragma Engine with a local database
  • Postman is the most convenient way to send service calls to test the platform
  • Git must be set up with your identity e.g., must be set

Click on your OS for automated setup instructions. If you prefer to install dependencies manually, click Manual setup.

  1. Download the setup script, which can be found in the shared Pragma - Documentation folder in the Setup folder.

  2. Open cmd.exe and cd into the directory where you’ve downloaded the setup scripts.

  3. Run setup.bat in cmd.exe with the desired options (described below).

    • Allow Windows Powershell to run when prompted, as administrator privileges are required to install software.
    • To install all recommended dependencies, run
    setup.bat --default --intellij --tools
    --default           Installs git, make, maven, and corretto
    --intellij          Installs intellijidea-community
    --tools             Installs postman and mysql.workbench
    --infra             Installs docker-desktop
    --node              Installs nodejs
    --unity             Installs unity-hub and unity
    --visualstudio      Installs visualstudio2019community, -workload-netcoretools, -workload-vctools, -workload-netcorebuildtools, visualstudio2019buildtools, and netfx-4.7.1-devpack
    --extras            Installs firacode
    --gitkeys           Installs git and gpg4win, then generates SSH and GPG keypairs
    --all               Installs all available packages and assists with key generation.

Once you’ve run the script, proceed to the Code section.


We recommend Ubuntu 20.04 LTS or newer, or other Ubuntu-based distros. Debian-based distros may work. Other distributions will require manual setup and are currently unsupported.

  1. Download the setup script, which can be found in the shared Pragma - Documentation folder in the Setup folder.

  2. Open a terminal and cd into the directory where you’ve downloaded the setup scripts.

  3. chmod +x to make the script executable

  4. ./ -di to install the recommended dependencies. Enter your password when prompted; root privileges are required to install software.

    • is an uninstallation script
    • Additional software can be installed.
    -d    Defaults:  Installs git, gnupg2, Amazon Corretto 11 (JDK), and Maven
    -i    IntelliJ:  Installs IntelliJ 2022.1
    -n    Node:  Installs NodeJS 16
    -o    Docker:  Installs docker and docker-compose
    -e    Extras:  Installs Typora and MySQL Workbench
    -g    git setup:  Installs git if necessary, helps you enter your git information,
          and helps you create your SSH and GPG keys.
  5. Once you’ve run the script, proceed to the Code section.

This script does not install Postman, but you can install it manually in Ubuntu by running sudo snap install postman.
  • XCode - use this terminal command to install the XCode command-line tools
    xcode-select --install
Manual setup
Consult the automated setup scripts for your OS for the specific versions we install.

Code #

Now that you have the prerequisites, you’ll need the platform-engine code.

  • Windows - requires Git Bash (no powershell support currently)
  • MacOS / Linux - relies on bash

Git repo setup #

If you’re a current customer, view our README for direct links to our repos and directions for setting up the Git repo.

Git clone #

  • After completing the Code setup steps, you and your team can work out of your new repo.
git clone<YOUR ORG>/pragma-engine.git

Project Setup #

This setup is for developers who will be writing features with Pragma Engine, such as writing custom services, extensions, and plugins.

Set up MySQL database #

You will need to setup a local MySQL database. All configs are set to connect to default port: 3306. We also recommend downloading a database manager such as MySQL Workbench or Sequel Pro (MacOS only).

You must either set up MySQL using Docker or locally on your machine.

Docker setup
  1. Initialize and start MySQL and other required services:
    cd pragma-engine/platform/devenv/docker-compose-devenv
    docker-compose up -d
Local setup

You can complete the local setup using Windows, Linux, or Mac.

We recommend setting lower_case_table_names=1 in your config if you have issues with table names.


Run the following commands:

$ cd /platform/devenv/setup/
$ ./setup.bat --mysql

Run the following commands:

$ cd /platform/devenv/setup/
$ ./ --mysql

(optional) You can replace the second line with the following command to install mysqlworkbench at the same time:

$ ./ -m -e

Run the following commands to set up MySQL in Mac:

$ brew install mysql@8.0

(optional) You can replace this line with the following to install mysqlworkbench at the same time:

$ brew install --cask mysqlworkbench

Build and initial commit #

The first build generates a directory called 5-ext, where game specific services, extensions, and plugins are authored.

  1. Complete the first build:
    cd pragma-engine/platform
    make build
  2. Add the generated files to your Git repo:
    git add .
    git commit -m "Adding game project"
    git push

IntelliJ setup #

Open Pragma Engine

  1. Open pragma-engine/platform/pom.xml in IntelliJ.

  2. Click Open as Project.

  3. Click Trust Project and ignore plugin suggestions.

  4. Open the Maven tab on the right-hand side, then click the + button.

  5. Select pragma-engine/platform/5-ext/pom.xml and click OK.

Configure plugins

  1. Open the plugins window.
  • Windows: File menu ➨ SettingsPlugins
  • Mac: IntelliJ IDEA menu ➨ PreferencesPlugins
  1. Type protobuf into the search box.

  2. Install the Protobuf plugin by HIGAN.

  3. Click the Installed tab at the top center of the window.

  4. Type kotlin into the search box.

  5. Confirm that the bundled Kotlin plugin is version 1.6.2 or newer.

Configure JDK version

  1. Open the Project Structure window.
  • Windows: File menu ➨ Project Structure
  • Mac: IntelliJ IDEA menu ➨ Project Structure
  1. Ensure Project is selected in the left sidebar.

  2. Select Amazon Corretto under Project SDK.

  3. Select 11 - Local variable syntax for lambda parameters under Project Language Level and click OK.

Edit custom properties

  1. Add the following to your custom properties access. From Help menu -> Edit Custom Properties…


  1. Save the file then restart IntelliJ.

Configure Pragma to run in IntelliJ

  1. Run Build -> Build Project to build the project in the IDE.

  2. Click Add Configuration… in the IntelliJ toolbar.

  3. Under Kotlin, select MainKt - LocalConfiguration.

  4. Click OK.

Pragma is ready to run in IntelliJ. Whenever you want to run Pragma, click the play button in the IntelliJ toolbar.

Proto generation

After authoring or editing protobuf types, recompile the protos.

  • Show Maven panel (View->Tool Windows->Maven), right-click on 1-protos and Run Maven Build.
IntelliJ may report a red error, but Maven should say BUILD SUCCESS if you click on 1-protos-pragma[install] in the run window.

Optional IDE configuration

  • Configure IntelliJ memory: Help menu -> Change Memory Settings -> set Maximum Heap Size to 4000-8000 MB.
  • To clean up the project view: IntelliJ IDEA -> Preferences -> Editor -> File Types. Add *.iml;*.idea;.flattened-pom.xml to the Ignore Files and Folders list.

IDE Troubleshooting

  • Type shift + shift and run Reload All Maven Projects.
  • From the application menu, run Build -> Rebuild Project.

Docker setup #

This setup uses a Docker container to avoid installing a majority of the Pragma Platform dependencies, but still allows a developer to run a local Pragma Platform. For example, a game designer editing the content files (stores, inventory, etc) can use this setup to change the JSON files without needing a fully functional programming environment.

  • install docker
  • build project with docker=true make skip-tests build
  • run the service with docker=true make run

Postman setup #

  1. Open a terminal window and cd to the folder where Pragma Engine has been cloned, and navigate to pragma-engine/platform
  2. Run make build to create all required directories and files.
  3. Open Postman and click on the File menu, then Import.
  4. Click on the Folder tab, then click Choose folder from your computer.
  5. Navigate to pragma-engine/platform/devenv/postman, then click Select Folder.
  6. Click the Import button.
  7. Open the Environment dropdown menu and select localhost <latest date>.
Remember to import the newest collection regularly, as we often update with new calls.

Command line workflow #

The command line workflow allows developers to build, test, and run packaged builds of the platform. This is more representative of a real running platform, but the packaging process does add time to the development loop. The IDE workflow relies on configuring IntelliJ but provides a faster feedback loop while developing.

Core workflow #

# First time setup, builds engine and 5-ext game project
make build run

# When just updating 5-ext game project
make ext run

# if your platform is already built
make run

Additional commands #

Running the make help command on the Makefile will list out all the available commands currently supported. If the readme does not list a make target, please use make help for the most up-to-date documentation.

Configuration #

Configs are located in pragma-engine/platform/5-ext/config/:

  • CommonConfig.yml - checked in, common configuration such as studio plugins
  • LocalConfig.yml - not checked in, machine specific configuration such as local install paths to Unity/Unreal for local game loop

Execution #

When running the Pragma Platform directly, a variety of command line arguments are expected. Here is an example of how to run a complete shard.

java -jar ./pragma-platform.jar server \
 --backend-type BOTH \
 --decrypter PassthroughDecrypter \
 --database-validator CheckCreateMigrateDatabaseValidator \
 --configuration-filepath <path to configuration file> \
 --content-data-directory <path to content>

For the most up-to-date command-line arguments, look at the run target at the end of platform/Makefile.

More resources #

To learn more about Pragma’s features, visit the Pragma website.