diff --git a/lua/acf/core/classes/entities/registration.lua b/lua/acf/core/classes/entities/registration.lua index aa73b46d1..2c11b50ba 100644 --- a/lua/acf/core/classes/entities/registration.lua +++ b/lua/acf/core/classes/entities/registration.lua @@ -1,3 +1,7 @@ +--[[ +The purpose of this class is to define a class that represents an entity, storing its spawn function as well as registering the arguments attached to the entity with duplicators. +--]] + local duplicator = duplicator local isfunction = isfunction local isstring = isstring @@ -7,7 +11,10 @@ local Classes = ACF.Classes local Entities = Classes.Entities local Entries = {} - +--- Gets the entity table of a certain class +--- If an entity table doesn't exist for the class, it will register one. +--- @param Class table The class to get the entity table from +--- @return {Lookup:table, Count:number, List:table} # The entity table of this class local function GetEntityTable(Class) local Data = Entries[Class] @@ -24,6 +31,11 @@ local function GetEntityTable(Class) return Data end +--- Adds arguments to an entity for storage in duplicators +--- The Entity.Lookup, Entity.Count and Entity.List variables allow us to iterate over this information in different ways. +--- @param Entity entity The entity to add arguments to +--- @param Arguments any[] # An array of arguments to attach to the entity (usually {...}) +--- @return any[] # An array of arguments attached to the entity local function AddArguments(Entity, Arguments) local Lookup = Entity.Lookup local Count = Entity.Count @@ -43,6 +55,10 @@ local function AddArguments(Entity, Arguments) return List end +--- Registers a class as a spawnable entity class +--- @param Class string The class to register +--- @param Function fun(Player:entity, Pos:vector, Ang:angle, Data:table):Entity A function defining how to spawn your class (This should be your MakeACF_ function) +--- @param ... any #A vararg of arguments to attach to the entity function Entities.Register(Class, Function, ...) if not isstring(Class) then return end if not isfunction(Function) then return end @@ -56,6 +72,10 @@ function Entities.Register(Class, Function, ...) duplicator.RegisterEntityClass(Class, Function, "Pos", "Angle", "Data", unpack(List)) end +--- Adds extra arguments to a class which has already been called in Entities.Register +--- Should be called after Entities.Register if you want to specify any additional arguments +--- @param Class string A class previously registered as an entity class +--- @param ... any #A vararg of arguments function Entities.AddArguments(Class, ...) if not isstring(Class) then return end @@ -68,6 +88,9 @@ function Entities.AddArguments(Class, ...) end end +--- Returns an array of the entity's arguments +--- @param Class string The entity class to get arguments from +--- @return any[] # An array of arguments attached to the entity function Entities.GetArguments(Class) if not isstring(Class) then return end @@ -89,6 +112,15 @@ do -- Spawning and updating local hook = hook local undo = undo + --- Spawns an entity with the given parameters + --- Internally calls the class' Spawn method + --- @param Class string The class of entity to spawn + --- @param Player entity The player creating the entity + --- @param Position vector The position to create the entity at + --- @param Angles angle The angles to create the entity at + --- @param Data table The data to pass into the entity's spawn function + --- @param NoUndo boolean Whether the entity is added to the undo list (can be z keyed) + --- @return boolean, table? # Whether the spawning was successful and the reason why function Entities.Spawn(Class, Player, Position, Angles, Data, NoUndo) if not isstring(Class) then return false end @@ -118,6 +150,11 @@ do -- Spawning and updating return true, Entity end + --- Triggers the update function of an entity + --- Internally calls the ENT:Update(Data) metamethod that's implemented on all entities + --- @param Entity table The entity to update + --- @param Data table The data to pass into the entity on update + --- @return boolean, string # Whether the update was successful and the reason why function Entities.Update(Entity, Data) if not IsValid(Entity) then return false, "Can't update invalid entities." end if not isfunction(Entity.Update) then return false, "This entity does not support updating." end diff --git a/lua/acf/core/networking/data_vars/data_vars_cl.lua b/lua/acf/core/networking/data_vars/data_vars_cl.lua index 4fd1a6b1f..468863b33 100644 --- a/lua/acf/core/networking/data_vars/data_vars_cl.lua +++ b/lua/acf/core/networking/data_vars/data_vars_cl.lua @@ -122,6 +122,11 @@ do -- Client data getter functions end do -- Client data setter function + --- Sets a client data var and networks it to the server. + --- Internally calls the ACF_OnClientDataUpdate hook + --- @param Key string The key of the datavar + --- @param Value any The value the datavar + --- @param Forced boolean Whether to send regardless of if the value has changed function ACF.SetClientData(Key, Value, Forced) if not isstring(Key) then return end @@ -138,11 +143,18 @@ do -- Client data setter function end do -- Server data setter function + --- Proposes changes to server datavars and networks them to server. + --- Internally calls the ACF_OnServerDataUpdate hook. + --- @param Key string The key of the datavar + --- @param Value any The value of the datavar + --- @param Forced boolean Whether to send regardless of if the value has changed function ACF.SetServerData(Key, Value, Forced) if not isstring(Key) then return end local Player = LocalPlayer() + -- Check if the client is allowed to set things on the server + -- (Usually restricted to super admins and server owners) if not ACF.CanSetServerData(Player) then return end Value = Value or false diff --git a/lua/acf/core/networking/data_vars/data_vars_sh.lua b/lua/acf/core/networking/data_vars/data_vars_sh.lua index 08bb92ba8..3df30c2cf 100644 --- a/lua/acf/core/networking/data_vars/data_vars_sh.lua +++ b/lua/acf/core/networking/data_vars/data_vars_sh.lua @@ -1,5 +1,8 @@ local ACF = ACF +--- Returns whether a client is allowed to set a server datavars +--- @param Player table The player entity to check +--- @return boolean # Whether the player can set server datavars function ACF.CanSetServerData(Player) if not IsValid(Player) then return true end -- No player, probably the server if Player:IsSuperAdmin() then return true end diff --git a/lua/acf/core/networking/data_vars/data_vars_sv.lua b/lua/acf/core/networking/data_vars/data_vars_sv.lua index 4f09f047a..75187e65b 100644 --- a/lua/acf/core/networking/data_vars/data_vars_sv.lua +++ b/lua/acf/core/networking/data_vars/data_vars_sv.lua @@ -178,11 +178,18 @@ do -- Client data getter functions return ACF.CheckString(Value, "") end + --- When called, returns all the table storing all of the client's datavars ACF.GetClientData = GetData ACF.GetClientRaw = GetData end do -- Server data setter function + --- Sets a server datavar and networks it to the client + --- The server cannot modify the client because we don't want ACF to natively support servers modifying the client + --- Internally calls the ACF_OnServerDataUpdate hook + --- @param Key string The key of the datavar + --- @param Value any The value the datavar + --- @param Forced boolean Whether to send regardless of difference checks function ACF.SetServerData(Key, Value, Forced) if not isstring(Key) then return end diff --git a/lua/acf/core/utilities/util_sh.lua b/lua/acf/core/utilities/util_sh.lua index ba906c28e..e5d4607b9 100644 --- a/lua/acf/core/utilities/util_sh.lua +++ b/lua/acf/core/utilities/util_sh.lua @@ -356,12 +356,20 @@ do -- ACF.GetHitAngle end do -- Native type verification functions + --- Returns the numerical representation of a value or a default of this type + --- @param Value number The input to be converted to a number + --- @param Default number The default value if the input canno tbe made into a number + --- @return number # The numerical result function ACF.CheckNumber(Value, Default) if not Value then return Default end return tonumber(Value) or Default end + --- Returns the string representation of a value or a default of this type + --- @param Value string The input to be converted to a string + --- @param Default string The default value if the input cannot be made into a string + --- @return string # The string result function ACF.CheckString(Value, Default) if Value == nil then return Default end diff --git a/lua/acf/core/validation_sv.lua b/lua/acf/core/validation_sv.lua index c9f2f1fb1..d027a37bc 100644 --- a/lua/acf/core/validation_sv.lua +++ b/lua/acf/core/validation_sv.lua @@ -224,6 +224,7 @@ function ACF.Activate(Entity, Recalc) Entity.ACF.Type = ACF.GetEntityType(Entity) Entity.ACF.PhysObj = PhysObj + -- Note that if the entity has its own ENT:ACF_Activate(Recalc) function, the rest of the code after this block won't be ran (instead the function should specify the rest) if Entity.ACF_Activate then Entity:ACF_Activate(Recalc) return diff --git a/lua/acf/menu/tool_functions.lua b/lua/acf/menu/tool_functions.lua index 05b1b6e78..98a55bd57 100644 --- a/lua/acf/menu/tool_functions.lua +++ b/lua/acf/menu/tool_functions.lua @@ -372,6 +372,10 @@ do -- Clientside Tool interaction local Key = "ToolMode:%s" local Value = "%s:%s" + --- Sets and networks to the server, the current state of a tool, its stage and its operation. + --- @param Tool string The name of the tool (e.g. "acf_menu"/"acf_copy") + --- @param Stage string The stage of the tool (e.g. "Spawner"/"Main") + --- @param Op string The operation of the tool (e.g. "Weapon"/"Sensor"/etc.) function ACF.SetToolMode(Tool, Stage, Op) if not isstring(Tool) then return end if not isstring(Stage) then return end @@ -593,6 +597,13 @@ do -- Generic Spawner/Linker operation creator end end + --- Creates a menu operation + --- Mostly serves as a wrapper for (https://wiki.facepunch.com/gmod/Tool_Information_Display) + --- Internally links the helpers SpawnEntity and SelectEntity to your left and right mouse + --- To actually define an entity's linking or spawn behaviour, use the entity files (e.g. init.lua) + --- @param Name string The name of the link type performed by the toolgun (e.g. Weapon, Engine, etc.) + --- @param Primary string The type of the entity to be spawned on left click (purely aesthetical) + --- @param Secondary string The type of entity to be spawned on shift + right click (purely aesthetical) function ACF.CreateMenuOperation(Name, Primary, Secondary) if not isstring(Name) then return end if not isstring(Primary) then return end @@ -600,6 +611,7 @@ do -- Generic Spawner/Linker operation creator Secondary = ACF.CheckString(Secondary) do -- Spawner stuff + -- These basically setup the tool information display you see on the top left of your screen ACF.RegisterOperation("acf_menu", "Spawner", Name, { OnLeftClick = SpawnEntity, OnRightClick = function(Tool, Trace)