[ev0lution]

SmartFilter
Add multi-user selection to your commands!

What is it?
SmartFilter adds the ability to select multiple users with one parameter, using a special SmartFilter format to filter through players, producing a list of players resulting from the given filter set.
You can use this to perform a command/action on multiple players from a given criteria, saving time from repeating commands and simplifying tasks such as messaging.

How do I integrate it?
Copy the "smartfilter.inc" file into your include folder, it'll probably follow the same directory structure in the download.
Include the file (with "#include <smartfilter>") into scripts you would like to use the SmartFilter system in.

Where you want to integrate SmartFilter processing, create the following variables, and call the function as follows:

pawn Код:

new output_type,output_value,output_array[MAX_PLAYERS]; // Variables for SmartFilter output
sf_filter(input,output_type,output_array,output_value); // Call filter function

(above: where "input" is the string (array) containing the parameter)
The filter function sf_filter will return the following values into the respective variables:

• output_type: 0 = no players matched. 1 = players matched, check output_value and output_array. 2 = error in filter.
• output_array: array from 0 to MAX_PLAYERS. array entry (player ID) is 1 if all filters matched on that player, 0 if not.
• output_value: -1 if no players matched, otherwise the number of players matched.

How do I use it?
The following describes the SmartFilter filter syntax.
All filters are enclosed within < and > brackets.
Different set criteria are separated by "/" (forward slash).
Sets are specified in the format "type;value", where "type" is a one-letter code, and value is the criteria for that type. (see below)
Types and values
Type 'u' = Username: Search for a username. Use the wildcard '*' anywhere to specify a partial name.
Type 'p' = Player ID: Search for a player ID.
Type 's' = Score: Search based on a player's score.
For types 'p' and 's' (player ID and score), value must be numeric, with the following formats:
+value = greater than or equal to value
-value = less than or equal to value
value,value2 = between value and value2
Confused? You'll get used to it. Here are a few examples:

Код:

  <u;[lol]*>  =  Selects players with a username beginning with "[lol]".
  <p;+50/s;-100>  =  Selects players with a player ID above 50 and a score below 100.
  <u;lol*cake/s;10,50/p;-100>  =  Selects players with a username starting with "lol" and ending with "cake", a score between 10 and 50, and a player ID below 100.

How is this useful?
Personally I just think it makes it easier for players.
There are some things which, without selecting multiple players, you'd have to repeat manually.
What if you want to give $5000 to each of your clan mates, for example, with 10 of them online? What's easier; repeating a 'give cash' command 10 times, or specifying a filter matching your clan tag?

Yes, it's one more thing to learn, but if you find a way to explain this better than I can, I'm sure you won't have any problems.

What am I allowed to do with it?
SmartFilter is licensed under the GNU General Public License. Please see http://www.gnu.org/licenses/gpl.html.

Where can I download it?
Right here - this also includes the source.
http://code.******.com/p/sa-mpsmartf...1.0.0-full.zip (1.0.0 @ 25/02/11)
Please abide by the terms of the license!

Other Notes
If you'd like to implement this on your server, you can (and please do!) copy any part of my wonderfully-written (heh) documentation to help explain the system to players.
Also, please provide feedback; this system has only been tested on a dummy playerlist, real-player testing would be great. While any major bugs should have been obvious, you can't be too careful. :P

Example Implementation

pawn Код:

COMMAND:givemoney(playerid, params[]) {
    if(IsPlayerAdmin(playerid)) {
        new
            filter[128],
            amount;
        if(!sscanf(params,"si",filter,amount)) {
            new
              message[40];
            format(message, sizeof(message), "You got $%d from admin!", amount);
            new output_type,output_value,output_array[MAX_PLAYERS];
            sf_filter(filter,output_type,output_array,output_value);
            if(output_type == 0) SendClientMessage(playerid,0xFF0000FF,"SmartFilter didn't match any players"); // No players matched
            else if(output_type == 1) {
                // Valid filter
                // Loop through the players and check the result array, apply the action on them if included
                for(new i=0;i<MAX_PLAYERS;i++) {
                    if(output_array[i]) {
                        GivePlayerMoney(i,amount);
                        SendClientMessage(i,0x00FF00FF,message);
                    }
                }
            }
            else if(output_type == 2) {
                // Invalid filter
                // My method here is unadvisable - generally, you would check 'filter' as usual if it matches any user
                //   - Either by ID or player name, whichever you usually use.
                new tmp = strval(filter);
                if(IsPlayerConnected(tmp)) {
                    GivePlayerMoney(tmp,amount);
                    SendClientMessage(tmp,0x00FF00FF,message);
                }
                else {
                    SendClientMessage(playerid,0xFF0000FF,"Invalid player specified");
                }
            }
        }
        else SendClientMessage(playerid,0xFFFFFFFF,"Usage: /givemoney <player(s)> <amount>");
    }
    else SendClientMessage(playerid,0xFF0000FF,"Only admins can use this command!");
    return 1;
}