[Library] [I-ZCMD]Improved ZCMD - Fastest Command Processor

[Kwarde]

NOTE: Directly copied from SAMP Forums (web archive). Fixed some links, and attempted to make the post look prettier (no empty lines). Somehow this editor keeps adding back those empty lines. I'll fix it later (right now gtg)


Improved ZCMD







Latest Version:0.2.3.0 (August 2016)







NOTE: Please do not credit me for the include. The original concept is from ZCMD. This is just a useless optimized (practically insignificant) cleaner version of ZCMD with one bug fixed.








ZCMD hasn't been updated in the last 6 years. We (the SAMP community) have advanced a lot in these years and these advancements haven't been implemented in ZCMD. I just re-wrote ZCMD 0.3.1 include and updated it. This is now a lot faster (still negligible) than ZCMD which makes this the fastest 'PAWN code' based Command Processor at the moment. The speed test results are given at the end of this thread. iZCMD also addresses few issues/bugs with ZCMD and also adds some new features (Case-sensitivity can be turned on/off using a define).






The great improvement in efficiency can be observed when you have small commands(commands which do not take a lot of CPU). If you have just one format function call in your command, I-ZCMD will be almost 2x faster than ZCMD. If you have 10 format calls in your command, I-ZCMD will be 1.5x faster than ZCMD.The main reason why I-ZCMD is amazingly fast when compared to ZCMD is because I-ZCMD gets rid of two CallLocalFunction(very slow function) calls. However, this improvement is negligible compared to the overall performance of your server which means don't expect your server to show measurable improvements after installing iZCMD. Anyway, its always advisable to use updated includes.




Changes from ZCMD:

• OnPlayerCommandReceived & OnPlayerCommandPerformed are now called directly instead of using CallLocalFunction
  
• Removed the OnGameModeInit/OnFilterscriptInit Hooks
  
• Minor optimizations
  
• Case Sensitivity now toggled on/off using a define
  
• Addresses few ZCMD bugs
  

How to install?



For those who are already using ZCMD, you just need to replace ZCMD include with IZCMD include.There is no change in functionality (by default), all the changes affect the speed and efficiency of the script. The only new feature in I-ZCMD is that now case-sensitivity can be turned on/off by defining IZCMD_ENABLE_CASE_SENSITIVITY before including IZCMD. To maximize compatibility, iZCMD is not case-sensitive by default (ZCMD is not case-sensitive).




For those who are not using ZCMD, you need to download I-ZCMD include and paste it in your include folder. Any ZCMD tutorial will do for I-ZCMD since the syntax and functionality are the same in both.








How to use?






To create a command, all you need to do is create a public function using any of the given formats.

PHP Code:

COMMAND:yourcommand(playerid,params[])
{
? ? return CMD_SUCCESS;
}
CMD:yourcommand(playerid,params[])
{
? ? return CMD_SUCCESS;
}
command(yourcommand,playerid,params[])
{
? ? return CMD_SUCCESS;
}
cmd(yourcommand,playerid,params[])
{
? ? return CMD_SUCCESS;
} 


When a player types "/yourcommand parameters", the public function will be called.The playerid parameter will have the id of the player who used the command and the params[] parameter will have the text which the player typed after typing the command (for the given example, params[] will have "parameters").






The "params" parameter will never be empty. If the player did give any parameters then params[0] will be '\1'.



You must return CMD_SUCCESS if the command was executed successfully (return CMD_FAILURE if you wish the server to send the "Unknown Command" message). This result will be passed on to OnPlayerCommandPerformed.




You can also use the ZCMD style of returning, i.e: 1 for success and any other value for failure.






You cannot use OnPlayerCommandText once you include this include. It won't be called if you still have it in your code. There are two new callbacks instead.






OnPlayerCommandReceived




This callback is called before the actual command function is called.




Parameters:

• playerid is the ID of the player who used the command
  
• cmdtext is text which the player typed
  

Return Values:


1 - command function will be called




0 - the command function won't be called.

PHP Code:

public OnPlayerCommandReceived(playerid,cmdtext[])
{
return 1;
} 


OnPlayerCommandPerformed



This callback is called after the command function is executed.




Parameters:

• playerid is the ID of the player who used the command
  
• cmdtext is text which the player typed
  
• success is what the command function returned (CMD_SUCCESS or CMD_FAILURE)
  

Return Values:




0 or CMD_FAILURE - Player will see the Error Message, i.e "Unknown command"



1 or CMD_SUCCESS - The error message won't be sent

PHP Code:

public OnPlayerCommandPerformed(playerid,cmdtext[], success)
{
return success;
} 


If you are not using OnPlayerCommandPerformed then what you return in your command function will decide if the Error Message will be sent or not.




Returning 0 or CMD_FAILURE in the command function means the error message will be sent.



Returning 1 or CMD_SUCCESS in the command function means the error message won't be sent.





Case-Sensitivity




Case Sensitivity is disabled by default which means that "/pm" and "/PM" will be treated to be the same. Case-sensitivity can be enabled by defining IZCMD_ENABLE_CASE_SENSITIVITY before you include izcmd to your script.






Tips & Tricks




1. Calling command functions manually


You can call a command function using the following code.

PHP Code:

cmd_yourcommand(playerid,params); 


You need to prefix "cmd_" to your command to call the command function.






2. Shortcut Commands?
You can make shortcut commands using the idea given below.

PHP Code:

COMMAND:arrest(playerid,params[])
{
? ? //your arrest code
? ? return CMD_SUCCESS; 
}
COMMAND:ar(playerid,params[])
{
? ? return cmd_arrest(playerid,params);
} 


3. Disable Commands if player is not logged in


You can disable commands for a player who hasn't logged in using the following idea.

PHP Code:

public OnPlayerCommandReceived(playerid,cmdtext[])
{
? ? ? ? if(!PlayerLoggedIn[playerid]) 
? ? ? ? {
? ? ? ? ? ? ? SendClientMessage(playerid,-1,"You need to log in to use commands");
? ? ? ? ? ? ? return 0;
? ? ? ? }
return 1;
} 


4. I-ZCMD with[b] sscanf is the fastest way to process commands[/b]

PHP Code:

COMMAND:setskin(playerid,params[])
{
? ? ? new skinid;
? ? ? if(sscanf(params,"i",skinid)) SendClientMessage(playerid,-1,"Usage:/setskin [skinid]");
? ? ? else SetPlayerSkin(playerid, skin);
? ? ? return CMD_SUCCESS;
} 


More Examples

PHP Code:

COMMAND:getvid(playerid,params[])
{
new id,string[144],vid;
if(sscanf(params,"u",id))
{
if(IsPlayerInAnyVehicle(playerid))
{
? ? vid = GetPlayerVehicleID(playerid);
? ? format(string,sizeof(string),"The vehicle ID of your vehicle is %d.Use/getvid [Name/ID] to get vehicle ID of other player's vehicle.",vid);
return SendClientMessage(playerid,-1,string);
}
return SendClientMessage(playerid,-1,"Your not in a vehicle nor you have specified any player from which to get the vehicle id.Use /getvid [Name/ID] to get the vehicle ID of their vehicle.");
}
if(IsPlayerConnected(id))
{
? ? if(IsPlayerInAnyVehicle(id))
? ? {
? ? ? ? ? ? ? ? ? ? ? ? new pName[MAX_PLAYER_NAME];
? ? ? ? ? ? ? ? ? ? ? ? GetPlayerName(playerid,pName,MAX_PLAYER_NAME);
? ? ? ? vid = GetPlayerVehicleID(id);
? ? ? ? format(string,sizeof(string),"The vehicle ID of the vehicle which %s(%d) is using is %d.",pName,id,vid);
SendClientMessage(playerid,-1,string);
}
? ? else
? ? {
? ? ? ? SendClientMessage(playerid,-1,"The given player is not using any vehicle.");
? ? }
}
else { return SendClientMessage(playerid,-1,"Usage:/getvid:Invalid Player ID"); }
}
return CMD_SUCCESS;
} 


Speed Tests




The test code approximately has 250 test commands out of which 6 valid commands are called and one invalid command is called.




The code which was used for speed test can be found [/url]here.




I-ZCMD (case-sensitive) is 5.4 times faster than ZCMD




I-ZCMD (non-case-sensitive) is 2.2 times faster than ZCMD




ZCMD and y_command perform equally well in cases such as in the above speed test where there are lot of commands.






Please note that if you need any of the y_command features, then use y_commands. If you try to implement a similar feature in iZCMD then iZCMD will most likely get slower than y_commands. Use iZCMD if and only if you don't use any of y_command features.








Download




Download izcmd.inc if you need the I-ZCMD include.





Download izcmd-original.inc if you need the original ZCMD Include








[url=https://web.archive.org/web/20200314132456/https://github.com/YashasSamaga/I-ZCMD]Visit Github project page











Credits




Zeex for the original ZCMD Include & the concept/algorithm.




Yashas for spending 60 minutes to update the include.

[arber]

Really nice