A unified representation of League of Legends-related information
Project description
LoL Game DTO
A unified Data Transfer Object for League of Legends games. Currently developed by Tolki, FatalElement, and Kalturi.
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 true 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-V4 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 TypedDict
.
A TypedDict
does not enforce 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
Game
sources
represents unique identifiers for this game for a given data source"riotLolApi": { "gameId": 4409190456, "platformId": "KR" }
teams
is a dictionary with keys equal to'BLUE'
or'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 arisesroles
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 ituniqueIdentifiers
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 timestampsitemsEvents
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for lol_dto-2.0.0a2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e9ab21bda1bbea2bb6eab419795f7693e21a74ebc55dca9c27ee0431367e378 |
|
MD5 | 1e8a40e670d9656f254b651671843e64 |
|
BLAKE2b-256 | 144a778e94758013a98cf034ebeb66a2cdbaf7e9ed74695e9d9f9182cca41d52 |