Documented weapons menu

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