Difference between revisions of "Link"

From Mumble Wiki
Jump to: navigation, search
(Linking a game to Mumble)
(Initialization: Add C++ syntax highlight)
Line 12: Line 12:
Somewhere in your game initialization, add these lines of code:
Somewhere in your game initialization, add these lines of code:
<syntaxhighlight lang="cpp" line>
#ifdef _WIN32
#ifdef _WIN32
#include <windows.h>
#include <windows.h>
Line 80: Line 80:
Then, for each frame, do the following:
Then, for each frame, do the following:
<syntaxhighlight lang="cpp" line>
void updateMumble() {
void updateMumble() {
if (! lm)
if (! lm)
Line 138: Line 138:
lm->context_len = 16;
lm->context_len = 16;
== Coordinate system ==
== Coordinate system ==

Revision as of 22:19, 16 July 2016

Linking a game to Mumble

If you can change the source code of the game you want to add positional audio support to you can save yourself the trouble of creating your own plugin by using the facilities supplied by the Link plugin.

All code listed below is of public domain and can be used, shared or modified freely.

Note: Please don't forget to add your game to the list of supported games. If your game was already supported by a dedicated plugin, update the list and ask here to retract it.
You can also ask in the same page to add or update your game in the list, if you don't want to create a Wiki account.


Somewhere in your game initialization, add these lines of code:

 1 #ifdef _WIN32
 2 	#include <windows.h>
 3 #else
 4 	#include <sys/mman.h>
 5 	#include <fcntl.h> /* For O_* constants */
 6 #endif // _WIN32
 9 struct LinkedMem {
10 #ifdef _WIN32
11 	UINT32	uiVersion;
12 	DWORD	uiTick;
13 #else
14 	uint32_t uiVersion;
15 	uint32_t uiTick;
16 #endif
17 	float	fAvatarPosition[3];
18 	float	fAvatarFront[3];
19 	float	fAvatarTop[3];
20 	wchar_t	name[256];
21 	float	fCameraPosition[3];
22 	float	fCameraFront[3];
23 	float	fCameraTop[3];
24 	wchar_t	identity[256];
25 #ifdef _WIN32
26 	UINT32	context_len;
27 #else
28 	uint32_t context_len;
29 #endif
30 	unsigned char context[256];
31 	wchar_t description[2048];
32 };
34 LinkedMem *lm = NULL;
37 void initMumble() {
39 #ifdef _WIN32
40 	HANDLE hMapObject = OpenFileMappingW(FILE_MAP_ALL_ACCESS, FALSE, L"MumbleLink");
41 	if (hMapObject == NULL)
42 		return;
45 	if (lm == NULL) {
46 		CloseHandle(hMapObject);
47 		hMapObject = NULL;
48 		return;
49 	}
50 #else
51 	char memname[256];
54 	int shmfd = shm_open(memname, O_RDWR, S_IRUSR | S_IWUSR);
56 	if (shmfd < 0) {
57 		return;
58 	}
62 	if (lm == (void *)(-1)) {
63 		lm = NULL;
64 		return;
65 	}
66 #endif
67 }

Then, for each frame, do the following:

 1 void updateMumble() {
 2 	if (! lm)
 3 		return;
 5 	if(lm->uiVersion != 2) {
 6 		wcsncpy(lm->name, L"TestLink", 256);
 8 		lm->uiVersion = 2;
 9 	}
10 	lm->uiTick++;
12 	// Left handed coordinate system.
13 	// X positive towards "right".
14 	// Y positive towards "up".
15 	// Z positive towards "front".
16 	//
17 	// 1 unit = 1 meter
19 	// Unit vector pointing out of the avatar's eyes aka "At"-vector.
20 	lm->fAvatarFront[0] = 0.0f;
21 	lm->fAvatarFront[1] = 0.0f;
22 	lm->fAvatarFront[2] = 1.0f;
24 	// Unit vector pointing out of the top of the avatar's head aka "Up"-vector (here Top points straight up).
25 	lm->fAvatarTop[0] = 0.0f;
26 	lm->fAvatarTop[1] = 1.0f;
27 	lm->fAvatarTop[2] = 0.0f;
29 	// Position of the avatar (here standing slightly off the origin)
30 	lm->fAvatarPosition[0] = 0.001f;
31 	lm->fAvatarPosition[1] = 0.0f;
32 	lm->fAvatarPosition[2] = 0.5f;
34 	// Same as avatar but for the camera.
35 	lm->fCameraPosition[0] = 0.0f;
36 	lm->fCameraPosition[1] = 0.0f;
37 	lm->fCameraPosition[2] = 0.0f;
39 	lm->fCameraFront[0] = 0.0f;
40 	lm->fCameraFront[1] = 0.0f;
41 	lm->fCameraFront[2] = 1.0f;
43 	lm->fCameraTop[0] = 0.0f;
44 	lm->fCameraTop[1] = 1.0f;
45 	lm->fCameraTop[2] = 0.0f;
47 	// Identifier which uniquely identifies a certain player in a context (e.g. the ingame name).
48 	wcsncpy(lm->identity, L"Unique ID", 256);
52 	lm->context_len = 16;
53 }

Coordinate system




Tip: If your game uses a 3D positional audio API such as OpenAL you may want to take a look at the code where the listener gets updated since these APIs usually require the same vectors.

f* variables



Icons oxygen 48x48 actions view-pim-notes.png


Icons oxygen 48x48 actions view-pim-notes.png

The context string is used to determine which users on a Mumble server should hear each other positionally. If context between two Mumble users does not match the positional audio the data is stripped server-side and voice will be received as non-positional.



Icons oxygen 48x48 actions view-pim-notes.png



For example by including team information in the identity a script on the Mumble server can move players into team channels automatically. Additional information like squad number, squad leader status and so on can be used to trigger even more behavior like automatically maintaining a leadership structure inside Mumble which is kept in-sync with in-game state. E.g. someone is elected squad leader and now can whisper to all other squad leaders and the team leader. For an example of such a server-side script see the Battlefield 2 mumo plugin.


Tip: If identity is a regular string (not wide char) you have to convert it, e.g. like this:

std::string playername = client->getEnv().getLocalPlayer()->getName();
std::wstring wplayername;
wplayername.assign(playername.begin(), playername.end());
wcsncpy(mumblelm->identity, wplayername.c_str(), 256);