@lol-inspector/league-commons

Shared League of Legends domain knowledge, complete 173 champion registry, draft analytics, counters, damage profiles, and telemetry helpers.

🌐 Ecosystem & Maintenance

@lol-inspector/league-commons is the official, open-source core domain library powering the LoL Inspector platform:

• 🎮 Live Platform: https://lol-inspector.app/
• 🏛️ Organization / Monorepo: https://gitea.7u.pl/lol-inspector

📦 Installation

Install natively via NPM:

npm install @lol-inspector/league-commons

(Optional) If consuming inside the self-hosted internal Gitea registry, configure your .npmrc:

@lol-inspector:registry=https://gitea.7u.pl/api/packages/lol-inspector/npm/

🚀 Key Modules & Exports

1. Champion Registry & Fuzzy Search

• CHAMPIONS: Full canonical registry of all 173 champions with canonical IDs, display names, and lane assignments.
• champNames: Set of canonical champion display names.
• fuzzySearchChampions(query, limit): Fast, typo-tolerant fuzzy search for champion selectors and auto-completers.

import { CHAMPIONS, fuzzySearchChampions } from '@lol-inspector/league-commons';

// Search champions with instant ranking
const results = fuzzySearchChampions('kaisa', 5);
// => [{ id: 'KaiSa', name: "Kai'Sa", roles: ['BOTTOM'] }]

2. Damage Profiles & Archetypes

• DAMAGE_TYPES: Constants for AD (Physical), AP (Magic), HY (Hybrid), TD (True Damage).
• AP_CHAMPIONS, FRONT_CHAMPIONS, CC_CHAMPIONS: Curated sets of archetype classifications.
• Query functions: getChampionDamageProfile(champName), isApChampion(name), isHybridChampion(name), isFrontline(name), hasHardCc(name), isRangedChampion(name), isMeleeChampion(name).

import { getChampionDamageProfile, isFrontline, hasHardCc } from '@lol-inspector/league-commons';

getChampionDamageProfile('Aatrox'); // => 'AD'
isFrontline('Malphite');            // => true
hasHardCc('Leona');                 // => true

3. Roles & Positions

• CANONICAL_ROLES: Standard positions (TOP, JUNGLE, MIDDLE, BOTTOM, UTILITY).
• CHAMPION_ROLES: Lane assignment matrix.
• normalizeRole(role): Normalizes Riot API / LCU position strings into canonical enum values.
• getRoleDisplayName(role): Human-readable localized or display titles for roles.

import { normalizeRole, getRoleDisplayName } from '@lol-inspector/league-commons';

normalizeRole('mid');              // => 'MIDDLE'
getRoleDisplayName('UTILITY');     // => 'Support'

4. Draft Simulator & Counter Matrix

• championCounters: Pre-computed counter matchup matrix with win rates and matchup difficulty.
• predictLanesForTeam(champions): Permutation-based lane prediction algorithm.
• evaluateDraft(blueTeam, redTeam): Monte Carlo draft evaluation score based on damage distribution, frontline balance, crowd control, and counter picks.
• getCounterAdvantage(champA, champB): Fast pairwise matchup lookup.

import { evaluateDraft, getCounterAdvantage } from '@lol-inspector/league-commons';

const score = evaluateDraft(
  ['Malphite', 'Sejuani', 'Orianna', 'Ashe', 'Braum'],
  ['Fiora', 'KhaZix', 'Zed', 'Vayne', 'Lulu']
);

5. Summoner Spells

• summonerSpells: Registry of all Summoner Spells with base cooldowns, IDs, and tactical attributes.
• normalizeSpellName(name): Canonical spell name normalizer.

import { summonerSpells, normalizeSpellName } from '@lol-inspector/league-commons';

const flash = summonerSpells.find(s => s.id === 'SummonerFlash');
// => { id: 'SummonerFlash', name: 'Flash', cooldown: 300, ... }

6. Canonical Identifier Normalization

• CHAMPION_ALIASES: Resolves common nicknames and abbreviations (e.g. gp -> Gangplank, mf -> MissFortune, asol -> AurelionSol).
• CHAMPION_ID_EXCEPTIONS: Normalizes discrepancies between Riot LCU IDs and Data Dragon asset keys (e.g. Chogath <-> Cho'Gath).
• toCanonicalChampionName(input): Safe canonical resolver.
• toRiotChampionId(name): Converts common display names to numeric / Riot Client IDs.

import { toCanonicalChampionName } from '@lol-inspector/league-commons';

toCanonicalChampionName('asol');    // => 'Aurelion Sol'
toCanonicalChampionName('ChoGath'); // => "Cho'Gath"

7. Telemetry & Analytics

• calculateKdaRatio(kills, deaths, assists): Precision KDA calculator with safe zero-division handling.

import { calculateKdaRatio } from '@lol-inspector/league-commons';

calculateKdaRatio(10, 0, 5); // => 'Perfect'
calculateKdaRatio(8, 2, 4);  // => 6

8. Patch & Version Synchronization

• SUPPORTED_LOL_PATCH: Current verified League of Legends game patch ('16.18').
• SUPPORTED_DDRAGON_VERSION: Exact Riot Data Dragon CDN version ('16.18.1').
• TOTAL_SUPPORTED_CHAMPIONS: Canonical number of registered champions (173).

import {
  SUPPORTED_LOL_PATCH,
  SUPPORTED_DDRAGON_VERSION,
  TOTAL_SUPPORTED_CHAMPIONS
} from '@lol-inspector/league-commons';

🔄 Riot Patch Lifecycle & Compatibility

@lol-inspector/league-commons serves as the Single Source of Truth for League of Legends game metadata across the lol-inspector monorepo.

| Patch Update Type | Riot Game Changes | Impact on league-commons | Maintenance Procedure | | :--- | :--- | :--- | :--- | | Regular Bi-Weekly Patch (e.g. 16.17 → 16.18) | Numeric balance changes (buffs/nerfs to base stats, cooldowns, scalings, item gold costs). | Automatic. Consumers dynamically pull updated item.json and base stats from Data Dragon at runtime. | Bump SUPPORTED_LOL_PATCH and SUPPORTED_DDRAGON_VERSION in src/patch.js. | | New Champion / VGU Rework (Can occur on ANY patch, e.g. 16.13 Locke) | New champion introduced or complete kit/roles overhaul (e.g. Skarner VGU). | CRITICAL (High Priority). New champion lacks registry ID, role probability vectors, and counter ratings. | Full Champion Registration:1. Add entry in src/champions.js (ID, name, damage type, frontline/CC/ranged flags, role vector).2. Add matchups in src/counters.json.3. Increment TOTAL_SUPPORTED_CHAMPIONS in src/patch.js and update test assertions.4. Run npm test and publish new release to NPM & Gitea.5. Update @lol-inspector/league-commons in ui and agent. | | Major Season / Split Reset (e.g. 16.1, 17.1) | Structural item system additions/removals, map terrain changes, summoner spell updates. | Medium / High. Deprecated item or spell IDs may affect telemetry parsers. | Audit src/summoner_spells.js and item metadata parsers. |

🧪 Testing

Run internal unit and parity test suites:

npm test

📄 License

ISC © gkucmierz · Maintained as part of the LoL Inspector project.