API:MumbleLink

From Guild Wars 2 Wiki
Jump to navigationJump to search

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 always 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 and identity 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 with other coordinates in the game, they have to be converted first by multiplying them by 39.3701. 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 uses the context_len value above in conjunction with the data below to uniquely identify people on the same server shards. Mumble will only use the first context_len bytes of data for this purpose. Beyond that data, we are free to add additional data, useful for other addon developers.

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 48 bytes Mumble uses for identification
    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;
};
  • 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

identity

The identity field contains a JSON string with the following fields.[3]

  • 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
  • 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
}

See also

References

  1. ^ Mumble Wiki
  2. ^ This was discovered by various forum users and confirmed by Arena Net Staff [1]
  3. ^ The meaning of some numerical values were found by users on the Guild Wars 2 API development forums [2]