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

All values are updated every frame.
fAvatarPosition uses an estimated position instead of the real one, which synchronises with an update rate of 25 times per second.
The updates aren't directly tied to the rendering of the frame as the engine tick and the frame presentation are on different threads.

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 name
profession (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 race
- 0 – Asura
- 1 – Charr
- 2 – Human
- 3 – Norn
- 4 – Sylvari
map_id (number) – Per API:2/maps
world_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 active
fov (number) – Vertical field-of-view
uisz (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]

Notes

API bug:

The value exposed by world_id was not updated following the introduction of the megaserver system, and currently shows the same value as the shardId that can be found in the context field. (ref)