GS2-Formation SDK for Game Engine API Reference
Model
EzMold
Form Storage Area
An entity that holds information organized by the game player. Form information can be stored multiple times per Form Storage Area, and the capacity—how many can be stored—can be set individually for each game player × Form Storage Area.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| capacity | int | ✓ | 0 ~ 2147483646 | Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. |
EzForm
Form
An entity representing formation status. Slots can be defined as areas that can be formed.
For weapons and armor, slots can be represented as parts like “right hand”, “left hand”, “torso”, and “arms”. For parties, slots can be represented as positions like “front line”, “mid-line”, and “back line”.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Form name The name of the mold model this form belongs to. Identifies which form model (slot configuration) applies to this form instance. | ||
| index | int | ✓ | 0 ~ 2147483646 | Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. | ||
| slots | List<EzSlot> | 0 ~ 10 items | List of Slots The current slot assignments for this form. Each entry corresponds to a slot defined in the form model and holds the property ID of the resource assigned to that position. Slot names must match those defined in the form model. |
EzPropertyForm
Property Form
An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Property Form name The name of the property form model that defines the slot configuration for this property form. Determines which slots are available for assignment. | ||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. | ||
| slots | List<EzSlot> | 0 ~ 10 items | List of Slots The current slot assignments for this property form. Each entry corresponds to a slot defined in the property form model. For example, if the property form represents skill configuration for a piece of equipment, each slot might hold a different skill assignment. |
EzFormModel
Form Model
Form Model is an entity representing the configuration status.
You can define slots as areas that can be formed.
For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Form Model name Form 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. | |||
| slots | List<EzSlotModel> | ✓ | 1 ~ 10 items | List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. |
EzMoldModel
Form Storage Area Model
If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Form Storage Area Model name Form Storage Area 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. | |||
| formModel | EzFormModel | ✓ | Form Model | |||
| initialMaxCapacity | int | ✓ | 1 ~ 2147483646 | Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. | ||
| maxCapacity | int | ✓ | 1 ~ 2147483646 | Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. |
EzPropertyFormModel
Property Form Model
An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Property Form Model name Property Form 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. | |||
| slots | List<EzSlotModel> | ✓ | 1 ~ 10 items | List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. |
EzSlotModel
Slot Model
Defines a single slot within a form model. A slot represents an assignable position where a game resource (such as an item, character, or equipment) can be placed. The property regex validates what values can be assigned to the slot.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. | ||
| propertyRegex | string | “.*” | ~ 512 chars | Regular expressions for values that can be set as properties A regex pattern that validates the property ID values assignable to this slot. For example, restricting to specific GS2-Inventory item GRNs or GS2-Dictionary entry GRNs. Defaults to “.*” which allows any value. | ||
| metadata | string | ~ 512 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. |
EzSlot
Slot
Represents the actual assignment state of a single slot within a form. Each slot holds a property ID referencing the game resource (such as a GS2-Inventory item set or GS2-Dictionary entry) that the player has placed in that position.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. | ||
| propertyId | string | ~ 1024 chars | Property ID A developer-defined identifier referencing the game resource assigned to this slot. Typically a GS2-Inventory Item Set GRN, GS2-Dictionary Entry GRN, or other resource identifier. Must match the slot model’s propertyRegex pattern. | |||
| metadata | string | ~ 1024 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. |
EzSlotWithSignature
Signature Slot
A slot assignment that includes a cryptographic signature proving the player owns the referenced resource. Used when updating forms to verify that the player actually possesses the item, entry, or other resource being placed in the slot, preventing unauthorized assignments.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128 chars | Slot Model name Slot Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||||
| propertyType | String Enum enum { “gs2_inventory”, “gs2_simple_inventory”, “gs2_dictionary” } | ✓ | Property Type Specifies the type of GS2 resource referenced by this slot. Determines how the signature is verified: GS2-Inventory item sets, GS2-Inventory simple items, or GS2-Dictionary entries each have different signature formats.
| |||||||||||
| body | string | ~ 1048576 chars | Payload The serialized resource data obtained from the GS2 service that owns the resource. Contains the resource state information needed to verify the signature and confirm ownership. | |||||||||||
| signature | string | ~ 1024 chars | Signature that proves ownership of the resource referenced by the property ID A cryptographic signature generated by the GS2 service that owns the resource. Verified during form updates to ensure the player possesses the referenced item set, simple item, or dictionary entry. | |||||||||||
| metadata | string | ~ 1024 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. |
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 |
EzAcquireAction
Acquire Action
EzVerifyActionResult
Verify Action execution result
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction execution results
Result of a transaction executed using the server-side automatic transaction execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
getMoldModel
Get a specific loadout preset model by name
Retrieves a single mold model by specifying its name. The returned information includes the linked form model (slot structure), the initial number of presets a player can save, and the maximum capacity after expansion. Use this to display details about a specific preset category — for example, showing “Equipment Presets: 3/5 used, expandable to 10” on a formation detail screen.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzMoldModel | Form Storage Area |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->MoldModel(
"mold-0001" // moldModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-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.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-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->Formation->Namespace(
"namespace-0001" // namespaceName
)->MoldModel(
"mold-0001" // moldModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FMoldModel> 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.
listMoldModels
Get a list of loadout preset models
Retrieves all mold models registered in this namespace. A mold model defines a type of loadout preset storage — for example, “Equipment Presets” or “Party Presets” — including how many presets a player can save (initial capacity) and the maximum number after expansion. Each mold model is linked to a form model that defines the slot structure. Use this to show the player all available preset categories, such as “Equipment Sets (3/5 slots used)” on a formation management screen.
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<EzMoldModel> | List of Form Storage Areas |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.MoldModelsAsync(
).ToListAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.MoldModels(
);
List<EzMoldModel> items = new List<EzMoldModel>();
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->Formation->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->MoldModels(
);
TArray<Gs2::UE5::Formation::Model::FEzMoldModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeMoldModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeMoldModels(callbackId); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribeMoldModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeMoldModels(callbackId); const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeMoldModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeMoldModels(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.
getMold
Get a specific loadout preset storage by name
Retrieves the player’s mold record for a specific mold model. The returned information includes the current capacity — how many preset slots the player has available in this category. Use this to check a specific preset category’s status — for example, showing “Equipment Presets: 3/5 slots” before letting the player create a new preset.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzMold | Form Storage Area |
| moldModel | EzMoldModel | Form Storage Area |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-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.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FMold> 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.
listMolds
Get a list of the player’s loadout preset storages
Retrieves all of the player’s mold (preset storage) records. Each mold tracks the current capacity — how many form presets the player can save in that category. For example, a player might have “Equipment Presets” with 3 out of 5 slots used, and “Party Presets” with 1 out of 3 slots used. Use this to build a formation management overview showing all preset categories and their usage.
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 | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzMold> | List of Form Storage Area |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.MoldsAsync(
).ToListAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Molds(
);
List<EzMold> items = new List<EzMold>();
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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Molds(
);
TArray<Gs2::UE5::Formation::Model::FEzMoldPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeMolds(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeMolds(callbackId); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeMolds(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeMolds(callbackId); const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeMolds(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeMolds(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.
getFormModel
Get the slot structure definition for a form
Retrieves the form model associated with a specific mold model. A form model defines the available slots — for example, “weapon slot”, “armor slot”, “accessory slot” — that make up an equipment loadout or party formation. Each slot specifies what kind of item can be placed in it (from inventory, simple inventory, or dictionary). Use this to build the equipment or formation editing screen, so you know what slots are available and how to label them.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzFormModel | Form |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
).FormModel(
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
).FormModel(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->MoldModel(
"mold-0001" // moldModelName
)->FormModel(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
).FormModel(
);
// 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.Formation.Namespace(
namespaceName: "namespace-0001"
).MoldModel(
moldModelName: "mold-0001"
).FormModel(
);
// 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->Formation->Namespace(
"namespace-0001" // namespaceName
)->MoldModel(
"mold-0001" // moldModelName
)->FormModel(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FFormModel> 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.
deleteForm
Delete a saved loadout preset
Deletes a form preset at the specified index within a mold, clearing all slot contents. The preset slot becomes empty and can be reused for a new loadout later. Use this when the player wants to remove a saved preset — for example, a “Delete Preset” button on the loadout detail screen. Consider showing a confirmation dialog since the action cannot be undone.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| index | int | ✓ | 0 ~ 2147483646 | Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. |
Result
| Type | Description | |
|---|---|---|
| item | EzForm | Form |
| mold | EzMold | Form Storage Area |
| moldModel | EzMoldModel | Form Storage Area Model |
| formModel | EzFormModel | Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var result = await domain.DeleteFormAsync(
); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var future = domain.DeleteFormFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
)->Form(
0 // index
);
const auto Future = Domain->DeleteForm(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();getForm
Get a specific saved loadout preset
Retrieves a single form preset by specifying the mold model name and the preset index (0, 1, 2, etc.). The returned information includes the contents of each slot — which items are equipped in each position. Use this to display a loadout detail screen — for example, showing “Preset 1: Weapon = Iron Sword, Armor = Steel Plate, Accessory = Speed Ring”.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| index | int | ✓ | 0 ~ 2147483646 | Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. |
Result
| Type | Description | |
|---|---|---|
| item | EzForm | Form |
| mold | EzMold | Form Storage Area |
| moldModel | EzMoldModel | Form Storage Area Model |
| formModel | EzFormModel | Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
)->Form(
0 // index
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
// 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.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
// 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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
)->Form(
0 // index
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FForm> 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.
getFormWithSignature
Get a loadout preset with a tamper-proof signature
Retrieves a form preset along with a cryptographic signature that proves the data hasn’t been tampered with. This signature is required when updating the form from the client side using SetForm — you must first call this to get the current form and its signature, then submit changes along with that signature. Use this as the first step of the “edit loadout” flow: get the current preset with its signature, let the player make changes, then save with SetForm.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| index | int | ✓ | 0 ~ 2147483646 | Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. | ||
| keyId | string | “grn:gs2:{region}:{ownerId}:key:default:key:default” | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| item | EzForm | Form |
| body | string | Value to be signed |
| signature | string | Signature |
| mold | EzMold | Form Storage Area |
| moldModel | EzMoldModel | Form Storage Area Model |
| formModel | EzFormModel | Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var result = await domain.GetFormWithSignatureAsync(
keyId: "key-0001"
);
var item = await result.ModelAsync();
var body = result.Body;
var signature = result.Signature; var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var future = domain.GetFormWithSignatureFuture(
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
var body = future.Result.Body;
var signature = future.Result.Signature; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
)->Form(
0 // index
);
const auto Future = Domain->GetFormWithSignature(
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
const auto Body = Result->Body;
const auto Signature = Result->Signature;listForms
Get a list of saved loadout presets
Retrieves all form presets the player has saved within a specific mold (preset storage category). Each form is a set of slots filled with item references — for example, Preset 1 might have “Iron Sword” in the weapon slot and “Steel Armor” in the armor slot. Use this to build a preset selection screen where the player can see and switch between their saved loadouts, like “Preset 1: Attack Build”, “Preset 2: Defense Build”.
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzForm> | List of Form |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
var items = await domain.FormsAsync(
).ToListAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
var it = domain.Forms(
);
List<EzForm> items = new List<EzForm>();
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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
);
const auto It = Domain->Forms(
);
TArray<Gs2::UE5::Formation::Model::FEzFormPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
// Start event handling
var callbackId = domain.SubscribeForms(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeForms(callbackId); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
);
// Start event handling
var callbackId = domain.SubscribeForms(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeForms(callbackId); const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
);
// Start event handling
const auto CallbackId = Domain->SubscribeForms(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeForms(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.
setForm
Save changes to a loadout preset
Updates the slot contents of a form preset — for example, changing the weapon slot from “Iron Sword” to “Flame Blade”. This requires a signature obtained from GetFormWithSignature to prevent tampering. The typical flow is: (1) call GetFormWithSignature to get the current form and signature, (2) let the player edit their loadout, (3) call this API with the new slot values and the signature. If the mold doesn’t have a form at the specified index yet, a new preset is created (as long as the mold has available capacity).
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 (.). | ||
| moldModelName | string | ✓ | ~ 128 chars | Form Storage Area Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| index | int | ✓ | 0 ~ 2147483646 | Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. | ||
| slots | List<EzSlotWithSignature> | ✓ | 1 ~ 10 items | List of Slot | ||
| keyId | string | “grn:gs2:{region}:{ownerId}:key:default:key:default” | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| item | EzForm | Form |
| mold | EzMold | Form Storage Area |
| moldModel | EzMoldModel | Form Storage Area Model |
| formModel | EzFormModel | Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var result = await domain.SetFormAsync(
slots: new List<Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature> {
new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature() {
Name = "slot-0001",
PropertyType = "gs2_dictionary",
Body = "body",
Signature = "signature",
},
},
keyId: "key-0001"
);
var item = await result.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Mold(
moldModelName: "mold-0001"
).Form(
index: 0
);
var future = domain.SetFormFuture(
slots: new List<Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature> {
new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature() {
Name = "slot-0001",
PropertyType = "gs2_dictionary",
Body = "body",
Signature = "signature",
},
},
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Mold(
"mold-0001" // moldModelName
)->Form(
0 // index
);
const auto Future = Domain->SetForm(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Formation::Model::FEzSlotWithSignature>>>();
v->Add(
MakeShared<Gs2::UE5::Formation::Model::FEzSlotWithSignature>()
->WithName(TOptional<FString>("slot-0001"))
->WithPropertyType(TOptional<FString>("gs2_dictionary"))
->WithBody(TOptional<FString>("body"))
->WithSignature(TOptional<FString>("signature"))
);
return v;
}(), // slots
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();getPropertyFormModel
Get a specific per-item form model by name
Retrieves a single property form model by specifying its name. The returned information includes the slot definitions — what slots are available (e.g., “weapon”, “armor”, “skill”) and what kind of items can be placed in each slot. Use this to build the equipment editing screen for a specific character or item — for example, when the player taps on a character to manage their gear.
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 (.). | ||
| propertyFormModelName | string | ✓ | ~ 128 chars | Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzPropertyFormModel | Property Form |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).PropertyFormModel(
propertyFormModelName: "form-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).PropertyFormModel(
propertyFormModelName: "form-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->PropertyFormModel(
"form-0001" // propertyFormModelName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).PropertyFormModel(
propertyFormModelName: "form-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.Formation.Namespace(
namespaceName: "namespace-0001"
).PropertyFormModel(
propertyFormModelName: "form-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->Formation->Namespace(
"namespace-0001" // namespaceName
)->PropertyFormModel(
"form-0001" // propertyFormModelName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FPropertyFormModel> 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.
listPropertyFormModels
Get a list of per-item form models
Retrieves all property form models registered in this namespace. A property form model defines a slot structure for forms that are identified by a custom property ID (like a character ID or weapon ID) rather than being stored in numbered preset slots. This is useful when each character or item has its own individual equipment set — for example, “Hero’s equipment” or “Mage’s equipment” where the property ID is the character’s unique ID. Use this to show the player all available per-item form types on a formation management screen.
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<EzPropertyFormModel> | List of Property Form Model name |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.PropertyFormModelsAsync(
).ToListAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.PropertyFormModels(
);
List<EzPropertyFormModel> items = new List<EzPropertyFormModel>();
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->Formation->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->PropertyFormModels(
);
TArray<Gs2::UE5::Formation::Model::FEzPropertyFormModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribePropertyFormModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribePropertyFormModels(callbackId); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
);
// Start event handling
var callbackId = domain.SubscribePropertyFormModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribePropertyFormModels(callbackId); const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribePropertyFormModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribePropertyFormModels(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.
deletePropertyForm
Delete a character’s or item’s equipment set
Deletes the property form for a specific property ID, clearing all slot contents. After deletion, the character or item will have no equipment set — you can create a new one later by calling SetPropertyForm. Use this when the player wants to reset a character’s equipment to empty — for example, a “Clear All Equipment” button on the character detail screen. Consider showing a confirmation dialog since all equipped items will be unassigned.
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 | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. |
Result
| Type | Description | |
|---|---|---|
| item | EzPropertyForm | Property Form |
| propertyFormModel | EzPropertyFormModel | Property Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var result = await domain.DeletePropertyFormAsync(
); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var future = domain.DeletePropertyFormFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->PropertyForm(
"form-0001", // propertyFormModelName
"property-0001" // propertyId
);
const auto Future = Domain->DeletePropertyForm(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();getPropertyForm
Get a specific character’s or item’s equipment set
Retrieves a single property form by specifying the property form model name and the property ID (e.g., character ID). The returned information includes the contents of each slot — which items are equipped in each position for that specific character or item. Use this to display a character’s equipment detail screen — for example, showing “Hero: Weapon = Flame Blade, Armor = Dragon Mail, Shield = Holy Shield”.
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 (.). | ||
| propertyFormModelName | string | ✓ | ~ 128 chars | Property Form Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. |
Result
| Type | Description | |
|---|---|---|
| item | EzPropertyForm | PropertyForm |
| propertyFormModel | EzPropertyFormModel | Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->PropertyForm(
"form-0001", // propertyFormModelName
"property-0001" // propertyId
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-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.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->PropertyForm(
"form-0001", // propertyFormModelName
"property-0001" // propertyId
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Formation::Model::FPropertyForm> 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.
getPropertyFormWithSignature
Get a character’s equipment set with a tamper-proof signature
Retrieves a property form along with a cryptographic signature that proves the data hasn’t been tampered with. This signature is required when updating the property form from the client side using SetPropertyForm — you must first call this to get the current form and its signature, then submit changes along with that signature. Use this as the first step of the “edit character equipment” flow: get the current equipment with its signature, let the player make changes, then save with SetPropertyForm.
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 (.). | ||
| propertyFormModelName | string | ✓ | ~ 128 chars | Property Form Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. | ||
| keyId | string | “grn:gs2:{region}:{ownerId}:key:default:key:default” | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| item | EzPropertyForm | Property Form |
| body | string | Value to be signed |
| signature | string | Signature |
| propertyFormModel | EzPropertyFormModel | Property Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var result = await domain.GetPropertyFormWithSignatureAsync(
keyId: "key-0001"
);
var item = await result.ModelAsync();
var body = result.Body;
var signature = result.Signature; var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var future = domain.GetPropertyFormWithSignatureFuture(
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
var body = future.Result.Body;
var signature = future.Result.Signature; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->PropertyForm(
"form-0001", // propertyFormModelName
"property-0001" // propertyId
);
const auto Future = Domain->GetPropertyFormWithSignature(
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
const auto Body = Result->Body;
const auto Signature = Result->Signature;listPropertyForms
Get a list of per-item equipment sets
Retrieves all property form records the player has for a specific property form model. Unlike regular forms (which are stored in numbered preset slots), property forms are identified by a custom property ID — typically the ID of a character or item. For example, this returns “Hero’s equipment”, “Mage’s equipment”, “Archer’s equipment” where each character has their own individual gear setup. Use this to build an overview screen showing all characters and their equipment configurations.
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 (.). | ||
| propertyFormModelName | string | ✓ | ~ 128 chars | Property Form Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzPropertyForm> | List of PropertyForm |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.PropertyFormsAsync(
propertyFormModelName: "form-0001"
).ToListAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.PropertyForms(
propertyFormModelName: "form-0001"
);
List<EzPropertyForm> items = new List<EzPropertyForm>();
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->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->PropertyForms(
"form-0001" // propertyFormModelName
);
TArray<Gs2::UE5::Formation::Model::FEzPropertyFormPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribePropertyForms(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribePropertyForms(callbackId); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribePropertyForms(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribePropertyForms(callbackId); const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribePropertyForms(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribePropertyForms(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.
setPropertyForm
Save changes to a character’s or item’s equipment set
Updates the slot contents of a property form — for example, changing the Hero’s weapon from “Iron Sword” to “Flame Blade”. This requires a signature obtained from GetPropertyFormWithSignature to prevent tampering. The typical flow is: (1) call GetPropertyFormWithSignature to get the current form and signature, (2) let the player edit the equipment, (3) call this API with the new slot values and the signature. If no property form exists for the given property ID yet, a new one is created automatically.
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 (.). | ||
| propertyFormModelName | string | ✓ | ~ 128 chars | Property Form Model name | ||
| gameSession | GameSession | ✓ | GameSession | |||
| propertyId | string | ✓ | ~ 1024 chars | Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. | ||
| slots | List<EzSlotWithSignature> | ✓ | 1 ~ 10 items | List of Slot | ||
| keyId | string | “grn:gs2:{region}:{ownerId}:key:default:key:default” | ~ 1024 chars | Encryption Key GRN |
Result
| Type | Description | |
|---|---|---|
| item | EzPropertyForm | Property Form |
| proeprtyFormModel | EzPropertyFormModel | Property Form Model |
Implementation Example
var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var result = await domain.SetPropertyFormAsync(
slots: new List<Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature> {
new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature() {
Name = "slot-0001",
PropertyType = "gs2_dictionary",
Body = "body",
Signature = "signature",
},
},
keyId: "key-0001"
);
var item = await result.ModelAsync(); var domain = gs2.Formation.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).PropertyForm(
propertyFormModelName: "form-0001",
propertyId: "property-0001"
);
var future = domain.SetPropertyFormFuture(
slots: new List<Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature> {
new Gs2.Unity.Gs2Formation.Model.EzSlotWithSignature() {
Name = "slot-0001",
PropertyType = "gs2_dictionary",
Body = "body",
Signature = "signature",
},
},
keyId: "key-0001"
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Formation->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->PropertyForm(
"form-0001", // propertyFormModelName
"property-0001" // propertyId
);
const auto Future = Domain->SetPropertyForm(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Formation::Model::FEzSlotWithSignature>>>();
v->Add(
MakeShared<Gs2::UE5::Formation::Model::FEzSlotWithSignature>()
->WithName(TOptional<FString>("slot-0001"))
->WithPropertyType(TOptional<FString>("gs2_dictionary"))
->WithBody(TOptional<FString>("body"))
->WithSignature(TOptional<FString>("signature"))
);
return v;
}(), // slots
"key-0001" // keyId
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();