> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Formation SDK for Game Engine API Reference

Specifications of models and API references for GS2-Formation SDK for Game Engine



## Models

### EzMold

Form Storage Area

An entity that holds formation information configured 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<br>Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓ |  |  ~ 128 chars | User ID |
| capacity | int |  | ✓ |  | 0 ~ 2147483646 | Current Capacity<br>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. |

**Related methods:**
getMold - Get a specific loadout preset storage by name
listMolds - List the player's loadout preset storages
deleteForm - Delete a saved loadout preset
getForm - Get a specific saved loadout preset
getFormWithSignature - Get a loadout preset with a tamper-proof signature
setForm - Save changes to a loadout preset


---

### 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<br>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<br>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&lt;EzSlot&gt;](#ezslot) |  |  |  | 0 ~ 10 items | List of Slots<br>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. |

**Related methods:**
deleteForm - Delete a saved loadout preset
getForm - Get a specific saved loadout preset
getFormWithSignature - Get a loadout preset with a tamper-proof signature
listForms - List saved loadout presets
setForm - Save changes to a loadout preset


---

### EzPropertyForm

Property Form

Property Form is an entity representing the formation 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<br>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<br>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&lt;EzSlot&gt;](#ezslot) |  |  |  | 0 ~ 10 items | List of Slots<br>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. |

**Related methods:**
deletePropertyForm - Delete a character's or item's equipment set
getPropertyForm - Get a specific character's or item's equipment set
getPropertyFormWithSignature - Get a character's equipment set with a tamper-proof signature
listPropertyForms - List per-item equipment sets
setPropertyForm - Save changes to a character's or item's equipment set


---

### EzFormModel

Form Model

Form Model is an entity representing the formation 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<br>Unique Form Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| slots | [List&lt;EzSlotModel&gt;](#ezslotmodel) |  | ✓ |  | 1 ~ 10 items | List of Slot Model<br>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. |

**Related methods:**
getFormModel - Get the slot structure definition for a form
deleteForm - Delete a saved loadout preset
getForm - Get a specific saved loadout preset
getFormWithSignature - Get a loadout preset with a tamper-proof signature
setForm - Save changes to a loadout preset


**Related models:**
EzMoldModel - Form Storage Area Model



---

### 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<br>Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| formModel | [EzFormModel](#ezformmodel) |  | ✓ |  |  | Form Model |
| initialMaxCapacity | int |  | ✓ |  | 1 ~ 2147483646 | Initial capacity to store forms<br>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<br>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. |

**Related methods:**
getMoldModel - Get a specific loadout preset model by name
listMoldModels - List loadout preset models
getMold - Get a specific loadout preset storage by name
deleteForm - Delete a saved loadout preset
getForm - Get a specific saved loadout preset
getFormWithSignature - Get a loadout preset with a tamper-proof signature
setForm - Save changes to a loadout preset


---

### EzPropertyFormModel

Property Form Model

An entity that represents the formation 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<br>Unique Property Form Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| slots | [List&lt;EzSlotModel&gt;](#ezslotmodel) |  | ✓ |  | 1 ~ 10 items | List of Slot Model<br>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. |

**Related methods:**
getPropertyFormModel - Get a specific per-item form model by name
listPropertyFormModels - List per-item form models
deletePropertyForm - Delete a character's or item's equipment set
getPropertyForm - Get a specific character's or item's equipment set
getPropertyFormWithSignature - Get a character's equipment set with a tamper-proof signature
setPropertyForm - Save changes to a character's or item's equipment set


---

### 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<br>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<br>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<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |


**Related models:**
EzFormModel - Form Model
EzPropertyFormModel - Property Form Model



---

### 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<br>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<br>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<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |


**Related models:**
EzForm - Form
EzPropertyForm - Property Form



---

### 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<br>Unique Slot Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| propertyType | string (enum)<br>enum {<br>&nbsp;&nbsp;"gs2_inventory",<br>&nbsp;&nbsp;"gs2_simple_inventory",<br>&nbsp;&nbsp;"gs2_dictionary"<br>}<br> |  | ✓ |  |  | Property Type<br>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."gs2_inventory": GS2-Inventory::ItemSet / "gs2_simple_inventory": GS2-Inventory::SimpleItem / "gs2_dictionary": GS2-Dictionary::Entry /  |
| body | string |  |  |  |  ~ 1048576 chars | Payload<br>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<br>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<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |

**Related methods:**
setForm - Save changes to a loadout preset
setPropertyForm - Save changes to a character's or item's equipment set


---

### EzConfig

Configuration

Configuration values applied to transaction variables

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64 chars | Name |
| value | string |  |  |  |  ~ 51200 chars | Value |


---

### EzAcquireAction

Acquire Action

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)<br>enum {<br>}<br> |  | ✓ |  |  | Type of Acquire Action |
| request | string |  | ✓ |  |  ~ 524288 chars | JSON string of the request used when executing the action |


---

### EzVerifyActionResult

Verify Action execution result

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)<br>enum {<br>}<br> |  | ✓ |  |  | Type of Verify Action |
| verifyRequest | string |  | ✓ |  |  ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int |  |  |  | 0 ~ 999 | Status code |
| verifyResult | string |  |  |  |  ~ 1048576 chars | Result content |


**Related models:**
EzTransactionResult - Transaction Execution Result



---

### EzConsumeActionResult

Consume Action execution result

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)<br>enum {<br>}<br> |  | ✓ |  |  | Type of Consume Action |
| consumeRequest | string |  | ✓ |  |  ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int |  |  |  | 0 ~ 999 | Status code |
| consumeResult | string |  |  |  |  ~ 1048576 chars | Result content |


**Related models:**
EzTransactionResult - Transaction Execution Result



---

### EzAcquireActionResult

Acquire Action execution result

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)<br>enum {<br>}<br> |  | ✓ |  |  | Type of Acquire Action |
| acquireRequest | string |  | ✓ |  |  ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int |  |  |  | 0 ~ 999 | Status code |
| acquireResult | string |  |  |  |  ~ 1048576 chars | Result content |


**Related models:**
EzTransactionResult - Transaction Execution Result



---

### EzTransactionResult

Transaction Execution Result

Result of a transaction executed using the server-side automatic execution feature

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string |  | ✓ |  | 36 ~ 36 chars | Transaction ID |
| verifyResults | [List&lt;EzVerifyActionResult&gt;](#ezverifyactionresult) |  |  |  | 0 ~ 10 items | List of verify action execution results |
| consumeResults | [List&lt;EzConsumeActionResult&gt;](#ezconsumeactionresult) |  |  | [] | 0 ~ 10 items | List of Consume Action execution results |
| acquireResults | [List&lt;EzAcquireActionResult&gt;](#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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| moldModelName | string |  | ✓|  |  ~ 128 chars | Form Storage Area Model name<br>Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzMoldModel](#ezmoldmodel) | Form Storage Area|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).MoldModel(
        moldModelName: "mold-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).MoldModel(
        moldModelName: "mold-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### listMoldModels

List 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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| items | [List&lt;EzMoldModel&gt;](#ezmoldmodel) | List of Form Storage Areas|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.MoldModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| moldModelName | string |  | ✓|  |  ~ 128 chars | Form Storage Area Model name<br>Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzMold](#ezmold) | Form Storage Area|
| moldModel | [EzMoldModel](#ezmoldmodel) | Form Storage Area|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldModelName: "mold-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### listMolds

List 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<br>Unique Namespace 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&lt;EzMold&gt;](#ezmold) | List of Form Storage Area|
| nextPageToken | string | Page token to retrieve the rest of the listing|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.MoldsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| moldModelName | string |  | ✓|  |  ~ 128 chars | Form Storage Area Model name<br>Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzFormModel](#ezformmodel) | Form|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).MoldModel(
        moldModelName: "mold-0001"
    ).FormModel(
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).MoldModel(
        moldModelName: "mold-0001"
    ).FormModel(
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace 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<br>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](#ezform) | Form|
| mold | [EzMold](#ezmold) | Form Storage Area|
| moldModel | [EzMoldModel](#ezmoldmodel) | Form Storage Area Model|
| formModel | [EzFormModel](#ezformmodel) | Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldModelName: "mold-0001"
    ).Form(
        index: 0
    );
    var result = await domain.DeleteFormAsync(
    );

```

**Unity (Vanilla)**
```cs
    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;
    }

```

**Unreal Engine 5**
```cpp
    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<br>Unique Namespace 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<br>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](#ezform) | Form|
| mold | [EzMold](#ezmold) | Form Storage Area|
| moldModel | [EzMoldModel](#ezmoldmodel) | Form Storage Area Model|
| formModel | [EzFormModel](#ezformmodel) | Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldModelName: "mold-0001"
    ).Form(
        index: 0
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace 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<br>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](#ezform) | Form|
| body | string | Value to be signed|
| signature | string | Signature|
| mold | [EzMold](#ezmold) | Form Storage Area|
| moldModel | [EzMoldModel](#ezmoldmodel) | Form Storage Area Model|
| formModel | [EzFormModel](#ezformmodel) | Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    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;

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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

List 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<br>Unique Namespace 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&lt;EzForm&gt;](#ezform) | List of Form|
| nextPageToken | string | Page token to retrieve the rest of the listing|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Mold(
        moldModelName: "mold-0001"
    );
    var items = await domain.FormsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace 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<br>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&lt;EzSlotWithSignature&gt;](#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](#ezform) | Form|
| mold | [EzMold](#ezmold) | Form Storage Area|
| moldModel | [EzMoldModel](#ezmoldmodel) | Form Storage Area Model|
| formModel | [EzFormModel](#ezformmodel) | Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    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();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| propertyFormModelName | string |  | ✓|  |  ~ 128 chars | Property Form Model name<br>Unique Property Form Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzPropertyFormModel](#ezpropertyformmodel) | Property Form|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).PropertyFormModel(
        propertyFormModelName: "form-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).PropertyFormModel(
        propertyFormModelName: "form-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### listPropertyFormModels

List 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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| items | [List&lt;EzPropertyFormModel&gt;](#ezpropertyformmodel) | List of Property Form Model name|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.PropertyFormModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>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](#ezpropertyform) | Property Form|
| propertyFormModel | [EzPropertyFormModel](#ezpropertyformmodel) | Property Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PropertyForm(
        propertyFormModelName: "form-0001",
        propertyId: "property-0001"
    );
    var result = await domain.DeletePropertyFormAsync(
    );

```

**Unity (Vanilla)**
```cs
    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;
    }

```

**Unreal Engine 5**
```cpp
    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<br>Unique Namespace 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<br>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](#ezpropertyform) | PropertyForm|
| propertyFormModel | [EzPropertyFormModel](#ezpropertyformmodel) | Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).PropertyForm(
        propertyFormModelName: "form-0001",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace 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<br>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](#ezpropertyform) | Property Form|
| body | string | Value to be signed|
| signature | string | Signature|
| propertyFormModel | [EzPropertyFormModel](#ezpropertyformmodel) | Property Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    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;

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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

List 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<br>Unique Namespace 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&lt;EzPropertyForm&gt;](#ezpropertyform) | List of PropertyForm|
| nextPageToken | string | Page token to retrieve the rest of the listing|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.Formation.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.PropertyFormsAsync(
        propertyFormModelName: "form-0001"
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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




**Unity (UniTask)**
```csharp
    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);

```

**Unity (Vanilla)**
```cs
    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);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="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 jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### 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<br>Unique Namespace 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<br>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&lt;EzSlotWithSignature&gt;](#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](#ezpropertyform) | Property Form|
| proeprtyFormModel | [EzPropertyFormModel](#ezpropertyformmodel) | Property Form Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    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();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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();

```


---