Rework the matchmaker lobby (autolobby)

engine/User.lua

@@ -709,14 +709,15 @@ end
 ---@alias UILobbyProtocols "UDP" | "TCP" | "None
 
 --- For internal use by `CreateLobbyComm()`
----@param lobbyComClass fa-class
+---@generic T
+---@param lobbyComClass T
 ---@param protocol UILobbyProtocols
 ---@param localPort number
 ---@param maxConnections number
 ---@param playerName string
 ---@param playerUID? string
 ---@param natTraversalProvider? userdata
----@return UILobbyCommunication
+---@return T
 function InternalCreateLobby(lobbyComClass, protocol, localPort, maxConnections, playerName, playerUID, natTraversalProvider)
 end
 

engine/User/CLobby.lua

@@ -1,8 +1,13 @@
 ---@meta
 
----@class moho.lobby_methods : Destroyable
+
+
+---@class moho.lobby_methods : Destroyable, InternalObject
 local CLobby = {}
 
+--- "0", "1", "2", etc.
+---@alias UILobbyPlayerId string
+
 ---@alias GPGNetAddress string | number
 
 ---@class Peer
@@ -13,8 +18,57 @@ local CLobby = {}
 ---@field quiet number
 ---@field status string
 
+--- A piece of data that is one can send with `BroadcastData` or `SendData` to other player(s) in the lobby.
+---@class UILobbyReceivedMessage : table
+---@field SenderID UILobbyPlayerId  # Set by the engine, allows us to identify the source.
+---@field SenderName string         # Set by the engine, nickname of the source.
+---@field Type string               # Type of message
+
+--- A piece of data that is one can send with `BroadcastData` or `SendData` to other player(s) in the lobby.
+---@class UILobbyData : table
+---@field Type string               # Type of message
+
+--- All the following fields are read by the engine upon launching the lobby to setup the scenario.
+---@class UILobbyLaunchGameOptionsConfiguration
+---@field UnitCap any           # Read by the engine to determine the initial unit cap. See also the globals `GetArmyUnitCap`, `GetArmyUnitCostTotal` and `SetArmyUnitCap` to manipulate it throughout the scenario.
+---@field CheatsEnabled any     # Read by the engine to determine whether cheats are enabled.
+---@field FogOfWar any          # Read by the engine to determine how to manage the fog of war.
+---@field NoRushOption any      # Read by the engine to create the anti-rush mechanic.
+---@field PrebuiltUnits any     # Read by the engine to create initial, prebuilt units.
+---@field ScenarioFile any      # Read by the engine to load the scenario of the game.
+---@field Timeouts any          # Read by the engine to determine the behavior of time outs.
+---@field CivilianAlliance any  # Read by the engine to determine the alliance towards civilians.
+---@field GameSpeed any         # Read by the engine to determine the behavior of game speed (adjustments). 
+
+---@class UILobbyLaunchGameModsConfiguration
+---@field name string           # Read by the engine, TODO
+---@field uid string            # Read by the engine, TODO
+
+---@class UILobbyLaunchObserverConfiguration
+---@field OwnerID UILobbyPlayerId   # Read by the engine, TODO
+---@field PlayerName string         # Read by the engine, TODO
+
+---@class UILobbyLaunchPlayerConfiguration
+---@field StartSpot number          # Read by Lua code to determine start locations
+---@field ArmyName string           # Read by the engine, TODO
+---@field PlayerName string         # Read by the engine, TODO
+---@field Civilian boolean          # Read by the engine, TODO
+---@field Human boolean             # Read by the engine, TODO
+---@field AIPersonality string      # Read by the engine iff Human is false
+---@field ArmyColor number          # Read by the engine, is mapped to a color by reading the values of `lua\GameColors.lua`.
+---@field PlayerColor number        # Read by the engine, is mapped to a color by reading the values of `lua\GameColors.lua`
+---@field Faction number            # Read by the engine to determine the faction of the player.
+---@field OwnerID UILobbyPlayerId   # Read by the engine, TODO
+
+--- All the following fields are read by the engine upon launching the lobby.
+---@class UILobbyLaunchConfiguration
+---@field GameMods UILobbyLaunchGameModsConfiguration[] # ModInfo[]
+---@field GameOptions UILobbyLaunchGameOptionsConfiguration #  GameOptions
+---@field Observers UILobbyLaunchObserverConfiguration # PlayerData[]
+---@field PlayerOptions UILobbyLaunchPlayerConfiguration[] # PlayerData[]
+
 --- Broadcasts information to all peers. See `SendData` for sending to a specific peer.
----@param data CommunicationData
+---@param data UILobbyData
 function CLobby:BroadcastData(data)
 end
 
@@ -45,7 +99,7 @@ function CLobby:EjectPeer(targetID, reason)
 end
 
 --- Retrieves the local client identifier.
----@return number
+---@return UILobbyPlayerId
 function CLobby:GetLocalPlayerID()
 end
 
@@ -87,7 +141,7 @@ function CLobby:JoinGame(address, remotePlayerName, remotePlayerUID)
 end
 
 ---
----@param gameConfig GameData
+---@param gameConfig UILobbyLaunchConfiguration
 function CLobby:LaunchGame(gameConfig)
 end
 
@@ -106,7 +160,7 @@ end
 
 --- Sends data to a specific peer. See `BroadcastData` for sending to all peers.
 ---@param targetID string
----@param data CommunicationData
+---@param data UILobbyData
 function CLobby:SendData(targetID, data)
 end
 

engine/User/CUIMapPreview.lua

@@ -9,11 +9,13 @@ end
 
 ---
 ---@param textureName string
+---@return boolean
 function CUIMapPreview:SetTexture(textureName)
 end
 
 ---
 ---@param mapName string
+---@return boolean
 function CUIMapPreview:SetTextureFromMap(mapName)
 end
 

lua/lazyvar.lua

@@ -9,7 +9,7 @@ local setmetatable = setmetatable
 
 -- Set this true to get tracebacks in error messages. It slows down lazyvars a lot,
 -- so don't use except when debugging.
-local ExtendedErrorMessages = false
+local ExtendedErrorMessages = true
 local EvalContext = nil
 local WeakKeyMeta = { __mode = 'k' }
 

lua/ui/globals/GpgNetSend.lua

@@ -0,0 +1,108 @@
+---@declare-global
+
+--******************************************************************************************************
+--** Copyright (c) 2024 Willem 'Jip' Wijnia
+--**
+--** Permission is hereby granted, free of charge, to any person obtaining a copy
+--** of this software and associated documentation files (the "Software"), to deal
+--** in the Software without restriction, including without limitation the rights
+--** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+--** copies of the Software, and to permit persons to whom the Software is
+--** furnished to do so, subject to the following conditions:
+--**
+--** The above copyright notice and this permission notice shall be included in all
+--** copies or substantial portions of the Software.
+--**
+--** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+--** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+--** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+--** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+--** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+--** OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+--** SOFTWARE.
+--******************************************************************************************************
+
+--- Original function that we should not use directly
+local oldGpgNetSend = GpgNetSend
+
+--- Adds a hook that generates sim callbacks for communication to the
+--- server. Useful for moderation purposes.
+---@param command any
+---@param ... unknown
+_G.GpgNetSend = function(command, ...)
+
+    if SessionIsActive() and not SessionIsReplay() then
+        local stringifiedArgs = ""
+        for k = 1, table.getn(arg) do
+            stringifiedArgs = stringifiedArgs .. tostring(arg[k]) .. ","
+        end
+
+        local currentFocusArmy = GetFocusArmy()
+        SimCallback(
+            {
+                Func = "ModeratorEvent",
+                Args = {
+                    From = currentFocusArmy,
+                    Message = string.format("GpgNetSend with command '%s' and data '%s'", tostring(command),
+                        stringifiedArgs),
+                },
+            }
+        )
+    end
+
+    oldGpgNetSend(command, unpack(arg))
+end
+
+-------------------------------------------------------------------------------
+--#region Game <-> Server communications
+
+-- All the following logic is tightly coupled with functionality on either the
+-- lobby server, the ice adapter, the java server and/or the client. For more
+-- context you can search for the various keywords in the following repositories:
+-- - Lobby server: https://github.com/FAForever/server
+-- - Java server: https://github.com/FAForever/faf-java-server
+-- - Java Ice adapter: https://github.com/FAForever/java-ice-adapter
+-- - Kotlin Ice adapter: https://github.com/FAForever/kotlin-ice-adapter
+--
+-- If we do not send this information then the client is unaware of changes made
+-- to the lobby after hosting. These messages are usually only accepted from the
+-- host of the lobby.
+
+--- Sends player options to the lobby server. For more context:
+--- - https://github.com/search?q=org%3AFAForever+player_option&type=code
+---@param peerId UILobbyPlayerId
+---@param key 'Team' | 'Army' | 'StartSpot' | 'Faction' | 'Color'
+---@param value string | number
+GpgNetSendPlayerOption = function(peerId, key, value)
+    _G.GpgNetSend('PlayerOption', peerId, key, value)
+end
+
+--- Sends AI options to the lobby server. For more context:
+--- - https://github.com/search?q=org%3AFAForever+ai_option&type=code
+---@param key string
+---@param value string
+GpgNetSendAIOption = function(aiName, key, value)
+    _G.GpgNetSend('AIOption', aiName, key, value)
+end
+
+--- Sends game options to the lobby server. For more context:
+--- - https://github.com/search?q=repo%3AFAForever%2Fserver+game_option&type=code
+---@param key 'ScenarioFile' | 'Slots' | 'RestrictedCategories'
+---@param value string | number
+GpgNetSendGameOption = function(key, value)
+    _G.GpgNetSend('GameOption', key, value)
+end
+
+--- Sends game status to the lobby server. For more context:
+--- - https://github.com/search?q=repo%3AFAForever%2Fserver+GameState&type=code
+---@param value 'None' | 'Idle' | 'Lobby' | 'Launching' | 'Ended'
+GpgNetSendGameState = function(value)
+    _G.GpgNetSend('GameState', value)
+end
+
+--- Sends game status to the lobby server. For more context:
+--- - https://github.com/search?q=repo%3AFAForever%2Fserver+GameState&type=code
+---@param peerId UILobbyPlayerId
+GpgNetSendDisconnected = function(peerId)
+    GpgNetSend('Disconnected', peerId)
+end