Telemetry Models

The chicken_dinner package provides several objects for interfacing with PUBG match telemetry data, events, and objects.

Match Telemetry

The Telemetry class wraps the telemetry JSON response from the PUBG API. There are a number of methods for extracting specific events and formatted data for certain events like player positions and circle positions.

The purpose of most of the functionality here is to provide assistance to the playback visualizer, invoked by the method: playback_animation().

See Playback Visualizations for more details.

Note

  • Player positions are logged cyclically, approximately once every 10 seconds.

  • Circle positions are logged in the LogGameStatePeriodic events.

  • The elapsedTime key is used for time tracking the match events in this class.

  • Each event also provides a _D key which contains a UTC timestamp.

  • Telemetry instances store the raw deserialized response in the response attribute. Operationally, the class uses the telemetry attribute which maintains the response in a case-insensitive dict-like structure. The reason for this is because the key casing in responses are different between PC and XBox platforms.

  • The official api-asset repository contains more details on values related to events.

class chicken_dinner.models.telemetry.Telemetry(pubg, url, telemetry_json=None, shard=None, map_assets=False)[source]

Telemetry model.

Parameters
  • pubg – a PUBG instance

  • url (str) – the url for this telemetry

  • telemetry_json (list) – (optional) the raw telemetry response

  • shard (str) – the shard for the match associated with this telemetry

  • map_assets (bool) – whether to map asset ids to named values, e.g. map Item_Weapon_AK47_C to AKM.

care_package_positions(land=True)[source]

Get the crate positions for the match.

Returns the crate positions for a match as a list of tuples. Each tuple has four elements being (t, x, y, z) coordinates where t is taken from the “elapsedTime” field in the JSON response.

circle_positions()[source]

Get the circle positions for the match.

Returns a dict of circle positions with keys being circle colors and values being a list of tuples. Each tuple has five elements being (t, x, y, z, r) coordinates where t is taken from the “elapsedTime” field in the JSON response and r is the circle radius.

The circle colors are “white”, “blue”, and “red”

damage_done(player=None, combat_only=True, distribution=False)[source]

Damage done by each player in the match.

Parameters
  • player (str) – a player name to filter on

  • combat_only (bool) – return only PvP damage (default True)

  • distribution (bool) – return a player to player distribution of damage for the match if true. if false return total damage done by each player. (default False)

damage_taken(player=None, combat_only=True, distribution=False)[source]

Damage taken by each player in the match.

Parameters
  • player (str) – a player name to filter on

  • combat_only (bool) – return only PvP damage (default True)

  • distribution (bool) – return a player to player distribution of damage for the match if true. if false return total damage taken by each player. (default False)

event_types()[source]

A sorted list of event type names from this telemetry.

events = None

Snake cased object-attribute models for telemetry events and objects

filter_by(event_type=None)[source]

Get a list of telemetry events for a specific event type.

Parameters

event_type – the event type to filter

classmethod from_json(telemetry_json, pubg=None, url=None, shard=None)[source]

Construct an instance of telemetry from the json response.

classmethod from_match_id(match_id, pubg, shard=None)[source]

Construct an instance of telemetry from a match id.

is_pc = None

Whether this game was played on PC

is_xbox = None

Whether this game was played on xbox

killed()[source]

A list of player names of all killed players this match.

map_assets = None

Whether asset ids are mapped to names

map_id()[source]

Get the map id for PC matches. None if not PC.

map_name()[source]

Get the map name for PC matches. None if not PC.

match_id()[source]

The match id for the match.

match_length()[source]

The length of the match in seconds.

num_players()[source]

Number of participants in this match.

num_teams()[source]

Number of teams (rosters) in this match.

platform = None

The platform for this game, “pc” or “xbox”

playback_animation(filename='playback.html', **kwargs)[source]

Generate a playback animation from the telemetry data.

Generate an HTML5 animation using matplotlib and ffmpeg. Requires installation via pip install chicken-dinner[visual].

Parameters
  • filename – a file to generate for the animation (default “playback.html”)

  • labels (bool) – whether to label players by name

  • disable_labels_after (int) – if passed, turns off player labels after number of seconds elapsed in game

  • label_players (list) – a list of strings of player names that should be labeled

  • dead_players (bool) – whether to mark dead players

  • dead_player_labels (list) – a list of strings of players that should be labeled when dead

  • zoom (bool) – whether to zoom with the circles through the playback

  • zoom_edge_buffer (float) – how much to buffer the blue circle edge when zooming

  • use_hi_res (bool) – whether to use the hi-res image, best to be set to True when using zoom

  • use_no_text (bool) – whether to use the image with no text for town/location names

  • color_teams (bool) – whether to color code different teams

  • highlight_teams (list) – a list of strings of player names whose teams should be highlighted

  • highlight_players (list) – a list of strings of player names who should be highlighted

  • highlight_color (str) – a color to use for highlights

  • highlight_winner (bool) – whether to highlight the winner(s)

  • label_highlights (bool) – whether to label the highlights

  • care_packages (bool) – whether to show care packages

  • damage (bool) – whether to show PvP damage

  • end_frames (int) – the number of extra end frames after game has been completed

  • size (int) – the size of the resulting animation frame

  • dpi (int) – the dpi to use when processing the animation

  • interpolate (bool) – use linear interpolation to get frames with second-interval granularity

  • interval (int) – interval between gameplay frames in seconds

  • fps (int) – the frames per second for the animation

player_damages(include_pregame=False)[source]

Get the player damages for the match.

Returns a dict of attacker players as keys and values of damage attacker and victim positions with the values tuples. Each tuple has seven elements being (t, x_a, y_a, z_a, x_v, y_v, y_z) coordinates where a is attacker and v is victim.

Parameters

include_pregame (bool) – (default False) whether to include pre-game damage positions.

player_ids()[source]

The account ids of all players in the match.

player_names()[source]

A list of player names for all match pariticipants.

player_positions(include_pregame=False)[source]

Get the player positions for the match.

Returns a dict of players positions up to death with keys being player names and values being a list of tuples. Each tuple has four elements being (t, x, y, z) coordinates where t is taken from the event timestamps.

Parameters

include_pregame (bool) – (default False) whether to include pre-game player positions.

players()[source]

A map of player names to account ids for all players this match.

rankings(rank=None)[source]

The rankings of each team from this match.

Returns a map of rank : [players] for each team in the match.

Parameters

rank (int) – Get the specific rank number players for the match.

response = None

The API response associated with this object

rosters()[source]

The team rosters for the match.

property shard

The shard for this match.

started()[source]

A timestamp of when the match started.

winner()[source]

The winner(s) of the match.

Match winners as a list of player names.

Telemetry Events

The TelemetryEvent class provides a generic interface for interacting with individual telemetry events as described in the documentation for telemetry events.

To identify the specific event type, this class exposes an attribute named event_type which provides snake_cased event type label, e.g. log_match_start or log_match_end. Moreover, all keys associated with events are accessible as instance attributes by their snake_cased names, in an effort to provide a more pythonic interface to the API objects. Associated keys may also be accessed in a dict-like fashion.

class chicken_dinner.models.telemetry.TelemetryEvent(data, map_assets=False)[source]

Telemetry event model.

Generic object for all Telemetry events. To identify the event type use the object attribute event_type.

Provides an object attribute based model for telemetry events, creating embedded telemetry objects recursively. Converts all event and object keys to snake-cased key names.

Parameters
  • data (dict) – the JSON object data associated with the telemetry event

  • map_assets (bool) – whether to map asset ids to asset names

dumps()[source]

Serialize the event to a JSON string.

property event_type

The snake cased event type from _T.

items()[source]

Iterate through the attributes dictionary.

keys()[source]

Get all attributes names.

property timestamp

The timestamp value from _D.

to_dict()[source]

Get the event as a dict.

values()[source]

Get all attribute values.

Telemetry Objects

The TelemetryObject class provides a generic interface for interacting with individual telemetry objects, as described in the documentation for telemetry objects.

Each telemetry object provides an attribute named reference, which is the parent key name referencing this object, e.g. attacker or victim for log_player_attack and log_player_take_damage events, respectively when describing a character object. Like the TelemetryEvent object, all keys associated with telemetry objects are accessible as snake_cased instance attributes or dict-like keys from the object instance.

class chicken_dinner.models.telemetry.TelemetryObject(data, reference, map_assets=False)[source]

Telemetry object model.

Generic object for telemetry event objects.

Provides an object-attribute based model for telemetry objects, creating embedded telemetry objects recursively. Converts all event and object keys to snake-cased key names.

Parameters
  • data (dict) – the JSON object data associated with the telemetry object

  • reference (str) – the key from the parent object that refernces this object

  • map_assets (bool) – whether to map asset ids to asset names

dumps()[source]

Serialize the event object to a JSON string.

items()[source]

Iterate through the attributes dictionary.

keys()[source]

Get all attributes names.

reference = None

The key name that references this object

to_dict()[source]

Get the event object as a dict.

values()[source]

Get all attribute values.