Documentation index for AI agents

GS2-Script

Lua 스크립트 실행 환경

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

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

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

Lua 스크립트

스크립트 작성 언어로는 Lua를 채택하고 있습니다.
Lua는 게임 업계에서 채택 실적이 풍부한 경량 스크립트 언어로, 단순한 문법과 빠른 실행 성능을 갖추고 있습니다.

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

스크립트 트리거

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

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

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

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

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

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

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

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

스크립트 실행 모델

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

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

스크립트에서의 GS2 API 접근

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

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

Amazon EventBridge 연동

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

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

마스터 데이터 관리

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

트랜잭션 액션

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

구현 예제

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

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

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

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

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

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

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

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으로 참조합니다.
DependsOn으로 리소스 간의 의존 관계를 선언함으로써, 스크립트를 먼저 생성한 후 그것을 참조하는 네임스페이스를 생성하는 순서를 보장할 수 있습니다.

상세 레퍼런스

GS2-Script API 레퍼런스