Module:Abilities

Overview

The Abilities module provides functions for retrieving data about hero abilities and their upgrades.

• The function get_ability_name references Data:AbilityCards.json to link a hero and ability slot to an ability's display name.
• The functions get_ability_prop and get_ability_upgrade_prop reference Data:AbilityData.json to get specific stats from an ability's base data or its upgrades.

Examples

get_ability_name

To get the localized display name of a hero's ability (numbered 1 to 4):

{{#invoke:Abilities|get_ability_name|hero_atlas|1}}

Returns: Siphon Life

Function can be passed with lang parameter to override the current language to a specific language code.

{{#invoke:Abilities|get_ability_name|hero_atlas|1|lang=ru}}

Returns: Переливание жизни

get_ability_prop

To get a property from the base stats of an ability. You can use the ability's key (e.g., "ability_afterburn") or its proper name (e.g., "Afterburn").

{{#invoke:Abilities|get_ability_prop|Afterburn|BurnDuration}}

Returns: 3

You can also retrieve nested properties by using dot notation to drill down into the data structure. For example, to get a value nested inside a Scale table:

{{#invoke:Abilities|get_ability_prop|Lycan Curse|MaxRage.Scale.Value}}

Returns: 9.4

get_ability_upgrade_prop

To get a property from a specific upgrade of an ability.

{{#invoke:Abilities|get_ability_upgrade_prop|Afterburn|3|DPS}}

This example gets the DPS value from the 3rd upgrade for the ability "Afterburn".

Returns:

Another example, getting the `DamageAmplificationPerStack` from the 2nd upgrade of "Marksman":

{{#invoke:Abilities|get_ability_upgrade_prop|Marksman|2|DamageAmplificationPerStack}}

Returns: Ability Not Found

Submodules

Abilities - Simple functions. Eg. getting ability name

Abilities/utils - Common internal functions that are shared amongst any Abilities/ modules

Abilities/card - Generates hero ability cards

Abilities/icon - Functions for retrieving ability and attribute icon data

Abilities/details table (WIP) - Generates details table to show raw ability data

---

local data = mw.loadJsonData("Data:AbilityCards.json")
local raw_ability_data = mw.loadJsonData("Data:AbilityData.json")
local Lang = require('Module:Lang')

local p = {}

-- returns the table of a specific ability from Data:AbilityCards.json
function get_ability(hero_key, ability_num)
	local ui_data = data[hero_key]
	if(ui_data == nil) then return "Hero Not Found" end
	return ui_data[tonumber(ability_num)]
end

-- Returns the table of a specific ability from Data:AbilityData.json by its Key or Name
-- It first attempts a direct lookup by key for efficiency. If that fails, it iterates
-- through the data to find a matching Name property.
-- @function   find_json_ability
-- @param      {string} identifier - The ability's key or name
-- @return     {table} or nil
local function find_json_ability(identifier)
	-- First, try a direct lookup by key (most efficient method)
	if raw_ability_data[identifier] then
		return raw_ability_data[identifier]
	end
	
	-- If not found by key, search for key by ability name
	local resource_lookup = mw.loadJsonData("Data:ResourceLookup.json")
	local ability_resource = resource_lookup[identifier:lower()]
	
	if (ability_resource) then
		return raw_ability_data[ability_resource.key]
	end

	-- If not found by either method, return nil
	return nil
end

--{{#invoke:Abilities|get_ability_name|HERO_NAME|ABILITY_NUM|lang=LANG_CODE}}--
p.get_ability_name = function(frame)
	local hero_name = frame.args[1]
	local ability_num = frame.args[2]
	local lang = frame.args.lang
	
	local ability = get_ability(hero_name, ability_num)
	if(ability == nil) then return "Ability Not Found" end
	
	if lang and lang ~= "" then
		return Lang.get_string(ability.Key, tostring(lang))
	end

	return Lang.get_string(ability.Key)
end

-- Reverse function of get_ability_name
--{{#invoke:Abilities|get_ability_number|HERO_NAME|ABILITY_NAME}}--
p.get_ability_number = function(frame)
	local hero_name = frame.args[1]
	local ability_name = frame.args[2]
	
	local ui_data = data[hero_name]
	if(ui_data == nil) then return "Hero Not Found" end
	
	-- Normalize input for case-insensitive comparison
	local normalized_input = string.lower(ability_name)
	
	-- Iterate through the hero's abilities to find matching name
	for ability_num, ability in pairs(ui_data) do
		local current_name = Lang.get_string(ability.Key)
		if string.lower(current_name) == normalized_input then
			return ability_num
		end
	end
	
	return "Ability Not Found"
end

--{{#invoke:Abilities|get_ability_prop|ability_key_or_name|prop}}--
p.get_ability_prop = function(frame)
	local ability_identifier = frame.args[1]
	local prop = frame.args[2]
	
    -- Use the new, more flexible lookup function
	local ability = find_json_ability(ability_identifier)
	if(ability == nil) then return "Ability Not Found" end

	-- Handle nested properties via dot notation (e.g., "MaxRage.Scale.Value")
	local element = ability
	if prop and prop ~= "" then
		for segment in string.gmatch(prop, "[^%.]+") do
			if type(element) ~= "table" then
				return "" -- Can't traverse further
			end
			element = element[segment]
			if element == nil then return "" end
		end
	end
	
	if element == nil then return "" end

	-- if the property is a table, return its Value field
	if type(element) == "table" then
	    return element.Value or ""
	end

	-- otherwise return the scalar value
	return element
end

--{{#invoke:Abilities|get_ability_upgrade_prop|ability_key_or_name|upgrade_num|prop}}--
-- Gets a specific property from a specific upgrade of an ability.
-- @param {string} frame.args[1] - The ability's key (e.g., "ability_afterburn") or name (e.g., "Afterburn").
-- @param {string|number} frame.args[2] - The upgrade number (1, 2, or 3).
-- @param {string} frame.args[3] - The name of the property to retrieve.
p.get_ability_upgrade_prop = function(frame)
	local ability_identifier = frame.args[1]
	local upgrade_num_str = frame.args[2]
	local prop = frame.args[3]
	
	-- Check for missing arguments
	if not (ability_identifier and upgrade_num_str and prop) then
		return "Missing Arguments" -- Or return ""
	end

	-- Find the base ability data
	local ability = find_json_ability(ability_identifier)
	if not ability then
		return "Ability Not Found"
	end
	
	-- Get the list of upgrades for this ability
	local upgrades = ability.Upgrades
	if not upgrades or type(upgrades) ~= "table" then
		return "No Upgrades Found"
	end

	-- Convert the upgrade number from a string to an integer
	local upgrade_num = tonumber(upgrade_num_str)
	if not upgrade_num then
		return "Invalid Upgrade Number"
	end
	
	-- Get the specific upgrade table from the list (Lua tables are 1-indexed)
	local upgrade = upgrades[upgrade_num]
	if not upgrade or type(upgrade) ~= "table" then
		return "Upgrade Not Found"
	end
	
	-- Get the desired property from the specific upgrade
	local element = upgrade[prop]
	if prop and prop ~= "" then
		for segment in string.gmatch(prop, "[^%.]+") do
			-- If upgrade is not a table, return value. If it is, check for segments
			if type(element) ~= "table" then
				return element or ""
			end
			element = element[segment]
			if element == nil then return "" end
		end
	end

	-- Otherwise, return the direct value
	return element
end

return p