개인 매치 메이킹
개인 매치 메이킹은 한 명의 유저가 혼자 게임에 참여하고 싶은 경우 사용합니다.
SDK에서 매치 메이킹 동작 흐름¶
Hive SDK로 개인 매치 메이킹 구현 시, 전체적인 동작 흐름은 아래의 도식도와 같습니다.
매칭 요청¶
사용자별로 매칭을 요청합니다.
요청 전에 matchId
에 해당하는 매치 정보를 Hive 콘솔에 등록해야 합니다.
매칭 요청 시, 매치에 사용할 점수 point
(0부터 10^10 미만 정수)와 매치에 사용할 부가 정보 extraData
(닉네임, 레벨, 국가 등 256자 이내 정보)를 인자로 요청합니다.
Warning
이미 매칭을 요청한 상태에서 다시 매칭을 요청하면, 기존 매칭이 중단되지 않은 채 콜백 함수에서는 에러값(MatchMakingResponseError
)을 반환합니다. 따라서 반드시 매칭 상태 확인으로 먼저 매칭 상태를 확인 후 매칭을 요청하세요.
다음은 매칭 요청 예제 코드입니다.
API Reference: MatchMaking .requestMatchMaking
using hive;
int matchId = 25; // 콘솔에 등록한 matchId
int point = 300; // 매치 사용 점수
string extraData = "your extraData"; // 매치에 사용할 부가 정보
MatchMaking.requestMatchMaking(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingData data) => {
if (result.isSuccess()) {
// call successful
} else {
// Call failed. See error code below
}
});
API Reference: MatchMaking ::requestMatchMaking
#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;
int matchId = 25; // 콘솔에 등록한 matchId
int point = 300; // 매치 사용 점수
string extraData = "your extraData"; // 매치에 사용할 부가 정보
MatchMaking::requestMatchMaking(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingData data) {
if (result.isSuccess()) {
// call successful
} else {
// Call failed. See error code below
}
});
API Reference: MatchMaking.requestMatchMaking
import com.hive.MatchMaking
import com.hive.ResultAPI
val matchId = 25 // 콘솔에 등록한 matchId
val point = 300 // 매치 사용 점수
val extraData = "your extraData"; // 매치에 사용할 부가 정보
MatchMaking.requestMatchMaking(matchId, point, extraData, object : MatchMaking.MatchMakingDataListener {
override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
if (result.isSuccess) {
// call successful
} else {
// Call failed. See error code below
}
}
})
API Reference: MatchMaking .requestMatchMaking
import com.hive.MatchMaking;
import com.hive.ResultAPI;
int matchId = 25; // 콘솔에 등록한 matchId
int point = 300; // 매치 사용 점수
String extraData = "your extraData"; // 매치에 사용할 부가 정보
MatchMaking.INSTANCE.requestMatchMaking(matchId, point, extraData, (result, data) -> {
if (result.isSuccess()) {
// call successful
} else {
// Call failed. See error code below
}
});
API Reference: MatchMakingInterface.requestMatchMaking
import HIVEService
let matchId: Int = 25 // 콘솔에 등록한 matchId
let point: Int = 300 // 매치 사용 점수
let extraData: String? = "your extraData" // 매치에 사용할 부가 정보
MatchMakingInterface.requestMatchMaking(matchId: matchId, point: point, extraData: extraData) { result, data in
if result.isSuccess() {
// call successful
}
else {
// Call failed. See error code below
}
}
API Reference: HIVEMatchMaking requestMatchMaking
#import "HIVEService.h"
NSInteger matchId = 25; // 콘솔에 등록한 matchId
NSInteger point = 300; // 매치 사용 점수
NSString *extraData = @"your extraData"; // 매치에 사용할 부가 정보
[MatchMakingInterface requestMatchMakingWithMatchId:matchId
point:point
extraData:extraData
completion:^(HIVEResult *result, id data) {
if ([result isSuccess]) {
// call successful
} else {
// Call failed. See error code below
}
}];
requestMatchMatking()
, getRequestingStatus()
메서드 호출의 결과로 MatchMakingData
객체를 전달합니다.
MatchMakingData 오브젝트의 구성¶
매칭 요청, 매칭 상태 확인 요청에 대한 응답으로 전달되는 오브젝트입니다. 요청 시 입력한 정보와 매칭 결과 정보를 포함합니다.
필드명 | 설명 | 타입 |
---|---|---|
requestPlayerId | 매치 요청한 사용자 playerId | Long |
requestGameIndex | 매치 게임 인덱스 | Int |
requestMatchId | 요청한 매치 아이디 (Hive 콘솔에 등록된 매치 형태) | Int |
requestStatus | 매치 요청 상태 (requested : 매칭을 요청함, notRequested : 요청하지 않음(혹은, 이미 매칭되어 진행중인 매칭이 없음)) | String |
requestTimeUtc | 매치 요청 시각 (ex : 2025-01-02T11:13:50.96) | String |
requestPoint | 매치 점수 | Int |
requestExtraData | 매치 요청시 전달한 기타 정보 (요청 시 extraData를 사용한 경우 존재) | String |
matchingStatus | 매치 진행 상태 (matchingInProgress : 매칭 진행중, timeout : 제한 시간 내 매칭이 이루어 지지 않음, matched : 매칭이 성사됨) | String |
matchingType | 팀 참가 또는 개인 참가 여부 (matchingStatus가 matched인 경우 존재) (team : 팀, player : 개인, unknown : 매칭 확인이 되지 않은 경우) | String |
matchingId | 성사된 매칭에 부여된 id (matchingStatus가 matched인 경우 존재) (ex : 539:21_2025-01-02T11:45:55.25_1) | String |
matchingPlayerInfoList | 매칭된 유저들의 정보 MatchingResultPlayerInfo 리스트 (matchingStatus가 matched인 경우, 개인 참가시 존재) | Array |
matchingTeamInfoList | 매칭이 성사시 팀 정보 MatchingResultTeamInfo 리스트 (matchingStatus가 matched인 경우, 팀 참가시 존재) | Array |
MatchingResultTeamInfo 오브젝트의 구성¶
팀 매치에 참가하고 매칭이 성사되었을 때 matchingStatus가 matched인 경우 전달되는 오브젝트입니다. 팀 인덱스와 팀에 속한 유저의 정보가 포함되어 있습니다.
필드명 | 설명 | 타입 |
---|---|---|
teamIndex | 팀 고유 인덱스 | Int |
playerInfos | 팀에 속한 유저들의 정보 MatchingResultPlayerInfo 리스트 | Array |
Note
개인 매칭 요청 시 개인 매치, 팀 매치 모두 참가가 가능며, 매치 결과에 따라 위 오브젝트에 해당하는 matchingPlayerInfoList
혹은 matchingTeamInfoList
가 전달됩니다.
MatchingResultPlayerInfo 데이터의 구성¶
개인 매치에 참가하고 매칭이 성사되었을 때 matchingStatus가 matched인 경우 전달되는 오브젝트입니다. 매치에 참가한 유저의 정보가 포함되어 있습니다.
필드명 | 설명 | 타입 |
---|---|---|
playerId | 매칭된 유저의 playerId | Long |
point | 매칭된 유저의 point | Int |
extraData | 매칭된 유저가 전달한 기타 정보 (해당 유저가 요청 시 extraData를 사용한 경우 존재) | String |
매칭 상태 확인¶
개인 매치에 참여한 유저의 매칭 상태를 확인합니다.
매칭 상태 확인 메소드 호출 시, 아래의 3가지 매칭 상태 중 1가지를 반환합니다.
- 매칭 진행중 (matchingStatus : matchingInProgress)
- 매칭 성사 (matchingStatus : matched)
- 시간 초과 (matchingStatus : timeout)
다음은 매칭 상태 확인 예제 코드입니다.
API Reference: MatchMaking .getRequestingStatus
API Reference: MatchMaking ::getRequestingStatus
#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;
int matchId = 25; // 콘솔에 등록한 matchId
MatchMaking::getRequestingStatus(matchId, [=](ResultAPI const & result, MatchMakingData data) {
if (result.isSuccess()) {
// call successful
} else {
// Call failed. See error code below
}
});
API Reference: MatchMaking.getRequestingStatus
import com.hive.MatchMaking
import com.hive.ResultAPI
val matchId = 25 // 콘솔에 등록한 matchId
MatchMaking.getRequestingStatus(matchId, object : MatchMaking.MatchMakingDataListener {
override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
if (result.isSuccess) {
// call successful
} else {
// Call failed. See error code below
}
}
})
API Reference: MatchMaking.INSTANCE .getRequestingStatus
API Reference: MatchMakingInterface.getRequestingStatus
API Reference: HIVEMatchMaking getRequestingStatus
매칭 진행 중¶
매칭 상태가 매칭 진행중이면 해당 매칭 상태 확인 메서드를 반복해서 호출하여 매칭 성사 상태가 되었는지 확인해야 합니다.
반복 호출 주기는 3~10초 간격으로 호출하는 것을 권장합니다. 앱의 구현 특성에 따라 시간 간격을 늘리는 것도 가능합니다.
매칭 성사¶
매칭 상태가 매칭 성사이면 개발사 게임을 실행합니다. 즉, Hive SDK를 통해 게임을 함께 할 유저들이 연결된 상태로 매칭된 유저들은 개발사 게임에 참여할 수 있습니다.
시간 초과¶
매칭 상태가 타임아웃(matchingStatus: timeout
)이면 기존의 매칭을 삭제하고 다시 매칭을 요청해야 합니다.
매칭 삭제¶
기존 매칭을 삭제합니다.
아래의 경우 중 하나 이상에 해당할 때, 매칭을 삭제해야 합니다.
- 사용자가 매칭을 취소했을 경우
- 매칭 상태가 타임아웃인 경우 (matchingStatus : timeout)
-
유저 간 게임이 정상적으로 완료된 경우
※ 게임 서버 또는 게임 클라이언트에 게임 결과(순위, 점수, 승패 여부 등) 데이터를 업데이트한 이후에 매칭 삭제를 요청해야함
다음은 매칭 삭제 예제 코드입니다.
API Reference: MatchMaking .deleteRequesting
API Reference: MatchMaking ::deleteRequesting
API Reference: MatchMaking.deleteRequesting
import com.hive.MatchMaking
import com.hive.ResultAPI
val matchId = 25 // 콘솔에 등록한 matchId
MatchMaking.deleteRequesting(matchId, object : MatchMaking.MatchMakingResultListener {
override fun onMatchMakingResult(result: ResultAPI) {
if (result.isSuccess) {
// call successful
} else {
// Call failed. See error code below
}
}
})
API Reference: MatchMaking.INSTANCE .deleteRequesting
API Reference: MatchMakingInterface.deleteRequesting
API Reference: HIVEMatchMaking deleteRequesting
에러 코드¶
Error Code | Message | Description |
NEED_INITIALIZE | MatchMakingNotInitialized | SDK Setup이 되어 있지 않은 경우 (AuthV4.setup) |
INVALID_SESSION | MatchMakingNeedSignIn | AuthV4 Sign-In이 되어 있지 않은 경우 |
RESPONSE_FAIL | MatchMakingResponseError | - API 호출 시 잘못된 파라미터로 실패한 경우 - 네트워크 문제로 실패한 경우 - 이미 매칭 요청된 상태에서 다시 매칭 요청한 경우 - 요청되지 않은 매칭를 삭제 요청한 경우 |