GS2-Distributor SDK for Game Engine API Reference
Model
EzStampSheetResult
Transaction execution results (Legacy)
Records the execution results of a transaction processed via server-side auto-execution. Contains the request payloads and response results for each phase: verify actions (precondition checks), consume actions (that deduct resources), and the acquire action (that grants resources). Also tracks HTTP status codes for error detection and retry logic.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. | ||
| taskRequests | List<EzConsumeAction> | 0 ~ 100 items | List of Consume Action request payload | |||
| sheetRequest | EzAcquireAction | ✓ | Acquire Action request payload | |||
| taskResults | List<string> | [] | 0 ~ 100 items | Consume Action execution results | ||
| sheetResult | string | ~ 1048576 chars | Acquire Action execution results |
EzTransactionResult
Transaction execution results
Records the execution results of a distributed transaction processed via server-side auto-execution. Contains structured results for each phase: verify actions (precondition checks), consume actions (resource deductions), and acquire actions (resource grants). Each action result includes the request, HTTP status code, and response payload. Errors are detected by checking status codes (non-2xx), and retries are triggered for conflict (409) or server errors (5xx).
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 100 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | 0 ~ 100 items | List of Consume Action execution results | |||
| acquireResults | List<EzAcquireActionResult> | 0 ~ 100 items | List of acquire action execution results |
EzDistributorModel
Distributor Model
Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 2048 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| inboxNamespaceId | string | ~ 1024 chars | GS2-Inbox namespace GRN
to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. | |||
| whiteListTargetIds | List<string> | [] | 0 ~ 1000 items | Whitelist of target resources GRN that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. |
EzConfig
Configuration
Set values to be applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzDistributeResource
Distribute Resource
Represents a single resource distribution operation consisting of a acquire action and its request parameters. Used to specify which GS2 API action to execute and with what parameters when distributing resources to a player.
EzBatchRequestPayload
API Batch Request
Represents a single API request within a batch execution. Multiple batch request payloads can be sent together to execute several GS2 API calls in a single round trip, reducing network overhead and latency.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| requestId | string | ✓ | ~ 128 chars | Request ID A client-assigned identifier for this request within the batch. Used to correlate each request with its corresponding result in the batch response. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| service | String Enum enum { “account”, “adReward”, “auth”, “buff”, “chat”, “datastore”, “deploy”, “dictionary”, “distributor”, “enchant”, “enhance”, “exchange”, “experience”, “formation”, “friend”, “gateway”, “grade”, “guard”, “guild”, “identifier”, “idle”, “inbox”, “inventory”, “jobQueue”, “key”, “limit”, “lock”, “log”, “loginReward”, “lottery”, “matchmaking”, “megaField”, “mission”, “money”, “money2”, “news”, “quest”, “ranking”, “ranking2”, “realtime”, “schedule”, “script”, “seasonRating”, “serialKey”, “showcase”, “skillTree”, “stamina”, “stateMachine”, “version” } | ✓ | Service The GS2 microservice name to call (e.g., “inventory”, “experience”, “money”). Determines which service endpoint receives this API request.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| methodName | string | ✓ | ~ 128 chars | Method Name The API method name to invoke on the target service (e.g., “describeNamespaces”, “getInventory”). Must match a valid API method for the specified service. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| parameter | string | ✓ | ~ 10240 chars | Parameter The JSON-serialized request parameters for the API method. Must conform to the request schema of the specified service method. |
EzBatchResultPayload
API Batch Result
Represents the result of a single API request within a batch execution. Each result is correlated with its original request by the request ID and contains the HTTP status code and JSON response payload.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| requestId | string | ✓ | ~ 128 chars | Request ID The client-assigned identifier matching the corresponding batch request. Used to correlate this result with its original request. | ||
| statusCode | int | ✓ | 100 ~ 1000 | Status Code The HTTP status code returned by the GS2 API for this batch request. 2xx indicates success, 4xx indicates a client error, and 5xx indicates a server error. | ||
| resultPayload | string | ✓ | ~ 10240 chars | Response The JSON response body returned by the GS2 API for this batch request. Contains the API method’s response data or error details. |
EzAcquireAction
Acquire Action
Represents a resource acquisition operation within a distributed transaction. Corresponds to a acquire action that grants resources (e.g., items, currency, experience) to the player. Contains the GS2 API action identifier and the JSON-serialized request parameters.
EzConsumeAction
Consume Action
Represents a resource consumption operation within a distributed transaction. Corresponds to a consume action that deducts resources (e.g., items, currency, stamina) from the player. Consume actions are executed before the acquire action to ensure the player meets the required cost.
EzVerifyAction
Verify Action
Represents a precondition verification operation within a distributed transaction. Executed before consume and acquire actions to validate that conditions are met (e.g., checking inventory capacity, verifying quest completion status). If any verify action fails, the entire transaction is aborted.
EzAcquireActionResult
Acquire Action execution result
Records the result of a single acquire action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| acquireRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code The HTTP status code returned by the GS2 API for this acquire action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. | |||
| acquireResult | string | ~ 1048576 chars | Result payload The JSON response body returned by the GS2 API after executing the acquire action. Contains the details of the acquired resources and may include a chained transaction ID. |
EzConsumeActionResult
Consume Action execution result
Records the result of a single consume action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| consumeRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code The HTTP status code returned by the GS2 API for this consume action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. | |||
| consumeResult | string | ~ 1048576 chars | Result payload The JSON response body returned by the GS2 API after executing the consume action. Contains the details of the consumed resources. |
EzVerifyActionResult
Verify Action execution result
Records the result of a single verify action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| verifyRequest | string | ✓ | ~ 524288 chars | JSON string of the request used when executing the action | ||
| statusCode | int | 0 ~ 999 | Status code The HTTP status code returned by the GS2 API for this verify action. 2xx indicates the verification passed, and non-2xx indicates the precondition was not met. | |||
| verifyResult | string | ~ 1048576 chars | Result payload The JSON response body returned by the GS2 API after executing the verify action. Contains the verification result details. |
Methods
getDistributorModel
Get a distributor model definition by name
Retrieves a single distributor model by specifying its name. The returned information includes the allowed service actions and the inbox namespace configured for overflow handling.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| distributorName | string | ✓ | ~ 128 chars | Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzDistributorModel | Distributor Model |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).DistributorModel(
distributorName: "distributor-model-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).DistributorModel(
distributorName: "distributor-model-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->DistributorModel(
"distributor-model-0001" // distributorName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).DistributorModel(
distributorName: "distributor-model-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).DistributorModel(
distributorName: "distributor-model-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->DistributorModel(
"distributor-model-0001" // distributorName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Distributor::Model::FDistributorModel> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listDistributorModels
Get a list of distributor model definitions
Retrieves all distributor models registered in this namespace. A distributor model defines the rules for resource distribution, including which service actions are allowed and where to send overflow items when a player’s inventory is full (e.g., to the gift box / inbox).
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzDistributorModel> | List of Distributor Models |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.DistributorModelsAsync(
).ToListAsync(); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.DistributorModels(
);
List<EzDistributorModel> items = new List<EzDistributorModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->DistributorModels(
);
TArray<Gs2::UE5::Distributor::Model::FEzDistributorModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeDistributorModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeDistributorModels(callbackId); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeDistributorModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeDistributorModels(callbackId); const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeDistributorModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeDistributorModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
batchExecuteApi
Execute multiple API calls in a single batch
Sends multiple GS2 API requests in one call and receives all responses together. This reduces the number of round-trips and improves performance when you need to call several APIs at the same time — for example, fetching inventory, stamina, and quest progress all at once when a player opens the home screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| requestPayloads | List<EzBatchRequestPayload> | ✓ | 1 ~ 100 items | Batch request |
Result
| Type | Description | |
|---|---|---|
| results | List<EzBatchResultPayload> | Batch result |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: null
);
var result = await domain.BatchExecuteApiAsync(
requestPayloads: new List<Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload> {
new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
Service = "inventory",
Method = "describeSimpleItems",
Request = "{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}",
},
new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
Service = "exchange",
Method = "describeRateModels",
Request = "{\"namespaceName\": \"namespace-0001\"}",
},
}
);
var results = result.Results; var domain = gs2.Distributor.Namespace(
namespaceName: null
);
var future = domain.BatchExecuteApiFuture(
requestPayloads: new List<Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload> {
new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
Service = "inventory",
Method = "describeSimpleItems",
Request = "{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}",
},
new Gs2.Unity.Gs2Distributor.Model.EzBatchRequestPayload() {
Service = "exchange",
Method = "describeRateModels",
Request = "{\"namespaceName\": \"namespace-0001\"}",
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var results = future.Result.Results; const auto Domain = Gs2->Distributor->Namespace(
nullptr // namespaceName
);
const auto Future = Domain->BatchExecuteApi(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>>>();
v->Add(
MakeShared<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>()
->WithService(TOptional<FString>("inventory"))
->WithMethod(TOptional<FString>("describeSimpleItems"))
->WithRequest(TOptional<FString>("{\"namespaceName\": \"namespace-0001\", \"inventoryName\": \"inventory-0001\", \"accessToken\": \"accessToken-0001\"}"))
);
v->Add(
MakeShared<Gs2::UE5::Distributor::Model::FEzBatchRequestPayload>()
->WithService(TOptional<FString>("exchange"))
->WithMethod(TOptional<FString>("describeRateModels"))
->WithRequest(TOptional<FString>("{\"namespaceName\": \"namespace-0001\"}"))
);
return v;
}() // requestPayloads
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
const auto Results = Result->Results;freezeMasterData
Freeze master data at the current point in time
Creates a snapshot of the current master data so that subsequent transactions use this fixed version, even if the master data is updated later. This is useful for ensuring consistency — for example, if a player starts a quest, the rewards should be based on the master data at the time they started, not when they finish.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| newContextStack | string | Context recording the time at which master data is fixed |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Distribute(
);
var result = await domain.FreezeMasterDataAsync(
accessToken: null
); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Distribute(
);
var future = domain.FreezeMasterDataFuture(
accessToken: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Distribute(
);
const auto Future = Domain->FreezeMasterData(
nullptr // accessToken
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();freezeMasterDataBySignedTimestamp
Freeze master data at a specific signed timestamp
Freezes master data at a specific point in time using a signed timestamp. Unlike FreezeMasterData (which uses “now”), this lets you specify an exact time — useful when the freeze point was determined earlier (e.g., on the server side). The signed timestamp can be issued with SignFreezeMasterDataTimestamp.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| body | string | ✓ | ~ 1024 chars | Body | ||
| signature | string | ✓ | ~ 256 chars | Signature | ||
| keyId | string | ✓ | ~ 1024 chars | GS2-Key GRN of the cryptographic key used for signature calculation |
Result
| Type | Description | |
|---|---|---|
| newContextStack | string | Context recording the time at which master data is fixed |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Distribute(
);
var result = await domain.FreezeMasterDataBySignedTimestampAsync(
accessToken: null,
body: "body",
signature: "signature",
keyId: "key-0001"
); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Distribute(
);
var future = domain.FreezeMasterDataBySignedTimestampFuture(
accessToken: null,
body: "body",
signature: "signature",
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Distribute(
);
const auto Future = Domain->FreezeMasterDataBySignedTimestamp(
nullptr, // accessToken
"body", // body
"signature", // signature
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();runStampSheet
Run an acquire action (give resources)
Executes a single acquire action, which grants resources to the player as part of a transaction. For example, giving items, adding experience points, or awarding in-game currency. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| stampSheet | string | ✓ | ~ 5242880 chars | Transaction | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunStampSheetExpress
Execute all actions in a transaction at once (express mode)
Runs all verify, consume, and acquire actions of a transaction in a single API call, which is faster than running them one by one. If an error occurs, call this API again — retrying is safe because the system prevents consume actions from being applied more than once. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| stampSheet | string | ✓ | ~ 5242880 chars | Transaction | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| verifyTaskResultCodes | List<int> | Verify Action execution status code |
| verifyTaskResults | List<string> | Verify Action execution results |
| taskResultCodes | List<int> | Consume Action execution status code |
| taskResults | List<string> | Consume Action execution results |
| sheetResultCode | int | Acquire Action execution status code |
| sheetResult | string | Acquire Action execution result response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunStampSheetExpressWithoutNamespace
Execute all actions in a transaction at once without a namespace (express mode)
Combines the speed of express mode with the lightweight approach of skipping the namespace. Runs all verify, consume, and acquire actions in a single call. Retrying is safe because duplicate consume actions are prevented. Trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| stampSheet | string | ✓ | ~ 5242880 chars | Transaction | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| verifyTaskResultCodes | List<int> | Verify Action execution status code |
| verifyTaskResults | List<string> | Verify Action execution results |
| taskResultCodes | List<int> | Consume Action execution status code |
| taskResults | List<string> | Consume Action execution results |
| sheetResultCode | int | Acquire Action execution status code |
| sheetResult | string | Acquire Action execution result response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunStampSheetWithoutNamespace
Run an acquire action without specifying a namespace
A lightweight variant of RunStampSheet that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| stampSheet | string | ✓ | ~ 5242880 chars | Transaction | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunStampTask
Run a consume action (spend resources)
Executes a single consume action, which deducts resources from the player as part of a transaction. For example, spending in-game currency, consuming stamina, or using up an item. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| stampTask | string | ✓ | ~ 5242880 chars | Consume Action | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| contextStack | string | Request of context reflecting task execution results |
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunStampTaskWithoutNamespace
Run a consume action without specifying a namespace
A lightweight variant of RunStampTask that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| stampTask | string | ✓ | ~ 5242880 chars | Consume Action | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| contextStack | string | Request of context reflecting task execution results |
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunVerifyTask
Run a verify action (check a precondition)
Executes a single verify action, which checks whether a precondition is satisfied before a transaction proceeds. For example, verifying that a player owns a required item or has reached a certain level. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| verifyTask | string | ✓ | ~ 5242880 chars | Verify Action | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| contextStack | string | Request of context reflecting task execution results |
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIrunVerifyTaskWithoutNamespace
Run a verify action without specifying a namespace
A lightweight variant of RunVerifyTask that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| verifyTask | string | ✓ | ~ 5242880 chars | Verify Action | ||
| keyId | string | ✓ | ~ 1024 chars | Encryption Key GRN | ||
| contextStack | string | ~ 32768 chars | Context of request |
Result
| Type | Description | |
|---|---|---|
| contextStack | string | Request of context reflecting task execution results |
| statusCode | int | Status code |
| result | string | Response content |
Implementation Example
// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// New Experience ではSDKレベルで実行されるため明示的にAPIを呼び出す必要はありません
// New Experience runs at the SDK level, so there is no need to explicitly call the API// Runs at the SDK level, so there is no need to explicitly call the APIsetDefaultConfig
Set default config values for transactions
Prepares a context with default config values that will be used when issuing transactions. Config values act as variables that can be embedded in transaction actions — for example, specifying a slot name or a quantity. By setting defaults here, you do not need to pass them every time a transaction is issued.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | ✓ | 1 ~ 1000 items | Transaction placeholder applied settings values |
Result
| Type | Description | |
|---|---|---|
| newContextStack | string | Context stack reflecting the results of the task |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: null
);
var result = await domain.SetDefaultConfigAsync(
accessToken: null,
config: new List<Gs2.Unity.Gs2Distributor.Model.EzConfig> {
new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
Key = "key-0001",
Value = "value-0001",
},
new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
Key = "key-0002",
Value = "value-0002",
},
}
); var domain = gs2.Distributor.Namespace(
namespaceName: null
);
var future = domain.SetDefaultConfigFuture(
accessToken: null,
config: new List<Gs2.Unity.Gs2Distributor.Model.EzConfig> {
new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
Key = "key-0001",
Value = "value-0001",
},
new Gs2.Unity.Gs2Distributor.Model.EzConfig() {
Key = "key-0002",
Value = "value-0002",
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Distributor->Namespace(
nullptr // namespaceName
);
const auto Future = Domain->SetDefaultConfig(
nullptr, // accessToken
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Distributor::Model::FEzConfig>>>();
v->Add(
MakeShared<Gs2::UE5::Distributor::Model::FEzConfig>()
->WithKey(TOptional<FString>("key-0001"))
->WithValue(TOptional<FString>("value-0001"))
);
v->Add(
MakeShared<Gs2::UE5::Distributor::Model::FEzConfig>()
->WithKey(TOptional<FString>("key-0002"))
->WithValue(TOptional<FString>("value-0002"))
);
return v;
}() // config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();getStampSheetResult
Get the result of a completed transaction (legacy)
Retrieves the execution result of a previously completed transaction by specifying its transaction ID. The result includes the status and response of each action (verify, consume, acquire) that was executed. Use this to check what happened in a transaction — for example, to confirm what rewards were actually granted.
This API retrieves results for legacy (stamp-sheet-based) transactions. For newer transaction types, use GetTransactionResult instead.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. |
Result
| Type | Description | |
|---|---|---|
| item | EzStampSheetResult | Transaction execution results |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).StampSheetResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
var item = await domain.ModelAsync(); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).StampSheetResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->StampSheetResult(
"cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).StampSheetResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).StampSheetResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->StampSheetResult(
"cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Distributor::Model::FStampSheetResult> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getTransactionResult
Get the result of a completed transaction
Retrieves the execution result of a previously completed transaction by specifying its transaction ID. The result includes the status and response of each action (verify, consume, acquire) that was executed. Use this to check what happened in a transaction — for example, to confirm what rewards were actually granted or what resources were consumed.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. |
Result
| Type | Description | |
|---|---|---|
| item | EzTransactionResult | Transaction execution results |
Implementation Example
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).TransactionResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
var item = await domain.ModelAsync(); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).TransactionResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->TransactionResult(
"cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).TransactionResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); var domain = gs2.Distributor.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).TransactionResult(
transactionId: "cc1985c3-54f0-4fc3-b295-dc30214284ec"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Distributor->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->TransactionResult(
"cc1985c3-54f0-4fc3-b295-dc30214284ec" // transactionId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Distributor::Model::FTransactionResult> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
Event Handler
OnAutoRunStampSheetNotification
Push notification when transaction auto-execution is complete
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string | User ID |
| transactionId | string | Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. |
Implementation Example
gs2.Distributor.OnAutoRunStampSheetNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var transactionId = notification.TransactionId;
}; gs2.Distributor.OnAutoRunStampSheetNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var transactionId = notification.TransactionId;
}; Gs2->Distributor->OnAutoRunStampSheetNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
const auto TransactionId = Notification->TransactionIdValue;
});OnAutoRunTransactionNotification
Push notification when transaction auto-execution is complete
| Name | Type | Description |
|---|---|---|
| namespaceName | string | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string | User ID |
| transactionId | string | Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. |
Implementation Example
gs2.Distributor.OnAutoRunTransactionNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var transactionId = notification.TransactionId;
}; gs2.Distributor.OnAutoRunTransactionNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var transactionId = notification.TransactionId;
}; Gs2->Distributor->OnAutoRunTransactionNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
const auto TransactionId = Notification->TransactionIdValue;
});