Limited Grants #

Limited grants are one-time item grants given to players on login. Below are a few circumstances for why players might receive a limited grant:

• starter pack for new players
• incentive for returning players
• seasonal events for an entire playerbase

For an in-depth tutorial on how to create and apply limited grants, see Limited Grants.

Understanding limited grants #

Limited grants simplify the process of giving players items that should only be granted on login. A limited grant can include any combination of instanced and stackable items. In addition to items like a seasonal cosmetic, limited grants can be used to give players metadata items. This includes hidden inventory items such as a matchmaking rating.

Below is an example of a limited grant:

// platform/5-ext/content/src/LimitedGrants.json

[
    {
        "trackingId": "NewYear2023Grant",
        "stackableGrants": [
            {
            "catalogId": "coins",
            "amount": 50
            }
        ],
        "startTime": 1672560000000, //optional field
        "endTime": 1798761599000, // optional field
        "ext": {} // optional field
    }
]

Pragma Engine handles specifying which players are given limited grants and keeps track of the players who have received their limited grant. The trackingId is used to distinguish if a player has received their limited grant. If the trackingId is modified, Pragma Engine treats the limited grant as new.

Limited grants require corresponding stackable and instanced items. These items must first be defined in Pragma Engine’s Content Data system. The catalogId is used as an identifier to find the corresponding content in the limited grant.

Time windows can be defined, enabling limited grants to only be given to players during a specified start and end time. These dates are set in epoch-based milliseconds. Players will only receive their limited grant if they log in between these times.

The ext field can be used to store data required to make decisions on if a player should be given a limited grant.

For an example implementation of the ext field, see the Define a requirement section of the Limited Grant tutorial.

Limited Grant Plugin #

Custom logic to determine if a player should receive a limited grant can be defined within the Limited Grant Plugin.

Pragma Engine uses a default implementation if no custom plugin is configured. The default behavior returns true to give players the limited grant.

Add new conditions #

The LimitedGrantPlugin.shouldGrant function is used to create custom requirements for when a player should get a grant based on their inventory.

This function is called for each limited grant the player has not received. If shouldGrant() returns false, the limited grant is not given to the player.

Pragma Engine verifies if a limited grant has been given. The plugin will not be called if the limited grant has been granted and processed.

Configure your plugin #

To use your plugin, configure it in your Pragma Engine config:

game:
  pluginConfigs:
    InventoryService.limitedGrantPlugin:
      class: "demo.inventory.<Class-Name-Of-Your-Custom-LimitedGrantPlugin>"

Give players limited grants #

Pragma Engine’s GameDataService.getLoginDataV3() endpoint processes limited grants.

// On UPragmaGameDataService
void GetLoginDataV3(
  const FOnCompleteGetLoginDataV3Delegate OnComplete
) const;
DECLARE_EVENT_OneParam(
  UPragmaGameDataService, FGetLoginDataV3Event, FPragma_GameData_LoginDataV3
);

// On GameDataService
public Future<LoginDataV3> GetLoginDataV3()
public void GetLoginDataV3(GetLoginDataV3Delegate onComplete)
public delegate void GetLoginDataV3Delegate(Result<LoginDataV3> result);

/**
 * An RPC Request to get all login data for a player.
 */
message GetLoginDataV3Request {
  option (pragma_session_type) = PLAYER;
  option (pragma_message_type) = REQUEST;
}

message GetLoginDataV3Response {
  option (pragma_session_type) = PLAYER;
  option (pragma_message_type) = RESPONSE;

  LoginDataV3 login_data = 1;
}

/**
 * LoginDataV3 is a client packet containing all content data the game needs,
 * including inventory and catalogs.
 */
message LoginDataV3 {
  // A customer-defined ext declaring any custom login data.
  ExtLoginData ext = 1;
  InventoryLoginData inventory_data = 2;
}

message InventoryLoginData {
  // content used by the inventory service
  InventoryContent inventory_content = 1;
  
  // A list of the limited grant ids that were processed for the player.
  repeated string issued_limited_grant_tracking_ids = 2;
}

message InventoryContent {
  // A full copy of the game's item catalog.
  inventory.ItemCatalog item_catalog = 1;

  // A list of stores in the game, annotated with player-specific data.
  repeated inventory.AnnotatedStore stores = 2;

  // A list of all update entries in the game.
  repeated inventory.UpdateEntry update_entries = 3;

  // A list of all crafting entries within the game.
  repeated inventory.CraftingEntry crafting_entries = 4;

  // A list of all item bundles within the game.
  repeated inventory.ItemBundle item_bundles = 5;

  // A list of all provider entitlement mappings within the game.
  repeated inventory.ProviderEntitlementMappings provider_entitlement_mappings = 6;
}