GS2-Formation Transaction Actions

Specification of verify/consume/acquire transaction actions

Combining actions, and concurrency

The background common to every service is collected in Combining Transaction Actions. Read that first; the rest of this section is what GS2-Formation adds to it.

The transaction actions of GS2-Formation address two kinds of target.

Mold: identified by the combination of namespace, user, and mold model. It holds the capacity, that is, how many forms may be held.
Form: identified by the combination of namespace, user, mold model, and index. It holds the properties set into one slot.

Operation	Repeated in one transaction	Across a nested transaction	Boundary that separates targets
Adding to and subtracting from the capacity `AddMoldCapacityByUserId` `SubMoldCapacityByUserId`	Any mix; combined and the values added up	Added up	namespace, user, mold model
Setting the capacity `SetMoldCapacityByUserId`	Combined if equal; rejected when the transaction is issued if the values differ	The value is set if both are equal; the transaction fails at run time if they differ	namespace, user, mold model
Setting a form `SetFormByUserId`	Combined if equal; rejected when the transaction is issued if the values differ	The value is set if both are equal; the transaction fails at run time if they differ	namespace, user, mold model, index
Expanding into other actions `AcquireActionsToFormProperties` `AcquireActionsToPropertyFormProperties`	Combined where the acquire action passed in is the same; differ and each runs	Does not touch the form itself	namespace, user, mold model, index, and the acquire action passed in

The capacity has to be at least one and cannot exceed the maximum of the mold model. It is judged against the total after combining, so an addition that fits on its own can still be rejected when combined with another one.

A mold and a form are separate targets, so updating the capacity and setting a form in one transaction is fine.

AcquireActionsTo...Properties does not write the form itself; it issues the acquire actions it was given as a transaction of its own. Specifying two with different acquire actions against the same form runs both. What they issue still gathers into the same transaction, so check the restrictions of the services those belong to.

Take care with nested transactions

Capacity is safe across a nested transaction: additions and subtractions are applied together as one update whichever route they arrive by.

Setting the capacity and setting a form are not. Where one of them arrives from the inside while the other is specified on the outside against the same mold or form, the transaction fails.

If you want to avoid these restrictions

Adding to and setting the capacity, and setting a form, are acquire actions; subtracting from the capacity is a consume action. Turning acquireActionUseJobQueue on clears collisions between acquire actions, but setting the capacity together with subtracting from it needs enableAtomicCommit turned off.

Concurrency and retries

Adding to and subtracting from the capacity do not conflict however many concurrent requests overlap, as long as the result stays within range.

Setting the capacity, setting a form, and changes made through the console or the server API are written with a revision check, so they may return a conflict (409) when another update to the same target overlaps. Nothing is wrong with the request, so retrying will succeed.

Consume Action

Gs2Formation:SubMoldCapacityByUserId

Subtract capacity size by User ID

Decreases the capacity of the form storage area (mold) for the specified user. The capacity will not go below 0.

Quantity specification supported: YES

Reversible action: YES

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
moldModelName	string	✓	~ 128 chars	Form Storage Area Model name Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
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.
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:SubMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "moldModelName": "[string]Form Storage Area Model name",
        "capacity": "[int]Current Capacity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:SubMoldCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  moldModelName: "[string]Form Storage Area Model name"
  capacity: "[int]Current Capacity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").consume.sub_mold_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    moldModelName="[string]Form Storage Area Model name",
    capacity="[int]Current Capacity",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Formation:AddMoldCapacityByUserId

Add capacity size by User ID

Increases the capacity of the form storage area (mold) for the specified user. The capacity cannot exceed the maxCapacity defined in the Mold Model.

Quantity specification supported: YES

Reversible action: YES

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
moldModelName	string	✓	~ 128 chars	Form Storage Area Model name Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
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.
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:AddMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "moldModelName": "[string]Form Storage Area Model name",
        "capacity": "[int]Current Capacity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:AddMoldCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  moldModelName: "[string]Form Storage Area Model name"
  capacity: "[int]Current Capacity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").acquire.add_mold_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    moldModelName="[string]Form Storage Area Model name",
    capacity="[int]Current Capacity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Formation:SetMoldCapacityByUserId

Set capacity size with specified user ID

Directly sets the capacity of the form storage area (mold) for the specified user to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated mold. The capacity is capped at the maxCapacity defined in the Mold Model.

Quantity specification supported: YES

Reversible action: NO

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
moldModelName	string	✓	~ 128 chars	Form Storage Area Model name Unique Form Storage Area Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
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.
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:SetMoldCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "moldModelName": "[string]Form Storage Area Model name",
        "capacity": "[int]Current Capacity",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:SetMoldCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  moldModelName: "[string]Form Storage Area Model name"
  capacity: "[int]Current Capacity"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").acquire.set_mold_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    moldModelName="[string]Form Storage Area Model name",
    capacity="[int]Current Capacity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Formation:AcquireActionsToFormProperties

Apply acquire action to Form Properties by User ID

Applies an acquire action to the form’s slot properties and starts a transaction to execute it. This is used to grant items or resources to the slots of a form, with optional config parameters for customization. Returns a transaction for transaction processing.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
moldModelName	string	✓		~ 128 chars	Form Storage Area Model name
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”.
acquireAction	AcquireAction	✓			Get action to be applied to form properties
config	List<Config>		[]	0 ~ 1000 items	List of Acquisition config
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:AcquireActionsToFormProperties",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "moldModelName": "[string]Form Storage Area Model name",
        "index": "[int]Index of form",
        "acquireAction": {
            "action": "[string]Type of Acquire Action",
            "request": "[string]JSON string of the request used when executing the action"
        },
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:AcquireActionsToFormProperties
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  moldModelName: "[string]Form Storage Area Model name"
  index: "[int]Index of form"
  acquireAction: 
    action: "[string]Type of Acquire Action"
    request: "[string]JSON string of the request used when executing the action"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").acquire.acquire_actions_to_form_properties({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    moldModelName="[string]Form Storage Area Model name",
    index="[int]Index of form",
    acquireAction={
        action="[string]Type of Acquire Action",
        request="[string]JSON string of the request used when executing the action"
    },
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Formation:SetFormByUserId

Set form by User ID

Updates the slot values of a form for the specified user.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓	~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
moldModelName	string	✓	~ 128 chars	Form Storage Area Model name
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<Slot>	✓	1 ~ 10 items	List of Slots
timeOffsetToken	string		~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:SetFormByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "moldModelName": "[string]Form Storage Area Model name",
        "index": "[int]Index of form",
        "slots": [
            {
                "name": "[string]Slot Model name",
                "propertyId": "[string]Property ID",
                "metadata": "[string]Metadata"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:SetFormByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  moldModelName: "[string]Form Storage Area Model name"
  index: "[int]Index of form"
  slots: 
    - name: "[string]Slot Model name"
      propertyId: "[string]Property ID"
      metadata: "[string]Metadata"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").acquire.set_form_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    moldModelName="[string]Form Storage Area Model name",
    index="[int]Index of form",
    slots={
        {
            name="[string]Slot Model name",
            propertyId="[string]Property ID",
            metadata="[string]Metadata"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Formation:AcquireActionsToPropertyFormProperties

Apply acquire action to property form properties

Applies an acquire action to the properties of a property form, initiating a transaction. This is used to grant items or resources that are then set as slot values in the property form. The acquire action is executed as a transaction, and the resulting items are applied to the form’s slot properties. Configuration values can be passed to customize the acquire action behavior.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
propertyFormModelName	string	✓		~ 128 chars	Property Form Model name
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.
acquireAction	AcquireAction	✓			Get action to be applied to form properties
config	List<Config>		[]	0 ~ 1000 items	List of Acquisition config
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Formation:AcquireActionsToPropertyFormProperties",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "propertyFormModelName": "[string]Property Form Model name",
        "propertyId": "[string]Property ID",
        "acquireAction": {
            "action": "[string]Type of Acquire Action",
            "request": "[string]JSON string of the request used when executing the action"
        },
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Formation:AcquireActionsToPropertyFormProperties
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  propertyFormModelName: "[string]Property Form Model name"
  propertyId: "[string]Property ID"
  acquireAction: 
    action: "[string]Type of Acquire Action"
    request: "[string]JSON string of the request used when executing the action"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("formation").acquire.acquire_actions_to_property_form_properties({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    propertyFormModelName="[string]Property Form Model name",
    propertyId="[string]Property ID",
    acquireAction={
        action="[string]Type of Acquire Action",
        request="[string]JSON string of the request used when executing the action"
    },
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})