Refactor some of the Guis from the legacy plugin (#399)

* Fix bugs in core and add default args to Gui defs

* Refactor production Gui

* Refactor landfill blueprint button

* Fix more bugs in core

* Consistent naming of new guis

* Refactor module inserter gui

* Refactor surveillance gui

* Add shorthand for data from arguments

* Make element names consistent

* Add types

* Change how table rows work

* Refactor player stats gui

* Refactor quick actions gui

* Refactor research milestones gui

* Refactor player bonus gui

* Refactor science production gui

* Refactor autofill gui

* Cleanup use of aligned flow

* Rename "Gui.element" to "Gui.define"

* Rename Gui types

* Rename property_from_arg

* Add guide for making guis

* Add full reference document

* Add condensed reference

* Apply style guide to refactored guis

* Bug fixes

exp_scenario/module/commands/artillery.lua

@@ -10,6 +10,9 @@ local SelectionName = "ExpCommand_Artillery"
 local floor = math.floor
 local abs = math.abs
 
+--- @class ExpCommand_Artillery.commands
+local commands = {}
+
 --- @param player LuaPlayer
 --- @param area BoundingBox
 --- @return boolean
@@ -30,7 +33,9 @@ local function location_break(player, area)
 end
 
 --- Toggle player selection mode for artillery
-Commands.new("artillery", { "exp-commands_artillery.description" })
+--- @class ExpCommand_Artillery.commands.artillery: ExpCommand
+--- @overload fun(player: LuaPlayer)
+commands.artillery = Commands.new("artillery", { "exp-commands_artillery.description" })
     :register(function(player)
         if Selection.is_selecting(player, SelectionName) then
             Selection.stop(player)
@@ -39,7 +44,7 @@ Commands.new("artillery", { "exp-commands_artillery.description" })
             Selection.start(player, SelectionName)
             return Commands.status.success{ "exp-commands_artillery.enter" }
         end
-    end)
+    end) --[[ @as any ]]
 
 --- when an area is selected to add protection to the area
 Selection.on_selection(SelectionName, function(event)
@@ -94,3 +99,7 @@ Selection.on_selection(SelectionName, function(event)
         end
     end
 end)
+
+return {
+    commands = commands,
+}

exp_scenario/module/commands/research.lua

@@ -8,8 +8,8 @@ local format_player_name = Commands.format_player_name_locale
 
 local config = require("modules.exp_legacy.config.research") --- @dep config.research
 
---- @class Command.Research
-local module = {}
+--- @class ExpCommands_Research.commands
+local commands = {}
 
 local research = {
     res_queue_enable = false
@@ -21,7 +21,7 @@ end)
 
 --- @param force LuaForce
 --- @param silent boolean True when no message should be printed
-function module.res_queue(force, silent)
+local function queue_research(force, silent)
     local res_q = force.research_queue
     local res = force.technologies[config.bonus_inventory.log[config.mod_set].name]
 
@@ -38,7 +38,7 @@ end
 
 --- @param state boolean? use nil to toggle current state
 --- @return boolean # New auto research state
-function module.set_auto_research(state)
+local function set_auto_research(state)
     local new_state
     if state == nil then
         new_state = not research.res_queue_enable
@@ -51,37 +51,40 @@ function module.set_auto_research(state)
 end
 
 --- Sets the auto research state
-Commands.new("set-auto-research", { "exp-commands_research.description" })
+--- @class ExpCommand_Artillery.commands.artillery: ExpCommand
+--- @overload fun(player: LuaPlayer, state: boolean?)
+commands.set_auto_research = Commands.new("set-auto-research", { "exp-commands_research.description" })
     :optional("state", { "exp-commands_research.arg-state" }, Commands.types.boolean)
     :add_aliases{ "auto-research" }
     :register(function(player, state)
         --- @cast state boolean?
-        local enabled = module.set_auto_research(state)
+        local enabled = set_auto_research(state)
 
         if enabled then
-            module.res_queue(player.force --[[@as LuaForce]], true)
+            queue_research(player.force --[[@as LuaForce]], true)
         end
 
         local player_name = format_player_name(player)
         game.print{ "exp-commands_research.auto-research", player_name, enabled }
-    end)
+    end) --[[ @as any ]]
 
 --- @param event EventData.on_research_finished
 local function on_research_finished(event)
     if not research.res_queue_enable then return end
 
     local force = event.research.force
-    local research = assert(config.bonus_inventory.log[config.mod_set], "Unknown mod set: " .. tostring(config.mod_set))
-    local technology = assert(force.technologies[research.name], "Unknown technology: " .. tostring(research.name))
-    if technology.level > research.level then
-        module.res_queue(force, event.by_script)
+    local log_research = assert(config.bonus_inventory.log[config.mod_set], "Unknown mod set: " .. tostring(config.mod_set))
+    local technology = assert(force.technologies[log_research.name], "Unknown technology: " .. tostring(log_research.name))
+    if technology.level > log_research.level then
+        queue_research(force, event.by_script)
     end
 end
 
 local e = defines.events
---- @package
-module.events = {
-    [e.on_research_finished] = on_research_finished,
-}
 
-return module
+return {
+    commands = commands,
+    events = {
+        [e.on_research_finished] = on_research_finished,
+    },
+}

exp_scenario/module/commands/teleport.lua

@@ -10,8 +10,13 @@ local Commands = require("modules/exp_commands")
 local Roles = require("modules.exp_legacy.expcore.roles") --- @dep expcore.roles
 local player_allowed = Roles.player_allowed
 
+--- @class ExpCommands_Teleport.commands
+local commands = {}
+
 --- Teleports a player to another player.
-Commands.new("teleport", { "exp-commands_teleport.description-teleport" })
+--- @class ExpCommands_Teleport.commands.teleport: ExpCommand
+--- @overload fun(player: LuaPlayer, other_player: LuaPlayer, target_player: LuaPlayer?)
+commands.teleport = Commands.new("teleport", { "exp-commands_teleport.description-teleport" })
     :argument("player", { "exp-commands_teleport.arg-player-teleport" }, Commands.types.player_alive)
     :optional("target", { "exp-commands_teleport.arg-player-to" }, Commands.types.player_alive)
     :add_aliases{ "tp" }
@@ -29,10 +34,12 @@ Commands.new("teleport", { "exp-commands_teleport.description-teleport" })
         elseif not teleport_player(other_player, target_player.physical_surface, target_player.physical_position) then
             return Commands.status.error{ "exp-commands_teleport.unavailable" }
         end
-    end)
+    end) --[[ @as any ]]
 
 --- Teleports a player to you.
-Commands.new("bring", { "exp-commands_teleport.description-bring" })
+--- @class ExpCommands_Teleport.commands.bring: ExpCommand
+--- @overload fun(player: LuaPlayer, other_player: LuaPlayer)
+commands.bring = Commands.new("bring", { "exp-commands_teleport.description-bring" })
     :argument("player", { "exp-commands_teleport.arg-player-from" }, Commands.types.player_alive)
     :add_flags{ "admin_only" }
     :register(function(player, other_player)
@@ -42,10 +49,12 @@ Commands.new("bring", { "exp-commands_teleport.description-bring" })
         elseif not teleport_player(other_player, player.physical_surface, player.physical_position) then
             return Commands.status.error{ "exp-commands_teleport.unavailable" }
         end
-    end)
+    end) --[[ @as any ]]
 
 --- Teleports you to a player.
-Commands.new("goto", { "exp-commands_teleport.description-goto" })
+--- @class ExpCommands_Teleport.commands.goto: ExpCommand
+--- @overload fun(player: LuaPlayer, other_player: LuaPlayer)
+commands["goto"] = Commands.new("goto", { "exp-commands_teleport.description-goto" })
     :argument("player", { "exp-commands_teleport.arg-player-to" }, Commands.types.player_alive)
     :add_flags{ "admin_only" }
     :register(function(player, other_player)
@@ -55,10 +64,12 @@ Commands.new("goto", { "exp-commands_teleport.description-goto" })
         elseif not teleport_player(player, other_player.physical_surface, other_player.physical_position) then
             return Commands.status.error{ "exp-commands_teleport.unavailable" }
         end
-    end)
+    end) --[[ @as any ]]
 
 --- Teleport to spawn
-Commands.new("spawn", { "exp-commands_teleport.description-spawn" })
+--- @class ExpCommands_Teleport.commands.spawn: ExpCommand
+--- @overload fun(player: LuaPlayer, other_player: LuaPlayer)
+commands.spawn = Commands.new("spawn", { "exp-commands_teleport.description-spawn" })
     :optional("player", { "exp-commands_teleport.arg-player-from" }, Commands.types.player_alive)
     :defaults{
         player = function(player)
@@ -81,4 +92,8 @@ Commands.new("spawn", { "exp-commands_teleport.description-spawn" })
         else
             return Commands.status.unauthorised()
         end
-    end)
+    end) --[[ @as any ]]
+
+return {
+    commands = commands,
+}

exp_scenario/module/commands/trains.lua

@@ -6,34 +6,34 @@ local Commands = require("modules/exp_commands")
 local format_player_name = Commands.format_player_name_locale
 local format_number = require("util").format_number
 
---- @class Command.Trains
-local module = {}
-
-function module.manual(player, surface, force)
-    local trains = game.train_manager.get_trains{
-        stock = "locomotive",
-        has_passenger = false,
-        is_manual = true,
-        is_moving = false,
-        surface = surface,
-        force = force,
-    }
-
-    for _, train in ipairs(trains) do
-        train.manual_mode = false
-    end
-
-    game.print{ "exp-commands_trains.response", format_player_name(player), format_number(#trains, false) }
-end
+--- @class ExpCommand_Trains.commands
+local commands = {}
 
 --- Set all trains to automatic
-Commands.new("set-trains-to-automatic", { "exp-commands_trains.description" })
+--- @class ExpCommand_Artillery.commands.artillery: ExpCommand
+--- @overload fun(player: LuaPlayer, surface: LuaSurface?, force: LuaForce?)
+commands.set_trains_to_automatic = Commands.new("set-trains-to-automatic", { "exp-commands_trains.description" })
     :optional("surface", { "exp-commands_trains.arg-surface" }, Commands.types.surface)
     :optional("force", { "exp-commands_trains.arg-force" }, Commands.types.force)
     :register(function(player, surface, force)
         --- @cast surface LuaSurface?
         --- @cast force LuaForce?
-        module.manual(player, surface, force)
-    end)
+        local trains = game.train_manager.get_trains{
+            stock = "locomotive",
+            has_passenger = false,
+            is_manual = true,
+            is_moving = false,
+            surface = surface,
+            force = force,
+        }
 
-return module
+        for _, train in ipairs(trains) do
+            train.manual_mode = false
+        end
+
+        game.print{ "exp-commands_trains.response", format_player_name(player), format_number(#trains, false) }
+    end) --[[ @as any ]]
+
+return {
+    commands = commands,
+}

exp_scenario/module/commands/waterfill.lua

@@ -15,8 +15,13 @@ local planet = {
     ["aquilo"] = "ammoniacal-ocean"
 }
 
+--- @class ExpCommand_Waterfill.commands
+local commands = {}
+
 --- Toggle player selection mode for artillery
-Commands.new("waterfill", { "exp-commands_waterfill.description" })
+--- @class ExpCommands_Waterfill.commands.waterfill: ExpCommand
+--- @overload fun(player: LuaPlayer)
+commands.waterfill = Commands.new("waterfill", { "exp-commands_waterfill.description" })
     :register(function(player)
         if Selection.is_selecting(player, SelectionName) then
             Selection.stop(player)
@@ -26,13 +31,13 @@ Commands.new("waterfill", { "exp-commands_waterfill.description" })
             local item_count_craft = math.min(math.floor(player.get_item_count("explosives") / 10), player.get_item_count("barrel"), player.get_item_count("grenade"))
             local item_count_total = item_count_cliff + item_count_craft
             if item_count_total == 0 then
-                return player.print{ "exp-commands_waterfill.requires-explosives" }
+                return Commands.status.error{ "exp-commands_waterfill.requires-explosives" }
             else
                 Selection.start(player, SelectionName)
-                return player.print{ "exp-commands_waterfill.enter" }
+                return Commands.status.success{ "exp-commands_waterfill.enter" }
             end
         end
-    end)
+    end) --[[ @as any ]]
 
 --- When an area is selected to be converted to water
 Selection.on_selection(SelectionName, function(event)
@@ -116,3 +121,7 @@ Selection.on_selection(SelectionName, function(event)
         player.print({ "exp-commands_waterfill.complete", tile_count }, Commands.print_settings.default)
     end
 end)
+
+return {
+    commands = commands,
+}