Merge branch 'master' into dev

lua/acf/menu/items_cl/ammo_menu.lua

@@ -10,6 +10,10 @@ local CrateText = [[
 	Crate Mass : %s
 	Crate Capacity : %s round(s)]]
 
+---Quick copy helper function for menu settings.
+---@param Settings? table<string, boolean> Lookup table containing the keys for each menu aspect that has to be omitted.
+---This table can use the following keys: SuppressMenu, SuppressPreview, SuppressControls, SuppressTracer, SuppressInformation and SuppressCrateInformation.
+---@return table<string, boolean> Copy The copy of the original settings table.
 local function CopySettings(Settings)
 	local Copy = {}
 
@@ -22,6 +26,9 @@ local function CopySettings(Settings)
 	return Copy
 end
 
+---Gets a key-value table of all the ammo type objects a given weapon class can make use of.
+---@param Class string The ammo type ID that will be checked.
+---@return table<string, table> Result The ammo type objects said weapon class can use.
 local function GetAmmoList(Class)
 	local Entries = AmmoTypes.GetEntries()
 	local Result  = {}
@@ -36,12 +43,19 @@ local function GetAmmoList(Class)
 	return Result
 end
 
+---Returns the weapon group object depending on what Destiny and Weapons a player has set on their client data variables.
+---@param ToolData table<string, any> The copy of the local player's client data variables.
+---@return table<string, any> Group The weapon group object expected by the player's menu.
 local function GetWeaponClass(ToolData)
 	local Destiny = Classes[ToolData.Destiny or "Weapons"]
 
 	return Classes.GetGroup(Destiny, ToolData.Weapon)
 end
 
+---Returns the mass of a hollow box given the current size and armor thickness expected for it.
+---The size of the box will be defined by CrateSizeX, CrateSizeY and CrateSizeZ client data variables.
+---The thickness of the empty box will be defined by the ACF.AmmoArmor global variable.
+---@return number Mass The mass of the hollow box.
 local function GetEmptyMass()
 	local Armor          = ACF.AmmoArmor * 0.039 -- Millimeters to inches
 	local ExteriorVolume = BoxSize.x * BoxSize.y * BoxSize.z
@@ -50,6 +64,11 @@ local function GetEmptyMass()
 	return math.Round((ExteriorVolume - InteriorVolume) * 0.13, 2)
 end
 
+---Creates the entity preview panel on the ACF menu.
+---@param Base userdata The panel being populated with the preview.
+---@param Settings table<string, boolean> The lookup table containing all the settings for the menu.
+---This function will only use SuppressPreview. If it's defined, this function will effectively do nothing.
+---@param ToolData table<string, any> The copy of the local player's client data variables.
 local function AddPreview(Base, Settings, ToolData)
 	if Settings.SuppressPreview then return end
 
@@ -66,6 +85,13 @@ local function AddPreview(Base, Settings, ToolData)
 	Preview:UpdateSettings(Setup)
 end
 
+---Creates the ammunition control panels on the ACF menu.
+---@param Base userdata The panel being populated with the ammunition controls.
+---@param Settings table<string, boolean> The lookup table containing all the settings for the menu.
+---This function makes use of SuppressControls and SuppressTracer.
+---If the first is defined, this function will effectively do nothing.
+---If the latter is defined, only the Tracer checkbox will be omitted and the Tracer client data variable will be set to false.
+---@param ToolData table<string, any> The copy of the local player's client data variables.
 local function AddControls(Base, Settings, ToolData)
 	if Settings.SuppressControls then return end
 
@@ -145,6 +171,13 @@ local function AddControls(Base, Settings, ToolData)
 	end
 end
 
+---Creates the ammunition information panels on the ACF menu.
+---@param Base userdata The panel being populated with the ammunition information.
+---@param Settings table<string, boolean> The lookup table containing all the settings for the menu.
+---This function makes use of SuppressInformation and SuppressCrateInformation
+---If the first is defined, this function will effectively do nothing.
+---If the latter is defined, only the information regarding the ammo crate (armor, mass and capacity by default) will be omitted.
+---@param ToolData table<string, any> The copy of the local player's client data variables.
 local function AddInformation(Base, Settings, ToolData)
 	if Settings.SuppressInformation then return end
 
@@ -296,10 +329,15 @@ local function AddGraph(Base, ToolData)
 	end)
 end
 
+---Returns the client bullet data currently being used by the menu.
+---@return table<string, any> BulletData The client bullet data.
 function ACF.GetCurrentAmmoData()
 	return BulletData
 end
 
+---Updates and populates the current ammunition menu.
+---@param Menu userdata The panel in which the entire ACF menu is being placed on.
+---@param Settings? table<string, boolean> The lookup table containing all the settings for the menu.
 function ACF.UpdateAmmoMenu(Menu, Settings)
 	if not Ammo then return end
 
@@ -328,6 +366,9 @@ function ACF.UpdateAmmoMenu(Menu, Settings)
 	Menu:EndTemporal(Base)
 end
 
+---Creates the basic information and panels on the ammunition menu.
+---@param Menu userdata The panel in which the entire ACF menu is being placed on.
+---@param Settings? table<string, boolean> The lookup table containing all the settings for the menu.
 function ACF.CreateAmmoMenu(Menu, Settings)
 	Menu:AddTitle("Ammo Settings")
 

lua/acf/menu/items_cl/weapons.lua

@@ -7,13 +7,21 @@ local MagText   = "\nRounds : %s rounds\nReload : %s seconds"
 local Current   = {}
 local CreateControl, IsScalable
 
+---Wrapper function to update the entity preview panel with a given weapon entry object.
+---@param Base userdata The panel in which all the weapon controls and information are being placed on.
+---@param Data table<string, any> The weapon entry object selected on the menu.
+---Note that this could be a weapon group item if the weapon isn't scalable.
 local function UpdatePreview(Base, Data)
 	local Preview = Base.Preview
 
 	Preview:UpdateModel(Data.Model)
 	Preview:UpdateSettings(Data.Preview)
 end
 
+---Updates the current weapon class controls on the menu.
+---For scalable weapons, this will update the caliber slider values and the Weapon and Caliber client data variables.
+---For non-scalable weapons, this will update the combobox of weapon items.
+---@param Base userdata The panel in which all the weapon information and controls are being placed on.
 local function UpdateControl(Base)
 	local Control = Either(IsScalable, Base.Slider, Base.List)
 	local Class   = Current.Class
@@ -23,7 +31,7 @@ local function UpdateControl(Base)
 		CreateControl(Base)
 	end
 
-	if IsScalable then -- Scalable
+	if IsScalable then
 		local Bounds  = Class.Caliber
 		local Caliber = ACF.GetClientNumber("Caliber", Bounds.Base)
 
@@ -33,11 +41,15 @@ local function UpdateControl(Base)
 		ACF.SetClientData("Caliber", Caliber, true)
 
 		UpdatePreview(Base, Class)
-	else -- Not scalable
+	else
 		ACF.LoadSortedList(Base.List, Class.Items, "Caliber")
 	end
 end
 
+---Creates and updates the current weapon class controls on the menu.
+---For scalable weapons, this will create a caliber slider.
+---For non-scalable weapons, this will create a combobox with all the weapon items of the current weapon group.
+---@param Base userdata The panel in which all the weapon information and controls are being placed on.
 CreateControl = function(Base)
 	local Previous = Either(IsScalable, Base.List, Base.Slider)
 	local Title    = Base.Title
@@ -96,6 +108,9 @@ CreateControl = function(Base)
 	UpdateControl(Base)
 end
 
+---Updates or recreates the menu depending on the current weapon entry object's scalability being different from the one previously selected.
+---@param Base userdata The panel in which all the weapon information and controls are being placed on.
+---@param Class table<string, any> The weapon entry object selected on the menu.
 local function UpdateMode(Base, Class)
 	local Mode = tobool(Class.IsScalable)
 
@@ -108,6 +123,8 @@ local function UpdateMode(Base, Class)
 	end
 end
 
+---Returns the reload time of the selected weapon entry object using the current ammunition settings.
+---@return integer ReloadTime The expected reload time of the weapon with the given ammunition.
 local function GetReloadTime()
 	local BulletData = ACF.GetCurrentAmmoData()
 
@@ -116,6 +133,12 @@ local function GetReloadTime()
 	return ACF.BaseReload + (BulletData.ProjMass + BulletData.PropMass) * ACF.MassToTime
 end
 
+---Returns a string with the magazine capacity and reload time of a given weapon entry object.
+---@param Caliber? number The caliber of the weapon in mm.
+---@param Class? table<string, any> The weapon group object to get information from.
+---@param Weapon? table<string, any> The weapon item object to get informatio from, not necessary for scalable weapons.
+---@return string Text The string to be used in the weapon information label on the menu.
+---This can be an empty string if the magazine size can't be found.
 local function GetMagazineText(Caliber, Class, Weapon)
 	local MagSize = ACF.GetWeaponValue("MagSize", Caliber, Class, Weapon)
 
@@ -126,6 +149,14 @@ local function GetMagazineText(Caliber, Class, Weapon)
 	return MagText:format(math.floor(MagSize), math.Round(MagReload, 2))
 end
 
+---Returns the expected mass of a weapon that would be created by a given entry object.
+---For scalable weapons, this might be 0 at first if the model information hasn't been received from the server.
+---The panel will be automatically updated once the information is received.
+---@param Panel userdata The label panel in which the weapon information is being listed on.
+---@param Caliber? number The caliber of the weapon in mm. Not necessary for non-scalable weapons.
+---@param Class? table<string, any> The weapon group object to get information from. Not necessary for non-scalable weapons.
+---@param Weapon table<string, any> The weapon item object to get informatio from, not necessary for scalable weapons.
+---@return number Mass The expected mass.
 local function GetMass(Panel, Caliber, Class, Weapon)
 	if Weapon then return Weapon.Mass end
 
@@ -162,11 +193,12 @@ local function CreateMenu(Menu)
 	local EntData    = WeaponBase:AddLabel()
 	local AmmoList   = ACF.CreateAmmoMenu(Menu)
 
-	ACF.SetClientData("PrimaryClass", "acf_gun")
-	ACF.SetClientData("SecondaryClass", "acf_ammo")
-	ACF.SetClientData("Destiny", "Weapons")
+	-- Configuring the ACF Spawner tool
+	ACF.SetClientData("PrimaryClass", "acf_gun") -- Left click will create an acf_gun entity
+	ACF.SetClientData("SecondaryClass", "acf_ammo") -- Right click will create an acf_ammo entity
+	ACF.SetClientData("Destiny", "Weapons") -- The information of these entities will come from ACF.Classes.Weapons
 
-	ACF.SetToolMode("acf_menu", "Spawner", "Weapon")
+	ACF.SetToolMode("acf_menu", "Spawner", "Weapon") -- The ACF Menu tool will be set to spawner stage, weapon operation
 
 	function ClassList:OnSelect(Index, _, Data)
 		if self.Selected == Data then return end