Module:GameData

Documentation for this module may be created at Module:GameData/doc

-- Module:GameData
-- Provides generic access to game data files, with consistent active-entity filtering.
-- Used by ItemTables, and intended for future AbilityTables, HeroTables, etc.

local p = {}

-- Dataset descriptors. Values are the data file paths passed to mw.loadJsonData.
-- Callers should use these constants rather than raw strings.
p.Dataset = {
    ITEMS     = "Data:ItemData.json",
    ABILITIES = "Data:AbilityData.json",
    HEROES    = "Data:HeroData.json",
}

-- Returns true if a record represents an active, usable entity.
-- Applies consistently across all datasets:
--   - IsDisabled must not be true
--   - Name must not be nil
--   - IsSelectable, if present, must not be false
local function is_active(record)
    if record["IsDisabled"] == true then return false end
    if record["Name"] == nil then return false end
    if record["IsSelectable"] ~= nil and record["IsSelectable"] == false then return false end
    return true
end

-- Recursively searches a record for a given key at any nesting level,
-- including inside the Upgrades array. This means abilities or items that
-- only gain a property via an upgrade tier will still be matched.
-- @param   record  table   the data record to search
-- @param   key     string  the internal property name to look for
-- @return          any     the value if found, nil otherwise
local function find_value(record, key)
    for k, v in pairs(record) do
        if k == key then
            return v
        elseif type(v) == "table" then
            local found = find_value(v, key)
            if found ~= nil then return found end
        end
    end
    return nil
end

-- Returns all active entities from a dataset that have a non-nil, non-zero,
-- non-empty value for at least one of the given internal property keys.
-- @param   dataset     string  one of the GameData.Dataset constants
-- @param   properties  table   array of internal property name strings
-- @return              table   array of matching entity records
function p.get_entities(dataset, properties)
    local data = mw.loadJsonData(dataset)
    local results = {}

    for _, record in pairs(data) do
        if is_active(record) then
            for _, prop in ipairs(properties) do
                local value = find_value(record, prop)
                if value ~= nil and value ~= 0 and value ~= "" and value ~= "0" and value ~= "0m" then
                    table.insert(results, record)
                    break
                end
            end
        end
    end

    return results
end

return p