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
- The fAvatar* variables appear to be updated 25 times per second.
- The fCamera* variables appear to be updated every frame.
identity
appears to be updated every frame.context
appears to be updated every frame.- It would appear likely that everything (except the fAvatar* vars) is updated every frame, though this is difficult to determine for some variables as while they may be updated at said frequency the frequency can't be inferred by observing a variable's value if the value can't be changed as frequent or more frequently than the frame rate.
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; };
mapType
(enum) - identifies the map type as follows[3]:- 0 – Redirect (e.g., when logging in while in a PvP match)
- 1 – Character creation
- 2 – Competitive PvP (e.g. Activities)
- 3 – GvG
- 4 – Instances (e.g. Home instances, Personal story instances, Guild halls, Dungeons, Fractals of the Mists, the private variants of Strike Missions, Dragon Response Missions or Dragonstorm)
- 5 – Public (e.g. open world maps like Lion's Arch or Heart of the Mists)
- 6 – Tournament
- 7 – Tutorial
- 8 – User Tournament
- 9 – Eternal Battlegrounds
- 10 – Blue Borderlands
- 11 – Green Borderlands
- 12 – Red Borderlands
- 13 – WvW Reward
- 14 – Obsidian Sanctum
- 15 – Edge of the Mists
- 16 – Public Mini (e.g. Mistlock Sanctuary or the public variants of Strike Missions, Dragon Response Missions, Dragonstorm or Convergences)
- 17 – Big Battle
- 18 – Armistice Bastion
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.[4]
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 }
References
- ^ Mumble Wiki
- ^ This was discovered by various forum users and confirmed by Arena Net Staff [1]
- ^ https://github.com/arenanet/api-cdi/blob/master/mumble.md
- ^ The meaning of some numerical values were found by users on the Guild Wars 2 API development forums [2]