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

# GS2-Matchmaking API 레퍼런스

매치메이킹 기능




대전 상대와 협력 상대를 찾아주는 서비스입니다.

매치메이킹의 흐름은 다음과 같습니다.

호스트가 개더링을 생성<br>
↓<br>
참가자가 조건에 맞는 개더링을 검색<br>
↓<br>
규정 인원이 모이면 매치메이킹 완료

GS2-Matchmaking은 이 흐름 중 `참가자가 조건에 맞는 개더링을 검색`하는 부분에서 최대한 많은 요구 사항을 충족하도록 설계되어 있습니다.<br>
여기에서는 유스케이스를 곁들여 그 설계 예시를 설명합니다.

* 같은 게임 모드를 원하는 상대를 찾고 싶다

게임 내에는 캐주얼 플레이어용과 코어 게이머용, 두 가지 게임 모드가 있습니다.<br>
이러한 플레이어를 섞지 않고 매치메이킹 처리를 하고 싶다고 가정합니다.

개더링을 생성할 때나 개더링을 검색할 때 모두 최대 5개의 속성값을 지정할 수 있습니다.<br>
개더링을 생성할 때는 모집할 플레이어가 가진 속성값의 범위를 지정하고,<br>
개더링을 검색할 때는 자신의 속성값을 지정하여 처리를 요청합니다.

즉, 호스트가 개더링을 생성할 때 `속성값1`에 모집할 게임 모드를 지정하고,<br>
검색하는 쪽도 자신이 참가하고 싶은 게임 모드를 `속성값1`에 지정함으로써, 원하는 게임 모드가 같은 플레이어끼리 매치메이킹됩니다.

* 1에 더해 같은 레벨대의 상대를 찾고 싶다

호스트는 개더링을 생성할 때 `속성값2`에 모집할 레벨의 최솟값과 최댓값을 지정합니다.<br>
검색하는 쪽은 자신의 레벨을 `속성값2`에 지정함으로써, 같은 레벨대의 플레이어끼리 매치메이킹됩니다.

여러 속성값을 지정한 경우에는 모든 속성값의 범위를 충족하는 상대를 찾도록 처리됩니다.

* 2에 더해 대기 시간이 길어졌을 때 모집할 레벨대를 넓히고 싶다

처음에는 좁은 범위로 모집하여 가능한 한 같은 레벨의 플레이어끼리 매치메이킹하지만, 좀처럼 상대를 찾지 못하는 경우 모집할 레벨대를 넓혀서 모집하고 싶다고 가정합니다.<br>
개더링을 생성한 후 약 1분마다 실행되는 GS2-Script 이벤트가 있습니다.<br>
이 스크립트에서 개더링의 속성값 범위를 완화함으로써, 점차 원하는 조건을 완화하는 처리를 구현할 수 있습니다.

* 친구만 참가할 수 있는 개더링 만들기

개더링을 생성할 때 옵션으로 참가를 허용할 사용자 ID 목록을 지정할 수 있습니다.<br>
이를 사용해 친구의 사용자 ID 목록을 지정함으로써 참가자를 제한할 수 있습니다.

* 괴롭힘을 가한 플레이어와 매치메이킹되지 않도록 하고 싶다

개더링 생성 시·검색 시에 사용자 ID의 블랙리스트를 지정할 수 있습니다.<br>
검색 시 지정한 블랙리스트는 조건에 일치하는 개더링을 발견하여 참가한 개더링의 블랙리스트에 추가됩니다.<br>
검색할 때 자신이 블랙리스트에 포함되어 있는 경우에는 매치메이킹 대상에서 제외됩니다.

* 역할별 매치메이킹

게임에 따라서는 방어역 1명, 회복역 1명, 공격역 2명으로 매치메이킹을 하고 싶은 경우가 있습니다.<br>
이때 사용할 수 있는 것이 `역할 속성`입니다.

방어역으로 `tank`를, 회복역으로 `healer`를, 공격역으로 `attacker`라는 역할을 가정합니다.<br>
개더링을 생성할 때 각 역할의 모집 인원을 설정합니다.<br>
개더링 검색 시 자신의 역할을 설정함으로써, 해당 역할에 여유가 있는 개더링만 참가 가능한 개더링으로 처리됩니다.

모집 역할에는 별칭(에일리어스)을 설정할 수도 있습니다.<br>
예를 들어, `tank`를 더 구체적인 역할로 표현하여 `paladin`, `warrior`, `dark_knight` 중 하나로 개더링 검색을 수행한다고 가정합니다.<br>
개더링을 생성할 때 `tank`의 별칭으로 `paladin`과 `dark_knight`를 지정한 경우, `warrior`는 참가할 수 없는 개더링을 만들 수 있습니다.

* 추가 모집

매치메이킹 완료 후 1명이 이탈하여 1명만 보충하고 싶을 때 사용합니다.<br>
이때 사용하는 것이 파티 토큰입니다. 파티 토큰을 발급하려면 파티를 편성하는 플레이어의 플레이어 토큰이 필요합니다.<br>
플레이어 토큰은 플레이어 본인이 자신을 대신하여 파티 대표자가 매치메이킹을 수행하는 것을 허용하는 토큰으로, 3분간의 유효기간이 있습니다.<br>
파티 멤버는 각자 플레이어 토큰을 발급하는 API에 요청하여 플레이어 토큰을 입수하고, 파티 대표자에게 전송합니다.<br>
파티 대표자는 파티 멤버로부터 플레이어 토큰을 받아 3분 이내에 파티 토큰 발급 API로 전송함으로써 파티 토큰을 입수할 수 있습니다.<br>
파티 토큰에는 10분의 유효기간이 있으며, 10분 이내에 파티 토큰을 사용하여 개더링 생성 처리 또는 개더링 검색 처리를 호출합니다.<br>
이렇게 함으로써 파티 멤버 전원이 참가한 상태의 개더링을 생성하거나, 파티 멤버 전원이 참가할 수 있는 개더링에 참가할 수 있습니다.

* 파티 간 매치메이킹

4 대 4로 대전하는 게임에서, 사전에 편성한 파티를 아군과 적군으로 분산시키지 않고 대전하고 싶을 때가 있습니다.<br>
예를 들어, 사전에 3명으로 편성한 파티와 사전에 4명으로 편성한 파티, 그리고 1명의 솔로 플레이어를 매치메이킹하여,<br>
`사전에 3명으로 편성한 파티 + 1명의 솔로 플레이어` vs `사전에 4명으로 편성한 파티`라는 대전을 실현하고 싶다고 가정합니다.<br>
이러한 경우에는 먼저 4명 단위의 매치메이킹을 실행합니다.<br>
그러면 `3명으로 편성한 파티 + 1명의 솔로 플레이어`와 `사전에 4명으로 편성한 파티`라는 2개의 개더링이 만들어집니다.<br>
그 후 각 파티의 대표자가 정원 2명의 매치메이킹을 수행하여 파티끼리 매치메이킹됩니다.<br>
이렇게 함으로써 `사전에 3명으로 편성한 파티 + 1명의 솔로 플레이어` vs `사전에 4명으로 편성한 파티`를 실현할 수 있습니다.

* 매치메이킹 중 플레이어 간 통신

매치메이킹이 완료되지 않은 상태에서 플레이어 간의 소통이 필요한 경우가 있습니다.<br>
GS2-Matchmaking에서는 개더링 생성 시 플레이어 간 통신 수단으로 두 가지 방법을 제공합니다.

- GS2-Chat과 연동한 채팅방 생성
- GS2-Realtime과 연동한 게임 서버 기동

모집이 끝나지 않은 상태에서도 플레이어 간 메타데이터를 낮은 빈도로 교환하고 싶은 경우에는 전자를,<br>
모집하면서 NPC를 포함시키거나 인원이 부족한 상태에서 게임을 진행하고 싶은 경우에는 후자를 사용합니다.

저빈도·고빈도를 판단하는 기준으로 사용할 수 있는 것이 GS2-Chat이 가진 제한입니다.<br>
GS2-Chat은 하나의 채팅방에 대해 초당 3회만 발언할 수 있습니다. 이 빈도를 초과하는 경우에는 GS2-Realtime을 사용하십시오.

* 매치메이킹 완료 후 처리 방법

매치메이킹이 완료되었을 때 `GS2-Gateway를 사용한 게임 내 푸시 알림` 또는 `GS2-JobQueue에 의한 작업 등록`으로 플레이어에게 매치메이킹 완료를 알릴 수 있습니다.<br>
또한 GS2-Script를 사용하여 임의의 스크립트를 실행할 수도 있습니다.<br>
GS2-Realtime을 사용하여 매치메이킹 후의 대전·협력 플레이를 실현하는 경우에는, 매치메이킹 완료 후 실행되는 GS2-Script에서<br>
GS2-Realtime의 개더링을 생성하고, 해당 개더링의 IP 주소·포트 정보를 `GS2-Gateway를 사용한 게임 내 푸시 알림` 또는 `GS2-JobQueue에 의한 작업 등록`을 사용하여 알림으로써 게임 서버로 유도할 수 있습니다.

[마이크로서비스 소개 / GS2-Matchmaking](../../microservices/matchmaking)



- [GS2-Matchmaking Deploy/CDK 레퍼런스](/ko/api_reference/matchmaking/deploy/)
  
- [GS2-Matchmaking SDK API 레퍼런스](/ko/api_reference/matchmaking/sdk/)
  
- [GS2-Matchmaking SDK for Game Engine API 레퍼런스](/ko/api_reference/matchmaking/game_engine/)
  
- [GS2-Matchmaking 마스터 데이터 레퍼런스](/ko/api_reference/matchmaking/master_data/)
  
- [GS2-Matchmaking 스크립트 트리거 레퍼런스](/ko/api_reference/matchmaking/script/)
  
- [GS2-Matchmaking 트랜잭션 액션](/ko/api_reference/matchmaking/stamp_sheet/)