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 thetelemetry
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
toAKM
.
-
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)
-
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
-
map_assets
= None¶ Whether asset ids are mapped to names
-
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_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.
-
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
-
property
shard
¶ The shard for this match.
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
-
property
event_type
¶ The snake cased event type from _T.
-
property
timestamp
¶ The timestamp value from _D.
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
-
reference
= None¶ The key name that references this object