Move jail into exp_scenario

With the role system finished the jail module has nothing legacy left in
it, so it moves to exp_scenario/module/control/jail.lua and the copy in
exp_legacy is removed. The module takes LuaPlayer only, requires a reason,
returns false rather than nil when there is nothing to do, and exposes its
event ids as Jail.on_player_jailed and Jail.on_player_unjailed in the same
shape as exp_util's selection events.

exp_legacy/module/config/gui/player_list_actions.lua

@@ -10,7 +10,7 @@ local Gui = require("modules/exp_gui")
 local Roles = require("modules/exp_roles")
 local Reports = require("modules.exp_legacy.modules.control.reports") --- @dep modules.control.reports
 local Warnings = require("modules.exp_legacy.modules.control.warnings") --- @dep modules.control.warnings
-local Jail = require("modules.exp_legacy.modules.control.jail") --- @dep modules.control.jail
+local Jail = require("modules/exp_scenario/control/jail")
 local Colors = require("modules/exp_util/include/color")
 local format_player_name = ExpUtil.format_player_name_locale
 
@@ -119,7 +119,7 @@ end
 local jail_player = new_button("utility/multiplayer_waiting_icon", { "exp-gui_player-list.jail-player" })
     :on_click(function(def, player, element)
         local selected_player, selected_player_color = get_action_player(player)
-        if Jail.is_jailed(selected_player.name) then
+        if Jail.is_jailed(selected_player) then
             player.print({ "exp-commands_jail.already-jailed", selected_player_color }, Colors.orange_red)
         else
             set_selected_action(player, "exp_scenario.command.jail")
@@ -130,7 +130,7 @@ local function jail_player_callback(player, reason)
     local selected_player, selected_player_color = get_action_player(player)
     local by_player_name_color = format_player_name(player)
     game.print{ "exp-commands_jail.jailed", selected_player_color, by_player_name_color, reason }
-    Jail.jail_player(selected_player.name, player.name, reason)
+    Jail.jail_player(selected_player, player.name, reason)
 end
 
 --- Kicks the action player, requires a reason

exp_legacy/module/modules/control/jail.lua

@@ -1,119 +0,0 @@
---[[-- Control Module - Jail
-    - Adds a way to jail players.
-    @control Jail
-    @alias Jail
-
-    @usage
-    -- import the module from the control modules
-    local Jail = require("modules.exp_legacy.modules.control.jail") --- @dep modules.control.jail
-
-    -- This will give 'MrBiter' the jail role, which suppresses all of their other roles
-    -- 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')
-
-    -- This will remove the jail role from 'MrBiter', restoring their other roles
-    -- again as above the player name is only used in the event for user feedback
-    Jail.unjail_player('MrBiter', 'Cooldude2606')
-]]
-
-local Roles = require("modules/exp_roles")
-
-local valid_player = function(p) return type(p) == "userdata" and p or game.get_player(p) end
-
---- The role given to jailed players, it has a higher priority than every other role
-local function jail_role()
-    return assert(Roles.get_role_by_name("Jail"), "The Jail role does not exist")
-end
-
-local Jail = {
-    events = {
-        --- When a player is assigned to jail
-        -- @event on_player_jailed
-        -- @tparam number player_index the index of the player who was jailed
-        -- @tparam string by_player_name the name of the player who jailed the other player
-        -- @tparam string reason the reason that the player was jailed
-        on_player_jailed = script.generate_event_name(),
-        --- When a player is unassigned from jail
-        -- @event on_player_unjailed
-        -- @tparam number player_index the index of the player who was unjailed
-        -- @tparam string by_player_name the name of the player who unjailed the other player
-        on_player_unjailed = script.generate_event_name(),
-    },
-}
-
---- Used to emit the jail related events
--- @tparam number event the name of the event that will be emited
--- @tparam LuaPlayer player the player who is being acted on
--- @tparam string by_player_name the player who is doing the action
--- @tparam string reason the reason for the action (jail)
-local function event_emit(event, player, by_player_name, reason)
-    script.raise_event(event, {
-        name = event,
-        tick = game.tick,
-        player_index = player.index,
-        by_player_name = by_player_name,
-        reason = reason,
-    })
-end
-
---- Jail.
--- Functions related to jail
--- @section jail-functions
-
---- Checks if the player is currently in jail
--- @tparam LuaPlayer player the player to check if they are in jail
--- @treturn boolean whether the player is currently in jail
-function Jail.is_jailed(player)
-    local valid = valid_player(player)
-    return valid ~= nil and jail_role():has_player(valid)
-end
-
---- Moves a player to jail, which suppresses all of their other roles
--- @tparam LuaPlayer player the player who will be jailed
--- @tparam string by_player_name the name of the player who is doing the jailing
--- @tparam[opt='Non given.'] string reason the reason that the player is being jailed
--- @treturn boolean wheather the user was jailed successfully
-function Jail.jail_player(player, by_player_name, reason)
-    player = valid_player(player)
-    if not player then return end
-    if not by_player_name then return end
-
-    reason = reason or "Non given."
-
-    local role = jail_role()
-    if role:has_player(player) then return end
-
-    player.walking_state = { walking = false, direction = player.walking_state.direction }
-    player.riding_state = { acceleration = defines.riding.acceleration.nothing, direction = player.riding_state.direction }
-    player.mining_state = { mining = false }
-    player.shooting_state = { state = defines.shooting.not_shooting, position = player.shooting_state.position }
-    player.picking_state = false
-    player.repair_state = { repairing = false, position = player.repair_state.position }
-
-    role:assign(player, { by_player_name = by_player_name, silent = true })
-
-    event_emit(Jail.events.on_player_jailed, player, by_player_name, reason)
-
-    return true
-end
-
---- Moves a player out of jail, which restores all of their other roles
--- @tparam LuaPlayer player the player that will be unjailed
--- @tparam string by_player_name the name of the player that is doing the unjail
--- @treturn boolean whether the player was unjailed successfully
-function Jail.unjail_player(player, by_player_name)
-    player = valid_player(player)
-    if not player then return end
-    if not by_player_name then return end
-
-    local role = jail_role()
-    if not role:has_player(player) then return end
-
-    role:unassign(player, { by_player_name = by_player_name, silent = true })
-
-    event_emit(Jail.events.on_player_unjailed, player, by_player_name)
-
-    return true
-end
-
-return Jail

exp_scenario/module/commands/jail.lua

@@ -5,7 +5,7 @@ Adds a commands that allow admins to jail and unjail
 local Commands = require("modules/exp_commands")
 local format_player_name = Commands.format_player_name_locale
 
-local Jail = require("modules.exp_legacy.modules.control.jail") --- @dep modules.control.jail
+local Jail = require("modules/exp_scenario/control/jail")
 
 --- Puts a player into jail and removes all other roles.
 Commands.new("jail", { "exp-commands_jail.description" })

exp_scenario/module/control/discord_alerts.lua

@@ -167,8 +167,8 @@ end
 
 --- When a player is jailed or unjailed
 if config.player_jail then
-    local Jail = require("modules.exp_legacy.modules.control.jail")
+    local Jail = require("modules/exp_scenario/control/jail")
-    events[Jail.events.on_player_jailed] = function(event)
+    events[Jail.on_player_jailed] = function(event)
         local player_name, by_player_name = get_player_name(event)
         emit_event{
             title = "Jail",
@@ -181,7 +181,7 @@ if config.player_jail then
             },
         }
     end
-    events[Jail.events.on_player_unjailed] = function(event)
+    events[Jail.on_player_unjailed] = function(event)
         local player_name, by_player_name = get_player_name(event)
         emit_event{
             title = "Unjail",

exp_scenario/module/control/jail.lua

@@ -0,0 +1,89 @@
+--[[-- Control - Jail
+Adds a way to jail players, the jail role suppresses all of their other roles
+]]
+
+local Roles = require("modules/exp_roles")
+
+--- @class ExpScenario_Jail
+local Jail = {
+    --- Raised when a player is put into jail
+    --- @type EventData.ExpScenario_Jail.on_player_jailed
+    on_player_jailed = script.generate_event_name(),
+    --- Raised when a player is taken out of jail
+    --- @type EventData.ExpScenario_Jail.on_player_unjailed
+    on_player_unjailed = script.generate_event_name(),
+}
+
+--- @class EventData.ExpScenario_Jail.on_player_jailed : EventData
+--- @field player_index uint
+--- @field by_player_name string
+--- @field reason string
+
+--- @class EventData.ExpScenario_Jail.on_player_unjailed : EventData
+--- @field player_index uint
+--- @field by_player_name string
+
+--- The role given to jailed players, it has a higher priority than every other role
+--- @return ExpRoles.Role
+local function jail_role()
+    return (assert(Roles.get_role_by_name("Jail"), "The Jail role does not exist"))
+end
+
+--- Check if a player is in jail
+--- @param player LuaPlayer
+--- @return boolean
+function Jail.is_jailed(player)
+    return jail_role():has_player(player)
+end
+
+--- Put a player into jail, which suppresses all of their other roles
+--- @param player LuaPlayer
+--- @param by_player_name string
+--- @param reason string
+--- @return boolean # False when the player was already in jail
+function Jail.jail_player(player, by_player_name, reason)
+    local role = jail_role()
+    if role:has_player(player) then return false end
+
+    -- Stop whatever the player is doing, the jail permission group stops them from starting again
+    player.walking_state = { walking = false, direction = player.walking_state.direction }
+    player.riding_state = { acceleration = defines.riding.acceleration.nothing, direction = player.riding_state.direction }
+    player.mining_state = { mining = false }
+    player.shooting_state = { state = defines.shooting.not_shooting, position = player.shooting_state.position }
+    player.picking_state = false
+    player.repair_state = { repairing = false, position = player.repair_state.position }
+
+    role:assign(player, { by_player_name = by_player_name, silent = true })
+
+    script.raise_event(Jail.on_player_jailed, {
+        name = Jail.on_player_jailed,
+        tick = game.tick,
+        player_index = player.index,
+        by_player_name = by_player_name,
+        reason = reason,
+    })
+
+    return true
+end
+
+--- Take a player out of jail, which restores all of their other roles
+--- @param player LuaPlayer
+--- @param by_player_name string
+--- @return boolean # False when the player was not in jail
+function Jail.unjail_player(player, by_player_name)
+    local role = jail_role()
+    if not role:has_player(player) then return false end
+
+    role:unassign(player, { by_player_name = by_player_name, silent = true })
+
+    script.raise_event(Jail.on_player_unjailed, {
+        name = Jail.on_player_unjailed,
+        tick = game.tick,
+        player_index = player.index,
+        by_player_name = by_player_name,
+    })
+
+    return true
+end
+
+return Jail

exp_scenario/module/control/protection_jail.lua

@@ -4,7 +4,7 @@ When a player triggers protection multiple times they are automatically jailed
 
 local ExpUtil = require("modules/exp_util")
 local Storage = require("modules/exp_util/storage")
-local Jail = require("modules.exp_legacy.modules.control.jail")
+local Jail = require("modules/exp_scenario/control/jail")
 local Protection = require("modules.exp_legacy.modules.control.protection")
 
 local format_player_name = ExpUtil.format_player_name_locale

exp_scenario/module/control/report_jail.lua

@@ -3,7 +3,7 @@ When a player is reported, the player is automatically jailed if the combined pl
 ]]
 
 local ExpUtil = require("modules/exp_util")
-local Jail = require("modules.exp_legacy.modules.control.jail")
+local Jail = require("modules/exp_scenario/control/jail")
 local Reports = require("modules.exp_legacy.modules.control.reports")
 
 local max = math.max