마이크로서비스 소개 on Game Server Services | Docs

GS2-Account

Mon, 01 Jan 0001 00:00:00 +0000

Game Server Services가 제공하는 계정 시스템은 “익명 계정"이라는 종류의 계정 시스템입니다. 일본에서는 널리 사용되는 방식이지만, 많은 지역에서는 낯설게 느껴지는 계정 시스템일 수 있습니다.

그러나 이 계정 시스템은 게임에 있어서 매우 이치에 맞는 계정 시스템입니다.

익명 계정이란 무엇인가요?

일반적으로 떠올리는 계정 관리는 로그인ID가 있고 비밀번호가 있는 방식일 것입니다. 익명 계정도 그 점은 다르지 않습니다.

그러나 로그인ID와 비밀번호가 모두 시스템에 의해 무작위로 결정된다는 것이 가장 큰 특징입니다.

시스템에서 발급한 로그인ID·비밀번호를 디바이스의 로컬 스토리지에 저장해 두고, 두 번째 이후에는 그 정보를 이용해 로그인함으로써 게임을 재개할 수 있습니다.

GS2-AdReward

Mon, 01 Jan 0001 00:00:00 +0000

모바일 게임의 수익화 방법으로 플레이어에게 광고를 시청하게 하고 광고 플랫폼으로부터 보상을 받는 방식도 일반화되었습니다. 광고가 정상적으로 시청되었을 때 광고 플랫폼으로부터 서버 간 연동으로 통지를 받아 GS2에 보상을 지급함으로써 부정행위를 방지할 수 있습니다.

클라이언트 측 콜백만으로 보상을 지급하는 설계에서는 변조된 SDK를 사용한 부정행위가 발생할 위험이 있습니다. GS2-AdReward는 광고 플랫폼에서 GS2로의 직접적인 Server-to-Server(S2S) 통지를 통해 신뢰할 수 있는 시청 완료 이벤트를 계기로 보상을 발행하는 구조를 제공합니다.

시청 포인트

일반적으로 GS2에서는 대가와 보상을 설정하여 리소스 교환을 수행하지만, 서버 간 통신의 사양이 광고 플랫폼마다 다르고 데이터의 세분화 정도도 다르기 때문에 GS2-AdReward에서는 광고 시청이 확인되었을 때 《시청 포인트》를 1포인트 가산하도록 되어 있습니다.

GS2-Buff

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Buff는 GS2가 제공하는 마이크로서비스의 대가와 보상, 사용자 데이터 최대값의 보정을 일원화하여 관리하는 기능을 제공합니다. 기간 한정으로 보상을 증가시키는 기능이나, 구독 계약 상태라면 사용자 데이터의 최대값이 증가하는 기능을 구현할 때 활용할 수 있습니다.

GS2-Buff는 다른 마이크로서비스를 직접 수정하는 것이 아니라, API 호출 시 전달되는 “컨텍스트 스택"이라는 메타 정보를 통해 각 마이크로서비스에 보정값을 전파합니다. 따라서 버프의 내용이나 기간을 변경하더라도 각 마이크로서비스의 마스터 데이터나 플레이어 데이터를 전혀 수정하지 않고도 적용·해제가 가능하다는 점이 큰 특징입니다.

GS2-Chat

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Chat 을 이용하면 게임 내에 텍스트 채팅을 손쉽게 구현할 수 있습니다. 텍스트 채팅은 새로운 메시지를 감지하기 위해 상시 접속 세션이 필요하며, 서버에 요구되는 요건도 복잡해집니다.

Game Server Services 를 이용하면 그러한 번거로운 상시 접속 세션 관리로부터 해방될 수 있습니다.

룸

GS2-Chat 을 이용하려면 먼저 룸을 생성해야 합니다. 룸은 플레이어가 자유롭게 생성할 수 있도록 할 수도 있고, 개발 측에서 준비한 룸을 플레이어가 사용하게 할 수도 있습니다. 또한 게시할 수 있는 사용자ID의 화이트리스트를 설정하여 특정 멤버 전용 룸을 구성하는 것도 가능합니다.

GS2-Datastore

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Datastore를 이용하면 임의의 바이너리 데이터를 서버에 저장할 수 있습니다.

업로드한 데이터에는 접근 권한을 설정할 수 있으며, public(전체 공개), protected(지정한 사용자ID에게만 공개: 최대 100건), private(본인에게만 공개) 중에서 선택합니다.

GS2-Datastore는 UGC나 레이싱 게임의 고스트 데이터와 같은 데이터를 업로드하는 것을 주된 목적으로 하며, 플레이어의 사용자 데이터를 저장하는 데에는 반드시 적합하다고 할 수 없습니다.

왜냐하면 소지품의 소지 수량을 바이너리 데이터로 저장할 경우, 세이브 데이터나 앱 본체의 변조로 아이템을 복제하거나 입수량을 부정하게 늘린 개조 앱으로 플레이하는 것을 허용하게 되기 때문입니다. 소지품의 소지 수량이라면 GS2-Inventory와 같은 전용 마이크로서비스를 이용함으로써 이러한 부정 행위를 막을 수 있습니다.

GS2-Deploy

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Deploy는 GS2의 각 마이크로서비스의 네임스페이스나 마스터 데이터를 코드로 관리하고, 선언적으로 프로비저닝하기 위한 기능을 제공합니다.
AWS의 CloudFormation과 유사한 사상으로 설계되어 있으며, 템플릿 파일에 기술한 리소스 정의를 바탕으로 여러 마이크로서비스에 걸친 환경 구축·갱신·삭제를 하나의 단위(스택)로 다룰 수 있습니다.

게임 개발에서는 마스터 데이터 조정이나 네임스페이스 구성 변경이 빈번하게 발생합니다.
GS2-Deploy를 활용함으로써 이러한 변경 사항을 Git으로 관리하고, GitHub 등의 저장소와 연동한 CI/CD 파이프라인에서 자동으로 배포하는 운영이 가능해집니다.

스택 (Stack)

스택은 GS2의 리소스를 묶어서 관리하는 단위입니다.

GS2-Dictionary

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Dictionary 에서는 게임 내에서 입수한 아이템이나 캐릭터의 도감 기능을 구현합니다.

기본적으로 GS2-Inventory 의 단순화된 구현 버전이라고 생각하시면 되며, 입수 완료/미입수라는 2값의 소지 상태를 관리할 수 있습니다.

도감 이외의 용도로도 사용할 수 있습니다. 예를 들어 아바타 파츠의 소지 상태가 좋은 예입니다. 아바타 파츠를 가지고 있는지 여부는 파츠별로 2값으로 상태를 관리할 수 있으면 충분하므로 GS2-Dictionary 에 적합합니다. 그 외에도 완료된 튜토리얼 단계 관리, 해금된 컷신 관리, 해금된 BGM 목록 등 2값 상태로 표현할 수 있는 요소 전반에 활용할 수 있습니다.

GS2-Distributor

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Distributor 는 GS2 의 각 마이크로서비스를 넘나드는 트랜잭션 처리를 실현하기 위한 핵심 서비스입니다. 플레이어의 “아이템을 소비하여 보상을 얻는다”, “스태미나를 소비하여 퀘스트를 시작한다” 와 같은, 여러 마이크로서비스를 넘나드는 일련의 처리를 안전하게 실행하기 위한 기반을 제공합니다.

GS2 에서는 플레이어에게 불이익이 되는 조작을 《소비 액션》, 이익이 되는 조작을 《입수 액션》이라고 부릅니다.
GS2-Distributor 는 이러한 액션들을 모은 《트랜잭션》을 받아, 적절한 마이크로서비스로 전달·실행함으로써 게임 사이클을 구성하는 모든 처리를 일관된 형태로 다룰 수 있게 합니다.

트랜잭션의 구조에 대한 자세한 내용은 트랜잭션 을 참조하세요.

GS2-Enchant

Mon, 01 Jan 0001 00:00:00 +0000

장비나 캐릭터에 고유한 랜덤 파라미터를 부여하는 기능을 구현합니다. RPG에서의 무기 추가 스탯, 가챠로 입수한 카드에 부여되는 개체값, 핵앤슬래시 계열에서의 장비 추가 효과 등, “같은 아이템이라도 개체마다 성능이 다르다"는 표현을 구현할 때 활용할 수 있습니다.

랜덤 파라미터에는 2가지 종류를 준비하고 있습니다.

밸런스 파라미터
레어리티 파라미터

graph TD
  Item["장비·캐릭터 등<br/>(propertyId 로 식별)"] --> Choose{파라미터 종류}
  Choose -- 총량을 분배 --> Balance["밸런스 파라미터<br/>예: 공격력60/방어력40"]
  Choose -- 확률로 복수 부여 --> Rarity["레어리티 파라미터<br/>예: 크리티컬율+5%, HP+100"]
  Balance --> ReDraw1["재추첨 / 값 직접 설정"]
  Rarity --> ReDraw2["재추첨 / 추가 / 값 직접 설정"]

랜덤 파라미터는 “대상 아이템의 식별자"가 되는 propertyId를 키로 하여 관리됩니다. propertyId에는 GS2-Inventory의 아이템 인스턴스ID나 GS2-Formation의 폼 식별자 등을 지정함으로써, 장비 개체마다 파라미터를 연결할 수 있습니다.

GS2-Enhance

Mon, 01 Jan 0001 00:00:00 +0000

이 기능은 개발자에 따라서는 전혀 이해가 안 될 수도 있는 기능일 것입니다.

하지만 일본을 비롯한 모바일 게임의 사실상 표준 게임 시스템에는 반드시 존재하는 기능입니다. 이 게임 메커니즘 자체는 Game as a Service를 실현하는 데 유용한 지식이 될 것이므로, 이해가 어려운 개발자를 위해 게임 메커니즘에 대한 해설을 추가합니다.

강화 기능의 게임 메커니즘에 대해 충분한 지식이 있는 경우에는 이어지는 해설 섹션은 건너뛰어도 무방합니다.

강화 기능의 게임 메커니즘

강화 기능 자체는 매우 단순한 게임 시스템으로, 소재 아이템을 소비함으로써 대상의 경험치를 가산할 수 있는 구조입니다. 배틀에 참가해 경험치를 얻는 방법뿐만 아니라, 다양한 방법으로 캐릭터나 장비를 육성할 수 있게 되어 있습니다. (장비에도 레벨이 있습니다)

GS2-Exchange

Mon, 01 Jan 0001 00:00:00 +0000

GS2 가 제공하는 마이크로서비스 중에서도 특히 널리 사용되고 있는 기능입니다. 모든 마이크로서비스의 리소스를 전혀 다른 마이크로서비스의 리소스로 변환하는 역할을 담당합니다.

게임 사양에는 리소스 교환에 관한 것이 다수 존재하며, 그때마다 GS2-Exchange 가 활약하게 됩니다.

리소스 교환의 예

강화 소재 변환

GS2-Inventory 로 관리하는 ★1 강화 소재 10개를, 마찬가지로 GS2-Inventory 로 관리하는 ★2 강화 소재 1개와 교환

6시간에 1회 아이템을 입수할 수 있다

GS2-Stamina 로 관리하는 6시간마다 1 회복하는 스태미나 1을, GS2-Inventory 로 관리하는 아이템과 교환

GS2-Experience

Mon, 01 Jan 0001 00:00:00 +0000

Game as a Service 에서 성장 요소는 필수 불가결합니다. 캐릭터를 성장시키고, 성장한 캐릭터로 더욱 높은 난이도의 콘텐츠에 도전하는 게임 사이클을 구현하기 위한 경험치·랭크 기능을 제공합니다.

GS2-Experience 는 단일 캐릭터의 레벨뿐만 아니라, 여러 프로퍼티(캐릭터, 무기, 파티, 길드 등)의 성장을 하나의 마이크로서비스로 일원 관리할 수 있는 유연한 설계로 되어 있습니다.

유스케이스

GS2-Experience 가 상정하는 대표적인 유스케이스는 다음과 같습니다.

플레이어 캐릭터의 레벨 관리
육성 가능한 장비품의 레벨 관리
길드나 팀의 랭크 관리
칭호·배틀 패스의 레벨 관리
스킬 트리의 각 스킬 숙련도 관리

graph LR
  Player[플레이어] -->|경험치 가산| Exp[GS2-Experience]
  Exp -->|랭크 계산| Status[Status]
  Status -->|임계값 초과| RankUp[랭크업]
  RankUp -->|보상 지급| Inventory[GS2-Inventory]
  RankUp -->|스태미나 최대값 갱신| Stamina[GS2-Stamina]

랭크

GS2-Experience 는 경험치 값으로부터 자동으로 랭크 값을 계산합니다. 이를 위해서는 마스터 데이터를 이용해 랭크업 임계값이 되는 경험치 테이블을 정의해야 합니다. Experience Model 에서 랭크업 임계값을 관리하며, 그 아래에 임의의 값을 가지는 프로퍼티ID 를 종속시킬 수 있습니다. 프로퍼티ID 별로 경험치 값이 관리되고, 경험치 값에 따라 랭크가 결정됩니다.

GS2-Formation

Mon, 01 Jan 0001 00:00:00 +0000

소유하고 있는 리소스를 조합하여 하나의 무언가를 편성한다는 사양은 일반적입니다. 여러 캐릭터를 편성하여 파티를 만들거나, 무기·방어구 같은 아이템을 편성하여 장착하는 것 등이 그 예입니다.

GS2-Formation은 “어떤 슬롯이 존재하는지”, “각 슬롯에 무엇을 장착할 수 있는지”, “같은 종류의 편성을 몇 개까지 보유할 수 있는지"를 마스터 데이터로 정의하고, 플레이어별 편성 내용을 관리하는 마이크로서비스입니다.

용어

graph LR
  MoldModel --> FormModel
  FormModel --> SlotModel
  PropertyFormModel --> SlotModel2[SlotModel]

  Mold --> Form
  Form --> Slot
  PropertyForm --> Slot2[Slot]

용어	설명
`MoldModel`	같은 종류의 편성(파티·장비 세트 등)을 여러 개 보유하기 위한 타입. 용량(저장 슬롯)의 개념을 가짐
`FormModel`	Mold에 연결된 Form의 구성 정의. 어떤 슬롯을 가지는지를 정의
`PropertyFormModel`	프로퍼티ID로 참조하는 단독 편성 정의. Mold를 거치지 않고 캐릭터 1개당 편성 1개와 같은 형태로 사용
`SlotModel`	슬롯의 정의. 슬롯에 장착 가능한 프로퍼티를 정규 표현식으로 제한할 수 있음
`Mold`	플레이어별 Mold 실체. `capacity`를 가지며 최대 용량까지 Form을 생성할 수 있음
`Form`	Mold 내의 편성 인스턴스. `index`로 식별됨
`PropertyForm`	프로퍼티ID 단위의 편성 인스턴스
`Slot`	플레이어가 실제로 장착하고 있는 리소스를 보유

폼

캐릭터의 장비 기능을 구현할 때 무기·투구·건틀릿·상의·하의·신발 같은 여러 슬롯을 준비하고, 각 슬롯에 적합한 아이템만 장착할 수 있도록 설정할 수 있습니다.

GS2-Freeze

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Freeze 는 게임에서 이용하는 GS2 마이크로서비스의 버전을 임의의 시점에 고정(freeze)하고, 운영 측이 관리하는 시점에 버전을 업데이트할 수 있도록 하기 위한 기능입니다.

일반적으로 GS2 의 마이크로서비스는 지속적으로 버전 업이 이루어지며, 게임은 항상 최신 버전의 API 를 이용하게 됩니다. 대부분의 타이틀에서는 이러한 운용에 문제가 없지만, 출시 직후의 대규모 타이틀이나 장기간에 걸쳐 안정성을 최우선으로 하고 싶은 상황에서는 서비스 측의 업데이트 시점을 게임 운영 측에서 컨트롤하고 싶다는 요구가 존재합니다. GS2-Freeze 는 이러한 요구에 응답하기 위한 엔터프라이즈 대상 기능입니다.

GS2-Friend

Mon, 01 Jan 0001 00:00:00 +0000

게임 전용 소셜 그래프를 형성하기 위한 기능을 제공합니다. 소셜 그래프는 플랫폼 측에서도 제공되는 경우가 있지만, 게임 내에서 독자적으로 형성하는 것에도 가치가 있습니다.

플랫폼 전체에서 사용되는 친구 관계는 등록을 신중하게 하는 경향이 있습니다. 왜냐하면 “지금 함께 플레이하고 있는 이 게임에서는 함께 하고 싶지만, 다른 게임까지 함께 플레이하고 싶지는 않다"는 케이스가 존재하기 때문입니다. 플랫포머가 제공하는 소셜 그래프는 현실에 가까운 관계성을 반영한 것이고, 게임 고유의 소셜 그래프는 그 게임 내에서의 관계성을 반영한 것으로 취급하면, 플레이어는 더 부담 없이 친구 기능을 이용하게 됩니다.

GS2-Gateway

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Gateway는 게임 클라이언트와 서버 사이에서 WebSocket을 통한 상시 접속을 유지하고, 서버가 임의의 시점에 알림을 보낼 수 있도록 하는 기능을 제공합니다.

일반적인 게임 서버와의 통신은 클라이언트의 요청에 서버가 응답하는 형태이지만, GS2-Gateway를 사용하면 서버가 시작하는 알림(메시지 수신, 친구 신청, 길드로부터의 소집 등)을 실시간으로 클라이언트에 전달할 수 있습니다.

sequenceDiagram
  participant Client
  participant Gateway as GS2-Gateway
  participant Service as 각 마이크로서비스

  Client->>Gateway: WebSocket 접속
  Client->>Gateway: SetUserId(인증)
  Service->>Gateway: SendNotification
  Gateway->>Client: 알림 페이로드 전달

주요 기능

WebSocket 상시 접속

GS2-Gateway는 WebSocket 프로토콜로 클라이언트로부터의 접속을 받아들이고, 사용자별로 접속 정보를 보유합니다. 다른 마이크로서비스로부터 “이 사용자에게 알림을 보내고 싶다"는 요청이 오면, 접속 중인 클라이언트에 페이로드를 전달합니다.

GS2-Grade

Mon, 01 Jan 0001 00:00:00 +0000

캐릭터나 장비의 육성에는 단기 성장 목표인 레벨업과는 별도로 그레이드업을 마련하는 것이 일반적인 사양입니다. 그레이드업을 하면 레벨 캡을 끌어올릴 수 있어 캐릭터나 장비를 더욱 강력하게 육성할 수 있게 됩니다.

그레이드업 방법에는 여러 가지가 있을 수 있으며, 육성 소재를 소비함으로써 그레이드업할 수 있는 것이나, 같은 종류의 캐릭터나 장비를 합성함으로써 그레이드업할 수 있는 것도 있습니다. GS2-Grade는 방법을 따지지 않고, 그레이드별로 레벨 캡을 설정함으로써 GS2-Experience의 레벨 캡 운용을 더 간단하게 구현할 수 있도록 하는 것을 목적으로 합니다.

GS2-Guard

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Guard는 GS2의 API 엔드포인트에 대한 접근을 보호하기 위한 기능을 제공합니다. 특정 국가나 지역, IP 주소, 익명화된 IP, 호스팅 사업자의 IP, 평판이 나쁜 IP 등 다양한 조건으로 발신지를 판정하여, API 요청을 허용·거부하는 구조를 구축할 수 있습니다.

부정 이용이나 치트 행위, 공격적인 트래픽으로부터 게임 서버를 지키기 위한, 이른바 게임 전용 경량 WAF(Web Application Firewall)로 기능합니다.

GS2-Guard는 게임 클라이언트에서 직접 이용하는 기능이 아니라, 운영 측에서 차단 정책을 정의하고 다른 GS2 마이크로서비스의 API에 적용하기 위한 구조입니다.

GS2-Guild

Mon, 01 Jan 0001 00:00:00 +0000

여러 플레이어가 팀을 만들어 함께 어떤 목표를 향해 활동할 수 있도록 하는 기능이 길드 기능입니다. GS2-Guild는 길드 멤버의 관리와, 길드 멤버가 실행할 수 있는 권한 관리를 수행하기 위한 마이크로서비스입니다.

GS2-Guild에서 ‘길드’는 한 명의 플레이어로 취급되며, 길드 사용자라고 부릅니다. 길드 멤버는 길드 사용자로서 정보를 조회·갱신할 수 있는 페더레이션을 수행함으로써, 길드 멤버가 공통 프로퍼티를 조작할 수 있는 상태를 실현합니다.

예를 들어 플레이어A와 플레이어B가 소속되어 있는 길드A가 있다고 가정해 봅시다. 플레이어 레벨이나 스태미나와 같은 일반적인 정보가 플레이어A와 플레이어B에 연결되어 관리된다는 것은 쉽게 상상할 수 있을 것입니다. 이와 마찬가지로 길드A에 연결하여 길드 레벨과 같은 프로퍼티를 연결해서 관리하는 것도 쉽게 상상할 수 있을 것입니다.

GS2-Identifier

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Identifier는 GS2 관리 콘솔 및 GS2 API에 접근하기 위한 크리덴셜을 관리하는 서비스입니다.

GS2 오너 계정에 연결된 사용자, 각 사용자에게 부여되는 권한(보안 정책), 그리고 실제 API 호출에 사용하는 클라이언트ID/클라이언트시크릿을 발급·관리합니다.

GS2-Identifier는 게임 클라이언트에서 직접 호출하는 것을 상정하지 않은 서비스이며, 운영 측의 셋업이나 배포 자동화, CI/CD 파이프라인 등에서 이용됩니다.

IAM 적인 설계

GS2-Identifier는 클라우드 서비스의 IAM(Identity and Access Management)에 상당하는 개념을 제공합니다.

주요 요소는 다음과 같습니다.

사용자: GS2 오너 계정 산하에 생성하는 개별 이용 주체
보안 정책: 조작 가능한 리소스와 액션을 기술한 정책 문서
보안 정책의 어태치: 사용자에게 보안 정책을 연결하여 권한을 부여
클라이언트ID/클라이언트시크릿: 사용자별로 발급되는 API 인증 정보

graph TD
  Owner["GS2 오너"] --> User["사용자"]
  User -->|어태치| Policy["보안 정책"]
  User -->|발급| Credential["클라이언트ID<br/>클라이언트시크릿"]
  Credential -->|인증| API["GS2 API"]
  Policy -->|권한 제어| API

보안 정책

보안 정책은 JSON 형식으로 기술된 권한 정의입니다. 허용할 리소스 GRN과 허용할 액션(Gs2Account:CreateAccount와 같은 조작 식별자)을 기술함으로써, 해당 정책이 어태치된 사용자에게 어떤 조작을 허용할지를 표현합니다.

GS2-Idle

Mon, 01 Jan 0001 00:00:00 +0000

게임을 플레이하지 않은 기간에 따라 보상을 지급하는 구조를 구현합니다. 스마트폰 대상 게임에서는 “오랜만에 앱을 실행했더니 대량의 보상을 획득할 수 있었다"는 디자인이 플레이어의 재방문 촉진에 크게 기여합니다. GS2-Idle은 이러한 방치 보상을 간단하게 도입하기 위한 마이크로서비스입니다.

graph LR
  Start["대기 시작"] --> Idle["방치 시간 경과"]
  Idle --> Prediction["획득 예정 보상 조회"]
  Prediction --> Receive["보상 수령"]
  Receive --> Start

카테고리

방치 보상은 여러 개를 준비할 수 있습니다. 플레이어는 카테고리별로 1개의 대기 시간을 가질 수 있습니다.

GS2-Inbox

Mon, 01 Jan 0001 00:00:00 +0000

시스템이나 운영진이 플레이어에게 메시지나 선물을 전달하는 구조를 구현합니다.

게임에서는 “보상 배포(사과)”, “로그인 보너스”, “과금 특전”, “이벤트 보상” 등 플레이어에게 비동기적으로 보상을 전달해야 하는 상황이 자주 발생합니다. GS2-Inbox는 메시지의 큐잉, 읽음/안읽음 관리, 보상 첨부, 유효기간에 따른 자동 삭제 기능을 제공하며, 게임의 라이프사이클 전반에 걸쳐 프레젠트 박스 기능을 담당합니다.

sequenceDiagram
  participant Ops as 운영 / 서버
  participant Inbox as GS2-Inbox
  participant Player as 플레이어
  Ops->>Inbox: 메시지 송신 (보상 첨부)
  Inbox-->>Player: receiveNotification 알림
  Player->>Inbox: 메시지 목록 조회
  Player->>Inbox: 메시지 개봉 (Read)
  Inbox->>Player: 첨부 보상 지급 (트랜잭션)
  Player->>Inbox: 읽은 메시지 삭제

메시지

읽음 관리

메시지는 읽음 상태를 가집니다. 읽음 상태의 메시지를 목록에 남길지, 목록에서 삭제할지 설정할 수 있습니다.

GS2-Inventory

Mon, 01 Jan 0001 00:00:00 +0000

플레이어가 소지한 아이템 정보를 관리합니다.

아이템 관리에는 3가지 방식이 있습니다. 첫 번째는 스탠다드 인벤토리, 두 번째는 심플 인벤토리, 세 번째는 거대 인벤토리입니다.

스탠다드 인벤토리는 다음과 같은 기능을 제공합니다

인벤토리 용량 제한
동일한 아이템을 일정 수량마다 여러 스택으로 분할
아이템에 유효기간 설정

심플 인벤토리는 스탠다드 인벤토리가 가진 기능을 갖고 있지 않습니다. 그 대신 여러 아이템의 증감 처리를 한 번에 수행할 수 있습니다. 심플 인벤토리를 잘 활용하면 API 호출 횟수를 줄일 수 있습니다.

GS2-JobQueue

Mon, 01 Jan 0001 00:00:00 +0000

GS2-JobQueue는 게임 서버에서 실행하는 처리를 비동기적으로 쌓아두기 위한 잡 큐 기능을 제공합니다.

게임 처리 중에는 즉시 결과를 반환할 필요가 없는 것이나, 서버 측에서 시간을 들여 단계적으로 진행하고 싶은 것이 있습니다. 이러한 처리를 “잡"으로 큐에 등록해 두고, 이후 플레이어가 접속한 시점이나 명시적인 API 호출을 통해 실행할 수 있습니다.

주요 용도

GS2-Script를 비동기로 실행하기 위한 실행 기반
장시간 처리를 세부 단계로 분할하여, 각 단계를 잡으로 등록해 순차적으로 처리
로그인 중에 발생한 리워드 배포 등을 모아서 서버 측에서 트랜잭션 발행·실행
다른 마이크로서비스의 완료 알림 핸들러로서, 후속 처리를 비동기로 수행

graph LR
  Producer["잡 등록원<br/>(다른 마이크로서비스 / GS2-Script)"] --> Queue["GS2-JobQueue"]
  Queue --> Run["플레이어가 Run을 실행<br/>또는 자동 실행"]
  Run --> Script["GS2-Script"]
  Script -- 성공 --> Result["JobResult로 기록"]
  Script -- 실패 --> Retry{"최대 시도 횟수<br/>도달?"}
  Retry -- No --> Queue
  Retry -- Yes --> DeadLetter["DeadLetterJob으로 보관"]

자동 실행 모드

네임스페이스 설정에서 enableAutoRun을 활성화하면, 각 마이크로서비스의 API 처리 마지막에 사용자의 큐에 쌓여 있는 잡을 자동으로 실행합니다. 플레이어가 앱을 조작하는 것만으로 서버 측에 쌓인 잡이 순차적으로 소화됩니다.

GS2-Key

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Key는 GS2 내에서 사용되는 암호화 키(대칭키)를 관리하고, AES를 이용한 암호화·복호화 API를 제공하는 서비스입니다.

기밀성이 높은 데이터를 서버 측에서 암호화·복호화하는 용도 외에도, GS2 자체가 내부적으로 사용하는 각종 서명·암호화 처리를 위한 키 관리 기반으로도 활용됩니다.

암호화 키 관리

GS2-Key에서는 암호화 키를 네임스페이스 하위에 생성하여 관리합니다.

키에는 다음과 같은 정보를 담을 수 있습니다.

키 이름
설명(description: 용도나 설명 등, 운용상의 식별에 사용)

실제 암호화에 사용되는 비밀키(시크릿)는 키 생성 시 GS2 측에서 안전하게 생성되어 GS2 내부에 보관됩니다. 비밀키 자체를 클라이언트 측에서 꺼내어 사용하는 설계가 아니라, 암호화·복호화 요청을 GS2-Key에 전송하고 결과만 받는 구조로 되어 있습니다.

GS2-Limit

Mon, 01 Jan 0001 00:00:00 +0000

플레이어가 행동할 수 있는 횟수를 제한하기 위한 구조입니다. “하루에 5번까지 가챠를 뽑을 수 있다”, “일주일에 한 번만 받을 수 있는 보상” 등, 게임 내에서 자주 등장하는 횟수 제한을 일괄적으로 관리할 수 있습니다.

graph LR
  Action["플레이어의 행동"] --> CountUp["카운트업 (maxValue 지정)"]
  CountUp -- 상한에 도달하지 않음 --> Success["처리를 허가"]
  CountUp -- 상한에 도달함 --> Failure["처리를 거부"]
  Reset["리셋 주기"] --> Counter["카운터를 0으로 되돌림"]

카운터

플레이어의 행동 횟수를 표현하기 위한 엔티티로, 카운터의 값을 증가시킬 때 허용 가능한 최댓값을 지정하여 카운트업을 시도함으로써, 최댓값을 초과하는 경우에는 카운트업이 실패하고 후속 처리도 실패시킬 수 있는 메커니즘으로 횟수 제한을 실현합니다. 이때, 카운터 자체에 최댓값이 존재하는 것이 아니라 카운트업 액션에 최댓값을 설정할 수 있다는 점이 특징입니다.

GS2-Lock

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Lock 는 리소스 단위로 동작하는 뮤텍스를 제공하여, 여러 서버 프로세스·여러 처리계에서 동일한 리소스에 동시에 접근하는 것을 방지하기 위한 분산 배타 제어 서비스입니다.

게임 운영에서는 “동일한 플레이어에 대해 같은 처리를 이중으로 실행해 버린다”, “서로 다른 백엔드 서버가 동일한 데이터를 동시에 덮어써 버린다” 와 같은 문제가 쉽게 발생합니다. GS2-Lock 을 이용하면, 이러한 문제를 마이크로서비스로 제공되는 공유 뮤텍스를 통해 방지할 수 있습니다.

뮤텍스의 기본

GS2-Lock 의 잠금은 “네임스페이스”, “사용자ID”, “프로퍼티 ID” 의 조합으로 식별되는 “뮤텍스” 라는 리소스에 대해 획득합니다.

GS2-Log

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Log는 게임에 통합된 모든 Game Server Services 마이크로서비스의 API 액세스 로그를 집약·저장하는 기능을 제공합니다.

게임 운영에 있어 “언제·누가·어떤 API를·어떤 인수로 호출하고·어떤 결과를 반환했는가"를 나중에 추적할 수 있는 것은 매우 중요합니다. 부정 플레이어 조사, 게임 밸런스 확인, 문의 대응, KPI 집계 등 모든 운영 업무의 기반으로 GS2-Log의 데이터를 활용할 수 있습니다.

GS2-Log의 기능은 게임 클라이언트에서 직접 이용하는 것이 아니라, 운영 측 도구나 데이터 분석 기반과 연동하여 활용하기 위한 것입니다.

로그의 종류

GS2-Log는 다음 4가지 종류의 로그를 기록합니다.

GS2-LoginReward

Mon, 01 Jan 0001 00:00:00 +0000

게임에 매일 로그인한 플레이어에게 보상을 지급하는 구조입니다. 일별 아이템 지급이나 7일/30일 주기로 반복되는 로그인 보너스, 놓친 날의 보상을 나중에 보전해 주는 기능 등, 운영 현장에서 자주 사용되는 패턴을 범용적으로 제공합니다.

모드

로그인 보너스의 제공 방식에는 《스케줄 모드》와 《스트리밍 모드》 2가지 방식이 있습니다.

graph LR
  Mode{보너스 모드} --> Schedule["스케줄 모드<br/>(mode: schedule)"]
  Mode --> Streaming["스트리밍 모드<br/>(mode: streaming)"]
  Schedule -- 날짜에 고정 --> SchEx["1일차=금화, 2일차=은화…<br/>놓치면 건너뜀"]
  Streaming -- 순서대로 소화 --> StrEx["1번째=금화, 2번째=은화…<br/>놓쳐도 다음으로 이월"]
  Streaming --> Repeat{"repeat 설정"}
  Repeat -- enabled --> Loop["끝에 도달 후 처음부터 재개"]
  Repeat -- disabled --> Stop["끝에서 정지"]

스케줄 모드

GS2-Schedule 의 이벤트와 연결하여 이용합니다. 보상으로 지급할 트랜잭션 액션을 각 일정별로 정의합니다. 이벤트 시작 일시부터 24시간마다 보상이 변경되며, 각 보상은 1회씩 받을 수 있습니다. 도중에 놓친 보상이 있을 경우 건너뜁니다.

GS2-Lottery

Mon, 01 Jan 0001 00:00:00 +0000

가챠를 구현하기 위한 시스템입니다. GS2-Lottery는 일반 가챠와 박스 가챠를 지원합니다.

graph TD
  Trigger["추첨 트리거<br/>(GS2-Showcase의 구매 보상 / 퀘스트 클리어 보상 등)"] --> LotteryModel["LotteryModel<br/>(추첨 모델)"]
  LotteryModel -- "mode = normal" --> Normal["일반 모드 추첨"]
  LotteryModel -- "mode = box" --> Box["박스 모드 추첨"]
  Normal --> PrizeTable["경품 테이블<br/>(PrizeTable)"]
  Box --> BoxData["플레이어 전용 박스"]
  PrizeTable --> Prize["Prize<br/>(acquireActions)"]
  BoxData --> Prize
  Prize --> Acquire["GS2-Distributor<br/>보상 배포"]

일반 가챠

일반 가챠는 지정된 확률로 순수한 추첨을 진행합니다.

GS2-Matchmaking

Mon, 01 Jan 0001 00:00:00 +0000

플레이어를 조건에 따라 그룹화하는 기능입니다. 대전 상대를 찾기 위해 사용할 수 있습니다.

스크립트 트리거

네임스페이스에 createGatheringTriggerScriptId · completeMatchmakingTriggerScriptId · changeRatingScript 를 설정하면, 개더링 생성 완료 시·매칭 완료 시·레이팅 변동 시에 커스텀 스크립트를 실행할 수 있습니다.

설정 가능한 주요 이벤트 트리거와 스크립트 설정명은 다음과 같습니다.

createGatheringTriggerScriptId: 개더링 생성 완료 시
completeMatchmakingTriggerScriptId: 매칭 완료 시
changeRatingScript: 레이팅 변동 시

푸시 알림

설정 가능한 주요 푸시 알림과 설정명은 다음과 같습니다.

joinNotification: 매칭 참가 시 알림
leaveNotification: 매칭 이탈 시 알림
completeNotification: 매칭 완료 시 알림
changeRatingNotification: 레이팅 변동 시 알림

모두 GS2-Gateway 를 통해 알림을 보낼 수 있으며, 오프라인 단말로의 모바일 푸시 전송도 가능합니다.

GS2-MegaField

Mon, 01 Jan 0001 00:00:00 +0000

GS2-MegaField는 거대한 3D 공간에 존재하는 대량의 플레이어 위치 정보를, 효율적으로 공유·동기화하기 위한 기능을 제공합니다.

MMORPG나 오픈 월드, 메타버스형 서비스 등, 같은 월드에 대량의 플레이어가 동시에 로그인하는 타이틀에서는, 모든 플레이어의 위치 정보를 전체 플레이어에게 배포하면 네트워크 대역도 CPU도 감당할 수 없게 됩니다. GS2-MegaField는 “자신의 근방에 있는 플레이어만"을 효율적으로 가져올 수 있도록 함으로써 이 문제를 해결합니다.

에어리어와 레이어

GS2-MegaField의 공간은 “에어리어(Area)“와 “레이어(Layer)“라는 두 가지 개념으로 구성됩니다.

AreaModel(에어리어 모델): 하나의 커다란 3D 공간을 나타내는 마스터 데이터. 예를 들어 “마을 안”, “던전”, “필드” 등, 월드 내의 논리적인 구획별로 작성합니다.
LayerModel(레이어 모델): 하나의 에어리어 안에 존재하는, 용도별 레이어. 예를 들어 “플레이어용”, “NPC용”, “아이템용"과 같이, 같은 장소를 다른 목적으로 겹쳐서 이용할 수 있습니다.

에어리어 모델은 여러 레이어 모델을 포함하는 형태로 마스터 데이터로서 정의합니다. 플레이어의 위치는 “어느 에어리어의, 어느 레이어의, 어느 좌표에 있는가"라는 형태로 표현됩니다.

GS2-Mission

Mon, 01 Jan 0001 00:00:00 +0000

게임 내에 축적된 행동을 기반으로 플레이어에게 보상을 지급하기 위한 구조입니다. 일반적으로 업적·트로피·미션이라고 불리는 기능을 구현하기 위한 기능입니다.

graph TD
  Action["게임 내 행동<br/>(퀘스트 클리어 / 가챠 실행 등)"] -- "카운터 상승<br/>(IncreaseCounterByUserId)" --> Counter["미션 카운터<br/>(Counter / Scope)"]
  Counter -- "목표값 도달" --> Task["미션 태스크<br/>(MissionTaskModel)"]
  Task -- "ReceiveRewards" --> Reward["completeAcquireActions"]
  Reward --> Distributor["GS2-Distributor<br/>보상 배포"]
  Task --> Group["미션 그룹<br/>(MissionGroupModel)"]
  Group -- "resetType 에 기반해<br/>수령 플래그를 리셋" --> Task

미션 카운터

플레이어의 행동에 기반한 횟수를 세기 위한 엔티티입니다. “퀘스트를 클리어한 횟수”, “캐릭터를 강화한 횟수”, “가챠를 뽑은 횟수"와 같은 게임 내 행동 횟수를 카운트하기 위한 카운터를 준비합니다.

GS2-Money

Mon, 01 Jan 0001 00:00:00 +0000

Warning

GS2-Money2가 릴리스되었습니다.

특별한 이유가 없는 한 새로 이용할 경우에는 GS2-Money2를 이용해 주세요.

게임 내 리소스 중, 현금에 상당하는 가치를 가진 리소스를 다루는 기능입니다. 일본의 자금결제법상 선불식 지급수단(자사형)에 해당하는 자산을 취급하는 경우에는 반드시 이 기능을 이용해야 합니다.

잔액

GS2-Money는 플레이어가 보유한 과금 통화의 잔액을 단순한 수량으로 관리하지 않고, 구매 시점의 가치별로 수량을 관리합니다.

예를 들어, 100엔으로 100개의 과금 통화를 구매한 경우 과금 통화 1개의 가치는 1엔 상당이 됩니다. 동시에 1000엔으로 1200개의 과금 통화를 구매할 수 있다고 합시다. 어디까지나 과금 통화의 단가를 1엔으로 하고 200개는 덤으로 무료 처리하는 것도 하나의 방법이고, 1000엔으로 구매한 경우는 단가를 0.8334엔으로 하여 다른 단가로 취급하는 것도 하나의 방법입니다.

GS2-Money2

Mon, 01 Jan 0001 00:00:00 +0000

Tip

GS2-Money2 는 이름 그대로 버전 2에 해당하는 마이크로서비스입니다.

이전 버전에 관한 문서는 GS2-Money 를 참조하십시오.

게임 내 리소스 중 현금에 상당하는 가치를 가진 리소스를 다루는 기능입니다. 일본의 자금결제법상 선불식 지급수단(자가형)에 해당하는 자산을 취급하는 경우에는 반드시 이 기능을 이용해야 합니다.

GS2-Money2 는 단순히 “과금 통화의 잔고"를 다루는 서비스가 아니라, 다음과 같은 회계·법령 대응상의 요건을 함께 처리하는 마이크로서비스입니다.

입금 일시·단가별 잔고 관리
영수증 검증을 통한 부정 입금 방지
지갑의 가감산 이력 보관
플랫폼 가이드라인에 따른 통화 격리
구독(기간 과금) 계약 상태 관리
미사용 잔고 집계(선불식 지급수단 대응)

잔고

GS2-Money2 는 플레이어가 보유한 과금 통화의 잔고를 단순한 수량으로 관리하지 않고, 구매 시의 가치별로 수량을 관리합니다.

GS2-News

Mon, 01 Jan 0001 00:00:00 +0000

게임 내 공지사항을 HTML 형식으로 배포하기 위한 구조입니다. 배포하는 HTML 콘텐츠는 Hugo(https://gohugo.io/) 로 생성해야 합니다.

GS2-News 는 기사 데이터를 업로드하면 GS2 측에서 Hugo를 통한 빌드를 수행하여, 정적 웹 콘텐츠로 호스팅합니다. 게임 클라이언트는 배포된 임시 URL에 접근함으로써 공지사항을 열람할 수 있습니다.

graph LR
  Author["운영자"] -- "ZIP 업로드" --> GS2["GS2-News"]
  GS2 -- "hugo build (공개/비공개의<br/>모든 패턴을 사전 생성)" --> CDN["CDN (HTML / ZIP)"]
  Player["플레이어"] -- "GetContentsUrl" --> GS2
  GS2 -- "URL + Cookie<br/>(1시간 유효)" --> Player
  Player -- "WebView or ZIP DL" --> CDN

Hugo

Hugo 는 정적 웹페이지를 생성하기 위한 제너레이터입니다.

GS2-Quest

Mon, 01 Jan 0001 00:00:00 +0000

게임의 진행 관리와 퀘스트의 진행 관리를 수행합니다.

GS2-Quest는 게임의 인게임(전투나 스테이지)에 도전하기 위한 ‘입구’와 ‘출구’만을 서버에서 관리하는 마이크로서비스입니다. 인게임 내부의 로직에는 관여하지 않으며, 시작 시 비용 소비, 클리어 시 보상 지급, 전제 조건 판정과 같이 서버에서 신뢰해야 할 처리를 담당합니다.

graph LR
  Start["퀘스트 시작<br/>StartAsync"] --> Battle["인게임 실행<br/>(클라이언트 / 전용 서버)"]
  Battle -- 성공 --> End1["퀘스트 종료 보고<br/>EndAsync(isComplete:true)"]
  Battle -- 실패 --> End2["퀘스트 종료 보고<br/>EndAsync(isComplete:false)"]
  End1 --> Reward["클리어 보상 지급"]
  End2 --> FailedReward["실패 보상 지급"]

퀘스트

퀘스트는 인게임의 기본 단위로, 인게임을 시작할 때 선택하는 엔티티입니다. 퀘스트에는 도전에 필요한 비용과 도전을 통해 얻을 수 있는 보상을 설정할 수 있으며, GS2-Quest는 그 시작과 종료를 API로 받아들입니다. 즉, GS2-Quest는 인게임의 내용에는 관여하지 않습니다.

GS2-Ranking

Mon, 01 Jan 0001 00:00:00 +0000

Warning

GS2-Ranking2 가 릴리스되었습니다.

특별한 이유가 없는 한 새로 이용하실 경우에는 GS2-Ranking2 를 이용해 주세요.

게임의 점수나 클리어 타임을 겨루는 랭킹 기능을 실현합니다.

랭킹에는 2종류가 존재하며 “참가자 전원이 동일한 보드에서 경쟁하는 것"과 “구독한 플레이어의 점수와 경쟁하는 것"이 있습니다. 전자를 글로벌 랭킹, 후자를 스코프 랭킹이라고 부릅니다.

글로벌 랭킹

글로벌 랭킹은 모든 플레이어와 경쟁하기 위한 랭킹 기능을 제공합니다.

GS2-Ranking 에서는 수억 명 이상의 플레이어가 참가하는 대규모 랭킹을 실현할 수 있습니다.

대신, 랭킹의 집계는 리얼타임이 아니라 사전에 설정한 주기로 집계 처리가 이루어지며 그 집계 결과를 바탕으로 순위 계산 등을 수행합니다.

GS2-Ranking2

Mon, 01 Jan 0001 00:00:00 +0000

Tip

GS2-Ranking2 는 이름 그대로 버전2에 해당하는 마이크로서비스입니다.

이전 버전에 관한 문서는 GS2-Ranking 을 참조하세요.

게임의 점수나 클리어 타임을 겨루는 랭킹 기능을 실현합니다.

GS2-Ranking2 는 다음 3가지 종류의 모드를 제공합니다.

글로벌 랭킹
클러스터 랭킹
구독 랭킹

게임에 필요한 랭킹 기능의 대부분은 이 중 하나의 모드로 요건을 충족할 수 있을 것입니다.

랭킹 모드

글로벌 랭킹

글로벌 랭킹은 모든 플레이어와 경쟁하기 위한 랭킹 기능을 제공합니다. GS2-Ranking2 에서는 상위 1000위 플레이어만 랭킹에 참가할 수 있으며, 1000위 이하 플레이어의 점수는 전송하더라도 랭킹에 등록되지 않습니다.

GS2-Realtime

Mon, 01 Jan 0001 00:00:00 +0000

게임 플레이어 간의 대전 기능을 구현하기 위해, 낮은 레이턴시로 높은 빈도의 통신이 필요한 경우에 사용할 수 있는 기능입니다.

GS2에서는 일반적으로 API 리퀘스트 횟수에 대해 요금이 발생하지만, 이 서비스는 게임 서버가 기동하면 해당 게임 서버의 가동 시간과 통신 용량에 대해 비용이 발생하며, 통신 횟수에 대해서는 비용이 발생하지 않습니다.

graph TD
  Match["GS2-Matchmaking 에서<br/>로비 성립"] --> Want["RoomWant 으로 룸 요청"]
  Want -- 핫 스탠바이에서 할당 --> Warm["Warm Start (1~3초)"]
  Want -- 신규 기동 --> Cold["Cold Start (40~60초)"]
  Warm --> Connect["플레이어가 접속"]
  Cold --> Connect
  Connect --> Play["패킷 릴레이로 대전 중 통신"]
  Play -- 1분간 무통신 또는 3시간 경과 --> Shutdown["룸 종료"]

서버 타입

현재 GS2-Realtime은 패킷 릴레이 기능만을 제공하고 있습니다. 이는 게임 서버로 메시지를 전송하면 그 메시지가 다른 플레이어에게 브로드캐스트되는 기능을 기본으로 하며, 플레이어ID를 지정하여 지정한 플레이어에게 메시지를 전달하는 기능만을 가지고 있습니다.

GS2-Schedule

Mon, 01 Jan 0001 00:00:00 +0000

게임 내 이벤트 등의 스케줄을 관리하는 기능을 제공합니다.

GS2-Schedule 은 단독으로는 이벤트의 기간 정보만을 관리하는 기능을 가지고 있으며, 보상 지급이나 구매 제한과 같은 처리는 다른 마이크로서비스와 조합하여 실현합니다. GS2-Showcase / GS2-Exchange / GS2-LoginReward / GS2-Mission 등 거의 모든 게임 요소 마이크로서비스가 이벤트 기간과의 연계를 전제로 설계되어 있기 때문에, 기간 한정 운영 시책을 실시할 때 핵심이 되는 마이크로서비스입니다.

이벤트 개최 기간

이벤트 개최 기간에는 두 가지 종류가 있습니다. 첫 번째는 모든 플레이어가 동일한 기간을 공유하는 “절대 기간”, 두 번째는 플레이어마다 기간이 다른 “상대 기간"입니다.

GS2-Script

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

GS2-SeasonRating

Mon, 01 Jan 0001 00:00:00 +0000

플레이어 실력에 따라 플레이어를 분류하여, 더 비슷한 실력의 플레이어와의 매치메이킹을 실현하기 위한 기능입니다. 레이트 값에 의한 매치메이킹 기능은 GS2-Matchmaking에 갖추어져 있지만, 최근 늘어나고 있는 현실 시간으로 몇 주에서 몇 달 정도의 시즌을 통해 플레이어를 랭크 매기는 방식에는 대응하지 못했습니다.

이 마이크로서비스는 정해진 기간을 시즌으로 간주하고, 시즌 기간 동안 더 높은 티어를 목표로 대전을 반복하는 게임 사이클을 실현하기 위해 이용할 수 있습니다. 그렇기 때문에 이 기능에서 강함을 나타내는 지표는 레이트 값이 아니라 어느 티어에 속해 있는지로 표현됩니다.

GS2-SerialKey

Mon, 01 Jan 0001 00:00:00 +0000

게임 외부의 물품 판매나 오프라인 이벤트, SNS 캠페인, 콜라보 캠페인 등을 통해 게임 내 아이템을 배포하고 싶은 경우에 사용할 수 있습니다. 종이 패키지나 QR 코드에 인쇄한 코드, 이메일/SNS로 배포하는 문자열 모두 동일한 구조로 다룰 수 있습니다.

단, 이 기능은 일부 플랫폼 사업자가 구현을 허용하지 않는 경우가 있으므로, 채택할 때는 플랫폼 사업자의 가이드라인을 확인하도록 하십시오.

시리얼 코드의 종류

시리얼 코드에는 다음 두 가지 종류가 있습니다.

시리얼 키: 1회 사용하면 재사용할 수 없는 코드
캠페인 코드: 하나의 코드를 여러 사람이 공유할 수 있는 코드

graph TD
  SerialCode["시리얼 코드"]
  SerialCode --> SerialKey["시리얼 키<br/>1인 1회 한정"]
  SerialCode --> CampaignCode["캠페인 코드<br/>여러 명이 공용"]
  SerialKey --> SerialKeyUse["RPCLP-FP7N-NCDMJ-FLVA-IRI4"]
  CampaignCode --> CampaignCodeUse["NEWYEAR2026"]

시리얼 키

1회 사용하면 두 번 다시 사용할 수 없게 되는 코드 입니다.

GS2-Showcase

Mon, 01 Jan 0001 00:00:00 +0000

게임 내에서 상품을 판매할 때 사용합니다.

GS2-Exchange와의 차이점은 진열대가 존재한다는 점입니다. 진열대에는 DisplayItem을 진열할 수 있으며, DisplayItem을 구매하기 위해 필요한 대가와 상품을 구매했을 때 얻을 수 있는 보상을 설정할 수 있습니다.

진열대에는 2종류가 있으며, 고정된 DisplayItem이 진열되는 《스탠다드 진열대》와, 일정 간격으로 진열 내용이 랜덤으로 추첨되는 《랜덤 진열대》가 있습니다.

graph TD
  Master["마스터 데이터"] --> Showcase["스탠다드 진열대<br/>(ShowcaseModel)"]
  Master --> RandomShowcase["랜덤 진열대<br/>(RandomShowcaseModel)"]
  Showcase --> DisplayItem["DisplayItem<br/>(SalesItem / SalesItemGroup)"]
  RandomShowcase --> RandomDisplayItem["RandomDisplayItem<br/>(stock / weight)"]
  Player["플레이어"] -- Buy --> DisplayItem
  Player -- RandomShowcaseBuy --> RandomDisplayItem
  DisplayItem -- "consumeActions / acquireActions" --> Transaction["GS2-Distributor<br/>트랜잭션 실행"]
  RandomDisplayItem -- "consumeActions / acquireActions" --> Transaction

스탠다드 진열대

스탠다드 진열대는 지정한 DisplayItem이 모두 진열됩니다. DisplayItem에는 2종류가 있으며 《SalesItem》과 《SalesItemGroup》이 있습니다.

GS2-SkillTree

Mon, 01 Jan 0001 00:00:00 +0000

캐릭터 등의 성장 요소로 일반적으로 사용되는 스킬 트리 기능을 구현하기 위한 마이크로서비스입니다. 스킬 트리란 아래와 같은 트리 구조를 가지며, 노드를 해제함으로써 캐릭터의 파라미터를 향상시킬 수 있는 기능을 가리킵니다. 노드 해제에는 비용이 필요하며, GS2-SkillTree에서는 각 마이크로서비스가 제공하는 《소비 액션》을 설정할 수 있습니다.

flowchart TD
  Base --> Node1[STR+5]
  Node1 --> Node2[DEF+5]
  Node2 --> Node3[SPD+5]

  Node3 --> Node4[STR+5]
  Node4 --> Node5[DEF+5]
  Node5 --> Node6[STR+5]
  Node6 --> Node7[DEF+5]

  Node3 --> Node10[SPD+5]
  Node10 --> Node11[DEF+5]
  Node11 --> Node12[SPD+5]
  Node12 --> Node13[DEF+5]

  Node11 --> Node30[SPD+5]
  Node30 --> Node31[STR+5]
  Node31 --> Node32[SPD+5]

  Node7 --> Node20[STR+5]
  Node13 --> Node20
  Node20 --> Node21[STR+5]
  Node21 --> Node22[STR+5]

노드 정의(NodeModel)

스킬 트리를 구성하는 노드는 마스터 데이터 NodeModel로 정의합니다. 각 노드는 다음 필드로 구성되며, 이를 통해 노드의 해제 조건·비용·효과·의존 관계를 표현합니다.

GS2-Stamina

Mon, 01 Jan 0001 00:00:00 +0000

스태미나는 게임 내의 횟수 제한 기능을 실현하는 것입니다. GS2-Limit 는 “하루에 3회” 와 같이 횟수 제한을 표현하지만, GS2-Stamina 는 “8시간에 1포인트 회복하는 스태미나를 사용하여 하루 3회로 횟수를 제한한다” 와 같이, 시간 경과와 소비 액션의 조합으로 제한을 표현합니다.

스태미나의 경우, 소비하는 포인트에 차등을 둠으로써 A라는 행동이라면 하루 3회, B라는 행동이라면 하루 5회와 같은 사양을 구현할 수 있습니다. 이는 스태미나 1당 얻을 수 있는 경험치나 게임 내 통화의 기준을 마련함으로써, 게임 내에서 어떤 행동을 취하더라도 특별히 효율이 좋은 행동이라는 것을 배제할 수 있어, 게임 밸런스를 조정하기 쉬워집니다.

GS2-StateMachine

Mon, 01 Jan 0001 00:00:00 +0000

GS2-Quest 는 퀘스트의 시작·종료를 관리하고, 시작한 퀘스트에 따라 종료 시 보상을 받을 수 있는 구조를 제공했습니다. 하지만 인게임의 무작위성이 강해 보상을 사전에 특정하기 어려운 게임 사양은 GS2-Quest 로는 잘 다루지 못하는 과제가 있었습니다.

GS2-StateMachine 은 더 세밀한 단위로 인게임의 상태 관리를 하기 위해 개발되었습니다.

스테이트 머신

인게임의 상태 관리에 사용하는 것이 스테이트 머신입니다.

flowchart TD
  Start ----> MainStateMachine_Initialize
  MainStateMachine_Pass ----> Exit
  subgraph MainStateMachine
    MainStateMachine_Initialize[[Initialize]] -->|Pass| MainStateMachine_ChoiceSkill

    MainStateMachine_ChoiceSkill[/ChoiceSkill/]

    MainStateMachine_InGame([InGame]) -->|Pass| MainStateMachine_NextTurn
    MainStateMachine_InGame([InGame]) -->|Fail| MainStateMachine_Pass

    MainStateMachine_NextTurn[[NextTurn]] -->|Next| MainStateMachine_ChoiceSkill
    MainStateMachine_NextTurn[[NextTurn]] -->|Exit| MainStateMachine_Pass

    MainStateMachine_Pass[\Pass/]


    subgraph ChoiceSkill
        ChoiceSkill_Initialize[[Initialize]] -->|Pass| ChoiceSkill_LotterySkills

        ChoiceSkill_LotterySkills[[LotterySkills]] -->|Pass| ChoiceSkill_WaitChoiceSkill

        ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) -->|ChoiceSkill| ChoiceSkill_ChoiceSkill
        ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) -->|ReLotterySkill| ChoiceSkill_ReLotterySkill

        ChoiceSkill_ReLotterySkill[[ReLotterySkill]] -->|Pass| ChoiceSkill_LotterySkills
        ChoiceSkill_ReLotterySkill[[ReLotterySkill]] -->|AlreadyReLottery| ChoiceSkill_WaitChoiceSkill

        ChoiceSkill_ChoiceSkill[[ChoiceSkill]] -->|Pass| ChoiceSkill_Pass
        ChoiceSkill_ChoiceSkill[[ChoiceSkill]] -->|InvalidSkillIndex| ChoiceSkill_WaitChoiceSkill

        ChoiceSkill_Pass[\Pass/]


    end
  end

  MainStateMachine_ChoiceSkill --> ChoiceSkill_Initialize
  ChoiceSkill_Pass -->|Pass| MainStateMachine_InGame

  Player ----->|Interaction| MainStateMachine_InGame
  Player ----->|Interaction| ChoiceSkill_WaitChoiceSkill

당신이 프로그래머라면 기획자로부터 위와 같은 플로우차트를 받아본 적이 있을 것입니다. 이러한 상태 전이를 표현한 것이 스테이트 머신입니다.

GS2-Version

Mon, 01 Jan 0001 00:00:00 +0000

애플리케이션 버전이나 추가 에셋의 버전, 이용약관에 동의한 버전 등을 판정하는 기능을 제공합니다.

버전 체크를 통과했을 때, 새로운 임시 GS2 클라이언트ID/시크릿을 발급할 수 있습니다.

이 기능을 이용함으로써, 앱에 내장된 GS2의 클라이언트ID/시크릿은 로그인 및 버전 체크를 수행하는 API만 호출할 수 있는 권한만 가지도록 하고, 버전 체크를 통과한 후에 실제로 게임을 플레이하기에 충분한 권한을 가진 클라이언트ID/시크릿을 받을 수 있도록 할 수 있습니다.

graph TD
  Boot["앱 실행"] --> Login["GS2-Account 로 로그인"]
  Login -- "최소 권한의<br/>클라이언트ID/시크릿" --> Check["GS2-Version<br/>CheckVersion"]
  Check -- "OK" --> Token["새로운 ProjectToken 취득<br/>(원래 권한)"]
  Check -- "Warning" --> Notify["플레이어에게 업데이트 안내"]
  Check -- "Error" --> Force["강제 버전 업"]
  Notify --> Token
  Token --> Game["게임 본편"]

버전 모델

네임스페이스에는 최대 10개의 버전 모델을 선언할 수 있습니다. 버전 체크에는 여러 항목을 설정할 수 있으며, 모든 버전 체크를 통과한 경우에만 체크를 통과할 수 있습니다.