GS2-Script

Lua script execution environment

GS2-Script is a Lua-based script execution environment that runs custom logic on the server side in response to events from GS2 microservices.

Each GS2 microservice provides a mechanism called “script triggers” that runs a script before or after a specific API call.
By linking scripts written with GS2-Script to these triggers, you can execute on the server side game-specific validation logic, data processing, and external system integration that cannot be achieved with the standard features of each service.

Because client-side logic is at risk of tampering, in many cases you want fraud prevention and audit-critical processing to run on the server side.
With GS2-Script, you can write and operate such server logic within the GS2 fully-managed environment.

Lua scripts

The language used to write scripts is Lua.
Lua is a lightweight scripting language with a strong track record in the game industry, with simple syntax and high execution performance.

Scripts can be registered either by directly uploading a string, or by retrieving files via integration with a GitHub repository.
By using GitHub integration, you can manage script change history in Git and operate with pull request-based review.

Script triggers

In the namespace settings of each microservice, you can specify scripts to be run before or after specific API processing.
The execution timing of scripts is broadly divided into two types.

graph LR
  Request["API Request"] --> Pre["Pre-processing Script<br/>(Synchronous)"]
  Pre --> Process["GS2 Standard Processing"]
  Process --> Done["Completion Notification Script<br/>(Asynchronous)"]
  Process --> Response["API Response"]

Pre-processing script (synchronous execution)

A script that is executed synchronously immediately before the API processing.
The script’s execution result can transform the request parameters, or abort the processing itself (by raising an exception).
While this affects response time, it is useful when you want to dynamically determine or modify request content on the server side.

Example: Setting triggerScriptId of GS2-Account’s createAccountScript causes the script to run before the account creation API, allowing control such as rejecting creation under specific conditions.

Completion notification script (asynchronous execution)

A script that is executed asynchronously after the API processing has completed.
It does not affect response time, and can safely perform logging, statistics collection, and external service integration.

Example: Setting doneTriggerScriptId of GS2-Account’s createAccountScript causes the script to run after account creation succeeds, which can be used for purposes such as sending a new user creation event to an external analytics platform.

Script execution model

Script execution has a time limit set by default, and overly long scripts result in errors.
Script execution time is included in the response and tallied as execution cost.

Exceptions raised within a script propagate as exceptions of the entire API call. If an exception occurs in a pre-processing script, the GS2 standard processing is not executed.

Calling GS2 APIs from scripts

GS2 APIs can be called directly from within scripts.
You can compose logic that spans multiple microservices within a script, such as checking item counts in GS2-Inventory before processing in GS2-Account, or checking remaining stamina in GS2-Stamina before determining a mission achievement in GS2-Mission.

The script execution context also receives the access token of the user who initiated the API call, allowing server APIs to be called in the context of an authenticated player.

Amazon EventBridge Integration

Amazon EventBridge can be specified as the destination for completion notifications instead of a GS2-Script script.
By sending events to EventBridge, GS2 events can be integrated with AWS services such as AWS Lambda, or with SaaS event-driven workflows, making it easy to integrate with external systems.

By using GS2-Script for processing that completes within GS2 and EventBridge for broader integration with external systems, you can achieve simple and scalable operation.

Master Data Management

GS2-Script does not have the concept of master data; the scripts themselves are managed as configuration data.
Scripts can be registered and updated directly from the management console, or written as GS2-Deploy templates (Type: GS2::Script::Script) for a workflow that automatically applies them from CI.

Transaction Actions

GS2-Script does not provide transaction actions.
However, by calling GS2 APIs from within scripts, you can indirectly trigger transactions of each microservice.

Example Implementation

GS2-Script is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine).

Because script registration, updates, and execution involve server-side and namespace configuration operations, instead of calling them directly from the game client, we recommend operating via one of the following means.

Management console
GS2 CLI
General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java)
Template management via GS2-Deploy

For details on each SDK, see the corresponding reference page.

Linking scripts to microservices

When linking a script to an event trigger of a microservice, the target service’s namespace settings reference it.
In practice, you either configure it directly from the management console, or describe it in a GS2-Deploy template to manage the script linking via CI/CD.

Below is an example of setting up scripts for both “before account creation” (TriggerScriptId) and “account creation completion notification” (DoneTriggerScriptId) in CreateAccountScript of GS2-Account.

GS2TemplateFormatVersion: "2019-05-01"
Resources:
  Script:
    Type: GS2::Script::Script
    Properties:
      NamespaceName: namespace-0001
      Name: createAccount
      Script: |
        local result = { permit = true }
        return result

  AccountNamespace:
    Type: GS2::Account::Namespace
    Properties:
      Name: account-namespace
      CreateAccountScript:
        TriggerScriptId: !GetAttr Script.Item.ScriptId
        DoneTriggerTargetType: gs2_script
        DoneTriggerScriptId: !GetAttr Script.Item.ScriptId
    DependsOn:
      - Script

The script is registered in advance, and the namespace references it by GRN.
By declaring resource dependencies with DependsOn, you can guarantee the order so that the script is created first, then the namespace that references it.