LoL Game DTO
A unified Data Transfer Object for League of Legends games. Currently developed by Tolki.
2.0 note and JSON serialization
Version 2.0 moved the implementation from TypedDict
to dataclass
, which means the syntax changed and is not
backwards compatible.
dataclasses.asdict()
can be used to get the object as a dictionary, and then saved as a JSON.
Fields can be omitted when not supplied to make the object lighter. This is particularly useful for Snapshots objects.
Motivation
League of Legends game information can come in many forms. The most popular source is Riotβs API and in particular its MATCH-V5 endpoint, which defines its own MatchDto and MatchTimelineDto objects. While other sources of information could follow Riotβs data format, requiring multiple objects to represent a single game and being constrained by Riotβs data format is inconvenient.
This is why creating a unique, community-driven representation of League of Legends game data will help communication and teamwork in open source projects. Improving the data structure will also make the data more accessible to new developers, and will make existing libraries easier to maintain.
Constraints
-
Retain all the information present in the Riot API
-
Allow for external information, like role, to be added to the object
-
Be compatible across a wide variety of programming languages
General philosophy
- We try to adhere to the Google JSON Style Guide
- Information is as close as possible to the objects it refers to
- Player-specific information is directly under
player
objects - Team-wide information is directly under
team
objects
- Player-specific information is directly under
- Information is not duplicated
-
winner
is only defined once in thegame
object
-
- Field names are coherent and comply with modern LoL nomenclature
- Every field that is an identifier ends with
id
- Fields like
cs
ormonstersKilled
use current game vocabulary (as of June 2020) - All durations from the game start are expressed in seconds
- Every field that is an identifier ends with
null
The null
value should only be used for unknown information. The best practice is to not have unknown fields in
the object to keep it as light as possible.
lol_dto
This repository hosts a python
reference implementation in the form of a dataclass
.
A dataclass
does not enforce type constraints but will raise linter warnings and allows IDEs to autocomplete field names.
Another module focused on transforming MatchDto
and MatchTimelineDto
to a LolGame
can
be found here. Its
unit tests
and JSON examples
are useful sources to better understand the data structure.
LolGame DTO overview
game: dict
βββ sources: dict
βββ teams: dict
| βββ uniqueIdentifiers: dict
β βββ bans: list
β βββ monstersKills: list
β βββ buildingsKills: list
β βββ players: list
β βββ uniqueIdentifiers: dict
β βββ endOfGameStats: dict
β β βββ items: list
β βββ summonersSpells: list
β βββ runes: list
β βββ snapshots: list
β βββ itemsEvents: list
β βββ wardsEvents: list
β βββ skillsLevelUpEvents: list
βββ kills: list
βββ picksBans: list
βββ pauses: list
Game
-
sources
represents unique identifiers for this game for a given data source"riotLolApi": { "gameId": 4409190456, "platformId": "KR" }
-
teams
has properties equal to'BLUE'
and'RED'
-
kills
are present directly at the root of thegame
object as they refer to multiple players throughkillerId
,victimId
, andassistingParticipantsIds
- We have to rely on the arbitrary
participantId
given by the Riot API because:- Relying on
championId
makes it incompatible with blind pick - Relying on
inGameName
does not work forMatchTimeline
objects from the Riot API
- Relying on
- We have to rely on the arbitrary
-
picksBans
represents the full picks and bans and is mostly used for esports games
Team
-
bans
is a simple list ofid
of champions banned by the team. -
monsterKills
andbuildingKills
are at theteam
level because they are team-wide- They both define their own
BuildingKillEvent
andMonsterKillEvent
DTOs that are very different from Riotβs API
- They both define their own
-
players
are simply in a list because no unique key arises-
roles
are not guaranteed to be defined and unique
-
Player
-
id
refers to Riot APIβsparticipantId
and is unfortunately necessary to be able to link different objects coming from it -
uniqueIdentifiers
is similar togame['sources']
in that it represents a unique identifier for the player in the specified data source"riotLolApi": { "accountId": "3VcaXNMW8jq3adCqG0k0RPBaxoNL08NFXH_h4_2sKI_iEKw", "platformId": "KR" }
-
endOfGameStats
represents statistics that are only available at the end of the game, including end of gameitems
as well askills
,totalDamageDealtToChampions
, ... -
snapshots
is a list of timestamped information about the player, mostlygold
andposition
at given timestamps -
itemsEvents
are item-related events from players (buying, selling, undoing, destroying) -
wardsEvents
are ward-related events from players (placing, destroying) -
skillsLevelUpEvents
are skills level up events from players
Contributing
Currently wanted contribution are:
- Feedback about the data structure and field names
- Implementation of the data structure in other programming languages
- C functions to cast Riot API objects to this LolGame DTO as multiple languages can bind to them