HL SDK 2.2
This article was originally made available as part of version 2.2 of the Half-Life SDK. As such, all limitations, restrictions, license agreements, copyrights and trademarks from the original document apply here.
Voice API
In this version of the Half-Life engine and SDK, we have added the
ability for players to speak to each other while playing on a server.
MOD authors have full control over which players are allowed to speak to
each other.
There are two new functions in enginefuncs_s you can use to find out which players are allowed to talk to each other and to change who can talk to each other.
qboolean (*pfnVoice_GetClientListening)(int iReceiver, int iSender);
Use pfnVoice_GetClientListening to ask the engine if a certain player is currently allowed to hear another player's speech.
qboolean (*pfnVoice_SetClientListening)(int iReceiver, int iSender, qboolean bListen);
Use pfnVoice_SetClientListening to tell the engine if a certain player is allowed to hear another player's speech.
These two functions are all that the engine exposes to the MOD to
control voice. Most of the code involved in adding voice to a MOD is in
the form of HUD elements and such. A good way to add voice to your mod
and have its functionality appear familiar to players is to use the code
we have for Half-Life Deathmatch in the SDK. We describe the UI code
below.
On the client, there is a new function a MOD can implement that takes this form:
void DLLEXPORT HUD_VoiceStatus(int entindex, qboolean bTalking)
The engine calls this when it detects that players in the game have
started or stopped talking. Entity indices are usually passed into this
function, but there are two special entity indices that are passed in.
- If -1 is passed as the entity index, it means the local player
has pressed their voice key and the engine is now recording their voice
and sending it to the server.
- If -2 is passed as the entity index, it means that the server has received the local client's speech. This is used by CVoiceStatus to display an icon to the user confirming that their voice data got to the server.
SDK MOD Code
This section describes the SDK code that is available to MOD authors to use as a starting point for adding voice to their MOD.
In the MOD game DLL, we have a manager class called CVoiceGameMgr in the game_shared/voice_gamemgr.h file which:
- Receives info from clients describing whose voice they want to hear.
- Asks the MOD which players are allowed to speak to each other
(for example, players on opposite teams usually can't speak to each
other).
To use CVoiceGameMgr, derive a class from IVoiceGameMgrHelper and implement the CanPlayerHearPlayer function so CVoiceGameMgr can ask your MOD which players are allowed to hear each other. Then call its Update, ClientConnected, and ClientCommand functions from your CGameRules class in the corresponding callbacks (Update corresponds to Think).
Most of the game code that we have added to the SDK deals with
presentation of UI elements for players to control who they want to
hear. The core of this code is in the CVoiceStatus class in the game_shared/voice_status.h file. CVoiceStatus
manages a list of who is currently speaking in the game and displays
icons for the speakers on the screen. It also manages, saves, and loads
a list of which players the local player has banned from hearing. This
allows people to completely turn off players that abuse the voice
functionality.
Use GetClientVoiceMgr()
to get a pointer to a global instance of this class. Then call its
member functions from the appropriate places in the rest of your client
DLL code. You can find all the places CVoiceStatus is called from other code by doing a Find In Files through the client DLL files and searching for "GetClientVoiceMgr".
CVoiceStatus makes use of several resources for the HUD display if they exist:
- Sprites/voiceicon.spr - This icon is placed over a player's head when they are speaking.
- Scripts/voicemodel.txt - This file just contains a number telling how high voiceicon.spr should be above a player's head.
- gfx/vgui/icntlk_pl.tga - This icon is shown in the lower-right corner of the screen when a player has started speaking and sending data to the server.
- gfx/vgui/icntlk_sv.tga - This icon is shown
in the lower-right corner of the screen when the server confirms that it
is receiving the local player's voice data.
Console Variables and Commands of Interest
Server Console Variables/Commands
sv_voicecodec - The game
DLL or the server admin can set this cvar to "", in which case none of
the clients will be able to speak to each other or send voice data to
the server.
- voice_serverdebug - Setting this to 1 causes CVoiceGameMgr to print out debug information.
Client Console Variables/Commands
- voice_clientdebug - Setting this to 1 causes CVoiceStatus to print out debug information that can help track down bugs.
- voice_loopback - Setting this to 1
tells the server to send the local player's voice data back so they can
hear themselves speak and hear what they sound like to other players.
- voice_recordtofile and voice_inputfromfile
help if you're testing voice locally and you don't want to have to say
"testing testing 1, 2, 3" into the microphone repeatedly. To use this
functionality, follow these steps:
- Set voice_recordtofile to 1.
- Press your voice record button and say something like "testing 1, 2, 3" into the microphone.
- Set voice_recordtofile back to 0.
- You should now have a new file called voice_micdata.wav sitting in your executables directory. Rename this to voice_input.wav.
- From now on, if you set voice_inputfromfile to 1, it will send
the sound data in voice_input.wav to the server rather than recording
what you're saying into the microphone. Voice_inputfromfile and
voice_loopback are usually used hand-in-hand.
|
