Constants

Display-name helpers and lookup tables backed by bundled dotaconstants data.

gem.constants

Dota 2 game constants — heroes, items, abilities, XP thresholds.

Data is bundled from odota/dotaconstants and pre-processed by scripts/build_constants.py into src/gem/data/.

All public functions accept internal game names and return human-readable display strings, falling back gracefully when a name is not found.

Reference: https://github.com/odota/dotaconstants

hero_display(npc_name: str) -> str

Return the localized display name for an npc_dota_hero_* string.

Parameters:

Name	Type	Description	Default
npc_name	str	Internal hero name, e.g. "npc_dota_hero_axe".	required

Returns:

Type	Description
str	Localized name (e.g. "Axe"), or a cleaned-up fallback.

Source code in src/gem/constants.py

def hero_display(npc_name: str) -> str:
    """Return the localized display name for an ``npc_dota_hero_*`` string.

    Args:
        npc_name: Internal hero name, e.g. ``"npc_dota_hero_axe"``.

    Returns:
        Localized name (e.g. ``"Axe"``), or a cleaned-up fallback.
    """
    hero = HEROES.get(npc_name.lower())
    if hero:
        return hero.get("localized_name") or npc_name
    return npc_name.removeprefix("npc_dota_hero_").replace("_", " ").title()

hero_short(npc_name: str) -> str

Return display name from either a full npc_dota_hero_* or a bare suffix.

Parameters:

Name	Type	Description	Default
npc_name	str	Full internal name or bare suffix (e.g. "axe").	required

Returns:

Type	Description
str	Localized display name.

Source code in src/gem/constants.py

def hero_short(npc_name: str) -> str:
    """Return display name from either a full ``npc_dota_hero_*`` or a bare suffix.

    Args:
        npc_name: Full internal name or bare suffix (e.g. ``"axe"``).

    Returns:
        Localized display name.
    """
    if npc_name.startswith("npc_dota_hero_"):
        return hero_display(npc_name)
    return hero_display("npc_dota_hero_" + npc_name)

hero_meta(npc_name: str) -> dict

Return the full hero metadata dict, or an empty dict if not found.

Parameters:

Name	Type	Description	Default
npc_name	str	Internal hero name (case-insensitive).	required

Returns:

Type	Description
dict	Dict with keys id, localized_name, primary_attr, roles.

Source code in src/gem/constants.py

def hero_meta(npc_name: str) -> dict:
    """Return the full hero metadata dict, or an empty dict if not found.

    Args:
        npc_name: Internal hero name (case-insensitive).

    Returns:
        Dict with keys ``id``, ``localized_name``, ``primary_attr``, ``roles``.
    """
    return HEROES.get(npc_name.lower(), {})

item_display(internal: str) -> str

Return display name for an item_* prefixed internal name.

Parameters:

Name	Type	Description	Default
internal	str	Internal item name, e.g. "item_blink" or "blink".	required

Returns:

Type	Description
str	Display name (e.g. "Blink Dagger"), or the raw string as fallback.

Source code in src/gem/constants.py

def item_display(internal: str) -> str:
    """Return display name for an ``item_*`` prefixed internal name.

    Args:
        internal: Internal item name, e.g. ``"item_blink"`` or ``"blink"``.

    Returns:
        Display name (e.g. ``"Blink Dagger"``), or the raw string as fallback.
    """
    key = internal.removeprefix("item_")
    item = ITEMS.get(key)
    return item["dname"] if item else internal

ability_display(internal: str) -> str

Return display name for an ability or item internal name.

Falls back to item_display for item_* names, and to a prettified version of the internal name for any unrecognised ability (strips hero prefix, title-cases remainder).

Parameters:

Name	Type	Description	Default
internal	str	Internal ability or item name.	required

Returns:

Type	Description
str	Display name string.

Source code in src/gem/constants.py

def ability_display(internal: str) -> str:
    """Return display name for an ability or item internal name.

    Falls back to ``item_display`` for ``item_*`` names, and to a
    prettified version of the internal name for any unrecognised ability
    (strips hero prefix, title-cases remainder).

    Args:
        internal: Internal ability or item name.

    Returns:
        Display name string.
    """
    dname = ABILITIES.get(internal)
    if dname:
        return dname
    if internal.startswith("item_"):
        return item_display(internal)
    return _prettify_ability(internal)

xp_to_next_level(level: int, current_xp: int) -> int | None

Return XP needed to reach the next level, or None at max level.

Parameters:

Name	Type	Description	Default
level	int	Current hero level (1-based).	required
current_xp	int	Current cumulative XP total.	required

Returns:

Type	Description
int | None	XP remaining to next level, or None if already at max.

Source code in src/gem/constants.py

def xp_to_next_level(level: int, current_xp: int) -> int | None:
    """Return XP needed to reach the next level, or None at max level.

    Args:
        level: Current hero level (1-based).
        current_xp: Current cumulative XP total.

    Returns:
        XP remaining to next level, or ``None`` if already at max.
    """
    if level < len(XP_LEVEL):
        return max(0, XP_LEVEL[level] - current_xp)
    return None

permanent_buff_name(buff_id: int) -> str

Return the item name for a permanent buff integer ID.

Parameters:

Name	Type	Description	Default
buff_id	int	Integer buff identifier from entity state.	required

Returns:

Type	Description
str	Internal item name (e.g. "moon_shard"), or str(buff_id) as fallback.

Source code in src/gem/constants.py

def permanent_buff_name(buff_id: int) -> str:
    """Return the item name for a permanent buff integer ID.

    Args:
        buff_id: Integer buff identifier from entity state.

    Returns:
        Internal item name (e.g. ``"moon_shard"``), or ``str(buff_id)`` as fallback.
    """
    return PERMANENT_BUFFS.get(str(buff_id), str(buff_id))

league_name(leagueid: int) -> str | None

Return the league name for a given league ID, or None if unknown/not found.

Parameters:

Name	Type	Description	Default
leagueid	int	Numeric Dota 2 league ID.	required

Returns:

Type	Description
str | None	League name string (e.g. "The International 2024"), or None
str | None	if the league is not in the bundled data (e.g. pub games, unknown leagues).

Source code in src/gem/constants.py

def league_name(leagueid: int) -> str | None:
    """Return the league name for a given league ID, or None if unknown/not found.

    Args:
        leagueid: Numeric Dota 2 league ID.

    Returns:
        League name string (e.g. ``"The International 2024"``), or ``None``
        if the league is not in the bundled data (e.g. pub games, unknown leagues).
    """
    if not leagueid:
        return None
    return LEAGUES.get(str(leagueid))