Added comments

locale/en/addons.cfg

@@ -33,4 +33,6 @@ pre-kick=This is your last warning before you are kicked.
 kick=You were kicked for having too many warnings; you may rejoy if you wish.
 pre-pre-ban=You are close to reciving 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; Vist __1__ to request a ban appeal.
+ban=You were banned for having too many warnings; Vist __1__ to request a ban appeal.
+script-warning=You are reciving script warnings; if you recive too many you will recive a permiment warning (__1__/__2__)
+script-wrning-removed=A script warning has expired (__1__/__2__)

modules/addons/warnings-control.lua

@@ -2,6 +2,7 @@ local Game = require 'utils.game'
 local Global = require 'utils.global'
 local Event = require 'utils.event'
 local config = require 'config.warnings'
+require 'utils.table'
 
 local Public = {
     user_warnings={},
@@ -33,6 +34,11 @@ local function event_emit(event,player,by_player_name)
     })
 end
 
+--- Adds X number (default 1) of warnings to a player from the given player
+-- @tparam player LuaPlayer the player to add the warning to
+-- @tparam[opt='<server>'] by_player_name string the name of the player doing the action
+-- @tparam[opt=1] count number the number of warnings to add
+-- @treturn number the new number of warnings
 function Public.add_warnings(player,by_player_name,count)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -50,6 +56,11 @@ function Public.add_warnings(player,by_player_name,count)
     return #warnings
 end
 
+--- Removes X number (default 1) of warnings from a player, removes in order fifo
+-- @tparam player LuaPlayer the player to remove the warnings from
+-- @tparam[opt='<server>'] by_playey_name string the name of the player doing the action
+-- @tparam[opt=1] count number the number of warnings to remove (if greater than current warning count then all are removed)
+-- @treturn number the new number of warnings
 function Public.remove_warnings(player,by_player_name,count)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -69,11 +80,16 @@ function Public.remove_warnings(player,by_player_name,count)
     return #warnings
 end
 
+--- Clears all warnings from a player, emits event multiple times as if remove_warnings was used
+-- @tparam player LuaPlayer the player to clear the warnings of
+-- @tparam[oot='<server>'] by_player_name string the name of the player who is doing the action
+-- @treturn boolean true if the warnings were cleared, nil if error
 function Public.clear_warnings(player,by_player_name)
     player = Game.get_player_from_any(player)
     if not player then return end
     local warnings = Public.user_warnings[player.name]
     if not warnings then return end
+    by_player_name = by_player_name or '<server>'
     for _=1,#warnings do
         event_emit(Public.player_warning_removed,player,by_player_name)
     end
@@ -81,6 +97,10 @@ function Public.clear_warnings(player,by_player_name)
     return true
 end
 
+--- Gets the number of warnings that a player has, raw table will contain the names of who gave warnings
+-- @tparam player LuaPlayer the player to get the warnings of
+-- @tparam[opt=false] raw_table when true will return a table which contains who gave warnings (the table stored in global)
+-- @treturn number the number of warnings a player has, a table if raw_table is true
 function Public.get_warnings(player,raw_table)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -92,6 +112,10 @@ function Public.get_warnings(player,raw_table)
     end
 end
 
+--- Adds a temp warning to a player that will timeout after some time, used for script given warnings (ie silent to outside players as a buffer)
+-- @tparam player LuaPlayer the player to give the warnings to
+-- @tparam[opt=1] count number the number of warnings to give to the player
+-- @treturn number the new number of warnings
 function Public.add_temp_warnings(player,count)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -108,6 +132,7 @@ function Public.add_temp_warnings(player,count)
     return #warnings
 end
 
+-- temp warnings cant be removed on demand only after X amount of time
 local temp_warning_cool_down = config.temp_warning_cool_down*3600
 Event.on_nth_tick(temp_warning_cool_down/4,function()
     local check_time = game.tick-temp_warning_cool_down
@@ -125,11 +150,16 @@ Event.on_nth_tick(temp_warning_cool_down/4,function()
     end
 end)
 
+--- Clears all temp warnings from a player, emits events as if the warnings had been removed due to time
+-- @tparam player LuaPlayer the player to clear the warnings of
+-- @tparam[opt='<server>'] by_player_name string the name of the player doing the action
+-- @treturn boolean true if the warnings were cleared, nil for error
 function Public.clear_temp_warnings(player,by_player_name)
     player = Game.get_player_from_any(player)
     if not player then return end
     local warnings = Public.user_temp_warnings[player.name]
     if not warnings then return end
+    by_player_name = by_player_name or '<server>'
     for _=1,#warnings do
         event_emit(Public.player_temp_warning_removed,player,by_player_name)
     end
@@ -137,6 +167,10 @@ function Public.clear_temp_warnings(player,by_player_name)
     return true
 end
 
+--- Gets the number of temp warnings, raw table is a table of when temp warnings were given
+-- @tparam player LuaPlayer the player to get the warnings of
+-- @tparam[opt=false] raw_table if true will return a table of ticks when warnings were added (the global table)
+-- @treturn number the number of warnings which the player has, a table if raw_table is true
 function Public.get_temp_warnings(player,raw_table)
     player = Game.get_player_from_any(player)
     if not player then return end
@@ -148,10 +182,39 @@ function Public.get_temp_warnings(player,raw_table)
     end
 end
 
-Event.add(Public.player_temp_warning_added,function(event)
-    if event.temp_warning_count > config.temp_warning_limit then
-        Public.add_warnings(event.player_index,event.by_player_name)
+-- when a player gets a warning the actions in config are ran
+Event.add(Public.player_warning_added,function(event)
+    local action = config.actions[event.warning_count]
+    if not action then return end
+    local player = Game.get_player_by_index(event.player_index)
+    if type(action) == 'function' then
+        -- player: player who got the warnings,by_player_name: player who gave the last warning,number_of_warnings: the current number of warnings
+        local success,err = pcall(action,player,event.by_player_name,event.warning_count)
+        if not success then error(err) end
+    elseif type(action) == 'table' then
+        -- {locale,by_player_name,number_of_warning,...}
+        local current_action = table.deep_copy(action)
+        table.insert(current_action,1,event.by_player_name)
+        table.insert(current_action,1,event.warning_count)
+        player.print(current_action)
+    elseif type(action) == 'string' then
+        player.print(action)
     end
 end)
 
+-- when a player gets a tempo warnings it is checked that it is not above the max
+Event.add(Public.player_temp_warning_added,function(event)
+    local player = Game.get_player_by_index(event.player_index)
+    if event.temp_warning_count > config.temp_warning_limit then
+        Public.add_warnings(event.player_index,event.by_player_name)
+    else
+        player.print{'warnings.script-warning',event.temp_warning_count,config.temp_warning_limit}
+    end
+end)
+
+Event.add(Public.player_temp_warning_removed,function(event)
+    local player = Game.get_player_by_index(event.player_index)
+    player.print{'warnings.script-warning-removed',event.temp_warning_count,config.temp_warning_limit}
+end)
+
 return Public