Getting Started with Limited Grants #

In this section, we’ll show an example of how to create and apply a limited grant. To implement a limited grant, there are a few steps that need to be taken:

1. Define the stackable and instanced specs for the items you would like to grant.
2. Define the limited grant.
3. Add and apply the new content with the content data apply command.

Get started #

Run the following commands in the terminal from the platform directory:

1. make skip-tests protos engine ext
2. make init-inventory-content

Define stackable item specs #

A limited grant contains catalogIds that map to stackable and instanced items. These items require corresponding stackable and instanced specs.

In the example below, we define a stackable spec for the stackable item coins with a limit of 1,000,000. Add the following to the contents of platform/5-ext/content/src/StackableSpecs.json:

[
  {
    "catalogId": "coins",
    "name": "coins",
    "limit": 1000000,
    "tags": ["currency"],
    "removeIfNone": false
  }
]

Now that we’ve defined the stackable spec and item coins, in the next section we’ll define a limited grant that uses this item.

Define a limited grant spec #

Here we define a limited grant with a stackable grant of 50 coins. Add the following code to the contents of platform/5-ext/content/src/LimitedGrants.json:

[
  {
    "trackingId": "StarterPack",
    "stackableGrants": [
      {
        "catalogId": "coins",
        "amount": 50
      }
    ]
  }
]

The trackingId is how Pragma Engine distinguishes whether a player has already received this limited grant. Do not modify the trackingId after applying new content data as Pragma Engine will treat the modified trackingId as a new limited grant.

Define a time window #

We can also define a limited grant that will only be granted within a specified time window. To do this, set a start and end time in epoch-based milliseconds. Players will only be given the limited grant if they log in between the start and end time.

Here we define a limited grant for 50 coins with a start time of January 1, 2023 12:00 am UTC and end time of December 31, 2026, 11:59 pm UTC. Add the following object into the array in platform/5-ext/content/src/LimitedGrants.json:

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

[
  {
    "trackingId": "StarterPack",
    "stackableGrants": [
      {
        "catalogId": "coins",
        "amount": 50
      }
    ]
  },
  {
    "trackingId": "NewYear2023Grant",
    "stackableGrants": [
      {
        "catalogId": "coins",
        "amount": 50
      }
    ],
    "startTime": 1672560000000,
    "endTime": 1798761599000
  }
]

Define a requirement #

Next we’ll create a custom requirement where players must have a stackable item with an associated catalog ID to receive the limited grant.

1. In 5-ext/ext-protos/src/main/proto/shared/InventoryContentExt.proto define the ExtLimitedGrant message.

message ExtLimitedGrant{
  string required_stackable_catalog_id = 1;
}

2. Run make ext-protos after adding or updating any proto message.

3. Update your limited grant to include the ext.

[
  {
    "trackingId": "StarterPack",
    "stackableGrants": [
      {
        "catalogId": "coins",
        "amount": 50
      }
    ],
    "startTime": 1672560000000,
    "endTime": 1798761599000
    "ext": {
        "requiredStackableCatalogId": "special-player-token"
     }
  }
]

Apply content data #

In order to register the content you just defined with Pragma Engine, you must apply your content data changes. You may apply content data either using the command line with make or via an IntelliJ run configuration.

make ext-contentdata-apply