Module:AbilityTable

This module exposes two functions.

• render generates a table of hero abilities matching a named list, and is invoked via {{AbilityTable}}.
• is_member(list, ability_key, ability_num) is a shared function that decides whether a single ability belongs to a list (applying the same properties and exclusions); it is used both internally by render and externally by Module:AbilityHints, so the ability-hint icons always stay in sync with these tables.

See also

• Template:AbilityTable — the template that invokes this module
• Module:AbilityTable/Lists — defines which properties each list matches on, and which abilities to exclude
• Module:AbilityTable/Notes — editor-authored notes displayed in the Notes column
• Module:AbilityTable/ComplexRenderers — custom column renderers for lists that need more than just Notes
• Module:AbilityHints — reuses is_member to render interaction-hint icons on ability cards

---

-- Module:AbilityTables
-- Renders sortable wikitables of abilities filtered by a named stat.
-- Backing module for Template:AbilityTable.
--
-- Usage on wiki pages: {{AbilityTable|charges}}
--
-- ============================================================
-- ADDING A NEW STAT
-- ============================================================
-- 1. Add an entry to stat_to_props mapping the friendly name
--    (lowercase) to the internal AbilityData property keys that
--    determine whether an ability appears in the table.
--
-- 2. Add a matching entry to extra_columns:
--      - headers:    ordered list of column header strings.
--                    Include "Notes" if this stat generates notes.
--      - get_cells:  function(ability) -> { ["Column Name"] = value }
--                    The ability is guaranteed to match the stat.
--                    Omit a key or return nil to show "—" in that cell.
--    If no extra_columns entry is added, only Hero and Ability
--    columns are shown (plus Notes if human notes exist for the stat).
--
-- 3. Optionally add human-authored notes to human_notes:
--      human_notes["stat"]["Ability Name"] = "Note text."
--    Notes are appended to any renderer-generated note automatically.
--
-- 4. Optionally add entries to column_suffix to append a unit
--    string (e.g. "s", "%") after cell values in specific columns.
-- ============================================================

local p = {}
local GameData = require("Module:GameData")

-- ============================================================
-- stat_to_props
-- Maps lowercase friendly stat names to internal AbilityData
-- property keys used to filter which abilities appear.
-- ============================================================
local stat_to_props = {
    ["charges"] = { "AbilityCharges" },
}

-- ============================================================
-- human_notes
-- Editor-authored notes appended to the Notes column.
-- Keyed first by stat name, then by ability display Name.
-- ============================================================
local human_notes = {
    ["charges"] = {
        ["Jar of Dead"] = "Charges by being near when anything dies.",
    },
}

-- ============================================================
-- Shared helpers
-- ============================================================

local function num_val(v)
    if type(v) == "number" then return v end
    if type(v) == "table"  then return v["Value"] end
    return nil
end

-- Searches Upgrades[] for a field and returns { tier = N, value = V } at its
-- first appearance, or nil if the field is absent from all upgrade tiers.
local function find_in_upgrades(ability, field)
    local upgrades = ability["Upgrades"]
    if type(upgrades) ~= "table" then return nil end
    for i, tier in ipairs(upgrades) do
        if type(tier) == "table" and tier[field] ~= nil then
            return { tier = i, value = num_val(tier[field]) }
        end
    end
    return nil
end

-- ============================================================
-- Per-stat cell renderers
-- Each function receives a guaranteed-matching ability record
-- and returns { ["Column Name"] = value }.
-- Human notes are appended by the framework, not here.
-- ============================================================

local function charges_cells(ability)
    local base_charges  = num_val(ability["AbilityCharges"])
    local base_cooldown = ability["AbilityCooldownBetweenCharge"]
    local has_base      = base_charges ~= nil and base_charges > 0
    local upgrade_info  = find_in_upgrades(ability, "AbilityCharges")

    local cooldown, upgrade_cooldown
    if has_base then
        if type(base_cooldown) == "number" and base_cooldown > 0 then
            cooldown = base_cooldown
        else
            local cd = find_in_upgrades(ability, "AbilityCooldownBetweenCharge")
            if cd and cd.value and cd.value > 0 then cooldown = cd.value end
        end
    else
        local cd = find_in_upgrades(ability, "AbilityCooldownBetweenCharge")
        if cd and cd.value and cd.value > 0 then upgrade_cooldown = cd.value end
    end

    local cells = {}

    if has_base then
        cells["Charges"] = tostring(base_charges)
        if cooldown then
            cells["Time Between Charges"] = tostring(cooldown)
        end
    end

    local note_parts = {}
    if upgrade_info then
        local n = upgrade_info.value or "?"
        local charge_str = n .. " charge" .. (n ~= 1 and "s" or "")
        if has_base then
            table.insert(note_parts, "+" .. charge_str .. " on T" .. upgrade_info.tier .. " upgrade.")
        else
            local cd_str = upgrade_cooldown and (upgrade_cooldown .. "s") or "unknown"
            table.insert(note_parts, "Becomes charged on T" .. upgrade_info.tier
                .. " upgrade with " .. charge_str
                .. " and " .. cd_str .. " time between charges.")
        end
    end
    if ability["AbilityChargesConditionally"] ~= nil then
        table.insert(note_parts, "Has a conditional charge.")
    end
    if #note_parts > 0 then
        cells["Notes"] = table.concat(note_parts, " ")
    end

    return cells
end

-- ============================================================
-- extra_columns
-- Declares headers and cell renderer for each stat.
-- ============================================================
local extra_columns = {
    ["charges"] = {
        headers   = { "Charges", "Time Between Charges", "Notes" },
        get_cells = charges_cells,
    },
}

-- ============================================================
-- column_suffix
-- Unit strings appended to non-nil cell values by column name.
-- ============================================================
local column_suffix = {
    ["Time Between Charges"] = "s",
}

-- ============================================================
-- Hero lookup (ability key -> { heroName, abilityNum })
-- ============================================================

local _hero_lookup = nil

local function build_hero_lookup()
    if _hero_lookup then return _hero_lookup end
    _hero_lookup = {}

    local hero_data = mw.loadJsonData("Data:HeroData.json")
    local active_heroes = {}
    for _, hero in pairs(hero_data) do
        if type(hero) == "table"
            and hero["IsDisabled"] == false
            and type(hero["Name"]) == "string"
            and (hero["IsSelectable"] == nil or hero["IsSelectable"] ~= false)
        then
            active_heroes[hero["Name"]] = true
        end
    end

    local cards = mw.loadJsonData("Data:AbilityCards.json")
    for _, hero_entry in pairs(cards) do
        if type(hero_entry) == "table" then
            local hero_name = hero_entry["Name"]
            if hero_name and active_heroes[hero_name] then
                for slot_str, ability in pairs(hero_entry) do
                    local slot_num = tonumber(slot_str)
                    if slot_num and type(ability) == "table" and ability["Key"] then
                        _hero_lookup[ability["Key"]] = {
                            heroName   = hero_name,
                            abilityNum = slot_num,
                        }
                    end
                end
            end
        end
    end

    return _hero_lookup
end

-- ============================================================
-- Entry point
-- ============================================================

function p.abilityPropTable(frame)
    local stat = mw.text.trim(frame.args[1] or ""):lower()

    local internal_keys = stat_to_props[stat]
    if not internal_keys then
        return '<span class="error">AbilityTable: unknown stat "' .. stat .. '".</span>'
    end

    local lookup     = build_hero_lookup()
    local spec       = extra_columns[stat]
    local headers    = spec and spec.headers or {}
    local get_cells  = spec and spec.get_cells or function() return {} end
    local stat_notes = human_notes[stat]

    local abilities = GameData.get_entities(GameData.Dataset.ABILITIES, internal_keys)

    -- Keep only abilities belonging to active, released heroes
    local filtered = {}
    for _, ability in ipairs(abilities) do
        local key = ability["Key"]
        if key and lookup[key] then
            table.insert(filtered, ability)
        end
    end

    if #filtered == 0 then
        return "No abilities found for stat: " .. stat
    end

    -- Sort by hero name, then ability slot number
    table.sort(filtered, function(a, b)
        local ia = lookup[a["Key"]]
        local ib = lookup[b["Key"]]
        if ia.heroName ~= ib.heroName then
            return ia.heroName < ib.heroName
        end
        return ia.abilityNum < ib.abilityNum
    end)

    -- Determine final header list. "Notes" is included if declared in headers
    -- (meaning the renderer may produce notes) or if human notes exist for
    -- this stat. Either way it appears exactly once at the end.
    local has_notes_header = false
    local final_headers = {}
    for _, h in ipairs(headers) do
        if h == "Notes" then
            has_notes_header = true
        else
            table.insert(final_headers, h)
        end
    end
    local needs_notes = has_notes_header or stat_notes ~= nil
    if needs_notes then
        table.insert(final_headers, "Notes")
    end

    -- Render wikitable
    local out = {}
    table.insert(out, '{| class="wikitable sortable ability-table"')

    local header_cells = '! class="ability-table-col-hero" | Hero'
                      .. ' !! class="ability-table-col-ability" | Ability'
    for _, h in ipairs(final_headers) do
        local cls = "ability-table-col-" .. h:lower():gsub("%s+", "-")
        header_cells = header_cells .. ' !! class="' .. cls .. '" | ' .. h
    end
    table.insert(out, header_cells)

    for _, ability in ipairs(filtered) do
        local info = lookup[ability["Key"]]

        local hero_cell = frame:expandTemplate{
            title = "HeroIcon",
            args  = { info.heroName }
        }
        local ability_cell = frame:expandTemplate{
            title = "AbilityIcon",
            args  = { ability["Name"] }
        }

        local extra = get_cells(ability)

        -- Append human note to any renderer-generated note
        if stat_notes and stat_notes[ability["Name"]] then
            local human = stat_notes[ability["Name"]]
            extra["Notes"] = extra["Notes"] and (extra["Notes"] .. " " .. human) or human
        end

        local row_cells = '| class="ability-table-cell-hero" | '    .. hero_cell
                       .. ' || class="ability-table-cell-ability" | ' .. ability_cell
        for _, header in ipairs(final_headers) do
            local value  = extra[header]
            local cls    = "ability-table-cell-" .. header:lower():gsub("%s+", "-")
            local content
            if value ~= nil then
                local suffix = column_suffix[header] or ""
                content = value .. suffix
            else
                content = "—"
            end
            row_cells = row_cells .. ' || class="' .. cls .. '" | ' .. content
        end

        table.insert(out, "|-")
        table.insert(out, row_cells)
    end

    table.insert(out, "|}")
    return table.concat(out, "\n")
end

return p