GS2-Script 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-Script adds to it.

GS2-Script provides one transaction action. GS2-Script keeps no per-user state of its own, so this action never collides with another one because of GS2-Script. What it may collide with is decided entirely by what the script does.

Operation	Repeated in one transaction	Across a nested transaction	Boundary that separates targets
Running a script `InvokeScript`	Not combined; each run stands on its own	Not combined; each run stands on its own	(every run is independent)

Every run happens, even when two runs match in the script, the user, the arguments, and the random seed. With acquireActionUseJobQueue turned on, runs that match completely may still be combined into one.

The restrictions come from what the script does

Whatever a script writes lands in the transaction that invoked it, so the restrictions of the services it touches apply as if you had specified those actions yourself. Two runs that both add to the same wallet, or both rewrite the same dictionary, run into exactly the same limits as two such actions written side by side.

Where a resource is touched only by that script within the transaction, none of this matters. What needs care is a resource that an action specified directly on the transaction, or another script, also touches.

Where a script issues a transaction of its own, it becomes nested and the section below applies.

Take care with nested transactions

Updates arriving from an inner transaction fall outside the actions specified directly on the outer one. A script that writes to a resource the outer transaction also writes to therefore makes the transaction fail, in the cases where that resource does not allow two writes.

Where a transaction contains a script, read that script as part of the transaction too.

If you want to avoid these restrictions

Running a script is an acquire action, so turning acquireActionUseJobQueue on separates it from the other acquire actions. Turning enableAtomicCommit off stops the script and the other actions from gathering into one write.

Concurrency and retries

GS2-Script itself never returns a conflict. Whether a run conflicts with a concurrent request is decided by what the script writes, and the retry guidance of those services applies.

Acquire Action

Gs2Script:InvokeScript

Execute the script

Synchronously executes the specified Lua script with the provided JSON arguments. Returns the execution result including status code, return value, transaction information, random number state, execution time, and standard output. Supports transaction handling for atomic operations across GS2 services.

Quantity specification supported: NO

Reversible action: NO

	Type	Required	Default	Value Limits	Description
scriptId	string	✓		~ 1024 chars	Script GRN
userId	string			~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
args	string		“{}”	~ 5242880 chars	Arguments (JSON Format)
randomStatus	RandomStatus				Random number status
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Script:InvokeScript",
    "request": {
        "scriptId": "[string]Script GRN",
        "userId": "[string]User ID",
        "args": "[string]Arguments (JSON Format)",
        "randomStatus": {
            "seed": "[long]Random Seed",
            "used": [
                {
                    "category": "[long]Category",
                    "used": "[long]Used Count"
                }
            ]
        },
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Script:InvokeScript
request:
  scriptId: "[string]Script GRN"
  userId: "[string]User ID"
  args: "[string]Arguments (JSON Format)"
  randomStatus: 
    seed: "[long]Random Seed"
    used: 
    - category: "[long]Category"
      used: "[long]Used Count"
  timeOffsetToken: "[string]Time offset token"

transaction.service("script").acquire.invoke_script({
    scriptId="[string]Script GRN",
    userId="[string]User ID",
    args="[string]Arguments (JSON Format)",
    randomStatus={
        seed="[long]Random Seed",
        used={
                {
                    category="[long]Category",
                    used="[long]Used Count"
                }
            }
    },
    timeOffsetToken="[string]Time offset token",
})