A) Overview

When HaloBrowser starts, it reads a configuration file that tells it what other files to use for various things, and where the Halo executable is located. It then reads a list of servers (defined by a network / IP address and a port) and queries each server in the list for its status:
Query-in-progress screenshot

Once HaloBrowser has all the responses, it reads another file that tells it what games you are not interested in, what games you particularly like and what other players you are interested in knowing about. The resulting list of game servers is displayed in a table with color highlighting any servers that have players with names you're looking for:
Query results screenshot

You can select any server in the list to see detailed information on the server, the game it is currently running and the players in that game. When a server is selected, you can tell HaloBrowser to launch Halo and you will automatically join that game (as long as there is still room in it after Halo starts).
Server details screenshot

When you tell HaloBrowser to perform a refresh it will re-read the server list and filters file, re-query the servers and filter the new results, displaying an updated list. HaloBrowser can also be set to automatically perform a refresh at intervals you set, for example every 5 minutes.

B) Configuration

Once HaloBrowser has been unzipped into the directory (folder) you created for it, there is one file that needs editting and another you will probably want to edit.

First, open HaloBrowser.ini in a text editor (an editor such as NotePad, which saves files in .TXT format, with only the text you type in and no additional formatting).

HaloBrowser.ini will initially look something like this: 

    # Default properties for HaloBrowser
    ServerListFile = ServerList.txt
    FilterFile = Filters.txt
    PathToHalo = "C:\\Program Files\\MicrosoftGames\\Halo"
    QueryDoneSound = bleep.wav
    NoServersSound = doh.wav
    PlayersFoundSound = elim.wav

Once HaloBrowser is running, you can also open the configuration file for editing via Edit → Settings, though if Windows does not already have an application designated for .INI files it will ask you to pick one (Notepad is suggested).

B.1) Comments

The first line is a comment -- something that is there for you or others but is ignored by HaloBrowser. A comment is defined by having its very first character being a pound sign ('#'). Comments can be put anywhere in the file; for example they can be used to easily switch between two different filter files: 

    FilterFile = normal.txt
    #FilterFile = boarding_action_phantoms.txt

With these lines in HaloBrowser.ini, the file normal.txt is used to define the server filters and player names. By commenting out the first line and un-commenting the second, a different set of filters will be applied the next time the server list is refreshed.

B.2) ServerListFile

ServerListFile is used to set the name of the file containing the servers to query. ServerList.txt is the default file distributed with HaloBrowser. This file and its format are described in more detail in section C below.

B.3) FilterFile

FilterFile specifies the name of the file containing all of the filters (these include what characteristic(s) a server must or must not have in order to remain in the list, what characteristic(s) you prefer (but do not require) a server to have, and what players you are interested in knowing about if they are on-line. Filters.txt is the default file distributed with HaloBrowser. This file and its format are described in more detail in section D below.

B.4) PathToHalo

PathToHalo tells HaloBrowser where you have installed Halo; it needs this information when you ask it to launch Halo and join a game.

The default path is 

    PathToHalo = "C:\\Program Files\\MicrosoftGames\\Halo"

The patch consists of a driver letter followed by a colon (':') and then the series of directories (folders) it must follow to your Halo installation. Each directory must be preceded by either a single forward slash ('/') or double backslashes ('\\').

Finally, if any of the directory names in the patch contain any blanks, then the entire path must be enclosed in quotation marks, as is done with the default value in the distribution.

B.5) QueryDoneSound

QueryDoneSound identifies the sound file (.WAV, .AU or .AIFF) that Halo is to play as it displays an updated list of servers. See section E for more information about the sound files HaloBrowser can play.

B.6) NoServersSound

QueryDoneSound identifies the sound file that Halo is to play when it finishes querying and filtering the servers and no servers remain (i.e. all have been filtered out). See section E for more information about the sound files HaloBrowser can play.

B.7) PlayersFoundSound

PlayersFoundSound identifies the sound file that Halo is to play when it displays an updated list of servers with one or more servers that contain player names matching those you are looking for. See section E for more information about the sound files HaloBrowser can play.

C) Server List File

If you open this file either directly or via Edit → Server List in the menu its format will be obvious -- simply one server per line, each server specified by a network / IP address followed by a colon (':') and then the server's port number, e.g. 

    63.208.74.59:2600
    66.158.14.230:2302
    69.31.96.65:2302
    64.37.104.75:2302
        .
        .
        .

You are free to add more servers to the list, remove servers that are no longer running Halo, or make your own short list of servers you frequent.

The need to have this list is unfortunate, especially because there is no way to automatically update it with new servers. But the only two "server servers" I know of, GameSpy and QTracker, both require a client to authenticate with their service before they will provide a list of game servers and I do not have the means to learn that protocol. If you know of a solution to this, please let me know at
My email address

D) Filters

Like the server list file, the filters file can be opened from your text editor or via Edit → Filters in the menu.

Here is an example set of filters illustrating the various commands that can be used in a filter file. 

    # a comment
    REQUIRE Version 01.00.04.0607
    FORBID NOT DedicatedServer
    FORBID Password
    FORBID Map Infinity
    FORBID Map BoardingAction AND Game NOT Slayer
    REQUIRE Game NOT Race
    REQUIRE NumPlayers Min 3 AND Open 1 AND Allowed 12 AND Max 8
    FAVOR Map NOT BloodGulch
    FAVOR Map Damnation AND Game CTF
    PLAYERS sarge
    PLAYERS *117
    # My clan
    PLAYERS XYZ*
    PLAYERS *noob*

D.1) Comments

Just like the server list discussed earlier, comment lines that HaloBrowser will ignore can be put in the filters file. A comment line is any line in the file that starts with a pound sign ('#').

Comment lines can be put anywhere in the file, not just at the beginning.

D.2) REQUIRE and FORBID

D.2.1) General

Filter lines are completely case insensitive -- you can use all capitals, all lower case or any combination. So FORBID, ctf and rAtRaCe are all valid.

If a string used in a filter contains a space (ex. "Blood Gulch" or "Gun Turrets"), then the entire value must be enclosed within single quotes (') like this: 

   FORBID Vehicles 'Gun Turrets'

There is no limit on the length of a line in the filter file (except for whatever constraints might be imposed by Windows and Java).

Note: This document does not explain what different Halo server and game settings mean! Please refer to Halo documentation, either the game's manual or the various on-line FAQs, for that information.

D.2.2) Line Format

Lines that exclude servers from the results start with either REQUIRE or FORBID That keyword is followed by a filter description (described next), and then it may optionally be followed by the keyword AND and another filter description. Any number of filter descriptions may be ANDed together on a single line.

There are two general types of filter descriptions, plus a third type that is used only for filtering on the number of players or spots in a game.

On / Off Filters

Some server characteristics, such as whether a server is password protected, are either true or false. These filters include the following:

The syntax for these filters, after REQUIRE, FORBID or AND, is the optional keyword NOT and then the filter name. Examples: 

    FORBID NOT Password
    REQUIRE Shields

The first excludes password-protected servers and the second excludes all games in which there are no shields.

Value-Based Filters

Most filters, however, need what I'll a "value" associated with them. For instance, when filtering by map the filter has to know what map name to look for. Filters in this category are:

The syntax for these filters, after REQUIRE, FORBID or AND, is the filter type, an optional NOT and then the filter name. Examples: 

    FORBID Map NOT BloodGulch
    REQUIRE Game Slayer

The first excludes all Blood Gulch games and the second excludes all games other than slayer.

Legal values for FriendlyFire filters are

Legal values for Game filters are

Legal values for Map filters are

Unlike the rest of the filters, some of the maps have two different values. This is because internally Halo uses different names for some maps. Both are supported so you can use whichever you are more familiar with.

Legal values for MaxHealth filters are 50, 100, 150, 200, 300 and 400.

Legal values for NumberOfLives filters are 0 (that's zero, which denotes "infinite"), 1, 3 and 5.

Legal values for Radar filters are

Legal values for Version filters are any string of four numbers separated by periods ('.'). Leading zeroes are not required (i.e. 1.0.4.607 is the same as 01.00.04.0607) but I prefer filtering a string that matches exactly what Halo reports in its Settings → About menu.

Legal values for Vehicles filters are

In team games, Vehicles filters are applied against both teams' vehicle settings (i.e. both teams' vehicle sets must pass the filter in order for the server to pass).

Legal values for Weapons filters are

Number of Players / Spots Filter

One filter, NumPlayers, is different from the two types discussed above. As usual, the filter type, NumPlayers, follows REQUIRE or FORBID (and perhaps AND; see below). However, after NumPlayers there may be any or all of 4 different constraints about how many players are or can be in a game.

An example of a NumPlayers filter using all four constraints is 

    REQUIRE NumPlayers Min 3 AND Open 1 AND Allowed 12 AND Max 8

The four constraints that may be part of a NumPlayers filter are

Any or all of the four constraints may be specified, with AND in between each if more than one is present. They may appear in any order.

The NOT keyword is not used in the NumPlayers filter.

It will not always make sense to specify all four constraints in a NumPlayers filter. However, each of the constraints on its own does provide a different filtering capability and can be valuable in specific situations; this is why all 4 are supported.

I believe NumPlayers can be combined with other filters using AND but this has not been tested. If it does work at all it will only be with with the NumPlayers filter being the last one on the line.

D.3) FAVOR

FAVOR filters do not exclude servers; rather they mark them "preferred". The more FAVOR filters a server matches, the more preferred it is and the higher it will appear in the list.

AND and NOT can be used with FAVOR in the same way as with REQUIRE and FORBID.

D.4) PLAYERS and AVOID

NOTE: AVOID is not yet implemented.

PLAYERS and AVOID lines in the filters file tell HaloBrowser to identify any servers that have a player with a matching name. You can specify whether the type of match has to be exact (the entire name), "starts with", "ends in" or "contains". PLAYERS indicate players you are looking to play with. AVOID indicates, well, the obvious.

PLAYERS and AVOID are not filters -- they do not exclude servers from the final list. They instead mark certain servers that you may be particularly interested in joining, or not joining. These servers are color-highlighted in the server list; this is described in section F.

The syntax of a player matching line is PLAYERS or AVOID followed by the string to match. An asterisk ('*') at the beginning of the string means a player can (but does not have to) have characters preceding those that match, and an asterisk at the end of the string means a player can have characters after the matching string.

The name matching is case sensitive; this means PLAYERS RANGER will not match a player named "Ranger" or "ranger".

If the string to match includes a space, then the string must be enclosed in single quotes, like this 

    PLAYERS 'silly name'

Example: A player named "SlayerBuffy" will be matched by these strings

but not these

E) Sound Files

HaloBrowser supports .WAV, .AU and .AIFF sound files. Audio formats that should work (audio format is different from file format) are those that use PCM (A-law or u-law), with 1 or 2 channels and 8 or 16 bits per sample at sample rates up to 48 KHz. However, some of those currently have problems. Until these are solved 16 bit stereo .WAVs at 8 KHz and 12 KHz do work, as do some if not all .AUs. .AIFF files may work but have not been tested.

The Windows Sound Recorder application can be used to convert a .WAV file's audio format.

F) Use

On starting, HaloBrowser will read the server list file, query all of the servers, filter the results and display the remaining servers.

Selecting any server in the list will display all of the information about that server, its current game and the players in that game.

Servers are usually displayed with black text on a white background. If a server passes your filters and has a player on whose name matches one that you are looking for, it will instead have a green background.

A server that has a player name match but does not pass your filters (and hence would normally not appear in the list) will appear at the end of the list and will have a yellow background. And once the AVOID keyword is implemented, a server with a player name matching your AVOID list will have a red background.

Clicking the "Refresh" button, pressing the F5 function key or selecting Action → Refresh in the menu will perform a complete update of the server information. This includes re-reading the server and filter files, so it is not necessary to restart HaloBrowser for changes to those files to take effect.

Automatic, periodic refreshes can be enabled by changing the "Refresh every <X> secs" setting (0 means "never refresh") to a non-zero value.

Once you find a server you want to join, launch Halo by double-clicking on that server, clicking the "Launch" button or selecting Action → Launch in the menu. Halo will start and automatically join that game.

Note: HaloBrowser creates a lot of network traffic when it querying servers, and it will bog down Halo if automatic refreshes are left on when you start Halo. This will not be a problem if you launch Halo from within HaloBrowser -- automatic refresh is automatically be disabled every time the "Launch" command is issued. However, if you start Halo separately, HaloBrowser will not know it and automatic refreshes will be left on if enabled.

Copyright (c) 2004 Thomas J. Ziomek. All rights reserved.