Merge branch 'release/5.9.0'

README.md

@@ -56,7 +56,8 @@ All are welcome to make pull requests and issues for this scenario, if you are i
 
 | Scenario Version* | Version Name | Factorio Version** |
 |---|---|---|
-| [v5.7][s5.8] | Home and Chat Bot | [v0.17.47][f0.17.49] |
+| [v5.9][s5.9] | Control Modules and Documentation | [v0.17.63][f0.17.63] |
+| [v5.8][s5.8] | Home and Chat Bot | [v0.17.47][f0.17.49] |
 | [v5.7][s5.7] | Warp System | [v0.17.47][f0.17.47] |
 | [v5.6][s5.6] | Information Guis | [v0.17.44][f0.17.44] |
 | [v5.5][s5.5] | Gui System | [v0.17.43][f0.17.43] |
@@ -75,6 +76,7 @@ All are welcome to make pull requests and issues for this scenario, if you are i
 
 \*\* Factorio versions show the version they were made for, often the minimum requirement.
 
+[s5.9]: https://github.com/explosivegaming/scenario/releases/tag/5.9.0
 [s5.8]: https://github.com/explosivegaming/scenario/releases/tag/5.8.0
 [s5.7]: https://github.com/explosivegaming/scenario/releases/tag/5.7.0
 [s5.6]: https://github.com/explosivegaming/scenario/releases/tag/5.6.0
@@ -90,6 +92,7 @@ All are welcome to make pull requests and issues for this scenario, if you are i
 [s1.0]: https://github.com/explosivegaming/scenario/releases/tag/v1.0
 [s0.1]: https://github.com/explosivegaming/scenario/releases/tag/v0.1
 
+[f0.17.63]: https://wiki.factorio.com/Version_history/0.17.0#0.17.63
 [f0.17.49]: https://wiki.factorio.com/Version_history/0.17.0#0.17.49
 [f0.17.47]: https://wiki.factorio.com/Version_history/0.17.0#0.17.47
 [f0.17.44]: https://wiki.factorio.com/Version_history/0.17.0#0.17.44

config/_file_loader.lua

@@ -1,7 +1,8 @@
---- This contains a list of all files that will be loaded and the order they are loaded in
--- to stop a file from loading add "--" in front of it, remove the "--" to have the file be loaded
--- config files should be loaded after all modules are loaded
--- core files should be required by modules and not be present in this list
+--- This contains a list of all files that will be loaded and the order they are loaded in;
+-- to stop a file from loading add "--" in front of it, remove the "--" to have the file be loaded;
+-- config files should be loaded after all modules are loaded;
+-- core files should be required by modules and not be present in this list;
+-- @config File-Loader
 return {
     --'example.file_not_loaded',
     'modules.factorio-control', -- base factorio free play scenario

config/action_buttons.lua

@@ -1,17 +1,19 @@
---- Config for the different action buttons that show on the player list
--- each button has the button define(s) given along side an auth function, and optional reason callback
--- if a reason callback is used then Store.set(action_name_store,player.name,'BUTTON_NAME') should be called during on_click
--- buttons can be removed from the gui by commenting them out of the config at the bottom of this file
--- the key used for the name of the button is the permision name used by the role system
-local Gui = require 'expcore.gui'
-local Roles = require 'expcore.roles'
-local Store = require 'expcore.store'
-local Game = require 'utils.game'
-local Reports = require 'modules.addons.reports-control'
-local Warnings = require 'modules.addons.warnings-control'
-local Jail = require 'modules.addons.jail-control'
-local Colors = require 'resources.color_presets'
-local format_chat_player_name = ext_require('expcore.common','format_chat_player_name')
+--- Config for the different action buttons that show on the player list;
+-- each button has the button define(s) given along side an auth function, and optional reason callback;
+-- if a reason callback is used then Store.set(action_name_store,player.name,'BUTTON_NAME') should be called during on_click;
+-- buttons can be removed from the gui by commenting them out of the config at the bottom of this file;
+-- the key used for the name of the button is the permission name used by the role system;
+-- @config Player-List
+
+local Gui = require 'expcore.gui' --- @dep expcore.gui
+local Roles = require 'expcore.roles' --- @dep expcore.roles
+local Store = require 'expcore.store' --- @dep expcore.store
+local Game = require 'utils.game' --- @dep utils.game
+local Reports = require 'modules.control.reports' --- @dep modules.control.reports
+local Warnings = require 'modules.control.warnings' --- @dep modules.control.warnings
+local Jail = require 'modules.control.jail' --- @dep modules.control.jail
+local Colors = require 'resources.color_presets' --- @dep resources.color_presets
+local format_chat_player_name = ext_require('expcore.common','format_chat_player_name') --- @dep expcore.common
 
 local action_player_store = 'gui.left.player-list.action-player'
 local action_name_store = 'gui.left.player-list.action-name'
@@ -50,7 +52,8 @@ local function teleport(from_player,to_player)
     return true
 end
 
--- teleports the user to the action player
+--- Teleports the user to the action player
+-- @element goto_player
 local goto_player =
 Gui.new_button()
 :set_sprites('utility/export')
@@ -66,7 +69,8 @@ Gui.new_button()
     end
 end)
 
--- teleports the action player to the user
+--- Teleports the action player to the user
+-- @element bring_player
 local bring_player =
 Gui.new_button()
 :set_sprites('utility/import')
@@ -82,7 +86,8 @@ Gui.new_button()
     end
 end)
 
--- kills the action player, if there are alive
+--- Kills the action player, if there are alive
+-- @element kill_player
 local kill_player =
 Gui.new_button()
 :set_sprites('utility/too_far')
@@ -98,15 +103,16 @@ Gui.new_button()
     end
 end)
 
--- reports the action player, requires a reason to be given
+--- Reports the action player, requires a reason to be given
+-- @element report_player
 local report_player =
 Gui.new_button()
 :set_sprites('utility/spawn_flag')
 :set_tooltip{'player-list.report-player'}
 :set_style('tool_button',tool_button_style)
 :on_click(function(player,element)
     local action_player_name = get_action_player_name(player)
-    if Reports.player_is_reported_by(action_player_name,player.name) then
+    if Reports.is_reported(action_player_name,player.name) then
         player.print({'expcom-report.already-reported'},Colors.orange_red)
     else
         Store.set(action_name_store,player.name,'command/report')
@@ -118,10 +124,11 @@ local function report_player_callback(player,reason)
     local by_player_name_color = format_chat_player_name(player)
     game.print{'expcom-report.non-admin',action_player_name_color,reason}
     Roles.print_to_roles_higher('Trainee',{'expcom-report.admin',action_player_name_color,by_player_name_color,reason})
-    Reports.report_player(action_player_name,reason,player.name)
+    Reports.report_player(action_player_name,player.name,reason)
 end
 
--- gives the action player a warning, requires a reason
+--- Gives the action player a warning, requires a reason
+-- @element warn_player
 local warn_player =
 Gui.new_button()
 :set_sprites('utility/spawn_flag')
@@ -135,18 +142,19 @@ local function warn_player_callback(player,reason)
     local action_player_name,action_player_name_color = get_action_player_name(player)
     local by_player_name_color = format_chat_player_name(player)
     game.print{'expcom-warnings.received',action_player_name_color,by_player_name_color,reason}
-    Warnings.add_warnings(action_player_name,player.name)
+    Warnings.add_warning(action_player_name,player.name,reason)
 end
 
--- jails the action player, requires a reason
+--- Jails the action player, requires a reason
+-- @element jail_player
 local jail_player =
 Gui.new_button()
 :set_sprites('utility/item_editor_icon')
 :set_tooltip{'player-list.jail-player'}
 :set_style('tool_button',tool_button_style)
 :on_click(function(player,element)
     local action_player_name,action_player_name_color = get_action_player_name(player)
-    if Roles.player_has_role(action_player_name,'Jail') then
+    if Jail.is_jailed(action_player_name) then
         player.print({'expcom-jail.already-jailed',action_player_name_color},Colors.orange_red)
     else
         Store.set(action_name_store,player.name,'command/jail')
@@ -157,18 +165,19 @@ local function jail_player_callback(player,reason)
     local action_player_name,action_player_name_color = get_action_player_name(player)
     local by_player_name_color = format_chat_player_name(player)
     game.print{'expcom-jail.give',action_player_name_color,by_player_name_color,reason}
-    Jail.jail_player(action_player_name,player.name)
+    Jail.jail_player(action_player_name,player.name,reason)
 end
 
--- temp bans the action player, requires a reason
+--- Temp bans the action player, requires a reason
+-- @element temp_ban_player
 local temp_ban_player =
 Gui.new_button()
 :set_sprites('utility/clock')
 :set_tooltip{'player-list.temp-ban-player'}
 :set_style('tool_button',tool_button_style)
 :on_click(function(player,element)
     local action_player_name,action_player_name_color = get_action_player_name(player)
-    if Roles.player_has_role(action_player_name,'Jail') then
+    if Jail.is_jailed(action_player_name) then
         player.print({'expcom-jail.already-banned',action_player_name_color},Colors.orange_red)
     else
         Store.set(action_name_store,player.name,'command/temp-ban')
@@ -182,7 +191,8 @@ local function temp_ban_player_callback(player,reason)
     Jail.temp_ban_player(action_player,player.name,reason)
 end
 
--- kicks the action player, requires a reason
+--- Kicks the action player, requires a reason
+-- @element kick_player
 local kick_player =
 Gui.new_button()
 :set_sprites('utility/warning_icon')
@@ -197,7 +207,8 @@ local function kick_player_callback(player,reason)
     game.kick_player(action_player,reason)
 end
 
--- bans the action player, requires a reason
+--- Bans the action player, requires a reason
+-- @element ban_player
 local ban_player =
 Gui.new_button()
 :set_sprites('utility/danger_icon')
@@ -235,7 +246,7 @@ return {
             if not Roles.player_allowed(player,'command/give-warning') then
                 return not Roles.player_has_flag(action_player,'report-immune')
             end
-        end, -- can report any player that isnt immune and you arnt able to give warnings
+        end, -- can report any player that isn't immune and you aren't able to give warnings
         reason_callback=report_player_callback,
         report_player
     },

config/advanced_start.lua

@@ -1,4 +1,5 @@
 --- This file is used to setup the map starting settings and the items players will start with
+-- @config Advanced-Start
 
 --- These are called factories because they return another function
 -- use these as a simple methods of adding new items
@@ -61,14 +62,14 @@ end
 ]]
 
 return {
-    skip_intro=true, -- skips the intro given in the default factorio free play scenario
-    skip_victory=true, -- will skip the victory screen when a rocket is launched
-    disable_base_game_silo_script=true, -- will not load the silo script at all
-    research_queue_from_start=true, -- when true the research queue is useible from the start
-    friendly_fire=false, -- weather players will be able to attack each other on the same force
-    enemy_expansion=false, -- a catch all for in case the map settings file fails to load
-    chart_radius=10*32, -- the number of tiles that will be charted when the map starts
-    items = { -- items and there condition for being given
+    skip_intro=true, --- @setting skip_intro skips the intro given in the default factorio free play scenario
+    skip_victory=true, --- @setting skip_victory will skip the victory screen when a rocket is launched
+    disable_base_game_silo_script=true, --- @setting disable_base_game_silo_script will not load the silo script at all
+    research_queue_from_start=true, --- @setting research_queue_from_start when true the research queue is useible from the start
+    friendly_fire=false, --- @setting friendly_fire weather players will be able to attack each other on the same force
+    enemy_expansion=false, --- @setting enemy_expansion a catch all for in case the map settings file fails to load
+    chart_radius=10*32, --- @setting chart_radius the number of tiles that will be charted when the map starts
+    items = { --- @setting items items and there condition for being given
         -- ['item-name'] = function(amount_made,production_stats,player) return <Number> end -- 0 means no items given
         -- Plates
         ['iron-plate']=scale_amount_made(100,10,10),

config/bonuses.lua

@@ -1,4 +1,6 @@
 --- Lists all bonuses which can be used, name followed by min max
+-- @config Bonuses
+
 return {
     character_mining_speed_modifier={0,3},
     character_crafting_speed_modifier={0,3},

config/chat_reply.lua

@@ -1,8 +1,11 @@
 --- This file defines the different triggers for the chat bot
-local format_time = ext_require('expcore.common','format_time')
+-- @config Chat-Reply
+
+local format_time = ext_require('expcore.common','format_time') --- @dep expcore.common
+
 return {
-    allow_command_prefix_for_messages = true, -- when true any message trigger will print to all player when prefixed
-    messages = { -- will trigger when ever the word is said
+    allow_command_prefix_for_messages = true, --- @setting allow_command_prefix_for_messages when true any message trigger will print to all player when prefixed
+    messages = { --- @setting messages will trigger when ever the word is said
         ['discord']={'info.discord'},
         ['expgaming']={'info.website'},
         ['website']={'info.website'},
@@ -39,13 +42,13 @@ return {
             return {'chat-bot.map-time',format_time(game.tick,{days=true,hours=true,minutes=true,seconds=true,long=true})}
         end,
     },
-    command_admin_only = false, -- when true will only allow chat commands for admins
-    command_permission = 'command/chat-bot', -- the permision used to allow command prefixs
-    command_prefix = '!', -- prefix used for commands below and to print to all players (if enabled above)
-    commands = { -- will trigger only when command prefix is given
+    command_admin_only = false, --- @setting command_admin_only when true will only allow chat commands for admins
+    command_permission = 'command/chat-bot', --- @setting command_permission the permission used to allow command prefixes
+    command_prefix = '!', --- @setting command_prefix prefix used for commands below and to print to all players (if enabled above)
+    commands = { --- @setting commands will trigger only when command prefix is given
         ['dev']={'chat-bot.not-real-dev'},
         ['blame']=function(player)
-            local names = {'Cooldude2606','arty714','badgamernl',player.name}
+            local names = {'Cooldude2606','arty714','badgamernl', 'mark9064', 'aldldl', 'Drahc_pro',player.name}
             for _,next_player in pairs(game.connected_players) do
                 names[#names + 1] = next_player.name
             end

config/compilatron.lua

@@ -1,10 +1,12 @@
--- config file for the compliatrons including where they spawn and what messages they show
+--- Config file for the compliatrons including where they spawn and what messages they show
+-- @config Compilatron
+
 return {
-    message_cycle=60*15, -- 15 seconds default, how often (in ticks) the messages will cycle
-    locations={ -- defines the spawn locations for all compilatrons
+    message_cycle=60*15, --- @setting message_cycle 15 seconds default, how often (in ticks) the messages will cycle
+    locations={ --- @setting locations defines the spawn locations for all compilatrons
         ['Spawn']={x=0,y=0}
     },
-    messages={ -- the messages that each one will say, must be same name as its location
+    messages={ --- @setting messages the messages that each one will say, must be same name as its location
         ['Spawn']={
             {'info.website'},
             {'info.read-readme'},

config/death_logger.lua

@@ -1,12 +1,14 @@
---- This config controls what happens when a player dies mostly about map markers and item collection
--- allow_teleport_to_body_command and allow_collect_bodies_command can be over ridden if command_auth_runtime_disable is present
+--- This config controls what happens when a player dies mostly about map markers and item collection;
+-- allow_teleport_to_body_command and allow_collect_bodies_command can be over ridden if command_auth_runtime_disable is present;
 -- if not present then the commands will not be loaded into the game
+-- @config Death-Logger
+
 return {
-    --allow_teleport_to_body_command=false, -- allows use of /return-to-body which teleports you to your last death
-    --allow_collect_bodies_command=false, -- allows use of /collect-body which returns all your items to you and removes the body
-    use_chests_as_bodies=false, -- weather items should be moved into a chest when a player dies
-    auto_collect_bodies=true, -- enables items being returned to the spawn point in chests upon corpse expiring
-    show_map_markers=true, -- shows markers on the map where bodies are
-    include_time_of_death=true, -- weather to include the time of death on the map marker
-    map_icon=nil -- the icon that the map marker shows; nil means no icon; format as a SingleID
+    --WIP_allow_teleport_to_body_command=false, -- allows use of /return-to-body which teleports you to your last death
+    --WIP_allow_collect_bodies_command=false, -- allows use of /collect-body which returns all your items to you and removes the body
+    use_chests_as_bodies=false, --- @setting use_chests_as_bodies weather items should be moved into a chest when a player dies
+    auto_collect_bodies=true, --- @setting auto_collect_bodies enables items being returned to the spawn point in chests upon corpse expiring
+    show_map_markers=true, --- @setting show_map_markers shows markers on the map where bodies are
+    include_time_of_death=true, --- @setting include_time_of_death weather to include the time of death on the map marker
+    map_icon=nil --- @setting map_icon the icon that the map marker shows; nil means no icon; format as a SingleID
 }

config/discord_alerts.lua

@@ -1,4 +1,6 @@
 --- Config file used to enable and disable different push messages for discord
+-- @config Discord-Alerts
+
 return {
     player_reports=true,
     player_warnings=true,

config/expcore-commands/auth_admin.lua

@@ -1,7 +1,9 @@
---- This is a very simple config file which adds a admin only auth function
--- not much to change here its more so it can be enabled and disabled from ./config/file_loader.lua
+--- This is a very simple config file which adds a admin only auth functio;
+-- not much to change here its more so it can be enabled and disabled from ./config/file_loader.lua;
 -- either way you can change the requirements to be "admin" if you wanted to
-local Commands = require 'expcore.commands'
+-- @config Commands-Auth-Admin
+
+local Commands = require 'expcore.commands' --- @dep expcore.commands
 
 Commands.add_authenticator(function(player,command,tags,reject)
     if tags.admin_only then

config/expcore-commands/auth_roles.lua

@@ -1,6 +1,8 @@
 --- This will make commands only work if the role has been allowed it in the role config
-local Commands = require 'expcore.commands'
-local Roles = require 'expcore.roles'
+-- @config Commands-Auth-Roles
+
+local Commands = require 'expcore.commands' --- @dep expcore.commands
+local Roles = require 'expcore.roles' --- @dep expcore.roles
 
 Commands.add_authenticator(function(player,command,tags,reject)
     if Roles.player_allowed(player,'command/'..command) then

config/expcore-commands/auth_runtime_disable.lua

@@ -1,17 +1,23 @@
---- This config for command auth allows commands to be globally enabled and disabled during runtime
+--- This config for command auth allows commands to be globally enabled and disabled during runtime;
 -- this config adds Commands.disable and Commands.enable to enable and disable commands for all users
-local Commands = require 'expcore.commands'
-local Global = require 'utils.global'
+-- @config Commands-Auth-Runtime-Disable
+
+local Commands = require 'expcore.commands' --- @dep expcore.commands
+local Global = require 'utils.global' --- @dep utils.global
 
 local disabled_commands = {}
 Global.register(disabled_commands,function(tbl)
     disabled_commands = tbl
 end)
 
+--- Stops a command from be used by any one
+-- @tparam string command_name the name of the command to disable
 function Commands.disable(command_name)
     disabled_commands[command_name] = true
 end
 
+--- Allows a command to be used again after disable was used
+-- @tparam string command_name the name of the command to enable
 function Commands.enable(command_name)
     disabled_commands[command_name] = nil
 end