Command LIB

Here you can understand how to use the library for your own scripts, this library allows the developer to create their own custom chat commands by just calling one function, as an overview, you can create your own commands by simply doing something like the next example:

Example

You can view and implementation of the library at admin_commands.gsc.

init() {
  setCommand("hello",::command_helloWorld);
}

command_helloWorld(player, args) {
  player iPrintLn("Hello world!");
}

This command will allow the player to use /hello to execute the command and print Hello world! for themselves.

Or you could even specify a condition for the command to be executed

init() {
  setCommand("hello",::command_helloWorld,::command_helloWorld_condition);
}

command_helloWorld(player, args) {
  player iPrintLn("Hello world!");
}

command_helloWorld_condition(player, args) {
  // The command above will only be executed if this condition is met (should return true or false)
  return IsAlive(player);
}

This command will allow the player to use /hello to execute the command and print Hello world! for themselves, but only if they are alive.

In-depth Guide

Now let's start with a guide on how to use the library for your own development, It's quite simple I promise.

Implementing the library

Although you can place the library wherever you want inside the storage, I'd recommend you to place it inside scripts\amrv\ as is where any APIs or script might search and it wont disturb to your zm or mp folders, in fact, you can use for both multiplayer and zombies scripts.

If you followed my recomendation, to be able to use the library you would then just add this line of code and it will work perfectly. #include scripts\amrv\_command_lib; If you placed it somewhere else, then the path should point towards the location of the file, being the root folder the storage of the game.

#include scripts\amrv\_command_lib;

Declaring commands

I'd recommend you to declare the commands inside the init() function but as the checking is dynamic you should be able to register the commands anywhere on the code. However, as a very important notice, keep in mind that no resources from the script are loaded until a command is declared, meaning that any call to a function to retrieve information from the script will result on a undefined variable or even a exception.

Having said that, declaring a command is pretty simple, the syntax is the next setCommand(<command_label>,::<calling_function>[,::<validation_function>]).

• <command_label> is the label (string) that the player must input for the command to be executed.
• <calling_function> is the name of the function that will process the command.
• [Optional] <validation_function> is a function that will be executed before the command and will act as a check to see if the command should be executed, this can implement a permission validation, conditional command or even include the command itself even if it's bad practise.

If you expect your command to be resource-consuming or just want to make sure it gets executed on its own thread no matter what, you can call setThreadedCommand(<command_label>,::<calling_function>[,::<validation_function>]) it has the same parameters as the setCommand function.

#include scripts\amrv\_command_lib;

init() {
  setCommand("command",::command_execution);
  // Multiple command declarations may use the same command requirement, this is useful
  // If you plan to make a system so you need certain rank to use some commands
  // And other rank to use other commands
  setCommand("conditional_command",::command_execution,::command_requirement);
  setThreadedCommand("threaded_command",::command_execution3);
}

Implementing the command

I recommend you to prefix any function that is called by a command with the prefix command_ but you can name the functions however you want.

After you register your own command I'm pretty sure you would like to implement it's functionallity, to do so you need to create a function called the same as the <calling_function> you specified on the command, something like this.

calling_function(player, args) {
  player // this is the player that executed the command in-game
  args // this is an array of strings containing each of the subsecuent words the player used among the command
}

For a better visualization:

If you type that command ingame and you have declared it, the player would then be you of course and the args would then be:

• arg[0] = param1
• arg[1] = param2

Same goes for any function you declare to be the validation for a command.

Aiding the player to use the commands

The library has a built-in command that allows the player to use /help to get information about a desired command, you can add some information to show when they request help for your command insted of the default No information provided by the developer message, to do so its really simple.

Calling setCommandHelp(<command_label>,<help_message>); will cause any subsecuent calls to the /help <command_label> to show that message on the chat.

• <command_label> is the label (string) of the command.
• <help_message> is the message (string) that will be displayed as the help for that command.

Sadly, command help does not support adding multiple lines, so avoid unnecesary information when possible.

Removing commands

Removing commands is not recommended but you can do so by using the function deleteCommand(<command>). You really should try to avoid deleting commands, if you want to execute a conditional command then you should use the validation function that commands allow.

• is directly the command structure, not the label, this is to avoid deletion of commands implemented by other scripts.

Extra information

In case you missed it, you can download the library from here.

This library comes with built in messages so if a command does not pass the validation (if exists) a You don't have permission to execute this command message will appear.
If a command does not exist a Unknown command message will appear.
If the developer of any command didn't implement a help message, then No help provided from the developer will be shown.