Using Game Roles

How to give people specific capabilities using the role system

Please read the parent page on Role Groups before reading this

Please be aware this documentation has been updated for v22.0.0. Game roles are string identifiers that correspond to capabilities inside an Unreal world. Game roles are given to users via a role group.

World Roles

You can configure game roles in the Unreal Editor when creating your own mods. For a given Unreal level, open the World Setting and search for Roles. For example, the template map shows:

Example world role configuration

Here you can configure the roles that are available in your world. This can be done by adding data tables to the "Data Tables" array property. We will look at role data table configuration later in this guide. You can also configure the default role for players and bots for your world.

Role Data Tables

If you open the DT_RolesExample asset you can will see the following rows.

Example roles from DT_RolesExample

Selecting the Participantrow will display the following:

An example role from DT_RolesExample

Here you can see all the fields that are configurable on a role. The following is an breif explantion of these properties:

Property	Meaning
Name	Name of the game role
Granted Capabilities	The capabilities associated with game role (i.e. the things they’re allowed to do in the world)
Pawn Lod Level Set	The player character model (and other player rendering options) for different LoD levels to use for players in this game role
Associated Color	Used for UI elements involving roles - make sure this is at least somewhat unique!
Starting Inventory Assets	Items which should be in players' starting inventories when using this role.
Sizes List	A list of possible scale values for the render targets of users with this role. Used primarily with resizable characters, but can also have a single value set to something other than 1.0 to reuse character models at different scales.
Default Size Index	The index in the above list used for scale when spawning the character.
Movement Scale	Scales the movement of users with this role to be faster or slower (multiplicatively).
Avatar Scheme Set	A list of cosmetic schemes for this role supported by the avatar system.
Live Config Value To Check	The live config value responsible for enabling/disabling this role
Emote Selection	The default emote selection set to use for this role

In order to modify one of these properties, you must enable the option using the Role Configuration Override property.

Using Role Configuration Override to show various role configurations properties.

Roles can inherit from a parent role, e.g. the Director role inherits from the Participant role. This grants the Director all of the same capabilities as Participant, as well as any additional ones configured on the Director. All other properties will be inherited from parent unless a properties is specifically overriden at the child level.

A Director role inheriting from a Default role in a data table called DT_Roles. Extra capabilities have been added to the Diretor role.

Example Setup

In order to be able to configure roles in your mod, you'll need to make a copy of a roles table or create one from scratch. We recommend making a copy of DT_RolesExample. Once you've created your own role table, you can freely create, edit, and delete games roles.

Example copy of DT_ExampleRoles named DT_MyCustomRoles.

To use your new data table, change the World Settings entry for your level. (Both the Default Role, and the Data Tables list).

There are in fact three ways of configuring the default role, in order of priority:

1. Live Config - if the General.DefaultRole live config value is used, this will trump other default role values.

2. World Settings - Default Role

3. the Morpheus Character - In your BPM character's Roles Component, it has a Default Role field. This will be used as a fallback if no world settings default role is present.

NOTE: For the live config or character default roles, they still require the relevant roles table to be present in the world settings' Data Tables list.

When you reupload your mod, our tooling parses the world settings and sends them to the web platform.

Capabilities

A full list of capabilities and desciptions can be found in the data table: DT_M2_GameplayTags. If you wish to add your own gameplay tags to your project, first create a new data table using the GameplayTagsTableRow. Then open your DefaultGameplayTags.ini file in your project's config directory and add the following:

[/Script/GameplayTags.GameplayTagsSettings] +GameplayTagTableList=PROJECT_RELATIVE_PATH_TO YOUR_DATA_TABLE

You should now be able to use your custom capabilities.

Pawn sets

A pawn set is an asset which contains a base pawn (the “true” representation of that character) and information about client LOD levels for that pawn for other clients. Pawn sets are intended to be highly reusable. As a (hypothetical) example, if the participant pawn and LOD levels for every map were the same then we’d only need one pawn set for a participant’s character and it’d be used in every map’s role data table. However, pawn sets also give us the flexibility of being able to change client LOD levels on a per-activity basis.

The first step is to create the asset that will contain your base pawn and client LOD levels. This should be a Data Asset of the form J_PawnSetAsset and should live in the appropriate plugin, in the Core/PawnSets folder.

The base pawn should always be the same pawn which is possessed by the player. This pawn will be seen on their client by the player taking on that role, but not necessarily by other players.

Client LoD levels are what other clients will see for players taking on this role. You can add as many client LOD levels as you like, but in most situations two or three will be all you need. In the example below, the first client LOD level is the rendering foreground and the second is an animated crowd render target which handles everything outside the 35 characters in the foreground

Play-in-Editor

When using Play-in-Editor, behaviour is controlled by the Roles section in Editor Preferences

Offline Mode

In offline mode (default), you are automatically granted all roles.

To change while role you spawn with, you can either add an extra to Role Data for Each Client OR change the Row Name in the Default Role section (NOTE - the latter affects launched worlds also).

While playing, you can change roles by hitting Shift + ESC to bring up the regular Escape menu and then navigate as normal to Profile.