BZFlagWiki - User contributions [en]

Talk:Quick keys

2012-03-22T06:05:14Z

Flash: Talk is good, but this page is questionable

I question the value of

# default mappings. Because they are easily customizable, players who use quick keys are most likely to set them in a way that works for their style of play. Since there are as many styles as there are players (or more) it will be very hard to come up with the "right" set of defaults.
# these mappings. These messages seem more appropriate to individual players than to team or all. Why would you tell the world "Thanks" or "Geno gone".

Compiling

2008-07-23T01:27:37Z

Flash: Added some real XCode content

==Overview==
Compiling BZFlag is the act of taking the raw source codes for the game and using tools to build an executable application(s) for a target system.

==Source Code==
In order to compile a user must have his or her own copy of the [[BZFlag_Source|Source Code]]. The code can be obtained from a source archive from the [[Download]] page, or from the [[BZFlag_SVN]] server.

==Readme Files==
Users should always read the README files for the appropriate operating system. These files are located in the root directory of the source code tree.

==Compilers==
BZFlag is capable of being built on a number of compilers. The compiler used will depend in some way on the operating system of the computer doing the build.

Linux computers, use the GCC compiler.
Macintosh Computers use the XCode compiler
Windows Computers can use the Visual C++ compiler, or the MinGW compiler (based on GCC)

===GCC===
The GCC build as a number of requirements;
* Automake X.XX
* Autoconf X.XX
* Autotools X.XX
* SDL Development libraries 1.2.10 or greater
* OpenGL Development libraries 1.1 or greater

If the required dependencies are installed, the user must then run the following commands from at root level of the source tree

./autogen.sh
./configure
./make
./make install

Please note that depending on permissions levels the '''make install''' command may need to be run as an administrator or root.

===XCode===
Launch XCode and open the '''bzflag/BZFlag.xcodeproj''' project. Note that XCode should have '''BZFlag''' selected as the active target and '''Development''' as the active build configuration. Click on '''Targets''' then click the '''Build''' icon. When this process completes, your application will be in '''bzflag/build/Development'''. You can then move it wherever you like.

===Visual C++===

==== 2.0.x ====

==== 2.99.x =====

===Other build systems===
Other build systems may be supported in the various readme files (minGW, IRIX, SOLARIS,etc..)

[[Category:Development]]
[[Category:Compiling]]

Talk:Sample conf

2008-05-19T04:33:33Z

Flash: Recommend removing redundant page.

This page would seem to be redundant with [[BZFS_Command_Line_Options]]. The latter page is more useful, in my opinion. If this page is to be retained, perhaps it should just point to the sample conf that is distributed with the game.
--[[User:Flash|Flash]] 00:33, 19 May 2008 (EDT)

BZFS API

2008-05-02T18:39:28Z

Flash: fixed typos

{{DoDoc|fill in articles for all API functions}}

The BZFS API (Application Programmers Interface) is a set of C++ functions, structures, and classes that is exported by [[BZFS]] to be used by [[Plug-ins]]. The API provides access to the various states and data structures of a running BZFS game and is the primary method of communication between a plug-in and the game server.

==Overview==
The BZFS API is defined entirely in the '''bzfsAPI.h''' header file that is part of the [[BZFlag Source]] code. The header is also included with each install of the BZFlag installer for Microsoft Windows.

Plug-ins include this file in their source code so that they may access the functions it contains.

==Naming Conventions==
All BZFS API code structures will begin with the prefix '''bz_''' for clarification and to prevent conflicts with names of code structures inside BZFS or any plug-ins.

==API Versions==
The API was added in version 2.0.4 of BZFlag. While working well for many users, it was found to be lacking in a number of features that would make make it difficult for plug-ins to run when the API itself was changed.

As of version 2.1 of BZFlag, the entire API was versioned and set up to use derived classes to that plug-ins written to use an older version of the API will work in newer versions of the software. Newer data structures would be put into further derived classes and would not be seen by the older plug-in. Due to this change a large number of API functions changed in name. This change causes all older 2.0.x plug-ins to no longer work with out a source code change. Once older plug-ins are updated to the new 2.1 API they will use the new versioning system and work fine in newer versions with out any needed changes.

==Entry Points==
There are 3 primary entry points into each plug-in. These entry points are the 3 core functions that every plug-in must implement.

BZF_PLUGIN_CALL int [[bz_Load]] ( const char* command );
BZF_PLUGIN_CALL int [[bz_Unload]] ( void );
BZF_PLUGIN_CALL int [[bz_GetVersion]] ( void );

[[bz_Load]] is called when the plug-in is first initialized. This is when the plug-in should register any [[Event(API)|event handlers]] needed and initialize any "one time" startup data.

[[bz_Unload]] is called when a plug-in is no longer needed and will be shut down. This is most commonly called when bzfs is shutting down, or when a plug-in is unloaded manualy.

[[bz_GetVersion]] is called by bzfs before any other functions are called. The function should return the version of the API that it is written for. This is to prevent bzfs from attempting to load plug-ins that use a newer incompatible API.

'''bzfsAPI.h''' defines a C MACRO to help ease the implementation of this function. All a plug-in must do is put the macro;

BZ_GET_PLUGIN_VERSION

somewhere in its sources, and then export the function. This will automatically return the API version of the current API you are using. See the sample plug-ins for examples. These will be the only 3 functions called by bzfs for non-event actions.

All entry point functions should be preceded with the BZF_PLUGIN_CALL macro. This macro will tell your compiler to export these functions so bzfs can call them after the plug-in is loaded.

==Types==

Due to how Microsoft Windows handles memory access between an application and dynamically loaded Libaries(DLLs), there are a few custom data types that are used in the API. These are used for common STL style containers, for strings and lists.

===bz_ApiString===
Any text passed back from the API or events will come in the form of a [[bz_ApiString]]. This is a class defined in the API that behaves much like a std::string. The 'c_str()' method can be used to get the text out as a normal 'const char*'. The class also supports many assignment functions for setting it's contents.

A plug-in should never need to make variables of its' own using the [[bz_ApiString]] type, but should use a standard stl std::string instead, [[bz_ApiString]] provides an appropriate assignment operator.

[[bz_ApiString]] also includes some utility functions such as replace all and tokenize that are commonly needed by plug-ins.

===bz_APILists===

A few API functions require lists of integers, strings, or floats. For these functions the plug-in will need to use one of the following list classes. These classes are similar to the std::vector in implementation. When a plug-in needs to allocate one of these lists, it must use the appropriate allocator function, so BZFS can make a new list for the plug-in to use. These will return a pointer to a new list for the plug-in to use. When the plug-in is finished with the list, it needs to tell BZFS to delete the list with a call to the appropriate delete function.
The lists types are;
{| border="1" cellpadding="20" cellspacing="0"
!List
!allocator function
!delete function
!contained type
|-
|[[bz_APIIntList]]
|[[bz_newIntList]]
|[[bz_deleteIntList]]
|int
|-
|[[bz_APIFloatList]]
|[[bz_newFloatList]]
|[[bz_deleteFloatList]]
|float
|-
|[[bz_APIStringList]]
|[[bz_newStringList]]
|[[bz_deleteStringList]]
|[[bz_ApiString]]
|}

===Enumerations===
A number of enumerations exist in the API and are used by a number of API functions and events.
[[bz_eTeamType]]
[[Event(API)|bz_eEventType]]
[[bz_eShotType]]
[[bz_eGameType]]
[[bz_ePlayerStatus]]
[[bz_eWorldObjectType]]
[[bz_eAPIColType]]
[[bz_ePlayerType]]
[[bz_eRejectCodes]]
[[bz_ePlayerDeathReason]]

==Events==
Plug-ins can register callbacks so they can be notified of various actions and state changes in the current BZFS game. These events tell a plug-in when important things happen, such as when a player has spawned, or is killed. These events are the primary form of communication from the BZFS server into the plug-in.

See the [[Event(API)|API events]] page for more detailed information on events.

==Functions==
The BZFS API provides a number of functions to plug-ins for use in querying the current game state. Functions are used both to get information about the game, and to trigger in game actions, such as activating a world weapon.

See the [[Functions(API)|API Functions]] page for more information on functions.

==Wiki Documnetation==
The documentation for the API provided on this wiki is mostly concerned with the current development version of the software. There have been changes over time to the API. Any changes to classes and functions will be noted in the new documentation under a ''History'' section. In general the initial API that was released with the 2.0.x product line was not consistent, and many of these inconsistencies are being worked out with newer versions of the API (3.0 and later)

All API developers should use the bzfsAPI.h file as well for exact spellings of methods and parameters.

==See Also==

[[Event(API)|API Events]]

[[Functions(API)|API Functions]]

[[Plug-ins]]

[[BZFS]]

[[Category:Development]]
[[Category:Plug-Ins]]

Talk:Builds List

2008-04-25T04:37:34Z

Flash: Nuke this page

Is there really any benefit to this page? Every time a new release comes out, all the clever titles for the following sections need to be updated. For example, 2.0.10 is now released, so the "unstable" tag no longer applies. I'd vote to remove this page.--[[User:Flash|Flash]] 00:37, 25 April 2008 (EDT)

BZFS Command Line Options

2008-04-24T21:19:38Z

Flash: add concept of "include" conf files

BZFS supports a number of command line options that let you set the various modes and parameters for the game.

==Use==
Any command line option can be passed to BZFS in the command line, or placed in a text file passed in with the -conf parameter.

==Config files==
A [[Sample conf|config file]] is simply a text file with a list of command line options, one per line. This file can be the parameter to the -conf command line option. BZFS will load all options in the config file as if they had been passed in as runtime options. Note that a config file may itself include the -conf option, allowing one config file to "include" another. This could be useful if a group of servers (hosted on the same machine) want to share common settings.

==The Options==

*'''-a''' ''linear angular''
Sets the maximum linear and angular accelerations. The units are somewhat arbitrary so you'll have to experiment to find suitable values. Positive values will set limits to the acceleration and lower they are, greater is the inertia. Zero or negative values disable acceleration limits. '''-a 50 38''' is recommended for standard-speed servers.

*'''-admsg''' ''message''
Define a message which will be broadcast to all players every 15 minutes. This option can be used multiple times to define a multi-line message.

*'''-advertise''' ''groupname,groupname,...''
Allows control of who can see this server on the server list. Use -advertise NONE to make a private server (no one will see the server, but global logins can be used). The default, if -advertise is not specified, is to allow everyone to see the server. Otherwise, your server will only be listed to members of the groups which you specify with -advertise.

*'''-autoTeam'''
Instructs the server to automatically assign joining players to the team that needs more players, overriding user preference. For specifics on operation, see [[Auto Team]].

*'''-b'''
When -c is supplied, this option randomly rotates the buildings.

*'''-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.

*'''-banTime'''
Default number of minutes player should be banned (unspecified, the default is 300).

*'''-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.

*'''-cache''' ''worldCacheURL''
Specifies the URL for the world cache file. This is a binary file that clients will attempt to download before getting the world from the bzfs server.

*'''-cacheout''' ''filename''
Save the currently specified world into a binary cache file and exit.

*'''-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 a number (default is 5). One team flag per team is provided, but more can be added through '''+f''' ''team''. By default, the free-for-all style is used.

*'''-d'''
Increase debugging level. If more '''-d''' is given, more debugging info is 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.

*'''-disableBots'''
Prevent clients from using the ROGER autopilot or from using robots.

*'''+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 teamflag-id must match one of the predefined [[FlagCode|Flag Codes]].

*'''-f''' ''{flag-id}''
Restricts a certain flag from existing.

*'''-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 that contain words listed 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.

*'''-handicap'''
Players are given a handicap advantage based on their ability in relation to the other players. Handicapped players will have faster tanks and shots. The handicap is determined by the player's score in relation to other players.

*'''-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 broadcast) on the given interface. Clients use this to find active servers on the network. This is 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.

*'''-loadplugin''' ''/filename''
[[http://my.bzflag.org/w/Plugins]]

*'''-mp''' ''total | 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.

*'''-noMasterBanlist'''
Server will not attempt to load the [[Master Ban]] list from the internet.

*'''-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, /ban, /mute, etc messages.

*'''-pidfile''' ''filename''
Specify a file where the server will write its process ID so it may be used for remote administration.

*'''-poll''' ''variable=value''
Configure several aspects of the in-game polling system.

*'''-public'''
Causes the server to register itself with a list server, which clients can query to get a list of bzfs servers. By default, a server will respond to broadcast queries, allowing clients to find servers running on the standard port on the local subnet.

*'''-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 Network Address Translation). 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 list 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. This argument may be provided multiple times to publicize a server to multiple list servers.

*'''-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 whomever 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.)

*'''-recbuf''' ''size''
Start with the recording buffer active, with the specified size (in megabytes).

*'''-recbufonly'''
Disable recording straight to files

*'''-recdir''' ''directory''
Specify the directory for record and replay files.

*'''-replay'''
Start the server in replay mode.

*'''-reportfile''' ''filename''
Enable the /report command and log all reports to ''filename''.

*'''-reportpipe''' ''command''
Enable the /report command and execute ''command'' when a report is filed. This can be used together with, or instead of the '''-reportfile''' option.

*'''-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.

*'''-set''' ''name value''
Set BZDB variable name to value

*'''-sl''' ''id num''
Restrict flag id to num shots.

*'''-spamtime''' ''time''
Minimum ''time'' between player chat messages that are alike.

*'''-spamwarn''' ''warnLimit''
Number of warnings a player/spammer gets, who violates '''-spamtime'''.

*'''-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. This option can be used multiple times to define a multiline 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.T he current time is determined by the server's clock. This disables the + and - keys on the clients.

*'''-t'''
Adds teleporters to the game.

*'''-timemanual'''
The countdown has to be started manually using the /countdown command. This is useful for matches.

*'''-tk'''
Changes the default behavior 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 not be killed in game.

*'''-tkannounce'''
Announces team kills to the admin channel

*'''-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.

*'''-ts''' ''[micros]''
Include timestamp information in DEBUG output useful for logging. If micros is specified, microseconds will be added to the timestamp.

*'''-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 BZFlag client, send a message with /set as the text.

*'''-version'''
Prints the version number of the executable.

*'''-vetoTime'''
Max seconds authorized user has to abort poll(default is 20).

*'''-votePercentage'''
Percentage of players required to affirm a poll (unspecified, the default is 50.1%).

*'''-voteRepeatTime'''
Minimum seconds required before a player may repeat a vote.

*'''-world''' ''world-file''
Reads a specific BZFlag .bzw world file in [[BZW]] format as the game map.

*'''-worldsize''' ''world-size''
Changes the size for random maps

==See also==
[[BZW|BZW world format]]

[[Category:Server]]

BZFlag on IRC

2008-04-24T12:56:00Z

Flash:

The BZFlag communities use the [http://freenode.net/ freenode IRC network] for communication and collaboration. [http://en.wikipedia.org/wiki/IRC IRC]

The [http://freenode.net/ freenode network] is used for all IRC communications.
Common channels include:
* [irc://irc.freenode.net/#bzflag #bzflag]
* [irc://irc.freenode.net/#bzchat #bzchat]

A web interface is provided to these channels at http://my.BZFlag.org/irc/irc.cgi
==Channels==

===#bzflag===
The #bzflag channel is the primary development and support channel. The major developers and many long time community members are users. Discussions in the channel range from development and coding discussions to technical support and bug reports. #bzflag is a great channel to discuss new features and bugs. The channel is moderated by the project administration and development staff. '''This channel is not for help with specific servers or administration issues'''

===#bzchat===
The #bzchat channel is a more informal channel designated for player community discussions.

===Other channels===
A number of players, servers, and [[leagues]] have their own channel for more focused discussion, some of these include:

* ##bar (DUCLeague team, The Barbarians)
* #BoomBZ (Team Channel for GU team [BoOm])
* ##bz-inc (DUCLeague team, [http://my.bzflag.org/league/index.php?link=teaminfo&id=689/ Bz-Incorporated])
* ##bzflagr (Support channel for the [http://bzflagr.net BZFlagr.net servers.])
* #bzfx (Support channel for the bzfx.net BZFlag servers)
* ##bzpod (Channel to discuss the BZFlag podcast, BZPod)
* ##bzw (A place to discuss map making for BZFlag, including ideas and help)
* #divi (Support channel for [http://divi.fairserve.net Divibox] and other [http://fairserve.bzflag.org Fairserve] servers)
* #dub (Support channel for the dub.bzflag.org BZFlag servers)
* ##ducleague (Support channel for [http://my.bzflag.org/league/ Ducati League (DucLeague)])
* #forestforce ([http://gu.bzleague.com/index.php?link=teaminfo&id=10 GULeague Team])
* ##guleague (Support channel for [http://gu.bzleague.com/ GamesUnited League (GULeague)])
* #hepcat (Support channel for borrego.hepcat.org BZFlag server) ''defunct''
* ##icf (Support channel for [http://gu.bzleague.com/index.php?link=teaminfo&id=112 Incredible Chipper Frogs, (GULeague)])
* #inleague (Support channel for [http://in.bzleague.com InterNational League (INLeague)])
* #kas (GULeague team, KAS)
* ##norang (Support channel for [http://bzflag.norang.ca Norang.ca] BZFlag servers)
* #pillbox (Support channel for [http://pillbox.bzleague.com/ Pillbox League (PBLeague)])
* ##planetmofo (Support channel for [http://www.planet-mofo.com planet-mofo.com] servers)
* #plosileague (Support channel for [http://bzfx.net/league/ Plosileague])
* #silvercat (Support channel for [http://silvercat.bzflag.org/ Silvercat BZFlag servers]) ''defunct''
* ##t42 ([http://gu.bzleague.com/index.php?link=teaminfo&id=39 GULeague team])
* ##untamed ([http://my.bzflag.org/league/index.php?link=teaminfo&id=909 DUCLeague team])

==IRC Clients==
To access the IRC network you need to use an IRC client, there are many IRC client softwares available for most operating systems.

http://irchelp.org/ is an excellent resource for more information on general IRC.

===Web IRC Interface===
The project provides a [http://my.BZFlag.org/irc/irc.cgi web based interface] to the main IRC channels. These are intended mostly for tech support issues, and the web interface is limited in the number of channels it can access.

==External links==
http://my.BZFlag.org/irc/irc.cgi

http://irchelp.org/

[[Category:Development]]
[[Category:Support]]

Creating a server

2008-04-18T05:20:11Z

Flash: /* Configure your Server */

Creating a server is the process of using [[BZFS]] software to host a game for users to play on.

==Overview==
Running a server can be done in both [[public]] or [[private]] modes. It involves running the server software [[BZFS]] on some host computer. For [[public]] servers this host computer must be connected to the internet, and be able to accept incoming connections on a fixed port.

== Planning a Server ==

Before you create a server, you need to decide what you want your server will be like. There are a few requirements in creating a server. First, you need a good connection. BZFS servers are usually on fast connections. On a 56k in the US, you can probably host up to 3 players under bearable latency. In other countries on a 56k, you can probably host up to 8 or so. This is due to more stricter and demanding interference restrictions in the US. If you are on a high end DSL or higher connection, you need not worry what country you are in since your connection is fast enough to handle many players. With really fast connections, such as T1 or related, you could host dozens (although you may not want to do so).

You must provide an address to connect to. You will specify this address when you run the server (more on this below). The address may be your IP address (something like 192.12.193.123), or the domain name pointing to your computer (e.g. BZFlag.ducati.org). If your server is going to be on a machine that is connected via DSL or Cable, figure out if your provider is giving you a dynamic or a static IP. If the IP address is static, your life will be a little easier since you can specify that address once and forever. If the IP is dynamic, this means that your internet provider will change the address once in a while (without warning). In this case you probably want to "[[Alias Your IP Address]]" to a static name (click on the link for how to).

Next you need to have an idea of how your server is going to look: you are probably already familiar with the game style (CTF, Rabbit) from playing on existing servers. You may specify a map or ask your server to create a random one. You will also be able to specify many details of the game play (how many good and bad flags, jumping, ricochet, etc...). All of this is accomplished in the next step.

== Configure your Server ==

In this step, you specify all the server options. The cleanest way to accomplish this is to create a configuration file. Fortunately, the BZFlag installation provides you with a sample configuration file that you can modify according to your wishes. You will find this file in the directory where you installed BZFlag under a subdirectory called <code>misc</code>. The file is named <code>bzfs.conf</code>. Open <code>bzfs.conf</code> in a text editor (in windows, notepad will be just fine; in GNU/Linux, Unix, Debian, etc.. : vi would work nice).

Read through <code>bzfs.conf</code> to understand all the options. Remove the # sign on the lines corresponding to the options you want to set. Add # at the beginning of the line if you don't want that option. After you have finished your changes, you can save that file with a different name (this will be helpful if you want to run server with different configurations: just save many files with different names).

Note also that recent BZFlag installations come with a "nice" web-based configuration builder that lets you create a configuration using a simple web form. Run it by selecting "BZFS configuration builder" from the BZFlag folder in the start menu. Your web browser will pop up with a web form that will prompt you for several configuration choices. Please note that the form will not save the configuration file for you: you will still have to copy and paste the text generated by the web form into your configuration file.

Here is an incomplete list of things you must or can specify in the configuration file.

* Choose a password for administrative purposes. With this password, you can use the administrative operations, such as changing the lag kick threshold or setting environment variables. This is done by adding the following line to your configuration : <code>-passwd PASS</code> (replacing PASS with a password of your choice). Once the server is running, run your client and login as an administrator by entering "<code>/password PASS</code>" (without quotes "") as a chat message.
* If the server is to be public, you must specify the server people should connect to. The option is added with the following line "<code>-publicaddr server.name.com:5154</code>" (without quotes), or "<code>-publicaddr 111.111.111.111:5154</code>" where you should replace <code>111.111.111.111:5154</code> with your IP address. <code>5154</code> is the port the server will listen to. Make sure it is the same number as the one specified in a line starting with <code>-p 5154</code>. You can change the port but don't do that if you don't know what you are doing. We recommend you use port numbers that are proven to work in other servers.
* Specify other options. For example, if you want to allow jumping, then your conf file should have a line starting with <code>-j</code>. Other options are: ricochet, which needs a line starting with <code>+r</code>. Read through <code>bzfs.conf</code> and you'll find out how to specify the game style (rabbit, ctf, etc...), the number of flags, etc.... If you want to run different configurations you can create as many conf files as you like (with different names of course). Just specify the correct configuration file you want to invoke in the bat file mentioned in the previous paragraph. One of the options that you can set in the configuration file is a map the server should use.
* You can choose whether to use a custom map or a random one. If you use a random one, decide whether or not to include teleporters. If you want to include them, add (again, to your configuration) the option "<code>-t</code>". If you are playing CTF and you want a random map, use "<code>-cr</code>" instead of standard "<code>-c</code>", in addition to "<code>-t</code>". For a custom server, use: <code>-world "MAP_NAME"</code> ; replacing <code>MAP_NAME</code> with the file name of the map, which must be in the BZFS directory. You have probably seen that when you visit other server, one of the menus has the "save map" option. That means you can save that map for use on your server. Just save it somewhere in your pc, and specify the location of the map in the configuration file, next to the line that starts with <code>-world</code>
* You can choose the max number of players (for example <code>-mp 10</code> says there can't be more than 10 players). But just because you can host many, decide if you really want to. The more players on your server, the higher the overall latency will be and the more bandwidth your server will consume. Moreover, more than 4 players per team on a ctf or more than 6 players on a rabbit style is just not fun. Experiment if you plan to host a lot, otherwise don't worry. Not only latency that matters, but many players will make the field busy. Tanks will get killed often and there would be a lot of action. This is good, and bad. Good in that it is a lot of fun! But bad in that the average alive time may only be a few seconds.
* A server description would be nice. Note that there is a small limit on how many characters you can put for description, and it gets smaller based on how long the server address is. Add a description by adding option: <code>-public DESCRIPTION</code>
* You can choose what flags, if any, to include or restrict. You must be familiar with the flag abbreviations, which are listed using command "<code>bzfs -help</code>" near the end of the help message. Add flags to the server using "<code>+f ABBR</code>" and restrict flags using "<code>-f ABBR</code>" replacing <code>ABBR</code> with the flag abbreviation.

This should get you started, but there are many more options you can set. Some of them are explained below in the section "Good Administration". In any event, most of the options can be understood by reading the file bzfs.conf provided with the installation.

== Getting your server on the public list ==

BZFlag has a central list server that keeps track of all the public servers. Using the <code>-public "some text"</code> command line argument will tell your local server to attempt to register itself on the public server. This is normally all that is required to get your server listed.

The list server will need to be able to access your server just as other players will. This is done by connecting back to the public IP address where your server is running. The list server only checks the tcp connection back to your server at present, though players will also try udp on the same IP address and port number.

You can test your server with the bot in #BZFlag on irc.freenode.net IRC network. See http://irchelp.org/ for more information on irc. You may want to use the web interface at http://my.BZFlag.org/irc/irc.cgi if you do not already have an irc client like [http://xchat.org/ X-Chat] or [http://mirc.com mIRC] installed. Once you are in the #BZFlag channel tell the bot to contact your server by doing this with your machine name or IP address and the :port number:
{|
|
~bzfquery bzflag.secretplace.us:5255
|}
You should get a list of players back like:

{|
|
<ibot> X:0(0-0) R:-78(95-173) G:4(67-63) B:-4(172-176) Tofe(R:anonymous)-27(29-56) zapped
(O:anonymous)0(0-0) cookiecutter(G)14(28-14) Shoot For Brains [CAN-NS](G:shoot@me.com)7(20-13)
Attilla(X:Terleckyjy@terleckyjy)42(79-37) emul(G)-15(18-33) immel(G)-2(1-3) shadow
(B:matt@tiger.prinz)-10(0-10) jp(R:PenovichJ@penovichj)-31(31-62)
|}
or
{|
|
<ibot> No Players
|}
which means the bot was able to contact your server, just that there are no players on it at the moment. This is ok.

If you get:
{|
|
<ibot> could not connect to 127.0.0.1:5154
|}
Then your server is firewalled and the list server cannot contact it. This means that you will not be able to get your server on the list. Chances are you have a firewall blocking external access to your server.

Note: when you run the bzflag client on the same network as a server it should discover the server by using a broadcast ping. If your server shows up in the list, but without the description next to it, this means that you found it through broadcast discovery, and '''not from the public list server'''. If the server description that you included on the <code>-public "this text"</code> command line option is there, then your server is correctly listed on the public server list.

Using multiple <code>-d</code> options to the server will result in some useful (and some useless) messages from the server.
{|
|
bzflag@phoenix:~/bzflag-1.10$ src/bzfs/bzfs -d -d -d -i 24.1.104.25 -p 51540 -public "My Server Name"
style: 0
There is a voting arbiter with the following settings:
vote time is 60 seconds
veto time is 10 seconds
votes required are 3
vote percentage necessary is 50.099998
vote repeat time is 300 seconds
available voters is initially set to 200
Running a public server with the following settings:
public address is 24.1.104.25:51540
listening on 24.1.104.25:51540
with title of "My Server Name"
Sent ADD message to list server
GET /db/?action=ADD&nameport=24.1.104.25:51540&version=BZFS1910&gameinfo=0000000100000000000000000000c800c800c800c800c800c800c8&
build=1.10.7.20040809-RELEASE-linux-gnu&title=My+Server+Name HTTP/1.1
Host: my.BZFlag.org
Cache-Control: no-cache

Player [0] accept() from 24.1.104.25:50579 on 6
Player [0] on 6 removed: Disconnected
|}
* the -i parameter is used here to force an IP address. This server happens to have more than one IP address. This is not required on most servers.
* the -p parameter is used to pick a different port number than the default. If you are only running one server, it is recommended that you leave this off and use the default port number.
* notice the debug line that starts with "<code>GET</code>". This is the request that was sent to the bzflag list server to attempt to get listed
* notice the "<code>Player [0]</code>" lines. This indicates that the list server connected back and then disconnected. If you don't see this then it is likely that your server is firewalled and the list server is unable to connect back and so will '''not''' list your server.

== Running the server ==

There are different ways to run a server. On both Windows and *nix, the program (BZFS) is in the directory where you installed BZFlag (most likely: "<code>C:/Program Files/BZFlag2.0.0</code>", or on your usr account). The program containing the server is BZFS.exe. Double clicking on it will run a server with default options, but clearly you want to specify your own options, for example those you saved in the configuration file generated in the previous step. One way to do it is to specify all the commands for the server in a batch file, so you can just double click on it to start a server. On other systems such as Linux, create an executable with the commands, or a shell script, or see if there are any related ways to store console/text based command interface commands in a "shortcut" style.

On Windows: Here is a [SampleBatchFile]. Open notepad or any other text editor, copy the content of the file, make the changes that you need to change (notably: the location of BZFS and the config file bzfs.conf). Save the file with a nice name and extension .bat (for example: nicename.bat) on your desktop or a window of your choice. You probably understand what the batch file is doing: the lines beginning with "set" specify the content of some variables, such as the location of BZFS and the configuration files. The server is started on the line next to last (before "pause").

If you don't want to have a batch file or for some reason your batch file doesn't work, here is a procedure that always works: from the start menu in your windows machine, look for the "command prompt" and click on it. A black window will open up. Type: <code>cd "c:\Program Files\BZFlag2.0.0"</code> (this should work in most cases, unless you installed BZFlag in a different directory). Once you are there type: <code>bzfs -conf "C:\Program Files\BZFlag2.0.0\Data\bzfs.conf"</code> (change what is between quotes with the exact location of the configuration file).

On *nix: Use a config file, or a shell script. A config file can be made simply by taking all of your command line options you want to pass to BZFS, and placing them in a config file, one options on each line. An HTML file has been created that is shipped with BZFlag (in /data/ on binary releases, and in /misc/ in source releases or CVS). A shell script can be made the same way. A config file can be used, by changing directory to BZFS, and do "bzfs -conf CONF.conf", replacing CONF.conf with the config file in the same BZFS directory.

Once the server is running, log into it with your client and type /password PASS, where PASS is the password you chose in the configuration step. You'll be greeted by the client as an administrator. The KeysAndCommands and ServerCommands pages list a number of things you can do as an admin (although I don't think either of those pages is complete). If when you type one of those commands you get a "You do not have permission" message on client commands, it means that you forgot to login as admin (or somehow your login failed). Type in your client /password PASS replacing PASS with the password that you specified in the configuration phase. If this doesn't work shut down your server, go back to the configuration step and make sure you are getting the right password.

== Sharing Administration Status ==

Helpful links about this topic:

http://my.bzflag.org/bb/viewtopic.php?t=5960
and
http://my.bzflag.org/bb/viewtopic.php?t=6516

Sometimes people will want to share administrator status. Multiple people can be assigned permissions on a server, and all can do more than the normal DEFAULT group (general public). This allows a server to be better administrated, as when one admin is not watching it, another one can. So how do you do this? This is quite easy to do. First off, configure your server to accept group permissions. This is done through BZFS command "<code>-groupdb FILE</code>". This stores group names and permissions for that group. Its syntax for adding groups is: "GROUPNAME: permissions...", replacing GROUPNAME with the name of the group. Don't worry about adding ADMIN or DEFAULT groups, as those get thrown in automatically. Make one up, but please do not alter ADMIN group, as this is stuff administrators can do, and why limit yourself? Groupnames may not have spaces or quotes. Replace "permissions" with permissions, and take out the backslash in the command. For example, write "lagstats" instead of "/lagstats". So a sample line would be, "JRADMIN: playerlist ban kick". Separate permissions by a space, and DO NOT put permissions on different lines! Make sure the group name and ALL permissions are on the same line!

Now that you have your groups laid out, you must create a pas-swo-rd dat-ab-ase to store nicks and passwords created using "/register", as only registered users may be added to groups. To add people to a group, have them register, and enter BZFlag admin client command "/setgroup CALLSIGN GROUPNAME", replacing CALLSIGN with their callsign, case sensitive (add quotes around it if the callsign has spaces), and GROUPNAME with the name of the group to add them to. And that?s it! Easy as pie! This enables you to have multiple admins on one server. But what if you don't want other admins? Easy, create a smaller admin group, such as JRADMIN, in which they have more privileges than a normal person, but not as many as an admin. One privilege you MUST be very careful in giving a person is /shutdownserver. This is terrible if misused, as it kills the server. Trust wisely. And finally, if your server supports /report, starting in 1.11.*, people with privilege to "/viewreports" can see any reports filed, regardless of whether or not the person with that privilege has the computer that stores the reports.

== Shutting down your server ==

If you have had enough of your server, shut it down by entering /shutdownserver in the client. You can also just terminate BZFS execution, but this is not proper and takes a while for the client server list to realize it was terminated.

Now that the server is running, how does it work? Well, the BZFS window or execution must stay alive to keep the server alive. If you close the BZFS window or halt its execution, the server goes too. It will stay on the server list for a short time if halted suddenly.

Closing the server window, or halting its execution, is somewhat like turning off the power suddenly as a way to shutdown your computer - it is not proper, and is not recommended.

== Good Administration ==

Just because you have a server, that's not all. You must maintain it and keep your players satisfied. Check it often. One way to get feedback is to support the "/report" command.

Enable this using BZFS by setting the configuration option "-reportfile FILENAME" replacing FILENAME with a file to use to write reports to, or "-reportpipe FILENAME" replacing FILENAME with the file to pipe reports to. Reports are made through the client and are simply human messages.

But besides that, you must watch the people that come on your server. Often times people will pause or become "NR", not responding. "Not responding" means that they haven't sent a packet in a while (5 seconds by default). This happens to people with slow connections, or people with messed up connections because their connection simply can't send packets fast enough to be within the threshold. Usually they will be kicked automatically for idling too long, but if not, a kick is suitable. Take action against teamkillers (people who kill their own team on PURPOSE, not by occasional mistake), cheaters (a ban is usually nice :), people who log in/off constantly (people who constantly log on & off to reset their score, a warning is suitable), and any other nasty behavior.

You may want to implement a filter to filter chat or callsigns or both from abusive words. Make a file with a phrase/word that should be filtered on every line, and add it to the server using configuration option "-badwords FILE", replacing FILE with the file name IN QUOTES that is found in the BZFS directory. Then set whether to filter chat, callsigns, or both using "-filterCallsigns" and/or "-filterChat". Sometimes, BZFS will be too strict and filter things that aren't bad. You can make simple exact matches happen using "-filterSimple".

So you have a filter, but what if a bad person comes on? Take reasonable action, a warning to start, a permanent ban at worst. Punishment severity is, in order, a warning (use the chat), a kick (/kick REASON), a temporary ban (/ban IP DURATION REASON), and a permanent ban (/ban IP REASON). IP is delinquent's IP address (found using "/playerlist" admin command), DURATION is the amount of time in minutes (do not put a number alone if to ban forever), and REASON is an optional text string of the reason, which will be sent to the player and recorded in your logs. If you want to just kick a person off the server temporarily, use "/kick REASON", replacing REASON with an optional text string of the reason why. If you want bans to last after you shut down or restart your server, make sure you specified a ban file, which is a file that BZFS can store banned IPs in, using BZFS command-line option "-banfile FILE", where FILE is the name of the file in the BZFS directory.

== World Files ==

World files should have the ".bzw" file extension and be in [[BZW]] format. If world files live in the "<code>worlds</code>" directory under the config directory they will be usable when you start a simple server from inside the client. You should not use this method to run a dedicated server, just for starting a LAN game etc. The "<code>worlds</code>" directory is located:

* "~/.bzf/worlds/" - on Linux and Unix Systems.
* "My Documents\My BZFlag Files\worlds\" - on Microsoft Windows.
* "~/Library/Application Support/BZFlag/worlds" - on Apple Mac OS X.

== Other Information ==

BZFlag has not been carefully audited for buffer overflows and other remote attacks, however, large packets or suspicious packets make the server kick the player that sent it. You should never trust the server to be your guard. It's a good idea to run your BZFlag server as a user with minimal permissions on your machine and to run it in a [[BZFS in a chroot jail|chroot jail]].

== Regarding "cheat" servers ==

While the license for BZFlag allows users to run any server modification that they wish, or to modify the code in any way, the project administration asks that users do not publish or host "cheat" type clients or servers. These cheats ruin the game for the average player, when they are mixed in with the normal game servers and clients. We understand the desire to expand and modify the game and it's sources, so it is requested that anyone wishing to run a game that uses modified code or logic to do so using a different network protocol than the current public release. This will let modified games be played, and prevent modified clients from being used on public unmodified games, as they would be incompatible. The BZFlag project administrators reserve the right to remove the public listings of any game servers that do not adhere to this rule. Administrators also reserve the right to remove any global accounts or access to public services at any time.

==See also==
[[Commands]]<br>
[[Server Variables]] <br>
[[BZFS in a chroot jail]]<br>
[[Known Cheats]]

==External Links==
http://my.bzflag.org/bb/viewtopic.php?t=2915 post on the BZFlag Forums

[[Category:Server]]
[[Category:Support]]

Category:Compiling

2008-03-30T08:10:56Z

Flash:

Pages dealing with the building and compiling of BZFlag into usable binary executables.

==Compiling BZFlag 2.0.x on Windows==
To compile BZFlag 2.0.x on Windows, it is recommended that you use Microsoft Visual C++. MSVC7 and MSVC8 are the recommended, MSVC9 may have some incompatibilities. You may use MSVC Express Edition to compile BZFlag, but you will not be able to distribute your executables.

Once you have downloaded your source code, you will also need libcURL, the Windows Server 2003 Platform SDK and DirectX April 2007 SDK. (Note that the November 2007 SDK is incompatible.) Install these libs.

Once the libs are installed, go to the win32 subdirectory of the BZFlag source and go to either the MSVC7 or MSVC8 directories, depending on the version you are using. Click on the BZFlag solution, and build the projects by pressing F5. This may take some time. Once the projects have been built look under the top directory for your executable.

==Compiling BZFlag 2.0.x on MacOSX==
To compile BZFlag 2.0.x on MacOSX, you need to have XCode installed. In addition, you will need to get SDL from the [http://www.libsdl.org SDL web site].

The simplest way to build is to use the Terminal command-line interface. From the '''bzflag''' directory, run
% '''./autogen.sh'''
% '''./configure'''
% '''make'''
Note that depending on your preferences, you may want to use the following arguments to configure: '''--enable-universal''' to make a universal binary and '''--enable-shared''' to use shared objects. For testing and development purposes, it is strongly recommended that you use '''--enable-debug'''.

After '''make''' has completed (without errors!) the three executables ([[:Category:client|BZFlag]], [[BZFS]], and [[BZAdmin]] will be located in the '''bzflag/src/''target''''' directory. You can run these programs from the command line, but if you want to make a double-clickable application, you will need to use XCode.

Launch XCode and open the '''bzflag/BZFlag.xcodeproj''' project. Note that XCode should have '''BZFlag''' selected as the active target and '''Development''' as the active build configuration. Click on '''Targets''' then click the '''Build''' icon. When this process completes, your application will be in '''bzflag/build/Development'''. You can then move it wherever you like.

Lag

2008-03-30T07:59:52Z

Flash: /* Lag and BZFlag */

The term Lag is a shorthand version for the concept of [http://en.wikipedia.org/wiki/Lag Network Latency]. It represents the real world delay in sending messages from one computer to another over a network. All network connections have latency.

==Overview==
Lag is the network latency of a connection, or the time it takes for a network packet to travel from one host to another. Due to the speed of light, all network transmissions take some time, there is no such thing is a true "0" lag.

Different types of internet connections have different latency characteristics, dependent on the technologies they use. Most modern broadband systems ( like cable modems or DSL ) have a minimum latency that measures in a few milliseconds. Modems can have minimum latencies that measure in the 10s to 100s of milliseconds. The bandwidth rating of a network connection has little impact on it's minimum latency. A DSL line rated at 3 megabits in bandwidth often has the same latency as one rated at 1 megabit.

The distance along the network a message travels will also increase the time it takes to reach it's destination. The more hubs, routers, and switches the packets have to travel ( or hops ) will add additional time, as each hop takes some time to complete. Hosts that are more physically distant usually have more hops between them, due to the nature of the internet.

==Lag and BZFlag==
Latency affects real time games in a very specific manner. A message sent from one user to the server will take some time to reach the server. This means that by the time the server receives a position update from a player, that user may and probably has) have already moved from that position. Additional time is spent sending the message from the server to the other players. Depending on the latency of the various network connections, each player will get the update message at a different real world time.

The short version of this is, when you get a message, the client isn't there anymore. This presents problems for messages that are time sensitive, such as positional updates, and shots.

The current version of BZFlag ([[BZFlag 2.0.8|v.2.0.8]]) does not do any type of latency compensation on player messages. This means that the player you see on your screen is not where he is on his screen. This can produce an error in the perceived game states between the 2 users. One user may shoot where he believes the other is, and in his view score a hit, while on the other user's screen he has moved away from the position and saw a clear miss. The first user simply has not received his new positional update yet, because it is in the middle of network transmission.

The BZFlag server has a method for measuring the latency of each client, and displaying it as a numeric value in milliseconds. You can check lag for all players by using the command '''/lagstats''' while playing (just send '''/lagstats''' as a chat message). Lagstats shows an approximation of the amount of time it takes for a network message to go back and forth from one player to the server and back again, not the amount of time it takes to go from one player to another player. For example, if you fire a shot, your client sends a message to the server, giving shot direction and speed. The server then relays this information to all the other clients.

Other lag-related problems are "missing" or "dropped" packets and "jitter". These can occur if there are more severe network problems which cause messages between players and the server to simply get lost, or to be delayed by inconsistent amounts of time. In an attempt to keep this explanation simple, these problems will not be covered here, other than to say that they compound the effects of lag to an even higher degree.

Lag affects what you see while playing BZFlag, especially if the delay is high. The most common effect seen is "shots going through other tanks." Many times you will hear players say "my shot went through you", or "why didn't you die." Many people have been accused of cheating due to the sometimes misunderstood effects of lag.

== Fixing Lag ==
How to fix lag depends on what is causing it.

=== Slow Internet Connection ===
Lag can be caused by a slow internet connection, such as dial-up. In that case, find a server that is more allowing, or get a better connection.

=== Satellite Internet ===
Satellite internet is far too laggy for BZFlag. Sorry.

=== Automatic Updates ===
Make sure software is not running scans for automatic updates in the background.

=== Downloads ===
Don't download something and play BZFlag at the same time.

=== Internet-intensive programs ===
Other programs, such as other people playing an online game on your network, can cause lag.

=== Distant Server ===
Try a different server. Often, lag is just caused by distance.

==The lag test program==
[[Image:Sample.png|thumb|200px|right|Chestal's lag-recording test program]]

On the right, is a capture from a test program created by Chestal. This test program allows us to accurately capture and replay events which occur in BZFlag. With a small modification to the BZflag client program, it is possible to log tank movements and shots to a file. This file can then be analyzed with a special visualization program. In this sample, you can see two tanks, surrounded by circles which are their 'hit-zones'. Any shots which intersect the hit-zone circle should result in an exploding tank! The green tank represents the player who was logging, other tank(s) are always red. Here, the green tank was lucky enough to avoid both shots by squeezing between them!

NOTE: The tools mentioned here are not generally available, due to the large size of the log files created, and requirements of the visualization tool. There was some progress on this (automatic playback, height indicator, map displaying, callsigns) but the results are not available to the public, either.

===A real, common example of lag.===

Here is a rather common example of a near-miss (no tanks exploded in this sequence). This is a real example, not an illustration. All three tankers were running the special logging client described above, and these images visualize all three captured logs at approximately the same moment. Note that even though lag was relatively low (all players were below 100ms), these captures show that each player sees something a bit different. Keep in mind that the green tank in each image is the one who's log is being shown. Click on any image for a full screen capture of the visualization tool.

[[Image:Smallb.png|thumb|262px|right|Tank B's View]]
TANK B's LOG:

Here we see tank B's point of view. From here, we see a shot which appears to hit tank A. In fact from this tank's point of view, it clearly does hit tank A.

(Note: Tank B lag was approx. 50ms)

[[Image:Smalla.png|thumb|262px|right|Tank A's View]]
TANK A's LOG:

And, here is tank A's point of view. The shot here has missed tank A. Keep in mind that tank A is moving forward here.

(Note: Tank A lag was approx. 90ms)

[[Image:Smallc.png|thumb|262px|right|Tank C's View]]
TANK C's LOG:

Tank C sees something similar to what tank B saw.

(Note: Tank C lag was approx. 25ms)

===So, what happened?===

'''Probably the most important factor to keep in mind here is that it is a player's OWN client which determines when he/she is hit,''' as it has the most accurate representation of its own tank location. Your tank's position is calculated locally, without any lag.

So, tank A did not explode, because it 'knew' that it had moved forward to avoid the shot. Due to the delay from lag, tanks B and C still saw tank A at its old position which had occurred a little over 1/10 second ago, so it '''appeared''' to them that the shot went through.

In conclusion, not only can understanding lag make you a better player, but it can also explain why shots seem to go through other tanks. In general, your shots will be much more accurate if you compensate for lag by shooting where you opponent will be in 100ms, or whatever you and your opponent's combined lag is. Of course, if your opponent is constantly switching directions, this can be difficult.

[[Category:Client]]
[[Category:Server]]

Talk:Installing

2008-01-06T03:52:52Z

Flash: Where to put details on how to compile

There is no place that actually talks about the process of compiling a source distribution. Does that belong here, or on the Compiling page? Compiling is even more of a stub than this...

Network Protocol

2007-04-23T04:42:16Z

Flash: spell check

{{Inaccurate}}
{{DesignDocument}}

= Introduction =

BZFlag uses standard IP (Internet) networking protocols. The code is written to the BSD socket interface, with adjustments for winsock on win32 platforms. Future revisions may centralize the network code into one file behind a single class interface to simplify porting to platforms without the BSD socket API.
Most communication is non-blocking. That is, reads and sends return immediately instead of waiting for data to become available or to be sent. That's important since BZFlag is a real time game. It can't afford to get stuck waiting for a packet to come in. (The one exception to this is when BZFlag connects to a server, and this should get fixed someday.)
Communication is multiplexed using the select() call, which notifies the caller which sockets have data pending for read and/or are ready for sends. Instead of checking for incoming data by trying to read every socket and testing for success, we simply ask the system which sockets have data and read on those only. This also means that we use just a single thread for network communication.
BZFlag uses two distinct transport protocols to communicate with the server. Server communication uses TCP/IP for reliability. Live game data communication uses UDP for speed and efficiency. See the other pages for more details.

= Client/Server Communication =
The BZFlag server manages games. It is the judge and arbiter between clients. It manages game-global resources and information, such as flags and scores. It does not enforce game rules. Clients are trusted to follow the rules, saving the server the trouble of validating kills and client maneuvering.
For example, the server is not told of changes to a client's position on the game board. Therefore the server cannot enforce the rule that players can't drive through walls (without the OO or PH flags). This allows each client to run freely. If it had to wait for the server to okay each movement, it would be impossible to play BZFlag except on fast or dedicated networks.
Furthermore, clients inform the server when they've killed another client player. The server doesn't verify the kill was legal beyond checking to see if someone has already claimed a kill on the same player. If more than one player claims a kill or tries to grab a particular flag, the server decides which player gets the kill or the flag.
Client/server communication is mostly limited to those messages that must be successfully delivered. These include, among others, notifications of players coming alive or being killed, notifications of shots being fired, flags coming or going or being grabbed or dropped.
Client/server communication in BZFlag is through TCP. TCP has the advantages of being bidirectional, reliable, and sequential. Bidirectional means each side of the connection can send to the other. Reliable means that each message will be delivered to the destination. Sequential means that messages (on a particular connection) will be received in the order they were sent.
The main disadvantage of TCP is that it's slow. Reliability may require a given message to be sent several times, until the receiver acknowledges its receipt. While delays can cause problems, there really isn't a way around it. Messages between the client and server are specifically those messages that must not be lost. If we didn't use TCP we'd simply have to implement something that did the same thing, and which would necessarily suffer from the same drawbacks.
There are some instances where client/server communication doesn't use TCP. One example is client attempts to locate servers on the network. Clients send broadcast `pings' which the servers listen for and respond to in kind. These messages are not part of normal game communication.

= Client/Client Communication =
BZFlag clients send certain information to other clients during a game. This information includes: status, position, orientation, and linear and angular velocity. This state can change quickly and getting it late is no better than not getting it at all. So client to client packets are sent using UDP, a datagram protocol.
UDP is unreliable, meaning that packets are not guaranteed to be delivered. It's also connectionless, meaning we don't even know if anybody is listening for the message. However, it's also fast because it's so simple. UDP suits our needs because: we need fast delivery; we don't care if a message is lost because another will arrive shortly afterwards; and we don't care if the receiver isn't listening.
BZFlag clients need to send their information to all the other clients. There are several ways to do this. First, each client can send each message to all the other clients. If there are N clients then each message is sent N-1 times. Traffic grows as the square of clients. This is slow and wasteful.
Alternatively, each client can send all messages to one special computer (for example, the server) and that computer can forward the messages to all the other players. This makes life easier on the clients and much harder on the server. It also delays the delivery of each message. And traffic from the server still grows as N squared (though traffic to the server grows linearly).
Another possibility is to broadcast messages. A broadcast message is sent once and received by all computers on a subnet. This scales linearly and minimizes network traffic but broadcast traffic is never routed outside the subnet, so it means only clients on the same subnet of the same local area network could play together.
BZFlag uses the second technique, using the server as a relay system. The server uses the TCP client/server connection to send client traffic that must be reliable and UDP for information that must be timely but does not need to be reliable.

= Protocol =
--> means from client to server
<-- means from server to client

All multi-byte data is in network byte order (aka big endian); that is, the most significant byte comes first followed by successively less significant bytes.
All numbers are integers unless otherwise specified. Integers can be 8, 16, or 32 bit signed 2's compliment or unsigned (encoding is the same in regardless of signed status). Values in this document in byte boxes are given in hexadecimal. Values in the text are given in decimal unless otherwise noted.
Bit fields are encoded as unsigned integers. All floating point numbers are in standard IEEE-754 single precision format. Multi-byte values are *not* necessarily aligned on 2 or 4 byte boundaries.
A client normally follows the following sequence during game play: connect to server get the world database join the game send/receive game messages leave game disconnect from server
common message structures ------------------------- Most messages begin with the length of the message in bytes followed by a 16 bit code. The length is 16 bits and excludes itself and the code, so it's the actual length of the message minus 4.

Player identifiers are 1 byte and are used in many messages.

0 - 243 : Regular Players
244 - 250 : Special Team Ids
251 - 252 : Unused IDs
253 : ServerPlayer (World weapons, etc)
254 : All Players
255 : No Player (Invalid Player)

Flag status is common to a few message types:

u16 flag id
u16 status
u16 type
u8 owner id
float position (x)
float position (y)
float position (z)
float launch (x)
float launch (y)
float launch (z)
float landing (x)
float landing (y)
float landing (z)
float flight time
float flight end time
float initial velocity

`Position,' `launch,' `landing,' `flight time,' `flight end,' and `initial velocity' are all floating point numbers. `Flag id' is the type of flag,enumerated in FlagId.

`Status' gives the current location of the flag:
FlagNoExist -- the flag is not active (i.e. not in the game)
FlagOnGround -- the flag is sitting on the ground ready to get picked up
FlagOnTank -- the flag is on a player's tank
FlagInAir -- the flag is in the air and will fall back down
FlagComing -- the flag just appeared and is falling to the ground
FlagGoing -- the flag was thrown in the air and is disappearing

`Type' indicates the behavior of the flag: FlagNormal means the flag is permanent and can be dropped normally (e.g. a team flag); FlagUnstable means the flag may disappear after use (e.g. a good super flag); FlagSticky means the flag cannot be dropped normally (e.g. a bad super flag).
`Player id' indicates which player has the flag when `status' is FlagOnTank. It isn't used for any other status.
`Position' is the location of the flag on the ground. It only has meaning when `status' is FlagOnGround. The position of a flag when on a tank is the position of the tank (centered on and at the top of the tank)
`Launch' is the location of the flag where it was thrown in the air. `Landing' is the location where the flag will/would touch ground. These are used when `status' is FlagInAir, FlagComing, and FlagGoing. The client should make the flag follow a reasonable flight path (e.g. a parabolic arc) from `launch' to `landing.'
`Flight time' is the time elapsed since the flag was thrown into the air. `Flight end' the time when the flag will reach the ground. `Initial velocity' gives the vertical (z) velocity of the flag when launched. The vertical position of the flag at time t (ranging from 0 to `flight end') is: z = z0 + v * t + 0.5 * g * t * t. z0 = `launch z;' v = `initial velocity;' g = acceleration due to gravity.

== Connecting to a server ==
The [http://bzflag.svn.sourceforge.net/viewvc/*checkout*/bzflag/trunk/bzflag/misc/bzfquery.php bzfquery.php script] is a nice example of how to connect to a server.

At the beginning you need to open a socket. Beginning with protocol 0048 you need to send "BZFLAG\r\n\r\n" in order to get any reply. At that time you unfortunately don't know the protocol, so send it by default or your client will probably freeze.

--> connect(server port)
--> +----+----+----+----+----+----+----+----+----+----+
| 42 | 5a | 46 | 4C | 41 | 47 | 0D | 0A | 0D | 0A | BZFLAG\r\n\r\n
+----+----+----+----+----+----+----+----+----+----+
<-- +----+----+----+----+----+----+----+----+----+
| 42 | 5a | 46 | 53 | 31 | 39 | 31 | 30 | FF | BZFS1910 FF
+----+----+----+----+----+----+----+----+----+

Client should verify the version. In old versions the first four bytes indicates a BZFlag server, the next byte indicates the major version number (as an ASCII digit), the two bytes after that are the minor version number (as ASCII digits), and the 7th byte is the revision. Major and minor version number changes indicate incompatible protocol changes. Different revisions of a given version are compatible and usually just indicate client user interface changes. A following FF ends the packet. In new versions the protocol is just a number increased by 1 when the protocol changes.

If the reply was a protocol older than 0048 then bzfs will kick the client connecting to it. In this case we recommend a fallback, not sending BZFLAG\r\n\r\n during connection try:

--> connect(server port)
<-- +----+----+----+----+----+----+----+----+----+
| 42 | 5a | 46 | 53 | 31 | 39 | 31 | 30 | FF | BZFS1910 FF
+----+----+----+----+----+----+----+----+----+

Server owners will see something like the following in the logs if their server(s) use a protocol older than 0048:
Player [0] sent huge packet length (len=16986), possible attack
Player [0] removed at 2007-04-11 15:52:55: large packet recvd

== Message types ==
Read this with caution, as it is very old information not reflecting the current status.

=== Negotiating world flags ===

--> +----+----+----+----+----+----+----+----+----+----+
| length | 6E | 66 | FlagID1 | FlagID2 | ....... | MsgNegotiateFlags
+----+----+----+----+----+----+----+----+----+----+ (List of client flag ids)
<-- +----+----+----+----+----+----+----+----+----+----+
| length | 6E | 66 | FlagID1 | FlagID2 | ....... | MsgNegotiateFlags
+----+----+----+----+----+----+----+----+----+----+ (List of server flag ids, that client doesn't know)

Client sends to the server the two byte representation of all flags known to the client. In the case that a flag is only one letter, (N) for instance, the second byte is null. Otherwise, the null byte is implied at position 3. The server upon receipt of this list, finds all flags that are used by the server, but not known by the client, and sends this list to the client. The client upon receipt of the list, either disallows play, if flags exist, or continues if the list is empty.

=== getting the world hash ===
--> +----+----+----+----+
| 00 | 00 | 77 | 68 | MsgWantWHash
+----+----+----+----+
<-- +----+----+----+----+----+----+----+----+
| length | 77 | 68 | world hash data... | MsgWantWHash
+----+----+----+----+----+----+----+----+

To improve performance World (bzc) files are cached on the client. The name of the cache file is an md5 hash of the file that is computed on the server. this hash is sent to the client, and the client looks for a file by that name in the bz world cache directory. If the hash starts with a 't', the world is a random world. If the hash starts with a 'p' the world is from a world file. If the client can find the file locally, it does not sent the following MsgGetWorld packet.

=== getting the world database ===
--> +----+----+----+----+----+----+
| 00 | 02 | 67 | 77 | offset | MsgGetWorld
+----+----+----+----+----+----+
<-- +----+----+----+----+----+----+----+----+
| length | 67 | 77 |remaining| data... | MsgGetWorld
+----+----+----+----+----+----+----+----+
or
+----+----+----+----+
| 00 | 00 | 73 | 6b | MsgSuperKill
+----+----+----+----+

Client sends MsgGetWorld requests until it has read the entire world database. Clients should send an `offset' of 0 for the first request and increase `offset' by however much data was sent in reply. Each MsgGetWorld reply includes the number of bytes left after the returned block of data in `remaining'. The server returns 0 in `remaining' when there is no more data left to read. In no event will the server return more than MaxPacketLen - 6 bytes of data in one reply (see protocol.h for the definition of MaxPacketLen). The server may return MsgSuperKill at any time during the download of the world database. The client should immediately close the connection to the server. No other messages should be returned by the server as long as the client sends only MsgGetWorld requests.

The `data' has the following encoding:

+----+----+----+----+
| 00 | 1E | 73 | 74 | length of data, WorldCodeStyle
+----+----+----+----+----+----+
| version | worldsize |
+----+----+----+----+----+----+----+----+
| style | mxPlyrs | mxShots | mxFlags |
+----+----+----+----+----+----+----+----+
|linear acceleration|angulr acceleration|
+----+----+----+----+----+----+----+----+
| shake t | shake w | epoch offset |
+----+----+----+----+----+----+----+----+

Values are:
version: version of the bzw format
worldsize: size in meters of world
style: bitfield of game style
maxPlayrs: maximum number of players
maxShots: maximum number of shots at once per player
maxFlags: maximum number of flags that may exist at once
linear acc.: linear acceleration limit (float)
angulr acc.: angular acceleration limit (float)
shake t: time to shake a bad flag (1/10ths of seconds)
shake w: number of wins to shake a bad flag
epoch offset: seconds since midnight Jan 1, 1970 GMT on the server, used when
synchronizing times across clients

The rest of the world database is encoded in individual blocks describing each object. Only permanent immovable objects are included. The encodings for each type of object are:

team base:
+----+----+----+----+
| 00 | 2A | 62 | 61 | length of base data, team code
+----+----+----+----+----+----+
| team id | center (x) |
+----+----+----+----+----+----+----+----+
| center (y) | center (z) |
+----+----+----+----+----+----+----+----+
| angle | size (x) |
+----+----+----+----+----+----+----+----+
| size (y) | size (z) |
+----+----+----+----+----+----+----+----+
| safety (x) | safety (y) |
+----+----+----+----+----+----+----+----+
| safety (z) |
+----+----+----+----+

wall:
+----+----+----+----+
| 00 | 18 | 77 | 6C | length of wall data, wall code
+----+----+----+----+----+----+----+----+
| center (x) | center (y) |
+----+----+----+----+----+----+----+----+
| center (z) | angle... |
+----+----+----+----+----+----+----+----+
| width | height |
+----+----+----+----+----+----+----+----+

pyramid:
+----+----+----+----+
| 00 | 1D | 70 | 79 | length of pyramid data, pyramid code
+----+----+----+----+----+----+----+----+
| center (x) | center (y) |
+----+----+----+----+----+----+----+----+
| center (z) | angle |
+----+----+----+----+----+----+----+----+
| width | depth |
+----+----+----+----+----+----+----+----+
| height | sdf|
+----+----+----+----+----+

box:
+----+----+----+----+
| 00 | 1D | 62 | 78 | length of box data, box code
+----+----+----+----+----+----+----+----+
| center (x) | center (y) |
+----+----+----+----+----+----+----+----+
| center (z) | angle |
+----+----+----+----+----+----+----+----+
| width | depth |
+----+----+----+----+----+----+----+----+
| height | sdf|
+----+----+----+----+----+

teleporter:
+----+----+----+----+
| 00 | 21 | 74 | 65 | length of teleporter data, teleporter code
+----+----+----+----+----+----+----+----+
| center (x) | center (y) |
+----+----+----+----+----+----+----+----+
| center (z) | angle |
+----+----+----+----+----+----+----+----+
| width | depth |
+----+----+----+----+----+----+----+----+
| height | border |
+----+----+----+----+----+----+----+----+
| sdf|
+----+

teleporter link:
+----+----+----+----+
| 00 | 04 | 6C | 6E | length of link data, link code
+----+----+----+----+
| from | to |
+----+----+----+----+
end of data:
+----+----+----+----+
| 00 | 00 | 65 | 64 | length of worldcodeend data, worldcodeend code
+----+----+----+----+

The above values are interpreted as follows:

angle (float): in radians from the x-axis in the xy plane
width (float): half width (in xy) measured from center
depth (float): half depth (in xy) measured from center
height (float): full height (in z) measured from bottom
border (float): full size of the square cross section teleporter border
center (float): center in xy, bottom in z
safety (float): safety position for team flags, used when team A drops team B's
flag on team C's base.
from & to: index of teleporter face starting from zero; the N'th teleporter
in the world data has face indices 2*N and 2*N+1. teleporter
links indicate which face teleports to which face; faces may
teleport to themselves.
sdf (byte): bit mask:
drive through is bitmask 0x01
shoot through is bitmask 0x02

== join game ==
Once connected a player normally requests to join the game. The server replies with
MsgSuperKill, MsgReject, or MsgAccept.

--> +----+----+----+----+----+----+----+----+
| length | 65 | 6e | player id... MsgEnter
+----+----+----+----+----+----+----+----+
| type | team |
+----+----+----+----+----+----+----+----+
| call sign (CallSignLen bytes)...
+----+----+----+----+----+----+----+----+
...
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+----+----+----+----+
| email address (EmailLen bytes)...
+----+----+----+----+----+----+----+----+
...
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+----+----+----+----+
<-- +----+----+----+----+
| 00 | 00 | 61 | 63 | MsgAccept
+----+----+----+----+
or
+----+----+----+----+----+----+
| 00 | 02 | 72 | 6a | code | MsgReject
+----+----+----+----+----+----+
or
+----+----+----+----+
| 00 | 00 | 73 | 6b | MsgSuperKill
+----+----+----+----+

`Type' is one of the enumerations in PlayerType and `team' is one from TeamColor.
The call sign is the player's `handle' during the game; the call sign is used
to identify the player. No attempt is made by the server to prevent the
duplication of call signs during a game. The email address can be anything,
but should be the email address for human players (e.g. username@hostname).
BZFlag players can choose `anonymous' instead of their email address. The call
sign and email address should be NUL terminated ASCII strings, padded with
NUL's to the required length. `Length' is 12 + CallSignLen + EmailLen.

If the server responds with MsgSuperKill the client should close the connection
immediately. If the server responds with MsgReject, the client has not joined the
game but may keep the server connection open and try again. The reason for rejection
is included with the MsgReject message:

RejectBadRequest -- bogus data in MsgEnter
RejectBadTeam -- invalid team id
RejectBadType -- invalid client type
RejectTeamFull -- no more players allowed on team
RejectServerFull -- no more players allowed on any team

If the server responds with MsgAccept, the player has successfully joined the game.
The server then automatically sends updates about each flag, team, and player. The
client should be prepared to accept these updates in any order. The flag and team
updates are sent as MsgFlagUpdate and MsgTeamUpdate messages, respectively. Player
updates are sent as MsgAddPlayer messages. The client will receive a MsgAddPlayer
for the player it just added, but only after it has received a MsgAddPlayer for each
of the players already joined.

Until it receives the MsgAddPlayer for the player it just added, the client will
only receive the following kinds of messages:

MsgSuperKill
MsgFlagUpdate
MsgTeamUpdate
MsgAddPlayer

Players of type ComputerPlayer are not sent team or flag updates and only get the
MsgAddPlayer for themselves. This probably wasn't a good idea, but there it is.

== leave game ==
Once entered, a player can leave the game at any time. This should be done by sending
the following message then closing the connection:

--> +----+----+----+----+
| 00 | 00 | 65 | 78 | MsgExit
+----+----+----+----+

There is no reply. Clients can also leave by simply closing the connection, but
sending MsgExit first is recommended.

== during a game ==
There are several types of messages that are delivered at any time after a player
enters a game. Clients must be prepared to handle them in any order.

MsgSuperKill
<-- +----+----+----+----+
| 00 | 00 | 73 | 6b |
+----+----+----+----+
Client must immediately disconnect from the server.

MsgTimeLeft
<-- +----+----+----+----+----+----+
| 00 | 02 | 74 | 6f |time left|
+----+----+----+----+----+----+
Gives the time remaining in the game. This message is only sent when the
server has time limit configured. If the time remaining is zero, the client
should indicate to the player that the game is over.
`Time left' is in seconds. It is not sent every second so clients will need
to do their own count down between messages.

MsgScoreOver
<-- +----+----+----+----+----+----+----+----+
| 00 | 0a | 73 | 6f | player id...
+----+----+----+----+----+----+----+----+
| team id |
+----+----+----+----+----+----+
Gives the player or team that won the game by reaching the target score.
This message is only sent when the server has a target score configured.
The client should indicate which team or player won and that the game is
over.

If `team id' is NoTeam then `player id' indicates which player has won.
Otherwise `team id' indicates which team won.

MsgAddPlayer
<-- +----+----+----+----+----+----+----+----+
| length | 61 | 70 | player id...
+----+----+----+----+----+----+----+----+
| type | team |
+----+----+----+----+----+----+----+----+
| wins | losses | call sign...
+----+----+----+----+----+----+----+----+
... (CallSignLen bytes)... |
+----+----+----+----+----+----+----+----+
| email address...
+----+----+----+----+----+----+----+----+
... (EmailLen bytes)... |
+----+----+----+----+----+----+----+----+
Sent when another player enters the game and when joining a game if other
players are already joined. `Type' is enumerated in PlayerType, `team'
is enumerated in TeamColor. `Wins' and `losses' give the player's score.
They are unsigned integers; the player's score equals wins minus losses.
`Call sign' and `email address' are NUL terminated ASCII strings. `Length'
is 16 + CallSignLen + EmailLen.

MsgRemovePlayer
<-- +----+----+----+----+----+----+----+----+
| 00 | 08 | 72 | 70 | player id...
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+
Sent when another player leaves the game.

MsgFlagUpdate
<-- +----+----+----+----+----+----+----+----+
| 00 | 40 | 66 | 75 |flag num | flag id |
+----+----+----+----+----+----+----+----+
| status | type | player id...
+----+----+----+----+----+----+----+----+
| position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
| launch (x) | launch (y) |
+----+----+----+----+----+----+----+----+
| launch (z) | landing (x) |
+----+----+----+----+----+----+----+----+
| landing (y) | landing (z) |
+----+----+----+----+----+----+----+----+
| flight time | flight end |
+----+----+----+----+----+----+----+----+
| initial velocity |
+----+----+----+----+
Sent when a flag's state changes. Also sent to a client when it enters
a game. `Flag num' is the index of the flag. Flags are indexed from
zero up to the maximum number of flags minus one.

Clients must update the flag positions while the flag is in flight (i.e.
`status' is FlagInAir, FlagComing, or FlagGoing. If FlagInAir or
FlagComing then the client should change the flag's status to
FlagOnGround when the flag's flight time equals or exceeds `flight end.'
The position should be set exactly to `landing.' If FlagGoing, the
client should change the flag's status to FlagNoExist when the flight
time equals or exceeds `flight end.'

BZFlag uses the first half of the flight time for FlagComing and the
last half of the flight time for FlagGoing to make the flag appear or
disappear from/to nothing. This allows players to adjust to the
appearance/disappearance of a flag.

MsgTeamUpdate
<-- +----+----+----+----+----+----+----+----+
| 00 | 0a | 74 | 6f | team | size |
+----+----+----+----+----+----+----+----+
| active | wins | losses |
+----+----+----+----+----+----+
Gives the current state of team `team.' `Size' is the number of
players on the team. `Active' is the number of active players on the
team. An active player is one that can participate in the game (e.g.
grab flags, shoot opponents, etc.); a non-active player can only
observe the game. Only active players are considered when deciding
if there are any players on a team (to decide if the team flag should
be inserted or withdrawn from the game). `Wins' and `losses' give the
team's score (wins minus losses).

MsgAlive
<-- +----+----+----+----+----+----+----+----+
| 00 | 20 | 61 | 6c | player id...
+----+----+----+----+----+----+----+----+
| position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
| forward (x) | forward (y) |
+----+----+----+----+----+----+----+----+
| forward (z) |
+----+----+----+----+
Sent when a player comes alive. A player that has joined is not on the
game board until it sends this message, which declares that it is in
game and gives the starting position and orientation. Players are removed
from the game board when killed and do not reappear until sending this
message again.

--> +----+----+----+----+----+----+----+----+
| 00 | 18 | 61 | 6c | position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
| forward (x) | forward (y) |
+----+----+----+----+----+----+----+----+
| forward (z) |
+----+----+----+----+
A player sends this message to enter the game board. Note that this
version of the message differs from the one sent by the server in that
it lacks the player id (which is implicit in the server connection).
Players must send this message to change their state from dead to alive.
Players should not send MsgAlive for a certain penalty period after
being killed (but the server does not enforce a minimum time). The
currently penalty is ExplodeTime.

`Position' gives the location of the player and `forward' gives the
player's forward direction vector.

MsgKilled
<-- +----+----+----+----+----+----+----+----+
| 00 | 12 | 6b | 6c | victim id...
+----+----+----+----+----+----+----+----+
| killer id...
+----+----+----+----+----+----+----+----+
| shot id |
+----+----+----+----+----+----+
Sent by the server when a player is killed by itself or another player.
The victim id is the player that was destroyed and the killer id is the
player credited with the kill. Shot id identifies which of the killer's
shots hit the victim; if the shot isn't a laser or shockwave, other
players may assume the shot has stopped and needn't check themselves
against the shot (or they can wait until the MsgShotEnd message arrives).

--> +----+----+----+----+----+----+----+----+
| 00 | 0a | 6b | 6c | killer id...
+----+----+----+----+----+----+----+----+
| shot id |
+----+----+----+----+----+----+
Sent by the victim when it detects that it's been hit, naming the killer
and which of the killer's shots was the one that hit. Note that the
server does not verify kills in any way so it's trivial to `cheat' by
claiming you've been killed; this is generally unproductive. It's
also easy to cheat by never sending MsgKilled, making you almost
immortal. Don't do this.

MsgGrabFlag
<-- +----+----+----+----+----+----+----+----+
| 00 | 48 | 67 | 66 | grabber id...
+----+----+----+----+----+----+----+----+
|flag num | flag id |
+----+----+----+----+----+----+----+----+
| status | type | owner id...
+----+----+----+----+----+----+----+----+
| position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
| launch (x) | launch (y) |
+----+----+----+----+----+----+----+----+
| launch (z) | landing (x) |
+----+----+----+----+----+----+----+----+
| landing (y) | landing (z) |
+----+----+----+----+----+----+----+----+
| flight time | flight end |
+----+----+----+----+----+----+----+----+
| initial velocity |
+----+----+----+----+
Sent by the server when a player is allowed to grab a flag. This is
both the notice to the player trying to grab the flag that it succeeded
and the notice to all other players that the flag was grabbed. Note
that `grabber id' is redundant; it's always equal to `owner id.'

`Flag num' is the index of the flag. Flags are indexed from zero up to
the maximum number of flags minus one.

--> +----+----+----+----+----+----+
| 00 | 02 | 67 | 66 |flag num |
+----+----+----+----+----+----+
Sent by a player when it wants to grab a flag. Players should only
send this message when their tank is within FlagRadius of a flag (that's
any part of the tank, not simply the center) and on the ground. The
server will not verify this, but it will verify some other stuff. The
player must not assume it will be able to grab the flag. Instead it has
to wait for a MsgGrabFlag reply.

MsgDropFlag
<-- +----+----+----+----+----+----+----+----+
| 00 | 48 | 64 | 66 | dropper id...
+----+----+----+----+----+----+----+----+
|flag num | flag id |
+----+----+----+----+----+----+----+----+
| status | type | owner id...
+----+----+----+----+----+----+----+----+
| position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
| launch (x) | launch (y) |
+----+----+----+----+----+----+----+----+
| launch (z) | landing (x) |
+----+----+----+----+----+----+----+----+
| landing (y) | landing (z) |
+----+----+----+----+----+----+----+----+
| flight time | flight end |
+----+----+----+----+----+----+----+----+
| initial velocity |
+----+----+----+----+
Sent by the server when a player is allowed to drop a flag. This is
both the notice to the player trying to drop the flag that it succeeded
and the notice to all other players that the flag was dropped. `Owner
id' is meaningless in this message.

`Flag num' is the index of the flag. Flags are indexed from zero up to
the maximum number of flags minus one.

--> +----+----+----+----+----+----+----+----+
| 00 | 0c | 64 | 66 | position (x) |
+----+----+----+----+----+----+----+----+
| position (y) | position (z) |
+----+----+----+----+----+----+----+----+
Sent by a player when it wants to drop a flag. Players should only
send this message when they have a flag and only when the flag dropping
constraints have been met (i.e. the flag can be dropped at any time, or
the player got the antidote flag, etc.) The player must not assume it
has dropped the flag until it receives a MsgDropFlag in response.

`Position' is in floating point and is the position of the tank that
dropped the flag when it was dropped.

MsgCaptureFlag
<-- +----+----+----+----+----+----+----+----+
| 00 | 0c | 63 | 66 | capturer id...
+----+----+----+----+----+----+----+----+
|flag num | team id |
+----+----+----+----+----+----+----+----+
Sent by the server when a team's flag has been captured. `Capturer id'
is the player who captured the flag. `Flag num' is the index of the
captured flag. Flags are indexed from zero up to the maximum number of
flags minus one. `Team id' is the id of the team who's flag was
captured. Note that the player who captures the flag may be on the team
that was captured.

The server makes all players on the captured team dead. This message is
the only notice that the players are now dead so clients should act
accordingly. This is also the only notice that the capturer is no longer
carrying a flag.

--> +----+----+----+----+----+----+
| 00 | 02 | 63 | 66 | team id |
+----+----+----+----+----+----+
Sent by a player when it captures a team flag. `Team id' is the id of
the team who's flag was captured. The player should wait until the
server sends back the MsgCaptureFlag response before assuming the
capture was successful. A player should send this message only when
1) its tank is at least halfway inside a team base, 2) the tank is on
the ground, and 3) the player has its own team flag in an enemy base
or the player has another team's flag in its own base. Note that the
server will not enforce any of these requirements.

MsgShotBegin
<--
--> +----+----+----+----+----+----+----+----+
| 00 | 2c | 73 | 62 | shooter id...
+----+----+----+----+----+----+----+----+
| shot id | position
+----+----+----+----+----+----+----+----+
(x) | position (y) | position
+----+----+----+----+----+----+----+----+
(z) | velocity (x) | velocity
+----+----+----+----+----+----+----+----+
(y) | velocity (z) | time
+----+----+----+----+----+----+----+----+
|flag type| lifetime |
+----+----+----+----+----+----+----+----+
Sent by the server when a player has fired a shot. The identical message
is send by a player when it fires a shot. The server does not verify
that the player is allowed to fire a shot.

`Shooter id' identifies the player that did the shooting. `Shot id' is
a number that uniquely identifies to the shooter which shot this is.
`Position,' `velocity,' `time,' and `lifetime' are floating point
numbers. `Position' is the starting position of the shot. `Velocity'
is the starting velocity of the shot. `Time' is the time the shot has
existed (probably 0.0). `Lifetime' is how long the shot exists. `Flag
type' is a FlagId and is the type of flag the shooter had when the shot
was fired.

Clients are expected to compute the flight path of shots (except Guided
Missiles) given the information in MsgShotBegin. That includes handling
ricochets, building impacts, and teleportation, but not tank impacts.
Each player decides if it itself has been hit by a shot at each time step
based on this flight path. Since the path of a guided missile cannot be
predicted, updates to a guided missile's path is sent throughout its
flight by the shooter via MsgGMUpdate messages.

A player should test itself against a shot using whatever algorithm it
likes, but at a minimum should test the line segments the shot moves
along during the time step against a tank aligned bounding box.
Accounting for the linear motion of the tank over the time step is
better and accounting for both the linear and angular motion is better
still. Note that the shot has a certain radius that should be taking
into account during intersection testing. This is particularly
important when testing against a tank with the narrow flag. Ideally,
the shot would be exactly tested against the tank geometry. However,
that's more work than realistically necessary.

MsgShotEnd
<--
--> +----+----+----+----+----+----+----+----+
| 00 | 0c | 73 | 65 | shooter id...
+----+----+----+----+----+----+----+----+
| shot id | reason |
+----+----+----+----+----+----+----+----+
Sent by the server when a shot has been terminated before its lifetime
has expired. The identical message is sent by the player that
terminates the shot. This is normally the player that has just been
hit by the shot. The server does not verify that the player has or
has not been hit. This message is also sent by the player that fired
a guided missile when the shot hits the ground or a building (note that
guided missiles don't ricochet).

`Shooter id' identifies the player that fired the shot and `shot id'
is the same as in the MsgShotBegin message for the shot. `Reason' is
one if the other players should show an explosion for the shot and
zero otherwise.

MsgScore
<-- +----+----+----+----+----+----+----+----+
| 00 | 0c | 73 | 63 | player id...
+----+----+----+----+----+----+----+----+
| wins | losses |
+----+----+----+----+----+----+----+----+
Sent by the server when a player's score changes. `Player id' is the
player with the new score, and `wins' and `losses' are the new scores.

--> +----+----+----+----+----+----+----+----+
| 00 | 04 | 73 | 63 | wins | losses |
+----+----+----+----+----+----+----+----+
Sent by a player when its score changes.

MsgTeleport
<-- +----+----+----+----+----+----+----+----+
| 00 | 0c | 73 | 63 | player id...
+----+----+----+----+----+----+----+----+
| from | to |
+----+----+----+----+----+----+----+----+
Sent by the server when a player teleports. `From' is the index of the
teleporter face the player entered and `to' is the index of the face
the player exited.

--> +----+----+----+----+----+----+----+----+
| 00 | 04 | 73 | 63 | from | to |
+----+----+----+----+----+----+----+----+
Sent by a player when it passes through a teleporter.

MsgMessage
<-- +----+----+----+----+----+----+----+----+
| length | 6d | 67 | from player id...
+----+----+----+----+----+----+----+----+
| to player id...
+----+----+----+----+----+----+----+----+
| team |message...
+----+----+----+----+----+----+----+----+
...(MessageLen bytes)...
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+----+----+----+----+
Sent by the server when one player sends a message to others. `Length'
is the length of the message (18 + MessageLen bytes). `From player id'
is the player sending the message, `to player id' is the player to
receive the message, and `team' is the team to receive the message.
If `to player id' is all zeros then the message is being sent to
everyone on `team'. If `to player id' is all zeros and `team' is
RogueTeam then the message is being sent to all players. If `to player
id' is not all zeros then `team' is ignored and the message is only for
the identified player.

--> +----+----+----+----+----+----+----+----+
| length | 6d | 67 | player id...
+----+----+----+----+----+----+----+----+
| team |message...
+----+----+----+----+----+----+----+----+
...(MessageLen bytes)...
+----+----+----+----+----+----+----+----+
|
+----+----+----+----+----+----+----+----+
Sent by player to send a message to other players. `Length' is is the
length of the message (10 + MessageLen bytes). `Player id' is the
player to receive the message (or all zeros for all players on the
given team) and `team' is the team to receive the message (or
RogueTeam for all teams).

MsgPlayerUpdate
+----+----+----+----+----+----+----+----+
| 00 | 2a | 70 | 75 | player id...
+----+----+----+----+----+----+----+----+
| status | position
+----+----+----+----+----+----+----+----+
(x) | position (y) | position
+----+----+----+----+----+----+----+----+
(z) | velocity (x) | velocity
+----+----+----+----+----+----+----+----+
(y) | velocity (z) | azimuth
+----+----+----+----+----+----+----+----+
| angular velocity |
+----+----+----+----+----+----+
Sent by players to notify other players of changes in its status,
position, or velocity.

`Status' is the tank's current status. See PlayerStatus for the
meaning of the bit field's bits. The FlagActive bit indicates whether
the player's flag's special powers are active or not. The Phantom
Zone flag is an example of a flag that's active only some of the time.
The CrossingWall bit indicates if the player's tank is intersected by
a wall or teleporter; other players can use this to draw the player
in some special way. CrossingWall could be computed by each player
from other information; it's only provided to save the other players
the trouble.

`Position,' `velocity,' `azimuth,' and `angular velocity' are floating
point numbers. `Azimuth' is the orientation of the tank in radians
(the +x axis is 0.0, +y is pi/2). `Angular velocity' is the change in
azimuth per second. `Position' is the tank position and `velocity' is
the change in tank position per second.

A player normally only sends an update when its position or orientation
as could be predicted by other players differs from its true position
or orientation by a certain tolerance. Other players are expected to
use the last known player data to extrapolate the current position and
orientation. This technique is known as dead reckoning and has two
primary benefits: network traffic is decreased since updates needn't
be sent continuously and players on systems with slower frame rates
appear to move smoothly to players on systems with faster frame rates.

Players that fail to send updates often enough should be considered
to be not responding. Unresponsive players should be ignored until
they start responding again.

MsgGMUpdate
+----+----+----+----+----+----+----+----+
| 00 | 2e | 67 | 6d | shooter id...
+----+----+----+----+----+----+----+----+
| shot id | position
+----+----+----+----+----+----+----+----+
(x) | position (y) | position
+----+----+----+----+----+----+----+----+
(z) | velocity (x) | velocity
+----+----+----+----+----+----+----+----+
(y) | velocity (z) | time
+----+----+----+----+----+----+----+----+
| target id....
+----+----+----+----+----+----+----+----+
|
+----+----+
Sent by players with active guided missiles to notify other players
of changes to the motion of the guided missile.

See MsgShotBegin for the meaning of most items. `Time' is the current
age of the shot (the time since being fired). `Target id' is the
current target of the guided missile or all zeros if there is no target.

Players are expected to use dead reckoning to update the position and
velocity of guided missiles between MsgGMUpdate messages. Since
guided missiles deviate from their predicted course only when the
target changes, these message will be fairly rare. Note that different
players may have different ideas of where the target is and that that
may cause slightly different courses. This is generally not a problem.

MsgLagPing
+----+----+----+----+----+----+
| 00 | 02 | 70 | 69 | seq. no.|
+----+----+----+----+----+----+
Sent by the server to active players every 10s to measure lag. The
client just echoes the message back to the server. The time
between sending and receiving the message in the server is
considered to be the current lag of the respective player.

The two byte sequence number is included to be able to deal with
lost or severely delayed messages. On each ping sent by the server,
the sequence number is incremented (modulo 10000). The server
manages this number on a per player basis.

MsgReplayReset
+----+----+----+----+----+
| 00 | 01 | 72 | 72 | lp |
+----+----+----+----+----+
Sent by the server to active replay observers to remove state
information that they might have regarding players and flags.
The 'lp' value is the last player to be removed. PlayerId's above
'lp' are replay observers, and are not removed.

== UDP negotiation ==

*solo bots don't do this, they should use the existing player's connection

*MsgUDPLinkRequest = 0x6f66; // 'of'

*MsgUDPLinkEstablished = 0x6f67; // 'og'

*if client has udp enabled player sends MsgUDPLinkRequest with player number over udp

*if request has valid player number and is from same address server sends MsgUDPLinkEstablished over tcp to confirm inbound server sends MsgUDPLinkRequest back over udp to test outbound

*player gets MsgUDPLinkEstablished and starts sending udp

*player gets MsgUDPLinkRequest and sends MsgUDPLinkEstablished over udp

*server gets MsgUDPLinkEstablished
server can now send over udp

[[Category:Concepts]]