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. user.name, user.email must be set

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

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 git@github.com:<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.

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

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

$ ./linux-setup.sh -m -e

$ brew install mysql@8.0

$ 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 ➨ Settings ➨ Plugins
• Mac: IntelliJ IDEA menu ➨ Preferences ➨ Plugins

2. Type protobuf into the search box.

3. Install the Protobuf plugin by HIGAN.

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

5. Type kotlin into the search box.

6. 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

2. Ensure Project is selected in the left sidebar.

3. Select Amazon Corretto under Project SDK.

4. 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…

idea.max.intellisense.filesize=20000

2. 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 \
 --mode DEVELOPMENT \
 --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.