This document describes the GME APIs for range voice.
GME's range voice service is specially developed for PUBG-like games. Unlike a team voice room, a range voice room has the following core capabilities:
Before using range voice, you need to call the SetRangeAudioTeamID
API to set the team ID (TeamID
) and then call the EnterRoom
API to enter the room. If the specified TeamID
is not equal to 0 during room entry, the range voice room mode will be triggered.
When the user enters a range voice room, the user can choose from two voice modes:
Voice Mode | Parameter Name | Feature |
---|---|---|
Everyone | RANGE_AUDIO_MODE_WORLD | In this mode, everyone within a certain range can hear the player as he or she chats with his or her teammates |
Team only | RANGE_AUDIO_MODE_TEAM | Only teammates can hear the user |
In different voice modes, the specific sound reachability is as follows:
a. Players in the same team can hear each other no matter how far apart they are or what voice modes they use.
b. Players in different teams can hear each other only if they are all in the "Everyone" voice mode and within a certain distance.
NoteFor more information on the specific sound reachability of players, please see Appendix.
If the voice mode is set to Everyone (RANGE_AUDIO_MODE_WORLD
), the voice reachability will be subject to the UpdateAudioRecvRange
API.
UpdateAudioRecvRange
API.TeamID
, which must be specified before room entry, in the range voice room is not supported.In a battle royale game, there are four members in a team, and they need to set a Team ID(TeamID). A voice room can contain 100 people, which is, 25 teams. In a game, if a player wants to communicate with a stranger within 10 meters, set the voice distance range to 10, set the voice mode to RANGE_AUDIO_MODE_WORLD
, and turn on the microphone and speaker at the same time. If he wants to communicate with his teammate, set the voice mode: RANGE_AUDIO_MODE_TEAM.
A range voice room is different from a team voice room because you must choose smooth sound quality when entering the range voice room. In addition, SetRangeAudioTeamID
and SetRangeAudioMode
(Can be modified after entering the room) must be called before EnterRoom
is called.
Once you enter the room, call UpdateAudioRecvRange
(once at least), and call UpdateSelfPosition
once per frame.
Note:
- Make sure to follow the flow chart to call the API.
- The blue part of the flow chart shows the process of the range voice.
Initialize the GME and the core API has been called correctly, e.g. the Poll function is called every frame.
###1. Set TeamID[](id: step0)
TeamID
) must be set by calling the API SetRangeAudioTeamID
before EnterRoom
. Otherwise, GME will return the error code AV_ERR_ROOM_NOT_EXITED(1202)
. If you enter the room after exiting the room, please call the API SetRangeAudioTeamID
after exiting the room successfully.Note:This parameter will not be automatically reset to
0
upon room exit. Therefore, once you decide to use range voice, please use this method to setTeamID
before callingEnterRoom
each time.
ITMGContext SetRangeAudioTeamID(int teamID)
Parameter | Type | Description |
---|---|---|
teamID | int | Team ID, which is used for audio upstream/downstream control in range voice. When it is set to 0 (default), the team voice room is used. |
SetRangeAudioMode
either before or after room entry.MODE_WORLD
upon room exit. Therefore, once you decide to call this method, please do so before each call of EnterRoom
.ITMGRoom int SetRangeAudioMode(RANGE_AUDIO_MODE rangeAudioMode)
Parameter | Type | Description |
---|---|---|
rangeAudioMode | int | 0 (MODE_WORLD): everyone; 1 (MODE_TEAM): team only |
Before entering a voice room by calling EnterRoom
, you need to call the following two APIs: SetRangeAudioTeamID
and SetRangeAudioMode
.
ITMGContext.GetInstance(this).EnterRoom(roomId,ITMG_ROOM_TYPE_FLUENCY, authBuffer);
Choose smooth sound quality when entering the voice room, and monitor and process the callback for room entry.
public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
if (ITMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_ENTER_ROOM == type)
{
// Analyze the returned result
int nErrCode = data.getIntExtra("result" , -1);
String strErrMsg = data.getStringExtra("error_info");
if (nErrCode == AVError.AV_OK)
{
//If you receive a success response for room entry, you can proceed with your operation
ScrollView_ShowLog("EnterRoom success");
Log.i(TAG,"EnterRoom success!");
}
else
{
//If you fail to enter the room, you need to analyze the returned error message
ScrollView_ShowLog("EnterRoom fail :" + strErrMsg);
Log.i(TAG,"EnterRoom fail!");
}
}
}
Once you enter the room, call UpdateAudioRecvRange
(once at least), and call UpdateSelfPosition
once per frame.
UpdateSelfPosition
to update the sound source position.ITMGRoom int UpdateAudioRecvRange(int range)
Parameter | Type | Description |
---|---|---|
range | int | Maximum voice reception range in the distance unit used by the game engine |
ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);
The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.
Update
.axisForward
, axisRight
, and axisUp
parameters as specified in the 3D Sound Effect section below.public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
Parameter | Type | Description |
---|---|---|
position | int[] | Local position (forward, right and up) in the world coordinate system |
axisForward | float[] | This parameter can be ignored in this product |
axisRight | float[] | This parameter can be ignored in this product |
axisUp | float[] | This parameter can be ignored in this product |
The range voice feature controls the reachability of sound through distance. It is recommended to use with 3D sound effects if you want a more immersive experience.
If you want to use 3D sound effects while using range voice, please complete the step 1, 2, 3 and then initialize 3D engine and open 3D sound effects.
Note:The green part of the flow chart shows the process of the range voice.
Please see Range Voice Usage and complete step 1,2,3.
This function is used to initialize the 3D sound effect engine and needs to be called after room entry. You must call this API before using the 3D sound effect, even if you want to enable only the 3D sound effect reception rather than the 3D sound effect playback.
public abstract int InitSpatializer(string modelPath)
Parameter | Type | Description |
---|---|---|
modelPath | string | Path of the 3D sound effect resource file. Please download the 3D sound effect model file here (md5: d0b76aa64c46598788c2f35f5a8a8694) and store it locally. Its storage path is passed to the SDK through this parameter. You must use this official file. |
This function is used to enable or disable the 3D sound effect. You can hear the 3D sound after enabling it.
public abstract int EnableSpatializer(bool enable, bool applyToTeam)
Parameter | Type | Description |
---|---|---|
enable | bool | You can hear the 3D sound effect after enabling it, |
applyToTeam | bool | Specifies whether the 3D sound effect is enabled within the team and takes effect only when enable is true |
The IsEnableSpatializer
API can be used to get the 3D sound effect status.
UpdateSelfPosition
to update the sound source position.ITMGRoom int UpdateAudioRecvRange(int range)
Parameter | Type | Description |
---|---|---|
range | int | Maximum voice reception range in the distance unit used by the game engine |
ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);
The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.
Update
.public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
Parameter | Type | Description |
---|---|---|
position | int[] | Local position (forward, right and up) in the world coordinate system |
axisForward | float[] | Forward vector in the local coordinate system |
axisRight | float[] | Right vector in the local coordinate system |
axisUp | float[] | Up vector in the local coordinate system |
Unreal
FVector cameraLocation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraLocation();
FRotator cameraRotation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraRotation();
int position[] = {
(int)cameraLocation.X,
(int)cameraLocation.Y,
(int)cameraLocation.Z };
FMatrix matrix = ((FRotationMatrix)cameraRotation);
float forward[] = {
matrix.GetColumn(0).X,
matrix.GetColumn(1).X,
matrix.GetColumn(2).X };
float right[] = {
matrix.GetColumn(0).Y,
matrix.GetColumn(1).Y,
matrix.GetColumn(2).Y };
float up[] = {
matrix.GetColumn(0).Z,
matrix.GetColumn(1).Z,
matrix.GetColumn(2).Z};
ITMGContextGetInstance()->GetRoom()->UpdateSelfPosition(position, forward, right, up);
Unity
Transform selftrans = currentPlayer.gameObject.transform;
Matrix4x4 matrix = Matrix4x4.TRS(Vector3.zero, selftrans.rotation, Vector3.one);
int[] position = new int[3] {
selftrans.position.z,
selftrans.position.x,
selftrans.position.y};
float[] axisForward = new float[3] {
matrix.m22,
matrix.m02,
matrix.m12 };
float[] axisRight = new float[3] {
matrix.m20,
matrix.m00,
matrix.m10 };
float[] axisUp = new float[3] {
matrix.m21,
matrix.m01,
matrix.m11 };
ITMGContext.GetInstance().GetRoom().UpdateSelfPosition(position, axisForward, axisRight, axisUp);
Player voice reachability in different voice modes is as follows:
In the same team | Within the range | Voice mode | A and B can hear each other |
---|---|---|---|
Yes | Yes | MODE_WORLD | Yes |
MODE_TEAM | Yes | ||
No | MODE_WORLD | Yes | |
MODE_TEAM | Yes | ||
No | Yes | MODE_WORLD | Yes |
MODE_TEAM | No | ||
No | MODE_WORLD | No | |
MODE_TEAM | No |
In the same team | Within the Range | Voice Mode | A and B can hear each other |
---|---|---|---|
Yes | Yes | MODE_WORLD | Yes |
MODE_TEAM | Yes | ||
No | MODE_WORLD | Yes | |
MODE_TEAM | Yes | ||
No | Yes | MODE_WORLD | No |
MODE_TEAM | No | ||
No | MODE_WORLD | No | |
MODE_TEAM | No |
In the 3D sound effect, the sound will begin to attenuate to almost zero as the distance to the sound source exceeds a specified threshold (range/10).
Distance (Unit in Engine) | Attenuation Coefficient |
---|---|
0 < N < range/10 | 1.0 (no attenuation) |
N ≥ range/10 | range/10/N |
Was this page helpful?