From cd5d8830d758cd523a71007e721ce830fbfd51db Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Mon, 22 Apr 2024 00:11:26 -0400 Subject: [PATCH] Add Networking and Tool Documentation Documents some of the ACF functions exposed to the user for the acf menu tool and the networking functions --- lua/acf/core/networking/data_vars/data_vars_cl.lua | 12 ++++++++++++ lua/acf/core/networking/data_vars/data_vars_sh.lua | 3 +++ lua/acf/core/networking/data_vars/data_vars_sv.lua | 7 +++++++ lua/acf/core/utilities/util_sh.lua | 8 ++++++++ lua/acf/menu/tool_functions.lua | 12 ++++++++++++ 5 files changed, 42 insertions(+) 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/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)