Stamp sheet
GS2 provides a system called Stamp Sheets as a mechanism for linking services. This system enables the implementation of processes that are conditional on the execution of resource operations and other operations performed by other services.
A stamp sheet is a system similar to a request for approval in a company. When each service approves a request, it puts a stamp (signature) on it, and when everything is in order, the process can be executed.
The process of consuming resources required for approval is called a stamp task. If each service is able to execute the requested stamp task, a stamp is obtained. When all stamps have been stamped on a stamp sheet, the stamp sheet and processing of each stamp task can be executed.
For example, if you are processing rewards for completing a quest A Stamp Task can be set to reduce the Stamina value or the number of times a quest can be completed, and then the Stamp Task can be set to reward the user for completing the quest. Then, as a reward for the consumption, the user will receive experience value and the quest clear flag will be rewritten. The process is then executed together at the end of the process.
Example of Quest Master Data.
{
"version": "2019-05-14",
"groups": [
{
"name": "main",
"metadata": "Main Scenario",
"quests": [
{
"name": "chapter-0001",
"metadata": "Chapter 1. The beginning of the adventure",
"contents": [
{
"metadata": "NORMAL",
"completeAcquireActions": [
{
"action": "Gs2Money:DepositByUserId",
"request": "{\"namespaceName\": \"money-0001\", \"userId\": \"#{userId}\", \"slot\": \"#{slot}\", \"price\": \"0\", \"count\": \"10\"}"
},
{
"action": "Gs2Money:DepositByUserId",
"request": "{\"namespaceName\": \"money-0001\", \"userId\": \"#{userId}\", \"slot\": \"#{slot}\", \"price\": \"0\", \"count\": \"10\"}"
}
],
"weight": 95
},
{
"metadata": "RARE",
"completeAcquireActions": [
{
"action": "Gs2Money:DepositByUserId",
"request": "{\"namespaceName\": \"money-0001\", \"userId\": \"#{userId}\", \"slot\": \"#{slot}\", \"price\": \"0\", \"count\": \"20\"}"
},
{
"action": "Gs2Money:DepositByUserId",
"request": "{\"namespaceName\": \"money-0001\", \"userId\": \"#{userId}\", \"slot\": \"#{slot}\", \"price\": \"0\", \"count\": \"10\"}"
}
],
"weight": 5
}
],
"consumeActions": [
{
"action": "Gs2Stamina:ConsumeStaminaByUserId",
"request": "{\"namespaceName\": \"stamina-0001\", \"staminaName\": \"main\", \"userId\": \"#{userId}\", \"consumeValue\": \"10\"}"
}
],
"failedAcquireActions": [
{
"action": "Gs2Stamina:RecoverStaminaByUserId",
"request": "{\"namespaceName\": \"stamina-0001\", \"staminaName\": \"main\", \"userId\": \"#{userId}\", \"recoverValue\": \"10\"}"
}
],
"premiseQuestNames": [],
"questModelId": "grn:gs2:ap-northeast-1:sampleproject:quest:quest-0001:group:main:quest:chapter-0001"
}
],
"questGroupModelId": "grn:gs2:ap-northeast-1:sampleproject:quest:quest-0001:group:main"
}
]
}
Stamp sheet variables
Stamp Sheets and Stamp Tasks issue requests to the respective services of GS2.
Stamp tasks are tasks that fulfill the conditions necessary to execute the API of the target service on the stamp sheet, and Actions (consumeActions) can be set to reduce the user’s resources.
Stamp sheets contain actions that increase the user’s resources on completion (completeAcquireActions), and A stamp sheet can have actions to increase user resources on completion (completeAcquireActions) and actions to return user resources on failure (failedAcquireActions).
Setting Stamp Sheet Issuance Parameters
Each request to a service requires information about which user’s resources are to be manipulated. However, it is not possible to statically specify user IDs in advance in the in-game store or quest master data. Therefore, variables can be embedded in stamp sheet requests.
If you set the placeholder string #{userId} in the request for the master data action This will be replaced by the user ID of the user who issued the stamp sheet when the stamp sheet is issued.
Config
A parameter called Config(EzConfig) can be passed to the stamp sheet issuance request. Config(EzConfig) is a key/value format that allows you to replace the placeholder string #{key value specified in Config} with the passed parameter.
Result of Stamp Task Execution If you set the placeholder string ${Gs2Money:WithdrawByUserId.price} as an example in the action’s request description The placeholder string will be replaced by the result of the stamp task execution and can be used as a variable. In the case shown in the example, the result of the Gs2Money:WithdrawByUserId execution of the executed task is referenced and the returned price is used as the value. Child elements can be referenced by connecting them with dots like ${Gs2Money:WithdrawByUserId.item.paid}.
The value adopted when the same action is registered as multiple stamp tasks is undefined.
Example of a stamp sheet that adds a balance to a wallet.
{
"name": "currency-120-jpy",
"metadata": "price: 120 currencyCount: 50",
"consumeActions": [
{
"action": "Gs2Money:RecordReceipt",
"request": "{\"namespaceName\": \"money-0001\", \"contentsId\": \"io.gs2.sample.currency120\", \"userId\": \"#{userId}\", \"receipt\": \"#{receipt}\"}"
}
],
"acquireActions": [
{
"action": "Gs2Money:DepositByUserId",
"request": "{\"namespaceName\": \"money-0001\", \"userId\": \"#{userId}\", \"slot\": \"#{slot}\", \"price\": 120, \"count\": 50}"
}
]
}
Example of setting Config values from Unity.
var result = await gs2.Showcase.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Showcase(
showcaseName: "showcase-0001"
).BuyAsync(
displayItemId: "display-item-0001",
quantity: 1,
config: new [] {
new EzConfig
{
Key = "slot",
Value = Slot.ToString(),
},
new EzConfig
{
Key = "receipt",
Value = receipt,
},
}
);