Difference between revisions of "Link"

From Mumble Wiki
Jump to: navigation, search
(Initialization: Add C++ syntax highlight)
Line 175: Line 175:
<b>Tip:</b> If identity is a regular string (not wide char) you have to convert it, e.g. like this:  
<b>Tip:</b> If identity is a regular string (not wide char) you have to convert it, e.g. like this:  
<syntaxhighlight lang="cpp" line>
std::string playername = client->getEnv().getLocalPlayer()->getName();
std::string playername = client->getEnv().getLocalPlayer()->getName();
std::wstring wplayername;
std::wstring wplayername;
wplayername.assign(playername.begin(), playername.end());
wplayername.assign(playername.begin(), playername.end());
wcsncpy(mumblelm->identity, wplayername.c_str(), 256);
wcsncpy(mumblelm->identity, wplayername.c_str(), 256);
[[Category:Documentation English]]
[[Category:Documentation English]]

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;
44 	lm = (LinkedMem *) MapViewOfFile(hMapObject, FILE_MAP_ALL_ACCESS, 0, 0, sizeof(LinkedMem));
45 	if (lm == NULL) {
46 		CloseHandle(hMapObject);
47 		hMapObject = NULL;
48 		return;
49 	}
50 #else
51 	char memname[256];
52 	snprintf(memname, 256, "/MumbleLink.%d", getuid());
54 	int shmfd = shm_open(memname, O_RDWR, S_IRUSR | S_IWUSR);
56 	if (shmfd < 0) {
57 		return;
58 	}
60 	lm = (LinkedMem *)(mmap(NULL, sizeof(struct LinkedMem), PROT_READ | PROT_WRITE, MAP_SHARED, shmfd,0));
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);
 7 		wcsncpy(lm->description, L"TestLink is a test of the Link plugin.", 2048);
 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);
49 	// Context should be equal for players which should be able to hear each other positional and
50 	// differ for those who shouldn't (e.g. it could contain the server+port and team)
51 	memcpy(lm->context, "ContextBlob\x00\x01\x02\x03\x04", 16);
52 	lm->context_len = 16;
53 }

Coordinate system

Mumble, like most sound systems, uses a left handed coordinate system (see this for a visual representation). If you imagine yourself looking over a large empty field; X increases towards your right, Y increases above your head, and Z increases in front of you. In other words, if we place origin in your chest and you stretch your arms out to your sides, your right hand will be (1,0,0), your left hand will be (-1,0,0) and your head will be (0,0.2,0). If you then stretch your arms out in front of you instead, they'll become (0,0,1).

We need three vectors. First is the position vector. This should be in meters, so you may need to scale it. The reason: If it is not in meters, distance attenuation will be different to the other games/plugins, meaning users will have a bad experience with positional audio (audio configuration is dependant on a common distance measurement).

The next two vectors are the heading. These should be unit vectors (length one), and should be perpendicular (to one another). The first vector is the front vector, which is simply the direction you are looking at. The second is the top vector, which is an imaginary vector pointing straight out the top of your head. If you do not supply a top vector, Mumble will assume you have a “Y-is-up” coordinate system and that the user can not tilt his head, and then compute the top vector based on that.

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

fAvatarPosition should be the player position in 3D space, to disable the transmission of positional information alongside audio without unlinking the plugin set x,y,z of the tuple to zero. fAvatarTop and fAvatarFront should be the orientation. The coordinate system is a left-handed one, and the units are in meters.

If the camera of your game is not independent of the avatar be sure to copy the avatar values over to the fCameraPosition|Top|Front variables. If the camera moves independent of the avatar these values should contain the position, top- and front-vector of the camera.

Icons oxygen 48x48 actions view-pim-notes.png
Mumble fetches these values 50 times a second, so please update them every frame.


Icons oxygen 48x48 actions view-pim-notes.png
The context does not need to be updated every single frame. It shouldn't change more than a few times per second if at all during a game.

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.

Accordingly the context should only match for players on the same server in the same game on the same map. Whether to include things like team in this string depends on the game itself. When in doubt err on the side of including less. This gives more flexibility later on.


Icons oxygen 48x48 actions view-pim-notes.png
The identity does not need to be updated every single frame. It shouldn't change more than a few times per second if at all during a game.

Identity should contain a string which uniquely identifies the player in the given context. This is usually satisfied by the in-game player name or the players ID (player-/connection-ID on the server or a global ID).

Additionally the identity can contain any additional information about the player that might be interesting for the mumble server.

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.

We recommend using an easily parseable format like JSON or CSV for encoding the information but this is up to the game. Remember that the link structures only allow for 256 characters of identity data.

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

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