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

# 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.<br>
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.<br>
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](https://www.lua.org/).<br>
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.<br>
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.<br>
The execution timing of scripts is broadly divided into two types.

```mermaid
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.<br>
The script's execution result can transform the request parameters, or abort the processing itself (by raising an exception).<br>
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.<br>
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.<br>
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.<br>
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.<br>
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.<br>
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.<br>
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.<br>
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.

```yaml
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.<br>
By declaring resource dependencies with `DependsOn`, you can guarantee the order so that the script is created first, then the namespace that references it.

## Detailed Reference

[GS2-Script API Reference](../../api_reference/script)