API:MumbleLink
GuildWars 2 is exposing a number of real-time contextual data using the MumbleLink specification.
This allows desktop developers to obtain information about the player state without having to query the API
MumbleLink structure
The MumbleLink specification is a Memory Shared File named "MumbleLink" using the following structure:[1]
struct LinkedMem { uint32_t uiVersion; uint32_t uiTick; float fAvatarPosition[3]; float fAvatarFront[3]; float fAvatarTop[3]; wchar_t name[256]; float fCameraPosition[3]; float fCameraFront[3]; float fCameraTop[3]; wchar_t identity[256]; uint32_t context_len; // Despite the actual context containing more data, this value is currently 48. See "context" section below. unsigned char context[256]; wchar_t description[2048]; };
Value updates
- f* vars should be updated every frame, you should safely be able to read from them 50 times a second
context
andidentity
shouldn't change more than a few times per second.
Coordinates
fAvatarPosition
is the position of the player in the coordinate system of the map. While the game uses inches as unit, mumble uses meters.
To use them like other coordinates in the game, they have to be converted to inches first.
API:1/event details#Coordinate recalculation describes the games coordinate systems in detail.
The context
field contains further information needed to process the position, as well as the position in the continent coordinate system.
Usage in Guild Wars 2
In addition to the f* vars, Guild Wars 2 utilizes the context
and identity
fields to store additional data.
context
The context
field holds another structure containing the following data.[2]
Note: Mumble only uses the first context_len
bytes of the data below to determine whether people are on the same server shard or not.
struct MumbleContext { unsigned char serverAddress[28]; // contains sockaddr_in or sockaddr_in6 uint32_t mapId; uint32_t mapType; uint32_t shardId; uint32_t instance; uint32_t buildId; // Additional data beyond the <context_len> bytes the game instructs Mumble to use to distinguish between instances. uint32_t uiState; // Bitmask: Bit 1 = IsMapOpen, Bit 2 = IsCompassTopRight, Bit 3 = DoesCompassHaveRotationEnabled, Bit 4 = Game has focus, Bit 5 = Is in Competitive game mode, Bit 6 = Textbox has focus, Bit 7 = Is in Combat uint16_t compassWidth; // pixels uint16_t compassHeight; // pixels float compassRotation; // radians float playerX; // continentCoords float playerY; // continentCoords float mapCenterX; // continentCoords float mapCenterY; // continentCoords float mapScale; uint32_t processId; uint8_t mountIndex; };
playerX
,playerY
,mapCenterX
,mapCenterY
- These values are not updated whilst in competitive maps.processId
- The ID of the process that last updated the MumbleLink data. If working with multiple instances, this could be used to serve the correct MumbleLink data.mountIndex
(enum) - Identifies whether the character is currently mounted, if so, identifies the specific mount.- 0 = None
- 1 = Jackal
- 2 = Griffon
- 3 = Springer
- 4 = Skimmer
- 5 = Raptor
- 6 = Roller Beetle
- 7 = Warclaw
- 8 = Skyscale
- 9 = Skiff
- 10 = Siege Turtle
identity
The identity
field contains a JSON string with the following fields.[3]
name
(string) – Character nameprofession
(number) – Character's profession- 1 – Guardian
- 2 – Warrior
- 3 – Engineer
- 4 – Ranger
- 5 – Thief
- 6 – Elementalist
- 7 – Mesmer
- 8 – Necromancer
- 9 – Revenant
spec
(number) – Character's third specialization, or 0 if no specialization is present. See /v2/specializations for valid IDs.race
(number) – Character's racemap_id
(number) – Per API:2/mapsworld_id
(number) – Formerly per API:2/worlds; not usable since the switch to the megaserver system (see the bug note below).team_color_id
(number) – Team color per API:2/colors (0 = white)commander
(boolean) – Whether the character has a commander tag activefov
(number) – Vertical field-of-viewuisz
(number) – A value corresponding to the user's current UI scaling.- 0 – Small
- 1 – Normal
- 2 – Large
- 3 – Larger
Example
{ "name": "Irwene", "profession": 4, "spec": 55, "race": 4, "map_id": 50, "world_id": 268435505, "team_color_id": 0, "commander": false, "fov": 0.873, "uisz": 1 }