@expcluster/legacy 7.0.1

package/module/expcore/external.lua

@@ -0,0 +1,146 @@
+--[[-- 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("modules.exp_legacy.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 ext --- @type table<string, any>
+local var --- @type table<string, any>
+local concat = table.concat
+
+local External = {}
+
+--[[-- 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()
+    local stored = storage.ext
+    if stored == nil then return false end
+    if ext == stored and var == ext.var then
+        return var ~= nil
+    else
+        ext = stored
+        var = stored.var
+        return var ~= nil
+    end
+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 (assert(servers[server_id], "No details found for server with id: " .. tostring(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 (assert(servers[server_id], "No details found for server with id: " .. tostring(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
+@tparam boolean raw When true Current will not be returned as status but rather the raw status for the server
+@treturn string The status of the given server, one of: Online, Modded, Protected, Current, Offline
+
+@usage-- Get the status of the given server
+local status = External.get_server_status('eu-01')
+
+]]
+function External.get_server_status(server_id, raw)
+    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")
+    local current = assert(ext.current, "No current id was found, please ensure that the external service is running")
+    return not raw and server_id == current and "Current" or assert(servers[server_id], "No status found for server with id: " .. tostring(server_id))
+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 themself, 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

package/module/expcore/permission_groups.lua

@@ -0,0 +1,355 @@
+--[[-- Core Module - Permission Groups
+- Permission group making for factorio so you never have to make one by hand again
+@core Groups
+@alias Permissions_Groups
+
+@usage--- Example Group (Allow All)
+-- here we will create an admin group however we do not want them to use the map editor or mess with the permission groups
+Permission_Groups.new_group('Admin') -- this defines a new group called "Admin"
+:allow_all() -- this makes the default to allow any input action unless set other wise
+:disallow{ -- here we disallow the input action we don't want them to use
+    'add_permission_group',
+    'delete_permission_group',
+    'import_permissions_string',
+    'map_editor_action',
+    'toggle_map_editor'
+}
+
+@usage--- Example Group (Disallow All)
+-- here we will create a group that cant do anything but talk in chat
+Permission_Groups.new_group('Restricted') -- this defines a new group called "Restricted"
+:disallow_all() -- this makes the default to disallow any input action unless set other wise
+:allow('write_to_console') -- here we allow them to chat, {} can be used here if we had more than one action
+
+]]
+
+local Event = require("modules/exp_legacy/utils/event")
+local Async = require("modules/exp_util/async")
+
+local PermissionsGroups = {
+    groups = {}, -- store for the different groups that are created
+    _prototype = {}, -- stores functions that are used on group instances
+}
+
+-- Async function to add players to permission groups
+local add_to_permission_group_async =
+    Async.register(function(permission_group, player)
+        permission_group.add_player(player)
+    end)
+PermissionsGroups.add_to_permission_group_async = add_to_permission_group_async
+
+-- Async function to remove players from permission groups
+local remove_from_permission_group_async =
+    Async.register(function(permission_group, player)
+        permission_group.remove_player(player)
+    end)
+PermissionsGroups.remove_from_permission_group_async = remove_from_permission_group_async
+
+--- Getters.
+-- Functions that get permission groups
+-- @section getters
+
+--[[-- Defines a new permission group that can have it actions set in the config
+@tparam string name the name of the new group
+@treturn Permissions_Groups._prototype the new group made with function to allow and disallow actions
+
+@usage-- Defining a new permission group
+Groups.new_group('Admin')
+
+]]
+function PermissionsGroups.new_group(name)
+    local group = setmetatable({
+        name = name,
+        actions = {},
+        allow_all_actions = true,
+    }, {
+        __index = PermissionsGroups._prototype,
+    })
+    PermissionsGroups.groups[name] = group
+    return group
+end
+
+--[[-- Returns the group with the given name, case sensitive
+@tparam string name the name of the group to get
+@treturn ?Permissions_Groups._prototype|nil the group with that name or nil if non found
+
+@usage-- Getting a permision group
+local admin_group = Groups.get_group_by_name('Admin')
+
+]]
+function PermissionsGroups.get_group_by_name(name)
+    return PermissionsGroups.groups[name]
+end
+
+--[[-- Returns the group that a player is in
+@tparam LuaPlayer player the player to get the group of can be name index etc
+@treturn ?Permissions_Groups._prototype|nil the group with that player or nil if non found
+
+@usage-- Get your permission group
+local group = Groups.get_group_from_player(game.player)
+
+]]
+function PermissionsGroups.get_group_from_player(player)
+    local group = player.permission_group
+    if group then
+        return PermissionsGroups.groups[group.name]
+    end
+end
+
+--- Setters.
+-- Functions that control all groups
+-- @section players
+
+--[[-- Reloads/creates all permission groups and sets them to they configured state
+
+@usage-- Reload the permission groups, used internally
+Groups.reload_permissions()
+
+]]
+function PermissionsGroups.reload_permissions()
+    for _, group in pairs(PermissionsGroups.groups) do
+        group:create()
+    end
+end
+
+--[[-- Sets a player's group to the one given, a player can only have one group at a time
+@tparam LuaPlayer player the player to effect can be name index etc
+@tparam string group the name of the group to give to the player
+@treturn boolean true if the player was added successfully, false other wise
+
+@usage-- Set your permission group
+Groups.set_player_group(game.player, 'Admin')
+
+]]
+function PermissionsGroups.set_player_group(player, group)
+    group = PermissionsGroups.get_group_by_name(group)
+    if not group or not player then return false end
+    group:add_player(player)
+    return true
+end
+
+--- Actions.
+-- Functions that control group actions
+-- @section actions
+
+--[[-- Sets the allow state of an action for this group, used internally but is safe to use else where
+@tparam ?string|defines.input_action action the action that you want to set the state of
+@tparam boolean state the state that you want to set it to, true = allow, false = disallow
+@treturn Permissions_Groups._prototype returns self so function can be chained
+
+@usage-- Set an action to be disallowed
+group:set_action('toggle_map_editor', false)
+
+]]
+function PermissionsGroups._prototype:set_action(action, state)
+    local input_action = defines.input_action[action] --[[@as defines.input_action?]]
+    if input_action == nil then input_action = action end
+    assert(type(input_action) == "number", tostring(action) .. " is not a valid input action")
+    self.actions[input_action] = state
+    return self
+end
+
+--[[-- Sets an action or actions to be allowed for this group even with disallow_all triggered, Do not use in runtime
+@tparam string|Array<string> actions the action or actions that you want to allow for this group
+@treturn Permissions_Groups._prototype returns self so function can be chained
+
+@usage-- Allow some actions
+group:allow{
+    'write_to_console'
+}
+
+]]
+function PermissionsGroups._prototype:allow(actions)
+    if type(actions) ~= "table" then
+        actions = { actions }
+    end
+    for _, action in pairs(actions) do
+        self:set_action(action, true)
+    end
+
+    return self
+end
+
+--[[-- Sets an action or actions to be disallowed for this group even with allow_all triggered, Do not use in runtime
+@tparam string|Array<string> actions the action or actions that you want to disallow for this group
+@treturn Permissions_Groups._prototype returns self so function can be chained
+
+@usage-- Disalow some actions
+group:disallow{
+    'add_permission_group',
+    'delete_permission_group',
+    'import_permissions_string',
+    'map_editor_action',
+    'toggle_map_editor'
+}
+
+]]
+function PermissionsGroups._prototype:disallow(actions)
+    if type(actions) ~= "table" then
+        actions = { actions }
+    end
+    for _, action in pairs(actions) do
+        self:set_action(action, false)
+    end
+
+    return self
+end
+
+--[[-- Sets the default state for any actions not given to be allowed, useful with :disallow
+@treturn Permissions_Groups._prototype returns self so function can be chained
+
+@usage-- Allow all actions unless given by disallow
+group:allow_all()
+
+]]
+function PermissionsGroups._prototype:allow_all()
+    self.allow_all_actions = true
+    return self
+end
+
+--[[-- Sets the default state for any action not given to be disallowed, useful with :allow
+@treturn Permissions_Groups._prototype returns self so function can be chained
+
+@usage-- Disallow all actions unless given by allow
+group:disallow_all()
+
+]]
+function PermissionsGroups._prototype:disallow_all()
+    self.allow_all_actions = false
+    return self
+end
+
+--[[-- Returns if an input action is allowed for this group
+@tparam ?string|defines.input_action action the action that you want to test for
+@treturn boolean true if the group is allowed the action, false other wise
+
+@usage-- Test if a group is allowed an action
+local allowed = group:is_allowed('write_to_console')
+
+]]
+function PermissionsGroups._prototype:is_allowed(action)
+    if type(action) == "string" then
+        action = defines.input_action[action]
+    end
+    local state = self.actions[action]
+    if state == nil then
+        state = self.allow_all_actions
+    end
+    return state
+end
+
+--- Players.
+-- Functions that control group players
+-- @section players
+
+--[[-- Creates or updates the permission group with the configured actions, used internally
+@treturn LuaPermissionGroup the permission group that was created
+
+@usage-- Create the permission group so players can be added, used internally
+group:create()
+
+]]
+function PermissionsGroups._prototype:create()
+    local group = self:get_raw()
+    if not group then
+        group = game.permissions.create_group(self.name) --[[@as LuaPermissionGroup]]
+    end
+    for _, action in pairs(defines.input_action) do
+        group.set_allows_action(action, self:is_allowed(action))
+    end
+
+    return group
+end
+
+--[[-- Returns the LuaPermissionGroup that was created with this group object, used internally
+@treturn LuaPermissionGroup the raw lua permission group
+
+@usage-- Get the factorio api permision group, used internally
+local permission_group = group:get_raw()
+
+]]
+function PermissionsGroups._prototype:get_raw()
+    return game.permissions.get_group(self.name)
+end
+
+--[[-- Adds a player to this group
+@tparam LuaPlayer player LuaPlayer the player you want to add to this group can be name or index etc
+@treturn boolean true if the player was added successfully, false other wise
+
+@usage-- Add a player to this permission group
+group:add_player(game.player)
+
+]]
+function PermissionsGroups._prototype:add_player(player)
+    local group = self:get_raw()
+    if not group or not player then return false end
+    add_to_permission_group_async(group, player)
+    return true
+end
+
+--[[-- Removes a player from this group
+@tparam LuaPlayer player LuaPlayer the player you want to remove from this group can be name or index etc
+@treturn boolean true if the player was removed successfully, false other wise
+
+@usage-- Remove a player from this permission group
+group:remove_player(game.player)
+
+]]
+function PermissionsGroups._prototype:remove_player(player)
+    local group = self:get_raw()
+    if not group or not player then return false end
+    remove_from_permission_group_async(group, player)
+    return true
+end
+
+--[[-- Returns all player that are in this group with the option to filter to online/offline only
+@tparam[opt] boolean online if nil returns all players, if true online players only, if false returns online players only
+@treturn table a table of players that are in this group; filtered if online param is given
+
+@usage-- Get all players in this group
+local online_players = group:get_players()
+
+@usage-- Get all online players in this group
+local online_players = group:get_players(true)
+
+]]
+function PermissionsGroups._prototype:get_players(online)
+    local players = {}
+    local group = self:get_raw()
+    if group then
+        if online == nil then
+            return group.players
+        else
+            for _, player in pairs(group.players) do
+                if player.connected == online then
+                    table.insert(player, player)
+                end
+            end
+        end
+    end
+    return players
+end
+
+--[[-- Prints a message to every player in this group
+@tparam string message the message that you want to send to the players
+@treturn number the number of players that received the message
+
+@usage-- Print a message to all players in thie group
+group:print('Hello, World!')
+
+]]
+function PermissionsGroups._prototype:print(message)
+    local players = self:get_players(true)
+    for _, player in pairs(players) do
+        player.print(message)
+    end
+
+    return #players
+end
+
+-- when the game starts it will make the permission groups
+Event.on_init(function()
+    PermissionsGroups.reload_permissions()
+end)
+
+return PermissionsGroups

package/module/expcore/player_data.lua

@@ -0,0 +1,152 @@
+--[[-- Core Module - PlayerData
+- A module used to store player data in a central datastore to minimize data requests and saves.
+@core PlayerData
+
+@usage-- Adding a colour setting for players
+local PlayerData = require("modules.exp_legacy.expcore.player_data")
+local PlayerColors = PlayerData.Settings:combine('Color')
+
+-- Set the players color when their data is loaded
+PlayerColors:on_load(function(player_name, color)
+    local player = game.players[player_name]
+    player.color = color
+end)
+
+-- Overwrite the saved color with the players current color
+PlayerColors:on_save(function(player_name, _)
+    local player = game.players[player_name]
+    return player.color -- overwrite existing data with the current color
+end)
+
+@usage-- Add a playtime statistic for players
+local Event = require("modules/exp_legacy/utils/event")
+local PlayerData = require("modules.exp_legacy.expcore.player_data")
+local Playtime = PlayerData.Statistics:combine('Playtime')
+
+-- When playtime reaches an hour interval tell the player and say thanks
+Playtime:on_update(function(player_name, playtime)
+    if playtime % 60 == 0 then
+        local hours = playtime / 60
+        local player = game.players[player_name]
+        player.print('Thanks for playing on our servers, you have played for '..hours..' hours!')
+    end
+end)
+
+-- Update playtime for players, data is only loaded for online players so update_all can be used
+Event.add_on_nth_tick(3600, function()
+    Playtime:update_all(function(player_name, playtime)
+        return playtime + 1
+    end)
+end)
+
+]]
+
+local Async = require("modules/exp_util/async")
+local Event = require("modules/exp_legacy/utils/event") --- @dep utils.event
+local Datastore = require("modules.exp_legacy.expcore.datastore") --- @dep expcore.datastore
+local Commands = require("modules/exp_commands")
+
+local table_to_json = helpers.table_to_json
+local write_file = helpers.write_file
+
+--- Common player data that acts as the root store for player data
+local PlayerData = Datastore.connect("PlayerData", true) -- saveToDisk
+PlayerData:set_serializer(Datastore.name_serializer) -- use player name
+
+--- Store and enum for the data saving preference
+local DataSavingPreference = PlayerData:combine("DataSavingPreference")
+local PreferenceEnum = { "All", "Statistics", "Settings", "Required" } --- @type table<string | number, string | number>
+for k, v in ipairs(PreferenceEnum) do PreferenceEnum[v] = k end
+
+DataSavingPreference:set_default("All")
+DataSavingPreference:set_metadata{
+    name = { "expcore-data.preference" },
+    tooltip = { "expcore-data.preference-tooltip" },
+    value_tooltip = { "expcore-data.preference-value-tooltip" },
+}
+
+--- Sets your data saving preference
+Commands.new("data-preference", { "expcore-data.description-preference" })
+    :optional("option", { "expcore-data.arg-option" }, Commands.types.enum(PreferenceEnum))
+    :register(function(player, option)
+        --- @cast option "All" | "Statistics" | "Settings" | "Required" | nil
+        if option then
+            DataSavingPreference:set(player, option)
+            return Commands.status.success{ "expcore-data.set-preference", option }
+        else
+            return Commands.status.success{ "expcore-data.get-preference", DataSavingPreference:get(player) }
+        end
+    end)
+
+--- Gets your data and writes it to a file
+Commands.new("save-data", { "expcore-data.description-data" })
+    :register(function(player)
+        player.print{ "expcore-data.get-data" }
+        write_file("expgaming_player_data.json", table_to_json(PlayerData:get(player, {})), false, player.index)
+    end)
+
+--- Async function called after 5 seconds with no player data loaded
+local check_data_loaded_async =
+    Async.register(function(player)
+        local player_data = PlayerData:get(player)
+        if not player_data or not player_data.valid then
+            player.print{ "expcore-data.data-failed" }
+            Datastore.ingest("request", "PlayerData", player.name, '{"valid":false}')
+        end
+    end)
+
+--- When player data loads tell the player if the load had failed previously
+PlayerData:on_load(function(player_name, player_data, existing_data)
+    if not player_data or player_data.valid == false then return end
+    if existing_data and existing_data.valid == false then
+        game.players[player_name].print{ "expcore-data.data-restore" }
+    end
+    player_data.valid = true
+end)
+
+--- Remove data that the player doesnt want to have stored
+PlayerData:on_save(function(player_name, player_data)
+    local data_preference = DataSavingPreference:get(player_name)
+    data_preference = PreferenceEnum[data_preference]
+    if data_preference == PreferenceEnum.All then
+        player_data.valid = nil
+        return player_data
+    end
+
+    local saved_player_data = { PlayerRequired = player_data.PlayerRequired, DataSavingPreference = PreferenceEnum[data_preference] }
+    if data_preference <= PreferenceEnum.Settings then saved_player_data["PlayerSettings"] = player_data.PlayerSettings end
+    if data_preference <= PreferenceEnum.Statistics then saved_player_data["PlayerStatistics"] = player_data.PlayerStatistics end
+
+    return saved_player_data
+end)
+
+--- Display your data preference when your data loads
+DataSavingPreference:on_load(function(player_name, data_preference)
+    game.players[player_name].print{ "expcore-data.get-preference", data_preference or DataSavingPreference.default }
+end)
+
+--- Load player data when they join
+Event.add(defines.events.on_player_joined_game, function(event)
+    local player = game.players[event.player_index]
+    check_data_loaded_async:start_after(300, player)
+    PlayerData:request(player)
+end)
+
+--- Unload player data when they leave
+Event.add(defines.events.on_player_left_game, function(event)
+    local player = game.players[event.player_index]
+    local player_data = PlayerData:get(player)
+    if player_data and player_data.valid == true then
+        PlayerData:unload(player)
+    end
+end)
+
+----- Module Return -----
+return {
+    All = PlayerData, -- Root for all of a players data
+    Statistics = PlayerData:combine("Statistics"), -- Common place for stats
+    Settings = PlayerData:combine("Settings"), -- Common place for settings
+    Required = PlayerData:combine("Required"), -- Common place for required data
+    DataSavingPreference = DataSavingPreference, -- Stores what data groups will be saved
+    PreferenceEnum = PreferenceEnum, -- Enum for the allowed options for data saving preference
+}

package/module/locale/en/addons.cfg

@@ -0,0 +1,31 @@
+[links]
+discord=https://discord.explosivegaming.nl
+website=https://www.explosivegaming.nl
+status=https://status.explosivegaming.nl
+github=https://github.com/explosivegaming/ExpCluster
+patreon=https://www.patreon.com/ExpGaming
+
+[info]
+players-online=There are __1__ players online
+total-map-time=This map has been on for __1__
+discord=Join us on our discord at: https://discord.explosivegaming.nl
+website=Please visit our website at: https://www.explosivegaming.nl
+status=Want to check if out servers are down? Visit: https://status.explosivegaming.nl
+github=Want to help improve our server with some extra features? Help us at: https://github.com/explosivegaming/ExpCluster
+patreon=Consider supporting our server at: https://www.patreon.com/ExpGaming
+custom-commands=We use custom commands, such as /tag and /me, use /chelp for more info.
+read-readme=Make sure you have read the information gui (It can be found through the info mark on the top left)
+softmod=We run a softmod on our servers. A softmod is a custom scenario that runs on this server, an example is the player list.
+redmew=We don't talk about redmew here; they beat us to 1000 members ;-;
+lhd=All trains must be LHD! This is a long standing rule on our servers, please respect this.
+
+[warnings]
+received=You received a warning from __1__. You have __2__ warnings. __3__
+pre-kick=This is your last warning before you are kicked.
+kick=You were kicked for having too many warnings; you may rejoin if you wish.
+pre-pre-ban=You are close to receiving a ban; successful ban appeals are unlikely.
+pre-ban=This your LAST warning before you are BANNED! Successful ban appeals are unlikely.
+ban=You were banned for having too many warnings; visit __1__ to request a ban appeal.
+script-warning=You are receiving script warnings; if you recive too many you will receive a permanent warning (__1__/__2__)
+script-warning-removed=A script warning has expired (__1__/__2__)
+script-warning-limit=__1__ has received a permanent warning from the script.