This plugin is primarily geared toward server admins who really know what they are doing. The plugin provides various methods of targeting specific players with great flexibility. This allows admins to target EXACTLY who they want to target, all at once.
If you are installing this plugin on TF2 or CS:GO, it is very recommended that you also install Double Quote Fix.
Methods of targeting
The plugin provides three methods to specify targets:
Inline filtering
The plugin can intercept arguments given to other commands, and seamlessly cause the command to target the desired players. For example:
Code:
/slay "@(@red + @scouts - someGuy)"
The previous command would slay all RED players, slay all scouts, but NOT slay the person named someGuy, even if he was RED or a scout, or both. Another example:
The previous command would teleport all blue heavies, and all red engies, to the admin's crosshair. In addition, by specifying - @me, the admin will not teleport himself, even if he was a blue heavy or a red engie.
Please note the syntax of the target selection. The entire thing is wrapped in quotes, with an @ symbol starting everything off within the quotes, followed by a pair of parentheses.
Code:
"@()"
Your custom targeting filters must go within these parenthesis. The syntax that goes within these parentheses will be discussed later on.
This functionality of inline filtering can be enabled/disabled on a per-player basis (through the /settings menu) and also on a server-wide basis through the cvar sm_dynamictargeting_listen.
You are limited to 58 characters within the parentheses. If this is a problem, consider "saving" the longer custom targeting string into one of the customizable filters.
Filters Customizable In-Game
This plugin provides four different types of customizable filters, which can be configured with the command sm_dtarget. These filters can be used to "save" a certain custom targeting for use in future commands.
Static, private filters. EXAMPLE @prs0, @spr0
Static, public filters. EXAMPLE @pbs1, @spb1
Dynamic, private filters. EXAMPLE: @prd5, @dpr5
Dynamic, public filters. EXAMPLE: @pbd29, @dpb29
A matching "inverse" filter corresponding to each filter listed above. EXAMPLE: @!prs0, @!spr0
How many of each filter type you are given is controlled by the cvar sm_dynamictargeting_numfilters.
As shown above, each filter can be described as either static or dynamic, and as either private or public. All filter names begin with a @ symbol, and end with a number.
A static filter will have an 's' in the filter name. A filter that is "static" is called so because its targets do not change once configured. Consider the following:
Code:
sm_dtarget @pbs1 @dead
This will cause all players who are currently dead to be stored in the filter "@pbs1". The filter will continue to target these same players even after they respawn. Players who were alive when the filter was configured will NOT be targeted, even if they happen to be dead when the filter is used in a command. Once the filter is configured, the specific players it targets will not change until they either leave the game, or the filter is reconfigured.
Static filters can be configured through a menu interface. This interface can be accessed by specifying nothing after the filter name in sm_dtarget, not even whitespace.
A dynamic filter will have a 'd' instead of an 's' in the filter name. A filter that is "dynamic" is called so because, unlike static filters, its targets are recalculated every time the filter is used. Consider the following:
Code:
/dtarget @prd2 @red - @me
The above command would cause the filter "@prd2" to target all players who are red, and exclude the command user. If a red player switches to the blue team, he will no longer be targeted by that filter. Similarly, if a blue player switches to the red team, he will then be a valid target for that filter.
A private filter will have a "pr" in the filter name. Private filters are called so because each player can independently configure his own filters. If AdminOne sets @prs1 to target a group of players, and AdminTwo sets @prs1 to target a different combination of players, AdminOne will still be able to use @prs1 to target the players that HE configured.
The server console has its own set of private filters, both static and dynamic, just like any human player.
A public filter will have a "pb" in the filter name. Public filters are the opposite of private filters, in that if AdminOne sets a public filter to target a combination of players, and then AdminTwo comes along and sets that SAME public filter to target a different combination of players, it will target the second combination for both of them.
A player cannot configure public filters without access to the override sm_dynamictargeting_changepublic (default access, generic), and cannot use these filters in other commands without access to sm_dynamictargeting_usepublic (default access, public.)
The syntax of sm_dtarget is as follows:
Code:
sm_dtarget @filter someplayers
The first argument is the filter that you would like to configure. Everything else after this first argument is taken as the custom filtering string, as demonstrated twice above. Specifying a single space after the filter name will blank out the filter, while typing NOTHING after the filter name will inform you of what the filter is currently set to. If the filter is static, then a menu will open up and allow you to modify the filter that way.
Permanent Filters
Custom dynamic public filters, referred to as "permanent" filters, can be created through the config file configs/dynamictargeting.txt. The syntax is as follows:
Code:
someFilter "Self plus blue players" @me + @blue
someOtherFilter "All reds and all deads" @red + @dead
deaddemos "Dead, blue, demomen" @demos & @dead & @blue
If dynamictargeting.txt contained these two lines, then the filters @someFilter, @!someFilter, @someOtherFilter, @!someOtherFilter, @dbdemos, and @!dbdemos would all be created. This file can be reloaded through the command sm_dtarget_reload (default access, config). A player cannot use these filters without access to the override sm_dynamictargeting_usepermanent (default access, public). These filters cannot be edited through sm_dtarget, hence why they are called "permanent."
The syntax is identical to the syntax of sm_darget. Do not include the preceeding @ or @! when naming a filter in your config file. They will be added for you.
Targeting String Syntax
The syntax used in all three methods of targeting can be very simple, but has the capability of facilitating complex custom targets.
Parenthesis are usable here, which will cause a given part of the string to be processed before others, similar to order of operations in basic algebra.
Parenthesis can be nested within other parentheses.
Spaces should be put in between most everything. Operators should have spaces on both sides. All parentheses should have spaces on the outside. If using ~ or ! in front of the parentheses, the first space should come before the ! or ~. For example:
When using a player's name, you should probably use quotation marks around the name. You NEED to use quotes if the name has any parenthesis characters in it, or a space in it. If the player's name has a doublequote mark " in it, then you must avoid using that part of the name.
Due to the nature of how the inline targeting works, doublequote marks cannot be used to surround a player's name when targeting in this manner. (Since the whole thing is must be surrounded in a pair of quotes. "@()" ) This means that you must avoid using any part of the player's name that includes doublequotes, parentheses, or spaces.
If you expect an issue with targeting a specific player due to his name having quotes, spaces, quotation marks, or apostrophes, please see this article on alternative methods of targeting that user. All of these methods are compatible with this plugin, save for any method that requires spaces or quotes being used in inline targeting.
Targeting strings are evaluated from left to right, with only parentheses able to change the order in any way.
Code:
/tele "@(@me + @engies & @red)"
This will evaluate @me + @engies first, and then use THAT result with & @red, meaning that you won't be targeted unless you are on the red team. Whereas:
Code:
/tele "@(@me + (@engies & @red) )"
... will target all red engies, plus the command user. Alternatively, you could forget the inner parentheses and just put + @me after the @engies & @red.
Operators are as follows. With the exception of + and -, most would require basic knowledge of bitwise operators.
| or +, which combines two groups into one. The bitwise OR.
-, which selects players who are in the first operand, but not in the second.
&, which selects only players who would be targeted by BOTH terms around the &. This is the bitwise AND.
^, which selects only players who would be targeted by ONLY ONE of the terms around the ^. Not zero, not both, just one. This is the bitwise XOR.
!& or ~&, the bitwise NAND.
!^ or ~^, the bitwise XNOR
!| or ~| or !+ or ~+, the bitwise NOR.
! or ~, the bitwise NOT. This operator is unique in that it is only usable directly in front of parentheses.
Important notes:
One quirk to be aware of is how "@me" works in public filters. In a static public filter, "@me" will always refer to the person who configured the filter. In a dynamic public filter (or a permanent filter) it will refer to the person who uses the filter in a command to target players.
Dynamic filters that call each other can cause a server-crashing infinite loop. To prevent this, if dynamic filters are called more than 10 times in a single command use, any subsequent call to a dynamic filter will return no targets, ending the loop.
If you are installing this plugin on TF2 or CS:GO, it is very recommended that you also install Double Quote Fix.
This plugin will see its greatest usage on servers where additional targeting filters are also provided. A list of plugins providing such filters will eventually be found in the second post in this thread.
Testing a filter:
To test a filter to see exactly who it would target, the command sm_testfilter has been provided. The command takes a single argument, which is the filter to be tested. The command will reply with a list of all players who would be affected by that filter, assuming that the command that you intend on using the filter with ignores alive/dead status, bot/human status, immunity rules, in-game status, and can target multiple players.
This plugin provides a native for use by other plugins. ProcessExtendedTargetString() is very similar to ProcessTargetString(), with two notable exceptions:
The final three arguments of ProcessTargetString are omitted, as the calling plugin is responsible for determining the 'target_name' information as well as any multi-lingual stuff.
The native can, obviously, process complex targeting strings that you might use in sm_dtarget or in dynamictargeting.txt.
To do:
Video demonstration.
Separate the various features of the plugin into individual plugins, emphasizing usage of the native.
CVARS, shown with default values:
sm_dynamictargeting_logging 1 - Controls how command usage is logged.
0 : Completely disables logging.
1 : Enables basic logging. The logs will show when a filter is configured, and also the filter string used to configure it.
2 : Enables semi-basic logging. The logs will show all of the above, as well as show a list of who exactly static filters were configured to target.
3 : Enables verbose logging. The logs will show all of the above, but also show a list of who exactly was targeted by a dynamic filter, every time it's used.
sm_dynamictargeting_listen 1 - Enables/disables use of inline filter processing. "@()"
-1 : Completely disables the feature.
0 : Disables the feature by default, but individual players can turn it on for themselves through the /settings menu.
1 : Enables the feature by default, but individual players can turn it off for themselves through the /settings menu.
2 : Enables the feature at all times for all players.
sm_dynamictargeting_numfilters 10 - Specifies how many of the sm_dtarget filters of each type you are given. The "last" filter of each type will have this number at the end, minus 1. Setting this cvar to 0 completely disables filters configurable with /dtarget.
1 : Updater will notify you in Updater.log if an update becomes available.
2 : Updater will automatically download any updates. They will be installed on the next server start or map change.
3 : Updater will automatically download and immediately install any updates. This WILL interfere stored filters!
Installation:
To install, simply ensure that your Sourcemod installation is up to date, and place the attached SMX in your plugins folder.
Please also consider installing Updater. This will let you automatically keep your plugins up-to-date. Updater is NOT required for Dynamic Targeting to function.
Compiling:
The plugin requires custom includes. As such, it does not compile here on the forums. Includes required to compile the plugin are:
18.0126.0 - Fixed link, various internal improvements and bugfixes, added native ProcessExtendedTargetString()
18.0807.0 - Hopefully removed 32 player limitation, and fixed error spam that would happen if a player joined the server, and then disconnected before fully loading in. Also apparently fixed nested parens lmao
18.0912.0 - fixes a bug with static filters, removes debug message spam, updates ddhoward_updater
Linear Mode
