[pull] master from beyond-all-reason:master

language/en/units.json

@@ -1723,7 +1723,7 @@
 			"leglts": "Light Air Transport",
 			"leglupara": "Bomb-Resistant Medium-Range Anti-Air Flak Battery",
 			"legmed": "Heavy Long-Range Salvo Rocket Tank",
-			"legmex": "Extracts Slightly Reduced Metal and Produces 7 Energy",
+			"legmex": "Extracts Metal from Metalspots",
 			"legmext15": "Extracts Extra Metal at a High Energy Cost",
 			"legmg": "Heavy Land/Air Gatling Gun Turret",
 			"legmh": "Hovercraft Rocket Launcher",

luarules/gadgets/api_build_blocking.lua

@@ -296,6 +296,11 @@ if gadgetHandler:IsSyncedCode() then
 		gadgetHandler:RemoveChatAction("buildunblock")
 	end
 
+	---Marks a unit definition as unbuildable by a team for the given reason.
+	---Reasons stack: the unit stays blocked until every reason is removed.
+	---@param unitDefID UnitDefID
+	---@param teamID TeamID
+	---@param reasonKey string Identifier for why the unit is blocked, e.g. "terrain_water".
 	function GG.BuildBlocking.AddBlockedUnit(unitDefID, teamID, reasonKey)
 		local blockedUnitDefs = teamBlockedUnitDefs[teamID]
 		if not blockedUnitDefs then
@@ -308,6 +313,11 @@ if gadgetHandler:IsSyncedCode() then
 		notifyUnitBlocked(unitDefID, teamID, unitReasons)
 	end
 
+	---Removes one block reason from a unit definition for a team.
+	---@param unitDefID UnitDefID
+	---@param teamID TeamID
+	---@param reasonKey string Identifier previously passed to `AddBlockedUnit`.
+	---@return boolean removed `true` if that reason was set and has been cleared.
 	function GG.BuildBlocking.RemoveBlockedUnit(unitDefID, teamID, reasonKey)
 		local blockedUnitDefs = teamBlockedUnitDefs[teamID]
 		if not blockedUnitDefs then

luarules/gadgets/api_pbr_enabler.lua

@@ -39,10 +39,14 @@ if not gadgetHandler:IsSyncedCode() then --unsynced gadget
 
 	local ENVLUT_SAMPLES -- number of cubemap samples
 
+	---Returns the name of the generated BRDF lookup texture.
+	---@return string? texName `nil` if the lookup table failed to generate.
 	local function GetBrdfTexture()
 		return brdfLut:GetTexture()
 	end
 
+	---Returns the name of the generated IBL environment lookup texture.
+	---@return string? texName `nil` if the lookup table failed to generate.
 	local function GetEnvTexture()
 		return envLut:GetTexture()
 	end

luarules/gadgets/cus_gl4.lua

@@ -244,6 +244,10 @@ local objectDefToUniformBin = {} -- maps unitDefID/featuredefID to a uniform bin
 -- objectDefs are negative for features
 -- objectIDs are negative for features too
 
+---Maps an object definition to the uniform bin its draw call belongs to.
+---@param objectDefID (UnitDefID|-FeatureDefID)? Positive for unitDefIDs, negative for featureDefIDs.
+---@param reason string? Label used in debug output when no bin is found.
+---@return string uniformBinID Falls back to `'otherunit'` for unmapped definitions.
 local function GetUniformBinID(objectDefID, reason)
 	if objectDefID and objectDefToUniformBin[objectDefID] then
 		return objectDefToUniformBin[objectDefID]
@@ -478,7 +482,9 @@ local unitDrawBins = nil -- this also controls whether cusgl4 is on at all!
 
 local objectIDtoDefID = {}
 
-local shaders = {} -- double nested table of {drawflag : {"units":shaderID}}
+---Compiled shaders, keyed by draw flag and then by material name.
+---@type table<integer, table<string, LuaShader>>
+local shaders = {}
 
 local modelsVertexVBO = nil
 local modelsIndexVBO = nil
@@ -550,6 +556,10 @@ end
 local featuresDefsWithAlpha = {}
 local unitDefsUseSkinning = {}
 
+---Returns the compiled shader used to draw an object in a given draw pass.
+---@param drawPass integer Draw flag of the current pass.
+---@param objectDefID (UnitDefID|-FeatureDefID)? Positive for unitDefIDs, negative for featureDefIDs.
+---@return LuaShader|false shader `false` when `objectDefID` is `nil`.
 local function GetShader(drawPass, objectDefID)
 	if objectDefID == nil then
 		return false
@@ -569,6 +579,10 @@ local function GetShader(drawPass, objectDefID)
 	end
 end
 
+---Returns the name of the shader used to draw an object in a given draw pass.
+---@param drawPass integer Draw flag of the current pass.
+---@param objectDefID (UnitDefID|-FeatureDefID)? Positive for unitDefIDs, negative for featureDefIDs.
+---@return "unit"|"unitskinning"|"tree"|"feature"|false shaderName `false` when `objectDefID` is `nil`.
 local function GetShaderName(drawPass, objectDefID)
 	-- this function does 2 table lookups, could get away with just one.
 	if objectDefID == nil then
@@ -603,6 +617,10 @@ local function SetFixedStatePost(drawPass, shaderID)
 	end
 end
 
+---Uploads the draw pass, clip plane, and uniform bin values to the active shader.
+---@param drawPass integer Draw flag of the current pass.
+---@param shaderID integer GL program id of the currently bound shader.
+---@param uniformBinID string Key into `uniformBins`, as returned by `GetUniformBinID`.
 local function SetShaderUniforms(drawPass, shaderID, uniformBinID)
 	-- Cache uniform locations per-shader to avoid repeated gl.GetUniformLocation calls every frame
 	local locCache = uniformLocCache[shaderID]

luarules/gadgets/game_apm_broadcast.lua

@@ -31,6 +31,8 @@ if gadgetHandler:IsSyncedCode() then
 		end
 	end
 
+	---Excludes the unit's next order from the team's APM count for one game frame.
+	---@param unitID UnitID
 	local function addSkipOrder(unitID)
 		ignoreUnits[unitID] = gameFrame + 1
 	end

luarules/gadgets/game_quick_start.lua

@@ -165,6 +165,9 @@ local buildsInProgress = {}
 
 GG.quick_start = {}
 
+---Moves tracked state from one commander unit to another.
+---@param oldUnitID UnitID?
+---@param newUnitID UnitID?
 function GG.quick_start.transferCommanderData(oldUnitID, newUnitID)
 	if oldUnitID and newUnitID and spValidUnitID(oldUnitID) and spValidUnitID(newUnitID) then
 		buildsInProgress[newUnitID] = buildsInProgress[oldUnitID]

luarules/gadgets/game_startbox_config.lua

@@ -51,6 +51,12 @@ function gadget:Initialize()
 	GG.startBoxConfig = startBoxConfig
 	GG.startBoxConfigSource = configSource
 
+	---Tests a map position against an allyteam's polygonal start box.
+	---@param x number
+	---@param z number
+	---@param allyTeamID AllyTeamID
+	---@return boolean? inside `nil` when no polygon config exists; the caller should
+	---fall back to the engine's axis-aligned start box.
 	GG.IsInsideStartbox = function(x, z, allyTeamID)
 		if not isExplicitConfig then
 			return nil -- caller should fall back to engine AABB
@@ -64,6 +70,13 @@ function gadget:Initialize()
 		return PolygonLib.PointInStartbox(x, z, entry)
 	end
 
+	---Returns the axis-aligned bounding box of an allyteam's start box polygons.
+	---@param allyTeamID AllyTeamID
+	---@return number? xmin `nil` when no polygon config exists; the caller should
+	---fall back to the engine's axis-aligned start box.
+	---@return number? zmin
+	---@return number? xmax
+	---@return number? zmax
 	GG.GetStartboxBounds = function(allyTeamID)
 		if not isExplicitConfig then
 			return nil -- caller should fall back to engine AABB
@@ -77,6 +90,10 @@ function gadget:Initialize()
 		return PolygonLib.GetStartboxBounds(entry)
 	end
 
+	---Returns the raw start box polygons configured for an allyteam.
+	---@param allyTeamID AllyTeamID
+	---@return Position2D[][]? boxes Array of polygons, each an array of `{x, z}` vertex
+	---pairs. `nil` when no polygon config exists.
 	GG.GetStartboxPolygons = function(allyTeamID)
 		if not isExplicitConfig then
 			return nil

luarules/gadgets/game_team_death_effect.lua

@@ -44,6 +44,12 @@ local function getSqrDistance(x1, z1, x2, z2)
 	return (dx * dx) + (dz * dz)
 end
 
+---Neutralizes a team's units and queues them to explode
+---@param teamID TeamID
+---@param originX number? Wave epicentre; when omitted the death frames are randomized.
+---@param originZ number? Wave epicentre; when omitted the death frames are randomized.
+---@param attackerUnitID UnitID? Credited as the killer of the destroyed units.
+---@param periodMult number? Scales how long the wave takes. Defaults to `1`.
 local function wipeoutTeam(teamID, originX, originZ, attackerUnitID, periodMult) -- only teamID is required
 	wipedoutTeams[teamID] = Spring.GetGameFrame()
 	periodMult = periodMult or 1
@@ -101,6 +107,12 @@ local function wipeoutTeam(teamID, originX, originZ, attackerUnitID, periodMult)
 	GG.maxDeathFrame = GG.maxDeathFrame and math.max(GG.maxDeathFrame, maxDeathFrame) or maxDeathFrame -- storing frame of total unit wipeout
 end
 
+---Wipes out every team in an allyteam, shortening the wave when few units remain.
+---@param allyTeamID AllyTeamID
+---@param attackerUnitID UnitID? Credited as the killer of the destroyed units.
+---@param originX number? Wave epicentre; when omitted the death frames are randomized.
+---@param originZ number? Wave epicentre; when omitted the death frames are randomized.
+---@param periodMult number? Scales how long the wave takes. Defaults to `1`.
 local function wipeoutAllyTeam(allyTeamID, attackerUnitID, originX, originZ, periodMult) -- only allyTeamID is required
 	-- xmas gadget uses this (to prevent creating xmasballs)
 	if not _G.destroyingTeam then