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

# GS2-Script

Lua 스크립트 실행 환경




GS2-Script는 GS2의 각 마이크로서비스 이벤트에 맞춰 서버 사이드에서 커스텀 로직을 실행하기 위한, Lua 기반의 스크립트 실행 환경입니다.

GS2의 각 마이크로서비스에는 특정 API 호출 전후에 스크립트를 실행하는 《스크립트 트리거》라는 구조가 마련되어 있습니다.<br>
여기에 GS2-Script로 작성한 스크립트를 연결함으로써, 각 서비스의 표준 기능으로는 실현할 수 없는 게임 고유의 검증 로직이나 데이터 가공 처리, 외부 시스템 연동 등을 서버 측에서 동작시킬 수 있습니다.

클라이언트 측 로직은 변조의 위험이 있기 때문에, 부정 방지나 감사 관점에서 중요한 처리는 서버 측에서 동작시키고 싶은 경우가 많습니다.<br>
GS2-Script를 사용하면 GS2의 완전관리형 환경 안에서 그러한 서버 로직을 작성·운용할 수 있습니다.

## Lua 스크립트

스크립트 작성 언어로는 [Lua](https://www.lua.org/)를 채택하고 있습니다.<br>
Lua는 게임 업계에서 채택 실적이 풍부한 경량 스크립트 언어로, 단순한 문법과 빠른 실행 성능을 갖추고 있습니다.

스크립트 등록은 문자열을 직접 업로드하는 방법과, GitHub 저장소와 연동하여 파일을 가져오는 방법 두 가지 모두를 이용할 수 있습니다.<br>
GitHub 연동을 이용하면, 스크립트의 변경 이력을 Git으로 관리하고 Pull Request 기반의 리뷰·운용이 가능해집니다.

## 스크립트 트리거

각 마이크로서비스의 네임스페이스 설정에서, 특정 API 처리 전후에 실행할 스크립트를 지정할 수 있습니다.<br>
스크립트 실행 타이밍은 크게 두 가지로 나뉩니다.

```mermaid
graph LR
  Request["API 요청"] --> Pre["전처리 스크립트<br/>(동기 실행)"]
  Pre --> Process["GS2 표준 처리"]
  Process --> Done["완료 통지 스크립트<br/>(비동기 실행)"]
  Process --> Response["API 응답"]
```

### 전처리 스크립트 (동기 실행)

API 처리 실행 직전에 동기적으로 실행되는 스크립트입니다.<br>
스크립트 실행 결과에 따라 요청 파라미터를 변환하거나, 처리 자체를 중단(예외 발생)시킬 수 있습니다.<br>
응답 시간에는 영향을 미치지만, 요청 내용을 서버 측에서 동적으로 판정·변경하고 싶은 경우에 유용합니다.

예: GS2-Account의 `createAccountScript`의 `triggerScriptId`를 설정하면, 계정 생성 API 실행 전에 스크립트가 실행되어, 특정 조건 하에서는 생성을 거부하는 등의 제어를 할 수 있습니다.

### 완료 통지 스크립트 (비동기 실행)

API 처리 완료 후 비동기로 실행되는 스크립트입니다.<br>
응답 시간에는 영향을 미치지 않으며, 로그 출력·통계 기록·외부 서비스 연동 등을 안전하게 수행할 수 있습니다.

예: GS2-Account의 `createAccountScript`의 `doneTriggerScriptId`를 설정하면, 계정 생성이 성공한 후에 스크립트가 실행되어, 외부 분석 기반에 신규 사용자 생성 이벤트를 전송하는 등의 용도로 이용할 수 있습니다.

## 스크립트 실행 모델

스크립트 실행에는 표준으로 시간 제한이 설정되어 있어, 지나치게 긴 스크립트는 오류가 됩니다.<br>
스크립트 실행 시간은 응답에 포함되며, 실행 비용으로 집계됩니다.

스크립트 내에서 발생한 예외는 API 호출 전체의 예외로 전파되며, 전처리 스크립트에서 예외가 발생한 경우 GS2 표준 처리는 실행되지 않습니다.

## 스크립트에서의 GS2 API 접근

스크립트 내에서는 GS2가 제공하는 API 그룹을 그대로 호출할 수 있습니다.<br>
GS2-Inventory의 아이템 수를 확인한 후 GS2-Account의 처리를 수행하거나, GS2-Stamina의 잔량을 보고 GS2-Mission의 달성 판정을 하는 등, 여러 마이크로서비스를 넘나드는 로직을 스크립트 내에서 구성할 수 있습니다.

스크립트 실행 컨텍스트에는 API를 호출한 사용자의 액세스 토큰 등도 전달되므로, 인증된 플레이어의 컨텍스트에서 서버 API를 호출할 수 있습니다.

## Amazon EventBridge 연동

완료 통지의 전송 대상으로, GS2-Script의 스크립트 대신 Amazon EventBridge를 지정할 수도 있습니다.<br>
EventBridge에 이벤트를 전송함으로써, AWS Lambda 등의 AWS 서비스나 SaaS의 이벤트 기반 워크플로우에 GS2의 이벤트를 연동할 수 있어, 게임 외부 시스템과의 통합이 용이해집니다.

GS2 내에서 완결되는 처리는 GS2-Script로, 외부 시스템과의 광범위한 연동은 EventBridge로 구분해서 사용함으로써, 단순하면서도 확장 가능한 운용이 가능합니다.

## 마스터 데이터 관리

GS2-Script에는 마스터 데이터라는 개념이 없으며, 스크립트 자체가 구성 데이터로 관리됩니다.<br>
스크립트 등록·갱신은 관리 콘솔에서 직접 수행하는 것 외에도, GS2-Deploy의 템플릿(`Type: GS2::Script::Script`)으로 작성하여 CI에서 자동으로 반영하는 워크플로우도 가능합니다.

## 트랜잭션 액션

GS2-Script에서는 트랜잭션 액션을 제공하지 않습니다.<br>
스크립트 내에서 GS2 API를 호출함으로써, 간접적으로 각 마이크로서비스의 트랜잭션을 발생시키는 것은 가능합니다.

## 구현 예제

GS2-Script는 관리 API 중심의 마이크로서비스입니다. 게임 엔진용 SDK(Unity / Unreal Engine / Godot)에는 전용 Domain 클래스가 제공되지 않습니다.

스크립트의 등록·갱신·실행은 서버 측 및 네임스페이스 구성에 관련된 조작이므로, 게임 클라이언트에서 직접 호출하지 말고 다음 중 하나의 수단으로 조작할 것을 권장합니다.

- 관리 콘솔
- GS2 CLI
- 각 언어용 일반 SDK(C# / Go / Python / TypeScript / PHP / Java)
- GS2-Deploy를 이용한 템플릿 관리

각 SDK의 상세 내용은 해당 레퍼런스 페이지를 참조해 주세요.

### 마이크로서비스에 스크립트 연결

스크립트를 각 마이크로서비스의 이벤트 트리거에 연결하는 경우에는, 대상 서비스의 네임스페이스 설정에서 참조합니다.<br>
실제 운용에서는 관리 콘솔에서 직접 설정하거나, GS2-Deploy의 템플릿에 작성함으로써, 스크립트 연결까지 포함하여 CI/CD로 관리할 수 있습니다.

다음은 GS2-Account의 `CreateAccountScript`에 "계정 생성 전"(`TriggerScriptId`)과 "계정 생성 완료 통지"(`DoneTriggerScriptId`) 스크립트를 설정하는 예입니다.

```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
```

스크립트는 사전에 등록해 두고, 네임스페이스 측에서는 GRN으로 참조합니다.<br>
`DependsOn`으로 리소스 간의 의존 관계를 선언함으로써, 스크립트를 먼저 생성한 후 그것을 참조하는 네임스페이스를 생성하는 순서를 보장할 수 있습니다.

## 상세 레퍼런스

[GS2-Script API 레퍼런스](../../api_reference/script)