Skip to main content

A unified representation of League of Legends-related information

Project description

LoL Game DTO

Code style: black

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
  • Information is not duplicated
    • winner is only defined once in the game object
  • Field names are coherent and comply with modern LoL nomenclature
    • Every field that is an identifier ends with id
    • Fields like cs or monstersKilled use current game vocabulary (as of June 2020)
    • All durations from the game start are expressed in seconds

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 the game object as they refer to multiple players through killerId, victimId, and assistingParticipantsIds
    • 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 for MatchTimeline objects from the Riot API
  • picksBans represents the full picks and bans and is mostly used for esports games

Team

  • bans is a simple list of id of champions banned by the team.
  • monsterKills and buildingKills are at the team level because they are team-wide
    • They both define their own BuildingKillEvent and MonsterKillEvent DTOs that are very different from Riot’s API
  • 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’s participantId and is unfortunately necessary to be able to link different objects coming from it
  • uniqueIdentifiers is similar to game['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 game items as well as kills, totalDamageDealtToChampions, ...
  • snapshots is a list of timestamped information about the player, mostly gold and position 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lol_dto-2.0.0.tar.gz (15.4 kB view details)

Uploaded Source

Built Distribution

lol_dto-2.0.0-py3-none-any.whl (16.7 kB view details)

Uploaded Python 3

File details

Details for the file lol_dto-2.0.0.tar.gz.

File metadata

  • Download URL: lol_dto-2.0.0.tar.gz
  • Upload date:
  • Size: 15.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.8.10 Linux/5.10.16.3-microsoft-standard-WSL2

File hashes

Hashes for lol_dto-2.0.0.tar.gz
Algorithm Hash digest
SHA256 d7cd85eb0ee7324fba4598d34b32b7556693ab781d466ea1ec5fccd7f82a1885
MD5 9856b7723b10539951d8bc6d512fbcbe
BLAKE2b-256 111e5cec520fbc449fb9ac82e952c5599f2ee0fa33343c9fbe7ec894598e3aa5

See more details on using hashes here.

File details

Details for the file lol_dto-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: lol_dto-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 16.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.8.10 Linux/5.10.16.3-microsoft-standard-WSL2

File hashes

Hashes for lol_dto-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 13ecb7fecf993c2790e6dbe4bb2c51512dee26daab7b5f483be78e9fc7b6ffa8
MD5 415a63a5055c354448b049ff87ccb7cf
BLAKE2b-256 ed175911de8151451197d035cda90902135529edcf9dc9dee68e98a8a505a298

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page