Added production to control

modules/control/jail.lua

@@ -1,9 +1,12 @@
 --[[-- Control Module - Jail
     - Adds a way to jail players and temp ban players.
-    @module Jail
+    @control Jail
     @alias Jail
 
     @usage
+    -- import the module from the control modules
+    local Jail = require 'modules.control.jail'
+
     -- This will move 'MrBiter' to the jail role and remove all other roles from them
     -- the player name and reason are only so they can be included in the event for user feedback
     Jail.jail_player('MrBiter','Cooldude2606','Likes biters too much')
@@ -17,9 +20,17 @@
     Jail.temp_ban_player('MrBiter','Cooldude2606','Likes biters too much')
 ]]
 
+--- Allows moving players into the jail role
+-- @dep expcore.roles
 local Roles = require 'expcore.roles'
+--- Allows accessing a player from any value
+-- @dep utils.game
 local Game = require 'utils.game'
+--- Allows storing data in the global table
+-- @dep utils.global
 local Global = require 'utils.global'
+--- Use of move_items to clear inventroies
+-- @dep expcore.common
 local move_items = ext_require('expcore.common','move_items')
 
 local valid_player = Game.get_player_from_any
@@ -82,7 +93,7 @@ local function event_emit(event,player,by_player_name,reason)
     })
 end
 
---- Jail functions.
+--- Jail.
 -- Functions related to jail
 -- @section jail-functions
 
@@ -137,7 +148,7 @@ function Jail.unjail_player(player,by_player_name)
     return true
 end
 
---- Temp ban functions.
+--- Temp ban.
 -- Functions related to temp ban
 -- @section temp-ban-functions
 

modules/control/production.lua

@@ -0,0 +1,237 @@
+--[[-- Control Module - Production
+    - Common functions used to track production of items
+    @control Production
+    @alias Production
+
+    @usage
+    -- import the module from the control modules
+    local Production = require 'modules.control.production'
+
+    -- This will return the less precise index from the one given
+    -- this means that one_second will return one_minute or ten_hours will return fifty_hours
+    -- the other precision work like wise
+    Production.precision_up(defines.flow_precision_index.one_second)
+
+    -- The get production function is used to get production, consumion and net
+    -- it may be used for any item and with any precision level, use total for total
+    Production.get_production(game.forces.player,'iron-plate',defines.flow_precision_index.one_minute)
+
+    -- The fluctuations works by compearing recent production with the average over time
+    -- again any precision may be used, apart from one_thousand_hours as there would be no valid average
+    Production.get_fluctuations(game.forces.player,'iron-plate',defines.flow_precision_index.one_minute)
+
+    -- ETA is calculated based on what function you use but all share a similar method
+    -- for production eta it will take current production average given by the precision
+    -- and work out how many ticks it will require to make the required amount (1000 by default)
+    Production.get_production_eta(game.forces.player,'iron-plate',defines.flow_precision_index.one_minute,250000)
+
+    -- Both get_color and format_number are helper functions to help format production stats
+    -- get_color will return green,orange,red,or grey based on the active_value
+    -- the passive_value is used when active_value is 0 and can only return orange,red,or grey
+    Production.get_color(clamp,active_value,passive_value)
+
+]]
+
+--- Provides colors for Production.get_color
+-- @dep resources.color_presets
+local Colors = require 'resources.color_presets'
+--- Provides format_number function to add surfixs
+-- @dep util
+local format_number = ext_require('util','format_number')
+
+local precision_index = defines.flow_precision_index
+local Production = {}
+
+--- Precision.
+-- Functions which are used to do basic things
+-- @section precision
+
+--- Gets the next lesser precision index value, eg 1 second -> 1 minute
+-- @tparam defines.flow_precision_index precision
+-- @treturn[1] defines.flow_precision_index the next precision value
+-- @treturn[1] number the multiplicive difference between the values
+function Production.precision_up(precision)
+    if precision == precision_index.one_second then return precision_index.one_minute,60
+    elseif precision == precision_index.one_minute then return precision_index.ten_minutes,10
+    elseif precision == precision_index.ten_minutes then return precision_index.one_hour,6
+    elseif precision == precision_index.one_hour then return precision_index.ten_hours,10
+    elseif precision == precision_index.ten_hours then return precision_index.fifty_hours,5
+    elseif precision == precision_index.fifty_hours then return precision_index.two_hundred_fifty_hours,5
+    elseif precision == precision_index.two_hundred_fifty_hours then return precision_index.one_thousand_hours,4
+    end
+end
+
+--- Gets the next greater precision index value, eg 1 minute -> 1 second
+-- @tparam defines.flow_precision_index precision
+-- @treturn[1] defines.flow_precision_index the next precision value
+-- @treturn[1] number the multiplicive difference between the values
+function Production.precision_down(precision)
+    if precision == precision_index.one_minute then return precision_index.one_second,60
+    elseif precision == precision_index.ten_minutes then return precision_index.one_minute,10
+    elseif precision == precision_index.one_hour then return precision_index.ten_minutes,6
+    elseif precision == precision_index.ten_hours then return precision_index.one_hour,10
+    elseif precision == precision_index.fifty_hours then return precision_index.ten_hours,5
+    elseif precision == precision_index.two_hundred_fifty_hours then return precision_index.fifty_hours,5
+    elseif precision == precision_index.one_thousand_hours then return precision_index.two_hundred_fifty_hours,4
+    end
+end
+
+--- Gets the number of tick that precision is given over, eg 1 minute -> 60 ticks
+-- @tparam defines.flow_precision_index precision
+-- @treturn number the number of ticks in this time
+function Production.precision_ticks(precision)
+    if precision == precision_index.one_second then return 60
+    elseif precision == precision_index.one_minute then return 3600
+    elseif precision == precision_index.ten_minutes then return 36000
+    elseif precision == precision_index.one_hour then return 216000
+    elseif precision == precision_index.ten_hours then return 2160000
+    elseif precision == precision_index.fifty_hours then return 10800000
+    elseif precision == precision_index.two_hundred_fifty_hours then return 54000000
+    elseif precision == precision_index.one_thousand_hours then return 216000000
+    end
+end
+
+--- Statistics.
+-- Functions used to get information about production
+-- @section stats
+
+--- Returns the production data for the whole game time
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @treturn table contains total made, used and net
+function Production.get_production_total(force,item_name)
+    local stats = force.item_production_statistics
+    local made = stats.get_input_count(item_name) or 0
+    local used = stats.get_output_count(item_name) or 0
+
+    return {
+        made=made,
+        used=used,
+        net=made-used
+    }
+
+end
+
+--- Returns the production data for the given precision game time
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @tparam defines.flow_precision_index precision the precision that you want the data given to
+-- @treturn table contains made, used and net
+function Production.get_production(force,item_name,precision)
+    local stats = force.item_production_statistics.get_flow_count
+    local made = stats{name=item_name,input=true,precision_index=precision} or 0
+    local used = stats{name=item_name,input=false,precision_index=precision} or 0
+
+    return {
+        made=made,
+        used=used,
+        net=made-used
+    }
+
+end
+
+--- Returns the current fluctuation from the average
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @tparam defines.flow_precision_index precision the precision that you want the data given to
+-- @treturn table contains made, used and net
+function Production.get_fluctuations(force,item_name,precision)
+    local percision_up = Production.precision_up(precision)
+    local current = Production.get_production(force,item_name,precision)
+    local previous = Production.get_production(force,item_name,percision_up)
+
+    return {
+        made=(current.made/previous.made)-1,
+        used=(current.used/previous.used)-1,
+        net=(current.net/previous.net)-1,
+    }
+
+end
+
+--- Returns the amount of ticks required to produce a certain amount
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @tparam defines.flow_precision_index precision the precision that you want the data given to
+-- @tparam[opt=1000] number required the number of items that are required to be made
+-- @treturn number the number of ticks required to produce this ammount of items
+function Production.get_production_eta(force,item_name,precision,required)
+    required = required or 1000
+    local ticks = Production.precision_ticks(precision)
+    local production = Production.get_production(force,item_name,precision)
+    return production.made == 0 and -1 or ticks*required/production.made
+end
+
+--- Returns the amount of ticks required to consume a certain amount
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @tparam defines.flow_precision_index precision the precision that you want the data given to
+-- @tparam[opt=1000] number required the number of items that are required to be consumed
+-- @treturn number the number of ticks required to consume this ammount of items
+function Production.get_consumsion_eta(force,item_name,precision,required)
+    required = required or 1000
+    local ticks = Production.precision_ticks(precision)
+    local production = Production.get_production(force,item_name,precision)
+    return production.used == 0 and -1 or ticks*required/production.used
+end
+
+--- Returns the amount of ticks required to produce but not consume a certain amount
+-- @tparam LuaForce force the force to get the data for
+-- @tparam string item_name the name of the item that you want the data about
+-- @tparam defines.flow_precision_index precision the precision that you want the data given to
+-- @tparam[opt=1000] number required the number of items that are required to be made but not used
+-- @treturn number the number of ticks required to produce, but not use, this ammount of items
+function Production.get_net_eta(force,item_name,precision,required)
+    required = required or 1000
+    local ticks = Production.precision_ticks(precision)
+    local production = Production.get_production(force,item_name,precision)
+    return production.net == 0 and -1 or ticks*required/production.net
+end
+
+--- Formating.
+-- Functions used to format production values
+-- @section formating
+
+--- Returns a color value bassed on the value that was given
+-- @tparam number clamp value which seperates the different colours
+-- @tparam number active_value first value tested, tested against clamp
+-- @tparam number passive_value second value tested, tested against 0
+-- @treturn table contains r,g,b keys
+function Production.get_color(clamp,active_value,passive_value)
+    if active_value > clamp then
+        return Colors.light_green
+    elseif active_value < -clamp then
+        return Colors.indian_red
+    elseif active_value ~= 0 then
+        return Colors.orange
+    elseif passive_value and passive_value > 0 then
+        return Colors.orange
+    elseif passive_value and passive_value ~= 0 then
+        return Colors.indian_red
+    else
+        return Colors.grey
+    end
+end
+
+--- Returns three parts used to format a number
+-- @tparam number value the value to format
+-- @treturn[1] string the sign for the number
+-- @treturn[1] string the surfix for any unit used
+function Production.format_number(value)
+    local rtn = format_number(math.round(value,1),true)
+    local surfix = rtn:sub(-1)
+
+    if value > 0 then
+        rtn = '+'..rtn
+    elseif value == 0 and rtn:sub(1,1) == '-' then
+        rtn = rtn:sub(2)
+    end
+
+    if not tonumber(surfix) then
+        return surfix,rtn:sub(1,-2)
+    else
+        return '',rtn
+    end
+
+end
+
+return Production

modules/control/reports.lua

@@ -1,9 +1,12 @@
 --[[-- Control Module - Reports
     - Adds a way to report players and store report messages.
-    @module Reports
+    @control Reports
     @alias Reports
 
     @usage
+    -- import the module from the control modules
+    local Reports = require 'modules.control.reports'
+
     -- This will place a report on "MrBiter" (must be a valid player) the report will have been made
     -- by "Cooldude2606" (must be the player name) with the reason 'Liking biters too much' this can be
     -- seen by using Reports.get_report.
@@ -21,7 +24,11 @@
 
 ]]
 
+--- Allows getting player from any value
+-- @dep utils.game
 local Game = require 'utils.game'
+--- Allows storing of data in global table
+-- @dep utils.global
 local Global = require 'utils.global'
 
 local valid_player = Game.get_player_from_any
@@ -49,7 +56,7 @@ Global.register(user_reports,function(tbl)
     user_reports = tbl
 end)
 
---- Get functions.
+--- Getters.
 -- Functions used to get information from reports
 -- @section get-functions
 
@@ -112,7 +119,7 @@ function Reports.count_reports(player,custom_count)
     end
 end
 
---- Set functions.
+--- Setters.
 -- Functions used to get information from reports
 -- @section set-functions
 

modules/control/warnings.lua

@@ -1,9 +1,12 @@
 --[[-- Control Module - Warnings
     - Adds a way to give and remove warnings to players.
-    @module Warnings
+    @control Warnings
     @alias Warnings
 
     @usage
+    -- import the module from the control modules
+    local Warnings = require 'modules.control.warnings'
+
     -- This will add a warning to the player
     Warnings.add_warning('MrBiter','Cooldude2606','Killed too many biters')
 
@@ -18,9 +21,17 @@
     Warnings.clear_warnings('MrBiter','Cooldude2606')
 ]]
 
+--- Allows registering of custom events
+-- @dep utils.event
 local Event = require 'utils.event'
+--- Allows getting player from any value
+-- @dep utils.game
 local Game = require 'utils.game'
+--- Allows storing in the global table
+-- @dep utils.global
 local Global = require 'utils.global'
+--- Config file for this module
+-- @dep config.warnings
 local config = require 'config.warnings'
 
 local valid_player = Game.get_player_from_any