Added External Core Module

expcore/external.lua

@@ -0,0 +1,159 @@
+--[[-- 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.validate() then
+    -- error code here
+end
+
+]]
+function External.validate()
+    if ext ~= nil and var ~= nil 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.validate() 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.validate() 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():match(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 for 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.validate() 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.validate() 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.validate() to ensure external data exists.')
+    local servers = assert(ext.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.validate() 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)
+    assert(ext, 'No external data was found, use External.validate() 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 = servers[server_id] or { address = server_id, name = 'Unknown Server', description = 'This server is not ran by us, please check the address of the server.' }
+    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. '..message end
+    player.connect_to_server{
+        address = server.address,
+        name = '\n[color=orange]'..server.name..'[/color]\n',
+        description = server.description..'\n'..message
+    }
+end
+
+--- Module return
+return External