Tutorial- How to add a silent opposite to nearly any ULX command

[Cobalt]

Ever wished that the command you're using had a silent option too, instead of only one button that echoes to everyone? I'm going to teach you how to add this functionality to the stock ULX commands by yourself even if you have very little lua knowledge.

For this tutorial I will use the command Cexec. This is something that a silent option for could help out many people.

The first step to doing this is you need to find the file where the module is located. This is usually in your addons/ulx/lua/ulx/modules/sh directory on your server. To find the corresponding module, simply look for the category the command would be under. Cexec is under the "Rcon" category, so we're going to open the Rcon file. Copy the rcon file from the server to your hard drive, anywhere you want. I have a lua folder for all of my lua stuff. Also, If you don't have notepad++ download it here.

Right click on the file and select "Edit with notepad++." The file will open in the text editor. From here you can look at the code for all of the Rcon commands. Scroll down to line 62 where you will find the cexec command. It looks like this:

Code: Lua

1. function ulx.cexec( calling_ply, target_plys, command )
2.         for _, v in ipairs( target_plys ) do
3.                 v:ConCommand( command )
4.         end
5.  
6.         ulx.fancyLogAdmin( calling_ply, "#A ran #s on #T", command, target_plys )
7. end
8. local cexec = ulx.command( CATEGORY_NAME, "ulx cexec", ulx.cexec, "!cexec" )
9. cexec:addParam{ type=ULib.cmds.PlayersArg }
10. cexec:addParam{ type=ULib.cmds.StringArg, hint="command", ULib.cmds.takeRestOfLine }
11. cexec:defaultAccess( ULib.ACCESS_SUPERADMIN )
12. cexec:help( "Run a command on console of target(s)." )

This is a pretty simple command, and it will be easy to edit.

The command is separated into two main parts: The function and the parameters. Functions look like this:

Code: Lua

1. function(arguments)
2. some code here
3. end

The parameters are added after the function.

The function in cexec is separated into 2 main parts: the part where it runs the command on the target and the part where it does the log echo.
The part where it runs the command is this part:

Code: Lua

1.         for _, v in ipairs( target_plys ) do
2.                 v:ConCommand( command )
3.         end

and the log is this part:

Code: Lua

1.         ulx.fancyLogAdmin( calling_ply, "#A ran #s on #T", command, target_plys )

The first part of the code we need to edit is the arguments. Arguments are the parts in the parentheses after the function. In this case,

Code: Lua

1. function ulx.cexec( calling_ply, target_plys, command )

The arguments for this function are calling_ply (the player who used the command), target_plys (the players who the command was used on), and command (the command used). We need to add a fourth argument to this function: should_silent. We will pass this argument to the function when the player wants the command to be silent.
Simply add a comma after "command", then add should_silent like so:

Code: Lua

1. function ulx.cexec( calling_ply, target_plys, command, should_silent )

The next thing we need to do is alter the log echo to log silently when the person wants the command to be silent. For this we're going to use an if then else statement.

Code: Lua

1.         if should_silent then
2.                 ulx.fancyLogAdmin( calling_ply, true, "#A ran #s on #T", command, target_plys )
3.         else
4.                 ulx.fancyLogAdmin( calling_ply, "#A ran #s on #T", command, target_plys )
5.         end

This will make it so that if should_silent is true (it is true when the player uses the alternate silent command), the log will print silently, otherwise it will print normally. The true after "calling_ply," indicates that the log will be echoed silently.


The next thing we need to do is add this line in the parameters section of the code. I don't think it matters where you put this. I usually put it right above the parameter for default access.

Code: Lua

1. cexec:addParam{ type=ULib.cmds.BoolArg, invisible=true }

The last thing is adding the opposite. To do this we will add a line at the end of the parameters below the help parameter, that will look like this:

Code: Lua

1. cexec:setOpposite ( "ulx scexec", { _, _, _, true }, "!scexec" )

This is the part where it actually adds the opposite command. The first part, "ulx scexec" is the name of the opposite command. You can change this to anything you want. The second part, { _, _, _, true }, indicates the arguments to pass to the main function. In this case we are only passing should_silent to the main function, so that is the only one we need to leave true. The rest are skipped by using the underscore character. If the command has more parameters, let's say 5, and should_silent is the last one, it will look like this:

Code: Lua

1. { _, _, _, _, true }

The last part, "!scexec", is the chat command. Again you can change this to whatever you want.


Save the file, and upload it to your server. You're done! You will now have a silent opposite for cexec. To make sure it works correctly, go into the xgui, rcon category, select cexec and click both the buttons to see the silent and normal logs. You can repeat this with any command you want. Just follow the steps above. If you have any questions or are confused, please ask.


The finished code will look like this:

Code: Lua

1. function ulx.cexec( calling_ply, target_plys, command, should_silent )
2.  
3.         for _, v in ipairs( target_plys ) do
4.                 v:ConCommand( command )
5.         end
6.        
7.         if should_silent then
8.                 ulx.fancyLogAdmin( calling_ply, true, "#A ran #s on #T", command, target_plys )
9.         else
10.                 ulx.fancyLogAdmin( calling_ply, "#A ran #s on #T", command, target_plys )
11.         end
12.        
13. end
14. local cexec = ulx.command( CATEGORY_NAME, "ulx cexec", ulx.cexec, "!cexec" )
15. cexec:addParam{ type=ULib.cmds.PlayersArg }
16. cexec:addParam{ type=ULib.cmds.StringArg, hint="command", ULib.cmds.takeRestOfLine }
17. cexec:addParam{ type=ULib.cmds.BoolArg, invisible=true }
18. cexec:defaultAccess( ULib.ACCESS_SUPERADMIN )
19. cexec:help( "Run a command on console of target(s)." )
20. cexec:setOpposite ( "ulx scexec", { _, _, _, true }, "!scexec" )

[Storm]

Thanks for obviously spending so much time putting this together! If you have ULX on svn do you think this will be wiped out in an update?

[Megiddo]

Nicely done, Cobalt! That tutorial is well written and definitely took some time to write. Interesting use for the command opposite feature, too.

@Storm, if you're using SVN it won't overwrite changes. If you have conflicts between your change and our changes in the future, it will give you an error, though.