[Feedback Needed] Server List Filter Documentation

Make suggestions for improving one of the best games on the net!
Post Reply
User avatar
Posts: 4804
Joined: Fri Mar 21, 2003 3:49 pm
Location: playing.cxx

[Feedback Needed] Server List Filter Documentation

Post by blast »

I've been work on some documentation for the server list filter in the game client. Version 2.4.4 will come with a built-in editor for the various quick filter presets, and I want to to also include good documentation for that right in the game. I have it split into different sections, each of which might span multiple pages of help in the game. Also note that the ffa/offa/ctf boolean filters don't actually exist in any released version yet, but will be included when I push this help text into the game.

Could I get some feedback on this please?

Structure of a filter

By default, when using the "search" function in the server list, it will search for the exact string of text you provided in both the server address and the description. Only servers that have that string in the address or description will be shown.

But there are also powerful filters you can use. These allow filtering the server list based on criteria such as player counts, shot count, address, description, and various server settings (such as jumping and ricochet). For instance, this filter would find any 2 or 3 shot servers that have at least one player online:
/p>1,s>1,s<4, # busy - 2 or 3 shots

Notice that the line begins with a forward slash. This tells the server list that this is an advanced filter. Multiple statements after the slash are then split apart by a comma, letting the filter know they are separate items. These are combined together with an "and" statement internally. So, with the example above, you can think of it as "Player count must be greater than 1 AND shot count must be greater than 1 AND shot count must be less than 4."

Multiple sets of filters can be listed by starting another set with a forward slash. These separate filter "sets" will be handled independently, so any servers that match any of the filter sets show up (effectively meaning they are joined with an "or" statement internally).

Filters are currently limited to 42 characters due to limitations with the menu system. Future versions of the game should be able to lift this restriction.

The next pages will describe the various filters. The text within the inital set of parenthesis for each item will include the short and longer forms of the filter. Either can be used in your filter, but the shorter form is recommended. Also, the filters are case sensitive, so make sure you write them exactly as shown.

Pattern filters

At present, you are limited to having only one of each of the following per filter set. If you use two or more within a single filter set, only the last one will take effect.

There are two possible operators that would immediately follow the filter name:
) glob: A pattern with wildcards in the form of an asterisk. If no asterisk is specifically included, it will surround the search string with asterisks. If you include a wildcard, it will not automatically surround the search string with asterisks.
] regex: Uses regular expressions. This allows for complex patterns, but the creation of these expressions is beyond the scope of this document.

Address (a or addr or address) - Looks for the pattern inside the address (hostname and port)
Description (d or desc or description) - Looks for the pattern inside the server description
Address/Description (ad or addrdesc) - Looks for the pattern in either the address or description

Here are some examples of pattern filters.

Find servers running on port 5155 or 5156:

Find servers with "league" in the description:

Find servers with a description starting with "league":

Find servers with "official" and "match" in the description, in that order:

Boolean filters

Boolean filters are either true or false. You prefix the filter name with either a + or a -. If a +, it will match if the boolean is true. If -, it will match if the boolean is false.

Game mode filters (include at most one positive game mode filter per filter set, otherwise you will find nothing):
FFA (F or ffa) - Server is running Free-For-All with teams
OpenFFA (O or offa) - Server is running Open Free-For-All without teams (colors don't matter)
CTF (C or ctf) - Server is running Capture-The-Flag
Rabbit (R or rabbit) - Server is running Rabbit Chase

Miscellaneous filters:
Jump (j or jump) - Tanks can jump without extra flags
Ricochet (r or rico) - Bullets ricochet off obstacles
Handicap (h or handicap) - Tank performance is affected by score
Replay (P or replay) - Server is a replay server
Inertia (I or inertia) - Tanks have inertia
Antidote (a or antidote) - Antidote flags spawn to drop bad flags
Favorite (F or favorite) - Server is on your favorites list

Here are some examples of boolean filters.

Find FFA servers in your favorites list:

Find servers that allow jumping but where bullets do not ricochet:

Show only CTF and rabbit chase servers:

Use multiple filter sets to show only CTF and rabbit chase servers:

Range filters

Range filters limit some value to a numeric boundary. It could be an exact value, or have a minimum and/or maximum. The format of a range filter is <filter><operator><number>.

Possible operators:
< less than
<= less than or equal to
> greater than
>= greater than or equal to
= equal to

Miscellaneous filters:
Shots (s or shots) - Maximum number of active shots per tank
Players (p or players) - Current number of players (excluding observers)
Free slots (f or freeSlots) - Available player slots (excluding observers)
Valid teams (vt or validTeams) - Number of teams enabled (excluding observers)
Max time (mt or maxTime) - Time limit on the game
Max players (mp or maxPlayers) - Maximum player count
Max team score (mts or maxTeamScore) - Team score that will end the game
Max player score (mps or maxPlayerScore) - Player score that will end the game
Shake wins (sw or shakeWins) - Number of kills to drop a bad flag
Shake time (st or shakeTime) - Number of seconds to drop a bad flag

Current amount of players by team:
Rogue count (Rp or roguePlayers)
Red count (rp or redPlayers)
Green count (gp or greenPlayers)
Blue count (bp or bluePlayers)
Purple count (pp or purplePlayers)
Observer count (op or observerPlayers)

Maximum amount of players by team:
Rogue max (Rm or rogueMax)
Red max (rm or redMax)
Green max (gm or greenMax)
Blue max (bm or blueMax)
Purple max (pm or purpleMax)
Observer max (om or observerMax)

Available player slots by team:
Rogue free (Rf or rogueFree)
Red free (rf or redFree)
Green free (gf or greenFree)
Blue free (bf or blueFree)
Purple free (pf or purpleFree)
Observer free (of or observerFree)

Here are some examples of range filters.

Find servers with observers online:

Find servers with between 1 and 5 players:

More than 3 shots, at least 5 players, and no rogue allowed:


Comments begin with a # to document the purpose of a filter. This is entirely optional though.

/op>3,# More than 3 observers

Combined examples

Now we will combine the various filter types to show some more advanced examples.

Find CTF maps with two teams:

Find league servers with at least one player or one observer (notice the second forward slash that starts a new filter set):

Find a rabbit chase server with ricochet and a shot count of 3

Short name version of the above filter (notice the capital R for rabbit chase):
"In addition to knowing the secrets of the Universe, I can assure you that I am also quite potty trained." -Koenma (Yu Yu Hakusho)

User avatar
Posts: 2036
Joined: Wed Mar 01, 2006 5:43 am

Re: [Feedback Needed] Server List Filter Documentation

Post by macsforme »

The filter capabilities seem very comprehensive. Since these days there are generally very few servers with players on my them, is the point of this feature to be able to locate servers to start games on with settings that a player prefers?
User avatar
Posts: 4804
Joined: Fri Mar 21, 2003 3:49 pm
Location: playing.cxx

Re: [Feedback Needed] Server List Filter Documentation

Post by blast »

The filtering has already existed for quite some time, though BZFlag 2.4.0 was the first release to actually include it. Only a few changes are being made to the actual filtering system as part of my changes, specifically only to game mode boolean filters. I'm renaming the boolean filters "flags" to "ffa" and "teams" to "ctf" (so that they actually describe what they filter), and adding a matching "offa" filter for OpenFFA. Quick filter presets have already been included in the game for a long time as well, which you can trigger by pressing 1 through 9 in the server list menu.

So beyond the minor changes to the game mode filtering, everything else is just the built-in filter editor (so you don't have to edit the config file by hand) and in-game documentation about how to write the filters.

So, basically, I'm wanting feedback about if this documentation is good enough and what I should improve or elaborate on.
"In addition to knowing the secrets of the Universe, I can assure you that I am also quite potty trained." -Koenma (Yu Yu Hakusho)

Post Reply