bzfs

NAME

bzfs - BZFlag game server

SYNOPSIS

bzfs [-a velocity rotation] [-admsg message] [-autoTeam] [-b] [-badwords badwordfile] [-ban ip{,ip}*] [-banfile filename] [-c] [-conf configfile] [-cr] [-d] [-density num] [+f {good|bad|team||flag-id}[{count}]] [-f {good|bad|flag-id}] [-fb] [-filterCallsigns] [-filterChat] [-filterSimple] [-g] [-groupdb file] [-h] [-help] [-helpmsg file name] [-i interface] [-j] [-lagdrop warn-count] [-lagwarn time/ms] [-maxidle time/s] [-mp {count|[rogue-count],[red-count],[green-count],[blue-count],[purple-count],[observer-count]}] [-mps {max-score}] [-ms shots] [-mts {max-score}] [-p port] [-passdb file] [-passwd password] [-printscore] [-prohibitBots] [-public description] [-publicaddr address[:port] [-publiclist url] [-q] [+r] [-rabbit [score|killer|random] [-reportfile filename] [-reportpipe command] [-requireudp] [+s flag-count] [-s flag-count] [-sa] [-sb] [-sl id num] [-speedtol factor] [-srvmsg message] [-st time] [-sw count] [-synctime] [-t] [-tftimeout time-limit] [-time time-limit] [-timemanual] [-tk] [-tkkr percent] [-userdb file] [-vars file] [-version] [-vetoTime seconds] [-votePercentage percentage] [-votesRequired num] [-voteTime seconds] [-world world-file] [-worldsize world size]

DESCRIPTION

Bzfs is the server for BZFlag, and it must be running to play. It can be run on any system on the network (including a player's system or one without graphics). Terminating the server terminates the game in progress.

Options

-a velocity rotation: Enables inertia and sets the maximum linear and angular accelerations. The units are somewhat arbitrary so you'll have to experiment to find suitable values. The values must be non-negative and higher values yield greater inertia.
-admsg message: Define a message which will be broadcast to all players every 15 minutes.
-autoTeam: Automatically assign players to teams when they connect so that there are an equal number of players on all available teams. Players are placed on teams that have the fewest players, otherrwise they will be placed on the weakest team. Weakest team is the team with the lowest combined kill ratio.
-b: When -c is supplied, this option randomly rotates the buildings.
-badwords badwordfile: Specify a file that contains bad words that will be used when either -filterCallsigns or -filterChat is enabled.
-ban ip{,ip}*: Prohibits connections from the listed IP addresses. Trailing 255 bytes are treated as mask bytes.
-banfile filename: Specifies the name of a file where bzfs will store the banlist. It will load the banlist from this file when it starts (if the file exists), and write the banlist back to the file when someone gets banned or unbanned. If this option isn't given the banlist will not be saved.
-c: Enables the capture-the-flag style game. By default this allocates one team flag per team. This can be modified see +f team. By default, the free-for-all style is used.
-conf configfilename: Specifies the name of a configuration file to be used to set all of the bzfs options, rather than setting them on the command line.
-cr: Enables the capture-the-flag style game with random map. You can optionally specify a building density by providing an number (default is 5). One team flag per team is provided, but more can be added thru +f team. By default, the free-for-all style is used.
-d: Increase debugging level. More -d are used, more debugging info are obtained.
-density num: Specify density for buildings, i.e. the higher the integer number, the more buildings you will get. This applies to automatically generated maps only.
+f {good|bad|teamflag-id}[{count}]: Forces the existence of the given flag. If specified multiple times for the same flag-id, then that many flags will appear. The good argument is equivalent to specifying +f once for each kind of good flag. Same goes for the bad argument. The team argument adds a team flag to each team, assuming that the game style is capture the flag. The optional {count} parameter allows the specification of multiple flags of the same type. Note that the curly braces are required.
-f {good|bad|flag-id}: Disallows random flags of the given type. Required flags given by the +f option are still provided. The bad argument is equivalent to specifying -f once for each kind of bad flag. Same goes for good, but you probably do not want to do that.
-fb: Allow flags on box buildings.
-filterCallsigns: Turn on the filtering of callsigns and email addresses. Callsigns and addresses are compared against bad words provided via -badwords.
-filterChat: Turn on the filtering of chat messages. Messages have words provided via a -badwords file are replaced with !@#$%^&* characters.
-filterSimple: By default, all filtering is aggressive, matching much more than what is strictly listed in a -badwords file for convenience. Providing this option will make the -filterCallsigns and -filterChat comparisons exact match only.
-g: Quit after serving one game.
-groupdb file: Load groups from file
-h: Buildings are given random heights.
-help: Shows a help page and lists all the valid flag id's.
-helpmsg file name: Create a help message accessible by /help name, which prints the contents of file. Restricted to 10 lines per help message.
-i interface: Server will listen for and respond to ``pings'' (sent via multicast) on the given interface. The server uses the first multicast enabled interface by default. Clients use this to find active servers on the network. This is also the TCP/UDP/IP address the server will listen on.
-j: Allows jumping.
-lagdrop warn-count: Kicks players after warn-count lag warnings.
-lagwarn time/ms: Send warnings to players that lag more than time.
-maxidle time/s: Kick players that did not play longer than time seconds. Pausing players are not kicked. If a player uttered a word recently, he will be kicked after thrice the given time.
-mp {count|[rogue],[red],[green],[blue],[purple],[observer]}: Sets the maximum number of players, total or per team. A single value sets the total number of players allowed. Five comma separated values set the maximum for each team. If a count is left blank then no limit is set for that team, except for the limit on the total number of players. Both forms may be provided.
-mps max-score: Sets a maximum score for individual players. The first player to reach this score is declared the winner and the game is over.
-ms shots: Allows up to shots simultaneous shots for each player. This is 1 by default.
-mts max-score: Sets a maximum score for teams. The first team to reach this score is declared the winner and the game is over.
-p port: Listen for game connections on port instead of the default port. Use -help to print the default port, or use -d debug printing.
-passdb file: Load passwords from file
-passwd password: Specify a server administrator password for use in remote administration such as /kick messages.
-printscore: Write score to stdout whenever it changes
-prohibitBots: Disallow clients from using the ROGER autopilot or from using robots.
-public description: Advertise this server on the internet with the given description. By default, a server will respond to broadcast or multicast queries, allowing clients to find servers on the local subnet or accessible through multicast routers. However, this doesn't allow clients to find servers not accessible via multicast. The -public option causes the server to register itself with a bzfls server, which clients can query to get a list of bzfs servers.
-publicaddr address[:port]: Advertise this server with the given address and port. Only has an effect when used with -public. Normally a server advertises itself at the local address and port. Some servers are not accessible from the internet at this address (for example servers behind a firewall using bzfrelay). Use this option to specify the address and/or port that internet users should use to access this server.
-publiclist url: Advertise this server on the bzfls servers listed at url. Only has an effect when used with -public. A built-in url is used by default. The BZFlag clients use the same built-in url so, by default, clients will see public servers automatically. See bzfls for a description of the format of url.
-q: If specified, the server will not listen for nor respond to ``pings''. BZFlag sends out these pings to give the user a list of available servers. This effectively makes the server private, especially if the -p option is also used.
+r: Makes most shots ricochet. Super bullets, shock waves, and guided missiles do not.
-rabbit [score|killer|random]: Enables the rabbit-hunt style game. By default, the free-for-all style is used. You must specify the algorithm used to pick a new rabbit when the old one dies. The score algorithm uses a modified wins/(wins+losses) score and picks the top scoring player to be the new rabbit. The killer algorithm specifies a reverse tag game where whoever kills the rabbit becomes the new rabbit. The random algorithm randomly picks a new rabbit without regard to score. (The score algorithm is the original behavior.)
-reportfile filename: Write messages to the server admin written using the /report command to this file. If neither -reportfile or -reportpipe is used the /report command will be disabled.
-reportpipe command: Pipe messages to the server admin written using the /report command to this program or shell command. See -reportfile.
-requireudp: Require clients to use parallel UDP. If players fire before opening a UDP channel, kick them off the server.
+s num-flags: The server will have an extra num-flags random super flags available at all times. The -f option can be used to restrict which types of flags will be added. Required flags given by the +f option are not included in the num-flags total.
-s num-flags: The server will have up to num-flags random super flags available at any time. The -f option can be used to restrict which types of flags will be added. Required flags given by the +f option are not included in the num-flags total.
-sa: Antidote flags are provided for players with bad flags.
-sb: Allow spawns on box buildings.
-sl id num: Restrict flag id to num shots.
-speedtol factor: Override the default speed auto kick factor. The factor should not be less then 1.0. The factor is a multiplier.
-srvmsg message: Define a server welcome message.
-st time: Bad flags are automatically dropped after time seconds.
-sw count: Bad flags are automatically dropped after count wins. Capturing a team flag does not count as a win.
-synctime: Forces all clients to use the same time of day. The current time is determined by the server's clock. This disables the + and - keys on the clients.
-t: Adds teleporters to the game.
-tftimeout time-limit: If the last player in a team leaves while someone else is carrying the team flag, the team flag will not reset until it is captured, or until the player drops it and it is left alone for some time. This option specifies the number of seconds that the flag should be left alone before it is reset. The default value is 30.
-time time-limit: Sets a time limit on the game to time-limit. The game will be stopped time-limit seconds after the first player connects.
-timemanual: When using -time, the countdown will start when the first player joins. With -timemanual, the countdown has to be started manually using the /countdown command. This is useful for matches.
-tk: Changes the default behaviour where a player dies when he kills a teammate. When using this option, he will just get a -1 score penalty for the kill but stay alive.
-tkkr percent: Kicks players whose team killing to normal kill ratio is greater than percent [1-100]. A start up grace period is given to players.
-userdb file: Load group associations from file
-vars file: Loads values for game configurable variables from file. Entries are one per line in the form: set variable value. For a list of variables that are configurable, in the the BZFlag client, send a message with /set as the text.
-version: Prints the version number of the executable.
-vetoTime seconds: Length of time in which a vote can be vetoed
-votePercentage percentage: The percentage of yes votes needed in order for the vote to be successful
-votesRequired num: The number of voters needed to hold a vote
-voteTime seconds: The length of time the players are able to vote
-world world-file: Reads a specific world layout for the game map.
-worldsize world-size: changes the size for random maps

Notes

The server uses nearly zero CPU time when nobody is playing, and even during a game the server uses very little CPU, so it's not a burden on the system to leave one running and it won't interfere with a player using the same system (except on Windows 95, which really sucks at multitasking). The server will continue to run until terminated. If a game is in progress when the server goes down, all players will be kicked off and the game will be aborted without warning. The server resets itself when all players have quit. All players must quit to reset the server when a game is over (because of a score or time limit).

The following game styles are recommended starting points.

-c [-b]: Basic capture-the-flag game. It teaches teamwork and dogfighting skills.
-s -t: Free-for-all with superflags and teleporters. Teaches players how to use superflags and teleporters for maximum effect. You may want to allow players to drop bad flags with any of -sa, -st, and -sw.

Notice that the maximum number of shots for these styles is one. Having only one shot greatly increases playability and learning speed. Multiple shots decrease the required skill level and make it virtually impossible for even a skilled player to avoid getting shot for any length of time. More experienced players will still dominate the game, but beginners will have an easier time making kills.

Networking

Communication between the server and clients (i.e. between bzfs and bzflag) during a game is via TCP and UDP. Use the -help option to get the server's default port. If there's a firewall between the server and client, the firewall must accept connections from the client to this port and forward them to the server. See bzfrelay for a BZFlag firewall relay.

Clients can search for servers by sending broadcast UDP packets. But they must be on the same local area network for this to work. Clients can also find servers advertised using -public by querying bzfls servers.

Game information is relayed through the server. Some communication between clients, such as position and orientation information, is normally sent via UDP packets. Other data, like flag grab and kill messages, are sent to the server via TCP. The server then turns around and broadcasts these packets to all players. Since being in a game implies connection to the server, all players are guaranteed to get all messages sent via TCP. But the UDP packets may be discarded. If other players can see your tank in the game but it never appears to move and shots go through it, chances are high that your UDP connection is not working.

GENERAL SERVER COMMANDS

/lagstats Lists network delays, jitter and number of lost resp. out of order packets by player. Example:

MrApathyCream 335 +- 10ms
Gerbol 210 +- 3ms
captain_macgyver 155 +- 0ms  12% lost/ooo

/idlestats
Displays the idle time in seconds for each player. A player is idle when
he is dead.

MrApathyCream: 0s
Gerbol: 80s
captain_macgyver: 13s

/flaghistory
Lists what flags players have grabbed in the past. Example:
MrApathyCream: (<-) (->) (O) (CB) (M) (B) (JM) (WA)
Gerbol: (L) (GM) (L) (GM) (CL) (ST) (GM) (L)
captain_macgyver: (SB) (SW)

/password {password}
Attempt to gain administrator status Example:
/password supersecretpassword
You are now an administrator!

/report {message}
Write a message to the server administrator. Example:
/report I like this map!

SERVER ADMINISTRATIVE COMMANDS

/shutdownserver

Stop serving BZFlag on this server

/superkill

Kick all players off the server

/gameover

Ends the current game

/flag reset {unused}

Repositions flags. If unused is specified, flags carried by tanks are not effected.

/flag up

Removes all flags from the game

/flag show

Shows all flags with information Example:

0: p:-1 r:1 g:1 1:V s:1 p:159.1x43.2x0.0
1: p:2 r:1 g:1 1:SW s:1 p:209.1x143.2x10.0
2: p:-1 r:1 g:3 1:L s:1 p:-29.1x301.2x0.0

/kick {playerName}
Kick a named player off the server.Example:
/kick Gerbol
You were kicked off the server by MrApathyCream

/playerlist
List player names and IP addresses. Example:
/playerlist
[0]MrApathyCream: 35.23.65.44:4808 udp id
[1]Gerbol: 130.123.1.55:4909 udp id
[2]captain_macgyver: 15.32.122.51:3201 udp id

/ban {ipList} {duration} {reason}

Ban players using the specified IPs for certain length of time from using this server. Example:
/ban 35.23.43.66 2 cheating
bans player with specific ip for 2 minutes
/ban 35.23.*.*,47.23.17.*
bans all ips in this range forever
/ban 36.37.2.8 2h30m "ShootMe" was abusing players
bans specific ip for 2.5 hours with given reason

/banlist
List all of the IPs currently banned from this server. Example:
/banlist
IP Ban List
------------
35.23.43.66
47.23.17.*

/hostban {hostpat} {duration} {reason}

Ban players using the specified hostnames for a certain length of time from using this server. Example:

/hostban *.foo.com 2 cheating
bans all players from foo.com for 2 minutes

Note: Bzfs must be compiled to use the ADNS asynchronous resolver library in order for this feature to work.

/hostbanlist
List all of the host patterns currently banned from this server.
/countdown
Starts the countdown sequence for a timed game. Example:

/countdown

/lagwarn

Dynamic change the maximum allowed lag time. Example:

/lagwarn 300

USER MANAGEMENT

Generally, you start with empty files for the user and password databases. These are maintained by the server, and modifiable through server commands. You will want to specify a groups file that has whatever specific groups you care to have on your server. These are laid out with one line in the file per group, using the following format:

GROUP_NAME: perm1 perm2 perm3 ... permN

Group names cannot have spaces, quotes, or other special characters in them.

This would be a sample line defining a "cop" group:

COPS:KICK BAN BANLIST UNBAN INFO

The server will automatically create three groups if they are not specified in the groups file: DEFAULT, REGISTERED, and ADMIN. ADMIN has every permission possible (similar to granting admin powers via /password). REGISTERED presently allows access to the voting system's /poll and /vote commands. DEFAULT allows /lagstats, /idlestats, /flaghistory and /report.

Once the server is running, users can register their callsigns and admins can set their group memberships. Users can use any command that their permissions allow. Every user, registered or not, is part of the DEFAULT group. When a user identifies, they become part of the REGISTERED group.

The available permissions are as follows:

IDLESTATS /idlestats
LAGSTATS /lagstats
FLAGMOD /flag
FLAGHISTORY /flaghistory
LAGWARN /lagwarn
KICK /kick
BAN /ban /hostban
BANLIST /banlist /hostbanlist
UNBAN /unban /hostunban
COUNTDOWN /countdown
ENDGAME /endgame
SETVAR                 /set /reset

SHUTDOWNSERVER /shutdownserver
SUPERKILL /superkill
PLAYERLIST /playerlist
INFO not implemented
LISTPERMS not implemented
SHOWOTHERS not implemented
REMOVEPERMS /removegroup
SETPERMS /setgroup
SETALL use of all set/remove commands
SETPASSWORD not implemented
POLL                   /poll ban|kick

VOTE                   /vote

VETO                   /veto

REQUIREIDENTIFY user must /identify when using this callsign

/register {password}

Register your current callsign to the specified password. Passwords must be at least 3 characters long, and the callsign may not contain quotes or other non-alphanumeric/space characters

/identify {password}

/setpass {password}

Changes your password

/ghost {callsign} {password}

Kicks off an impersonating player or ghost

/grouplist

Lists the available user groups

/groupperms

Lists the permissions for each group

/showgroup {callsign}

Lists the groups that a registered user is a member of

/setgroup {callsign} {group}

Add a user to a group

/removegroup {callsign} {group}

Remove a user from a group

/reload

Reloads the user, group, and password files (for synchronization between multiple servers on the same machine)

/deregister [callsign]

With an argument, it deregisters another user's callsign. Without, it removes your own registration.

/poll ban|kick|vote|veto [...]

Interact and make requests of the bzflag voting system via the /poll command. The ban and kick subcommands request a vote to respectively ban or kick some player. The playername is expected as the next argument. The vote and veto commands behave identical to the /vote and /veto command counterparts, expecting the same arguments in following. By default, you must be registered to request and vote on a poll.

/vote yes|no

If there is a poll active, this command will place a vote in favor or in opposition to the poll. Multiple languages are supported as a vote argument in addition to "yes" and "no". By default, you must be registered to vote on a poll.

/veto

If there is a poll active, this will cancel the poll. By default, you must be an admin to veto a poll.

WORLDS

BZFlag worlds come in two varieties, randomly generated ones, and human designed ones. By default, bzfs uses randomly generated world unless you specify the -world command line or configuration file option. The world file specified by the -world option is a text based file that contains a list of world objects. This file can be created using programs found on sourceforge.net through cvs, or can be hand edited.

The format of this text file consists of any number of objects listed in any order. The list of world types consists of

Each object is described by placing the type on one line, the word end on a following line, and a list of attributes for that object, one per line, inbetween. Attributes may be listed in any order. Attributes have default values, and if that is good enough, the attribute need not be listed. Words are always specified in lowercase. Line comments can be specified by placing a # sign at the start of the line. For documentation purposes, you can tag each object by adding a name attribute. There is set limit to the number of times you may use box, pyramid, teleporter, link, base and weapon objects. You must only supply one world object at most.

In the following examples, the values are the defaults.

The Box object

box
name example_box
position 0.0 0.0 0.0
size 30.0 30.0 9.42
rotation 0.0
end

The Pyramid object

pyramid
name example_pyramid
position 0.0 0.0 0.0
size 8.2 8.2 10.25
rotation 0.0
end

The Teleporter object

teleporter
name example_teleporter
position 0.0 0.0 0.0
size 5.06 4.48 20.16
rotation 0.0
border 1.12
end

The Link object

link
name example_link
from 0
to 0
end

The Base object

base
name example_base
position 0.0 0.0 0.0
size 60.0 60.0 0.0
rotation 0.0
color 0
end

The World object

world
name example_world
size 800.0
flagHeight 0.0
end

The Weapon object

weapon
name example_weapon
position 0.0 0.0 0.0
rotation 0.0
initdelay 10.0
delay 10.0 3.0 5.0 3.0
type V
end

Index

NAME

SYNOPSIS

DESCRIPTION

Options
Notes
Networking

GENERAL SERVER COMMANDS

SERVER ADMINISTRATIVE COMMANDS

USER MANAGEMENT

WORLDS

SEE ALSO