halo.bungie.org

They're Random, Baby!

Microsoft Halo PC Dedicated Server Readme File

December 2003, v1.03

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

  1. Dedicated Server Features
  2. System Requirements
  3. Installation
  4. Running Halo Dedicated Server
  5. init.txt configuration file
  6. Running multiple instances
  7. Using Remote Console
  8. Controlling Team Killing and Banning undesirable players
  9. Console Commands
  10. Getting Help
  11. Known Issues and Workarounds
  12. 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:

  • 8X 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 administrator 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.

With this release, the dedicated server is dependent on access to your save games folder. This will be addressed in an upcoming release.

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 connection) 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, they isare 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, they are automatically expulsed from the server. They 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 also 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, their banned period can be larger. It's possible to set as many as 4 different levels of punition. Upon the 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 punition 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 punition 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. However, this doesn't kick them out of the game however.

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).

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. This should be done in the init.txt file, before map cycling begins.

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.

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 [1, 0] (Default value is 1)
Determine if the server will be listed in the GameSpy Master Server list (1) or not (0). 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 [1, 0]
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  hamgemhigh
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.
bungie.org