factorio-scenario-ExpCluster/expcore/external.lua

--[[-- Core Module - External
- A module used to make accessing externally set data easier.
@core External
@alias External

@usage-- Printing all server to chat
local External = require 'expcore.external' --- @dep expcore.external

local message = 'id: %s name: %s version: %s status: %s'
for server_id, server in pairs(External.get_servers()) do
    local status = External.get_server_status(server_id)
    game.print(message:format(server_id, server.name, server.version, status))
end

]]

local Event = require 'utils.event' --- @dep utils.event
local concat = table.concat

local External = {}

--- Makes local links to the data is global.ext if it exists
local ext, var
Event.on_load(function()
    ext = global.ext
    if ext then var = ext.var end
end)

--[[-- Checks that local links are valid, will try to add the links if invalid
@treturn boolean If the external data is valid, if false you should not call any other methods from External

@usage-- Check that external data is valid
if not External.valid() then
    -- error code here
end

]]
function External.valid()
    if ext ~= nil and ext == global.ext then
        return true
    elseif global.ext ~= nil then
        ext = global.ext
        var = ext.var
        return var ~= nil
    end
    return false
end

--[[-- Gets a table of all the servers, key is the server id, value is the server details
@treturn table A table containing all the servers, key is the server id, value is the server details

@usage-- Get all servers
local servers = External.get_servers()

]]
function External.get_servers()
    assert(ext, 'No external data was found, use External.valid() to ensure external data exists.')
    return assert(ext.servers, 'No server list was found, please ensure that the external service is running')
end

--[[-- Gets a table of all the servers filtered by name, key is the server id, value is the server details
@tparam string search The string to search for, names, short_names and ids are checked for this string.
@treturn table A table containing all the servers filtered by name, key is the server id, value is the server details

@usage-- Get all servers with public in the name
local servers = External.get_servers_filtered(public)

]]
function External.get_servers_filtered(search)
    assert(ext, 'No external data was found, use External.valid() to ensure external data exists.')
    local servers = assert(ext.servers, 'No server list was found, please ensure that the external service is running')
    local found_servers = {}
    search = search:lower()
    for server_id, server in pairs(servers) do
        local str = concat{server.name, server.short_name, server.id}
        if str:lower():find(search, 1, true) then found_servers[server_id] = server end
    end
    return found_servers
end

--[[-- Gets the details of the current server
@treturn table The details of the current server

@usage-- Get the details of the current server
local server = External.get_current_server()

]]
function External.get_current_server()
    assert(ext, 'No external data was found, use External.valid() to ensure external data exists.')
    local servers = assert(ext.servers, 'No server list was found, please ensure that the external service is running')
    local server_id = assert(ext.current, 'No current id was found, please ensure that the external service is running')
    return servers[server_id]
end

--[[-- Gets the details of the given server
@tparam string server_id The internal server if for the server you want the details of
@treturn table The details of the given server

@usage-- Get the details of the given server
local server = External.get_server_details('eu-01')

]]
function External.get_server_details(server_id)
    assert(ext, 'No external data was found, use External.valid() to ensure external data exists.')
    local servers = assert(ext.servers, 'No server list was found, please ensure that the external service is running')
    return servers[server_id]
end

--[[-- Gets the status of the given server
@tparam string server_id The internal server if for the server you want the status of
@treturn string The status of the given server, one of: Online, Modded, Protected, Offline

@usage-- Get the status of the given server
local status = External.get_server_status('eu-01')

]]
function External.get_server_status(server_id)
    assert(var, 'No external data was found, use External.valid() to ensure external data exists.')
    local servers = assert(var.status, 'No server status was found, please ensure that the external service is running')
    return servers[server_id]
end

--[[-- Gets the ups of the current server
@usage-- Get the ups of the current server
local server_ups = External.get_server_ups()

]]
function External.get_server_ups()
    assert(var, 'No external data was found, use External.valid() to ensure external data exists.')
    return assert(var.server_ups, 'No server ups was found, please ensure that the external service is running')
end

--[[-- Connect a player to the given server
@tparam LuaPlayer player The player that you want to request to join a different server
@tparam string server_id The internal id of the server to connect to, can also be any address but this will show Unknown Server
@tparam[opt=false] boolean self_requested If the player requested the join them selfs, this will hide the message about being asked to switch

@usage-- Request that a player joins a different server
External.request_connection(player, 'eu-01')

@usage-- Request that a player joins a different server, by own request
External.request_connection(player, 'eu-01', true)

]]
function External.request_connection(player, server_id, self_requested)
    local server = { address = server_id, name = 'Unknown Server', description = 'This server is not ran by us, please check the address of the server.' }
    if ext and ext.servers and ext.servers[server_id] then server = ext.servers[server_id] end
    local message = 'Please press the connect button below to join.'
    if not self_requested then message = 'You have been asked to switch to a different server.\n'..message end
    player.connect_to_server{
        address = server.address,
        name = '\n[color=orange][font=heading-1]'..server.name..'[/font][/color]\n',
        description = server.description..'\n'..message
    }
end

--- Module return
return External