Arena pickers is a feature that only exists with this plugin and permits you to accomplish a wide variety of creative things.
By this, you're able to either select a specific set of arenas or one explicit one. You generally differentiate between an Arena Picker and an Arena Selector. The Arena Selector is the most common variant and can be used almost everywhere where you're able to add a name of an arena.
¶ Glossary:
- Arena Picker: A query for selecting multiple arenas (Example: [status=1])
- Arena Selector: A query for selecting exactly one or none arena (Example: (%best[status=3]%)
¶ Simple Example
¶ Usage
Alright, but what can I exactly do with that?
One usage is for example to use it within /bw join <arena selector>. You could for instance make the player automatically join the next best available duo arena or make him automatically spectate an arena. The possibility is endless.
An other usage would be to use it within arenas gui. You might not want to display all arenas within that one. You can filter out which arenas you don't want to be displayed using an arena picker.
Commands normally do NOT send a reason why or if the arena selector didn't work. It might tell for instance tell that the given arena hasn't been found, even tho you've inserted an arena selector, but it doesn't explicitly tell you that there's something wrong with your selector. You might want to check your logs as errors and warnings will be thrown in there. Furthermore, you might want to use
/bw debug 2 <arena selector>as that command exactly tells you if your query is valid or not.
¶ List of examples:
- /bw join %best[status=2 & players_per_team=1]% Join the best waiting solo match
- /bw join %best[status=2 & players_per_team=2]% Join the best waiting duo match
- /bw join %best[status=2 & players_per_team=3]% Join the best waiting trio match
- /bw join %best[status=2 & players_per_team=4]% Join the best waiting quad match
- /bw join %best_prefer_non_voting[status=3]% Spectate a random match
- /bw join %best[status=2 & display_name="My Arena"]% Join the best arena given by its display name. Useful when using the Enhanced ProxySync addon or when using the auto clone feature. In both cases there may be multiple arenas with the same display name, in which cases you possibly want to join the best arena under these given arenas. It is important that the " stay!
¶ Arena Picker
An arena picker generally has the following format: [thruth functions] while the brackets are being kept.
If you've programmed before you might be familar with thruth functions. They're basically a way for you to check if a property or multiple properties have the needed conditions to pass the test.
An example: [ingame_players=2]
This will check if there are exactly two players in a game.
You may connect further conditions using a & or | symbol.
&: AND. The left and right truth functions must be true
|: OR. Either the left, the right or both truth functions must be true
You'll likely understand it with some further examples:
[display_name="Sandstorm" | display_name="Castle"]
The name of the arena has to be either "Sandstorm" or "Castle".
[status=2 & players_per_team=2]
The arena must be in lobby state and be a duo mode.
[display_name="Castle" & ingame_players >= 1 | display_name="Castle"]
The arena with the name "Castle" may pass when it has at least one player inside it. Otherwise only the arena "Castle" may pass.
¶ Comparison Operators
There are multiple logical ways you can use to compare two things other than the = symbol. This includes:
=Are equal!=Are not equal>Number: Greater than | String: Starts with and ignore letter case<Number: Less than | String: Ends with and ignore letter case>=Number: Greather than or equaln | String: Starts with (letter casing must match as well)<=Number: Less than or equaln | String: Ends with (letter casing must match as well)
¶ Variables
There are some variables/properties of an arena you compare with.
display_nameString The name of the arena that'll be shown to the general public. You may use the custom names feature to make the arena appear with something else. If no custom name has been set, display_name will return the same thing as name (below)nameString The exact unique name of the arenaplayers_per_teamNumber The amount of players per teamteamsNumber The amount of existing teamsmin_playersNumber The minimum amount of players needed to start a matchmax_playersNumber The maximum amount of players that may join to playingame_playersNumber The amount of players who are currently playing inside the arenaremaining_playersNumber The amount of left players until the arena is full (basically max_players minus ingame_players)statusNumber The state of the arena. You can differentiate between:
1: Stopped
2: Lobby
3: Running
4: Resetting
5: End lobby (The place where players stay for a few seconds after a match has ended)typeString The type of the arena. Read more info here. You may differentiate between: world, region, votinggame_worldString The name of the world in which the game is being held in (not the lobby world!)cloned_arena_nameString The name of the arena from which the clone has been created from. "NOT_CLONED" if the arena is not clonedserver_channel_nameString The name of the server on which the arena is located on. The name is equal to the one you have configured in BungeeCord's configurations. It likely only makes sense to use this together with the Enhanced ProxySync addon. In case you are running standalone mode (without BungeeCord), this variable will output LOCAL instead.server_playing_arenas_countNumber Get the amount of arenas that have at least 1 player on the server the arena is on. Can be useful to avoid overfilling a server
The types (String, Number...) of the variables are important and must be kept in mind when comparing between them. E.g. string has to be put in quotes (like for instance [name="Sandstorm"]).
¶ Arena Selector
The arena selector now allows you to select one or none from the arenas you filtered using you the Arena Picker.
The format is the following: %type[arena picker]%. Keep the percentage and bracket symbols here as well.
Example: %best[status=2]%
¶ Types
¶ %random%
Literally picks a random arena from the filtered ones without any logic.
¶ %best%
Chooses the best arena for somebody to play in.
- Arena isn't full (may always join)
- Arena has the most players out of all (low waiting times)
- With RemoteAPI: Includes load-balancing. In case there are multiple potential arenas, it chooses the one from the server with the least amount of players
¶ %best_prefer_non_voting%
Basically, the same as the "best" type, with the only difference that it'll firstly look for existing non-voting arenas.
Can be useful when you'd like to players automatically join a running arena instead of a voting one when for instance using auto-join or a Cloud System.
Example: %best_prefer_non_voting[status=3 | type="voting"]%
-> Firstly looks for running arenas and tries to join them as a spectator. If there are none, then it'll look for voting arenas.
¶ %best_prefer_running%
It firstly looks for arenas that are currently running. This may be useful in case you e.g. only want to have one active arena at a time.