Microsoft Halo PC Dedicated Server Readme File
May 2004, v1.07
© Microsoft Corporation, 2001-2003. All rights reserved.

Welcome to Halo for the PC Dedicated Server!

This file contains information to help you setup, run and troubleshoot the Halo
Dedicated Server. The Halo Dedicated Server is definitely an advanced feature,
not designed for the casual user. This document is written assuming the reader
is familiar with running dedicated game servers, as well as having advanced
computer knowledge.

NOTE: HALO DEDICATED SERVER IS NOT SUPPORTED BY MICROSOFT CUSTOMER SUPPORT.

CONTENTS

A. Dedicated Server Features
B. System Requirements
C. Installation
D. Running Halo Dedicated Server
E. init.txt configuration file
F. Running multiple instances
G. Using Remote Console
H. Controlling Team Killing and Banning undesirable players
I. Console Commands
J. Getting Help
K. Known Issues and Workarounds
L. Versions History

A. Dedicated Server Features

With the v1.03 update, the following new features / bug fixes are introduced:

* Enhanced functionality to reduce online team killing and facilitate the
banning of users.
* Optimized map loading functionality, significantly reducing the time to
load large map cycling configuration files.
* Extended sv_players functionality.
* Teams are now persisted for the next game when map cycling occurs.
* It's now possible to restart the current game without requiring the
server to map cycle.
* User can now specify their data folder directories using -path.

The Halo Dedicated Server v1.02 includes:

* Stand-alone application.
* Flexible multiple instances support.
* Client RCon (Remote Console) functionality.
* Command line execution.
* Kicking and banning players.
* Pre-defined / custom game type and map rotation support.
* Password protected servers.

B. System Requirements

Halo Dedicated Server requires a personal computer with the following minimum
requirements:

* Multimedia personal computer with a 733 MHz or higher processor.
* Windows 98 SE, Windows Me, Windows 2000 Service Pack 1, or Windows XP.

* 128 Megabytes (MB) of RAM.
* 380 MB of available hard disk space.
* Keyboard and Microsoft Mouse or compatible pointing device.
* Broadband internet connection.

These differ from the retail version of Halo for the PC by not requiring:
* 8× CD-ROM drive.
* 32 MB 3D hardware-transform-and-lighting-capable video display.
* Sound card and speakers or headphones.
* DirectX 9.0b.

To run an optimal Halo Dedicated Server, a personal computer with the following
requirements is recommended:
* Personal computer with a 1.4 GHz or higher processor.
* Windows XP or Windows 2003 Server (with all service packs installed)
* 256 Megabytes (MB) of RAM or more.
* 380 MB of available hard disk space.
* Keyboard and Microsoft Mouse or compatible pointing device.

When running multiple instances on a server, these requirements have to be
adjusted to account for the additional resources required.

C. Installation

Halo Dedicated Server is released in two different self-extracting files:

Halo_DS_1_02.exe
This self-extracting file includes the Halo Dedicated Server binary files. When
we release updates to the dedicated server, these will be the only files you
need to update.

Halo_DS_Maps_1_02.exe
This self-extracting file includes the multiplayer maps required to run Halo
Dedicated Server. You only need to download these once. If you already have the
full retail Halo game installed on your server, you do not need to download the
maps at all; the server will use the maps that were installed by the game.

To install: double-click these files and follow the on-screen instructions.

D. Running Halo Dedicated Server

1. Browse to your Halo Dedicated Server installation directory.

2. Double-click haloded.exe.

This will open a console window and you will have access to the Halo Dedicated
Server console command line.

With v1.03, we are introducing the possibility for server administrators to
specify their data directory using the -path command line argument. This allows
storing custom game types and data files in any folder on the disk drive.

Important note: with this new command line argument, the default path for these
data files is changing from the dedicated server installation directory to the
user's "My Documents" folder. This is important for server administrators who
prefer to set per-user read / write access permissions to the Halo Dedicated
Server program files directory. If you will not be using the -path command line
argument, you will have to move your current ban list to the default
directory.

E. init.txt configuration file

Halo Dedicated Server uses init.txt file (located in the installation
directory) to pre-set some of the server options and setup map cycling. Any
console command can be invoked in the init.txt file (see Console Commands below
for a list of available console commands).

For example, to launch a server with the following parameters:
* Name: "Halo_DS"
* Listed on the GameSpy Master Server list? Yes
* Maximum number players: 12
* Password: "halo"
* Timeout between maps rotations: 15 seconds

Create the following init.txt file:

sv_name Halo_DS
sv_public 1
sv_maxplayers 12
sv_password halo
sv_mapcycle_timeout 15

To setup map cycling, you need to create a game entries map cycling list (a
game entry is a map name and a game type). To do so, simply use the
sv_mapcycle_add command in the init.txt file.

For example, to have the following maps and game types cycle:
* Timberland CTF
* Danger Canyon Assault
* Gephyrophobia Slayer
* Blood Gulch Crazy King

Add the following lines to the init.txt file:

sv_mapcycle_add timberland CTF
sv_mapcycle_add dangercanyon assault
sv_mapcycle_add gephyrophobia slayer
sv_mapcycle_add bloodgulch "crazy king"

Then, to start the dedicated server, use the following command:
sv_mapcycle_begin.

Every time you launch haloded.exe, it will look for init.txt for initialization
(unless you specify a different file using -exec. See below for more details on
-exec).

For the previous example, the final init.txt file would look like this:

sv_name Halo_DS
sv_public 1
sv_maxplayers 12
sv_password halo
sv_mapcycle_timeout 15
sv_mapcycle_add timberland CTF
sv_mapcycle_add dangercanyon assault
sv_mapcycle_add gephyrophobia slayer
sv_mapcycle_add bloodgulch "crazy king"
sv_mapcycle_begin

The default game types available are the following:

oddball
slayer
juggernaut
king
crazy king
race
ctf
assault
team slayer
team oddball
team race

Classic game variants are also supported as default game types (check out the
retail version of Halo for a list of all classic game variants).

You can create custom game types (using the full retail version of Halo) and
include these game types on your server rotation. This would enable you, for
example, to include a Rockets only game on your server rotation. To do so,
follow these steps:

* Launch the full retail version of Halo.
* Under Multiplayer, choose Edit Game Types.
* Create a new game type (refer to the Halo documentation if you need
help to do this).
* Save your new game type.
* Quit Halo.
* Open your Halo save games folder (by default, this would be "My
Documents\My Games\Halo\savegames").
* You will see the name of the custom game type you created as a folder
directory.
* Make sure this folder is available on your server (in the same location
on disk).
* Use the name of your custom game type in your mapcycle.txt file.

F. Running multiple instances

Halo Dedicated Server supports multiple instances running on one computer.
Obviously, each of these instances must be using a different network port. See
below for instructions on how to launch multiple instances of Halo Dedicated
Server. The maximum number of instances that can be run on a server is 8.

When running multiple instances, each instance will use its own init.txt file.

Here is an example on how to run multiple instances, assuming Halo Dedicated
Server is installed in the E:\HaloPC folder:

E:\HaloPC\haloded.exe -exec e:\halopc\init1.txt -cpu 0 -port 2301
E:\HaloPC\haloded.exe -exec e:\halopc\init2.txt -cpu 1 -port 2305
E:\HaloPC\haloded.exe -exec e:\halopc\init3.txt -cpu 0 -port 2307

Three command line arguments are specific to running Halo Dedicated Server with
multiple instances:

-exec
Specify which init.txt file to use for this instance of the dedicated server.
The name of this file can be any name.

-cpu
When using a multi-processor computer (SMP) server, it is possible to instruct
Halo Dedicated Server to run on a specific CPU. To do so, use the -cpu n
command line argument (where n is a given CPU, 0 being the first one).

-port
Different instances must, obviously, use different ports. -port is used to
specify the port for the instance being launched. If a port is not specified
the server will automatically choose an open port though the chosen port is not
reported.

G. Using RCon

By default RCon (remote console, ) to a server is disabled. To enable it, you
must specify an RCon password. You do this using the following console
command:

sv_rcon_password password

Once RCon is enabled on a server, any client can send it commands using the
following console command:

rcon password command argument

password is the RCon password to the server the client is connected to.
command is one of the server console commands (see Console Commands below).
argument is the argument to the server console command.

H. Controlling Team Killing and Banning undesirable players

Halo Dedicated Server v1.03 introduces a new system to control team killing in
online games.

At its core, the system is very simple. It's also very flexible and allows
server administrators to tweak servers to reflect settings they deem
appropriate to provide the best game experience to their users. Here's how it
works:

Every time a player kills someone on their team, they are awarded a "team
killing point" (let's call them TKP). If a player is awarded a certain number
of TKP, he is automatically kicked and banned from the server. To set the
number of TKP required for a user to be kicked and banned, server
administrators use the sv_tk_ban console command. For example:

sv_tk_ban 4

sets the number of TKP required for a player to be kicked and banned to 4.

When a player reaches the number of TKP necessary to be kicked and banned, he
is automatically expelled from the server. He will remain banned from the
server for a period of time specified using the sv_tk_penalty console command.
In addition to this, this period of time can be set to take into account
repeated offenses. This means if a player gets enough TKP to be kicked and
banned for 5 minutes, then comes back and misbehaves again, his banned period
can be larger. It's possible to set as many as 4 different levels of
punishment. Upon his fifth offense on the same server, a user is banned
indefinitely. Of course, the server administrators can always consciously
choose to unban the player.

sv_tk_penalty 5m 1d 0
sv_tk_penalty 5m 1h 8h 1d

The first example above will, for a server, set the first-offense punishment
to 5 minutes, the second offense to 1 day and the third one to an indefinite
ban (0 means indefinite). The second example will set the offense punishment
to 5 minutes, the second to 1 hour, the third to 8 hours, and the fourth to 1
day. On the fifth offense, the player will be indefinitely banned from the
server.

Because team kills can be accidental, we also introduce a "cool down" period.
If a player gets a TKP accidentally and doesn't kill another teammate for the
duration of the cool down period, the TKP will be forgiven. For example:

sv_tk_cooldown 5m

will set this cool down period to 5 minutes.

The last aspect of the team killing system is that, once again, by accident, a
rocket explosion or a grenade can kill three of your teammates. This poses the
risk of registering three TKP instantly, improving the chances of improperly
banning an accidental team kill. To address this, the concept of a "team kill
grace" period exists. This period is the delay (in seconds) that must expire
before a player can be credited with an additional TKP.

sv_tk_grace 3s

sets this period to 3 seconds. Once again, this means that if a player kills 4
teammates within a 3 seconds period, he will only be credited with 1 TKP.

Finally, as with v1.02, it is possible to ban players individually using their
player index. The sv_tk_players console command has been updated to display
players' TKPs and their cool down period timers.

I. Console Commands

The following commands are server specific console commands:

cls
Clear the console text.

help [command]
Tell you about the command.

quit
Quit Halo for the PC dedicated server.

sv_ban [player name or index]
Ban the player with the given name or index. Yes it does
sv_ban_penalty [time1] [time2] [time3] [time4]
Specifies the levels of punishment for repeat offenders. The first offense will
be punished for [time1], the second offense for [time2], the third offense for
[time3], the fourth offense [time4] and the fifth offense for an indefinite
period of time (the administrator has to unban the user). The format of time is
ns, nm, nh, nd or 0. n is a digit in the 1-9 range and 0 is infinite.

sv_banlist
Show the list of the banned players.

sv_banlist_file
Specifies the file to store and load the ban list to and from. Note: this
file's name is restricted to banlist##.txt where ## is a two digit number. This
allows multiple instances to use different ban lists while still restricting
the name of the ban list (for security purposes). Umm, you can set this to be
any string of alphanumeric characters, like
banlistTHISisAsuperLONGfilename123.txt.

sv_end_game
End the currently running game. This will proceed to the next game in the map
cycling game entries list.

sv_kick [player index or name]
Kick the player with the given name or index out of the game.

sv_map [map name] [game variant]
Start a game with the indicated map and game variant. When the game is over,
this game will restart itself. This command supersedes any map cycle the server
has.

sv_mapcycle
Show game list.

sv_mapcycle_add [map name] [game variant]
Append this game entry (map name and game type) to the end of the game list.

sv_mapcycle_begin
Start the map cycling with the specified game entries.

sv_mapcycle_del [index]
Delete the game entry from the map cycling game list (use sv_mapcycle to get
game IDs).

sv_mapcycle_timeout n
Time in seconds to restart the next game in the game list after game is
finished (this determines how long clients are sitting at the post carnage
report screen).

sv_map_next
End the current game and skip to the next game in the map cycling game entries
list.

sv_map_restart
Restart the game.

sv_maxplayers n (Default value is 16)
Set the maximum number players. Changed for 1.03: This can be done in the
init.txt or at any time using the console, but does not kick players out of the
current game if there are already more players than specified in the command.

sv_name [string] (Default value is "Halo")
Set the server name (64 characters max). This should be done in the init.txt
file, before map cycling begins. With the 1.03 update, the set of characters
allowed for server names is no longer limited to alphanumeric characters. Most
keyboard-accessible punctuation is now allowed, but not extended or accented
characters.

sv_password [string]
Set password for server. This should be done in the init.txt file, before map
cycling begins.

sv_players
List the players and their indices for reference in banning and kicking players
from the dedicated server. With v1.03, sv_players also shows the number of TKP
per players and their cool down period (as appropriate).

sv_public [true, false] (Default value is true)
Determine if the server will be listed in the GameSpy Master Server list (true)
or not (false). This should be done in the init.txt file, before map cycling
begins. Note: setting this to false is equivalent to hosting a LAN game.

sv_rcon_password [string]
Set the RCon password. To remove the password, thus disabling RCon, specify an
empty string "" as the password.

sv_status [true, false]
Displays the current status of the dedicated server in the console.

sv_tk_ban n
Specifies the number of "team kill points" required for a player to be kicked
and banned from a server. See section H for additional information about
Controlling Team Killing and Banning undesirable players.

sv_tk_grace [time]
Set the grace period during which a player can only be credited with one TKP.
For example, if set to 3s, a player can only be credited for one team kill
every 3 seconds, preventing an accidental grenade explosion from crediting
multiple TKP to a player.

sv_tk_cooldown [time]
Set the cool down period after which a player will be forgiven one TKP if they
have not committed another team kill.

sv_unban [player name]
Allow the player with the given name to join the server again.

J. Getting Help

Get Halo Dedicated Server help on the Gearbox Software community forums at the
following address:
http://www.gearboxsoftware.com/forums/postlist.php?Cat=&Board=ServerAdmin

Halo Dedicated Server engineers regularly browse these forums and answer
frequently asked questions.

NOTE: HALO DEDICATED SERVER IS NOT SUPPORTED BY MICROSOFT CUSTOMER SUPPORT.

K. Known Issues and Workarounds

Console does not recognize Battlecreek, Derelict, or Chiron map names.
You must use the actual multiplayer map file name. Here is a table with the
in-game name of the map and its associated file name:

In-game name = File name
Battle Creek = beavercreek
Sidewinder = sidewinder
Damnation = damnation
Rat Race = ratrace
Prisoner = prisoner
Hang 'Em High = hangemhigh
Chill Out = chillout
Derelict = carousel
Boarding Action = boardingaction
Blood Gulch = bloodgulch
Wizard = wizard
Chiron TL34 = putput
Longest = longest
Ice Fields = icefields
Death Island deathisland
Danger Canyon = dangercanyon
Infinity = infinity
Timberland = timberland
Gephyrophobia = gephyrophobia

Using sv_map, host is unable to launch a game using a game variant with spaces
in it: Sv_map takes multiple arguments. You need to add quotes around spaces in
the second argument (game variant) in order for this to work. For example,
sv_map mapname "game variant".

Console is unable to clear the server password: You need to enter an "empty"
password to clear it from the console. Enter sv_password "".

L. Versions History

Including main features summary.

v1.00 - 9/9/2003 - Halo Dedicated Server v1.00 private release

v1.01 - 10/1/2003 - Halo Dedicated Server v1.01 public pre-release
* Basic version of the dedicated server release to the community due to
the high-demand.

v1.02 - 10/7/2003 - Halo Dedicated Server v1.02 public release
* Multiple instances support.
* RCon support.
* Halo Dedicated Server instructions released.

v1.03 - 12/8/2003 - Halo Dedicated Server v1.03 public release
* Enhanced Team Killing / Banning System
* Optimized Map Cycling loading process.

v1.04 - 2/10/2004 - Halo Dedicated Server v1.04 public release
* The GameSpy Security update (update v1.04) for Halo for Windows
addresses a rare crash bug that could occur if a malicious individual (hacker)
purposely tries to exploit the GameSpy CDKey SDK.

v1.05 - 9/6/2004 - Halo Dedicated Server v1.05 public release
* Addresses a rare crash bug that could occur if a malicious individual
(hacker) purposely sends a malformed packet to a game server.
* Incorporates fixes to resolve compatibility problems with Windows XP
SP2 and certain 256MB video cards, which could cause the game not to launch, or
not to display chat messages.

v1.06 - 11/16/2004 - Halo Dedicated Server v1.06 public release
* Addresses a rare crash bug that could occur if a malicious individual
(hacker) purposely imitates a game server and sends invalid data to clients who
try to browse the server list.

v1.06 - 11/16/2004 - Halo Dedicated Server v1.06 public release
* Addresses a rare hang that could occur if a malicious individual
(hacker) purposely imitates a game server and sends invalid data to a server.
DEMOS
PATCHES - CHEATS
REVIEWS
GAME VIDEOS
NEWS ENTRIES
THIS WEEK'S MOST POPULAR DOWNLOADS