ULX Commands

[Aaron113]

Can I have an example of how to create an advanced ULX command?  (Logging, prints in chat, every argument)


I have been working on ULX commands lately and it would be nice to know how some of this works.  I have no been able to use logString or get it to print into chat without using ULib.tsayColor() or filex.Append().

[JamminR]

Though long and drawn out, I did a article comparing old to new ULX command structure a while back.
Maybe it can help you a bit.
http://forums.ulyssesmod.net/index.php/topic,4464.0.html
It's quite heavily commented in the code examples.

There's also the docs for ULib, which of course, those code examples use much of for the commands.
http://www.ulyssesmod.net/docs

[Aaron113]

Mind explaining the logging part to me?

Code: [Select]

explode:logString( "#1s exploded #2s with #3i damage in a #4i radius blast area" )

Whats with the s changing to an i?

[JamminR]

s = string
i = integer
There are others I think. I forget what they are.
Megiddo/Stickly Man, others around here who have taken formal coding classes can probably tell you the name of that style of string/variable substitution.
I've seen it used in other scripting languages when it comes to string output.
Megiddo used it (to much less extent) in older ULX string manipulation. Was usually #T for target.

In relation to current (SVN) ULib command objects and that 'rocket' example,
#1 is (always?) person who ran the command.
2,3,4... equals each additional "addparam" value.
#2s (string) in that example is the player(s) that the command was performed on.
#3i (integer) is set as damag.
#4i (integer) is radius.
In the actual log command, you could change it to " with a #4i radius and #3i damage".
Those numbers don't have to be in order in the logString command.
They just have to match what parameter order you give the command object.

[Megiddo]

You're right on JamminR. It's just a slight variation on string.format().

[Aaron113]

So what about the echoing into chat?  I looked though ULX and didn't see any ULib.tsayColor() on the commands.

[Aaron113]

Whats wrong with this that is not logging or echoing into chat?

Code: [Select]

local CATEGORY_NAME = "Custom"


function ulx.warn( calling_ply, target_plys, Reason )
end
local warn = ulx.command( CATEGORY_NAME, "ulx warn", ulx.warn, "!warn" )
warn:addParam{ type=ULib.cmds.PlayerArg }
warn:addParam{ type=ULib.cmds.StringArg, hint="reason", ULib.cmds.takeRestOfLine }
warn:defaultAccess( ULib.ACCESS_ADMIN )
warn:help( "Warn a player." )
warn:logString( "#1s warned #2s for #3s" )

[Aaron113]

Also, some help with setting common options.  Like ban has: spammer, Minge, Griefer, ect.

[JamminR]

I just spent about half hour poking around regarding your echo command to screen issue.
At first, I thought ULib might be expecting a 'return' function as I saw a few return <boolean>, <String message> at the end of some functions that looked like what would be output to a user.
Then I realized, not every ulx function has that and it seems to be meant as an override.
Are you getting the command logged to your ulx server logfile?
Is the command actually running? I know we put in some checks that if for any reason the command doesn't run, it doesn't echo.
In your (currently blank) function, try something as simple as a print to console Msg() and "return" with nothing else.

Megiddo, does logString do more than write to a log file. From log.lua, it didn't look like it. And if not, what should he do to have it echo to the screen?

As for the ban, there is a 'completes' variable you can pass in your parameters.
Pass it a table, and the parameter will suggest whatever is in the table after previous parameters are chosen (if any).

Cbrad24's recent ULX rate release shows this in action.
It has a screenshot of the 'legal' gmod allowed ratings after having typed

Earlier in his code, he sets up a table

Code: [Select]

ulx.ratings = { "naughty", "like", "love", "artistic", "star", "builder" }

Then in his command setup, he uses the following parameter after the Players parameter.

Code: [Select]

rate:addParam{ type=ULib.cmds.StringArg, completes=ulx.ratings, hint="rating", error="invalid rating \"%s\" specified", ULib.cmds.restrictToCompletes }
If you wanted to allow for more than just that table, you could leave out ULib.cmds.restrictToCompletes
It's pretty obvious what that does.

Have you seen http://ulyssesmod.net/docs/files/lua/ulib/shared/commands-lua.html ?
It has much on the command system ULX uses and the available parameters.

[Aaron113]

Are you getting the command logged to your ulx server logfile?
Is the command actually running? I know we put in some checks that if for any reason the command doesn't run, it doesn't echo.
In your (currently blank) function, try something as simple as a print to console Msg() and "return" with nothing else.

I've had to do filex.Append and ULib.tsayColor() for logging and echoing.  I know for a fact the command is running.  I just took all my code out.

Have you seen http://ulyssesmod.net/docs/files/lua/ulib/shared/commands-lua.html ?
It has much on the command system ULX uses and the available parameters.

I have seen it.  It can just be a bit confusing.

[Megiddo]

Unfortunately ULX isn't documented as well as ULib. You need to return true from the function in the event of success, otherwise ULX assumes that there was something wrong with the input (trying to jail a ragdoll, etc).

Tested with return true:

[ULX]Megiddo: !warn me one two
You warned yourself for one two

[JamminR]

Megiddo, thanks for confirming. I'd thought that was the case but wasn't sure. I remembered <command object>:<Ulib.mds.*> checking for success, but had forgotten how it went about doing that.

Aaron113, do you understand how the addparam work with the "completes" variable table suggestions from the rate code I showed?
I can write a longer bit of example command code with comments if needed.

[Aaron113]

Aaron113, do you understand how the addparam work with the "completes" variable table suggestions from the rate code I showed?
I can write a longer bit of example command code with comments if needed.

A longer version would be nice.  I haven't had time to try anything since you posted before.

[JamminR]

Here's code including 'suggestions' for autocomplete of your warning system.
I've not tested it.

Code: [Select]

local CATEGORY_NAME = "Custom"
-- Set table for autocomplete suggestions.
my_warn_reasons = { "Spamming", "Rude", "Language", "Arguing with a mod", "Prop Killing" }
-- Set your function as normal
function ulx.warn( calling_ply, target_plys, Reason )
return true
end
-- set your command as normal
local warn = ulx.command( CATEGORY_NAME, "ulx warn", ulx.warn, "!warn" )
warn:addParam{ type=ULib.cmds.PlayerArg }
-- Here, you deviate. You give addParam an additional table, "completes", set in previous table, "my_warn_reasons"
-- After you've typed "ulx warn <some player>" in console, the dropdown will contain the table. If you type the first
-- few letters of a word from the table (for instance, "S", "Spamming" would attempt to auto complete).
warn:addParam{ type=ULib.cmds.StringArg, hint="reason", completes=my_warn_reasons, ULib.cmds.takeRestOfLine }
warn:defaultAccess( ULib.ACCESS_ADMIN )
warn:help( "Warn a player." )
warn:logString( "#1s warned #2s for #3s" )
See http://ulyssesmod.net/docs/files/lua/ulib/shared/commands-lua.html#cmds.StringArg
According to that, the following apply with ULib.cmds.StringArg
"hint" = Gives hint as part of error (if error not overridden)
"completes" = Table of strings to be used as auto complete in option.
"ULib.cmds.restrictToCompletes" - Obvious, allow only what is given in "completes" as input.
or
"ULib.cmds.takeRestOfLine" - Obvious, take rest of line
"error" = Allow overriding the default command object error (allows for customization)
"autocomplete_fn" = Allow override of the default ULib autocomplete function.
"repeat_min", combined with "ULib.cmds.takeRestOfLine", from the description at our docs site, well, I'm not fully sure what it is myself.

Megiddo, explain repeat_min in a different way than stated at ulib docs?

[Megiddo]

I think hint is just used for autocomplete and command syntax. Repeat min ensures that an argument is repeated at least n times (and also states that it CAN be repeated). This was mainly added for XGUI's benefit, but it's useful for ULX as well.

For example:
vote:addParam{ type=ULib.cmds.StringArg, hint="options", ULib.cmds.takeRestOfLine, repeat_min=2, repeat_max=10 }

That's a line from the ulx vote definition. It makes sure that there are at least 2 options given, and a maximum of 10. (I need to document repeat_max )