BZFlagWiki - User contributions [en]

IRC Cloaks

2015-04-12T18:45:58Z

JeffM2501:

Since BZFlag is a registered project with the Freenode IRC network, we are able to give you IRC cloaks (custom hostmasks) for the project.

They are available to developers, server owners, and players that have helped the project out or been affiliated for a significant time.

==Process==
Cloaks must be requested with one of the project administrators (TimRiker, Blast007, and brlcad). It is the sole discretion of the project administrators on the use and distribution of cloaks.

They must (only) be requested in person on IRC. Do not send requests via BZBB or via E-mail. Send one of the project administrators a private message on IRC stating that you'd like to have a cloak and what you think that cloak should be.

Users that request cloaks must be registered on BZBB and have a valid E-Mail address attached to the name.

==Usage==
Users that have a BZFlag cloak must conduct themselves in a mature and civil manner at all times on Freenode. The cloak associates you as a representative of the project and your behavior should not reflect poorly upon the BZFlag community. Users that do not conduct themselves in a reasonable manner will have their cloaks removed.

==Cloak Format==
All BZFlag cloaks follow a standard format. There are different cloaks available depending on the amount of involvement in the project.

; /bzflag/player/BZ_NAME
: Long-time players in good standing can request a player cloak. Long-time means you've been playing for at least 6 months. You should have an established BZFlag callsign that you've been using over that timeframe.

; /bzflag/contributor/BZ_NAME
: Users that are contributors to the project in additional ways.

; /bzflag/serverop/BZ_NAME
: Server owners that run major servers that fully support global services, and promote good clean play can get a server owner cloak.

; /bzflag/developer/BZ_NAME
: Users that are developers (i.e., have commit access) can get a developer cloak.

; /bzflag/projectadmin/BZ_NAME
: Project administrators are allowed a project admin cloak.

'''BZ_NAME''' is your registered BZBB username. Spaces or Underscores "_" will be removed from cloaks.

==Examples==
; Player : /bzflag/player/SportChick/essy
; Contributor : /bzflag/contributor/ibot
; Server Op : /bzflag/serverop/Manu
; Developer : /bzflag/developer/Chestal
; Admin : /bzflag/projectadmin/learner

Category:Development

2015-04-12T18:45:34Z

JeffM2501:

==Overview==
BZFlag is developed as an open source guided development process involving a number of developers all over the world.

==Organization==
Open source development tends to not have as formal a structure as traditional development, but the bzflag project does have a group of developers that are responsible for various aspects of projet.

===Copyright Maintainer===
Tim Riker (TimRiker) is the copyright holder and intellectual property manager for the project and manages its various legal operations.

===Development Leads===
Scott Wichser (Blast007) and Jeff Makey (Bullet Catcher) are the development leads. They are responsible for the day to day development and planning of the various releases of BZFlag. They maintain the [[BZFlag Source]] Code, [[BZFlag_SVN|SVN]] repository, and ensure that development of the game goes according to the design goals and [[Development_RoadMap]].

===Service Managers===
Scott Wichser (Blast007) and Joe Vano (JoeVano) manage the public services that BZFlag clients and servers use such as the [[List Server]] and [[Global Registration]] System.

====Forum Administrators====
A number of community members maintain the [[BZFlag Forums]] including;

* L4m3r
* DTRemenak
* BRLCAD
* Blast007
* Bryjen
* joevano
* Bullet Catcher
* Constitution

==Communications==
Development communications mostly happens in the [[BZFlag_on_IRC|BZFlag IRC channel]]. There are development mailing lists on the sourceforge site but they are rarely used. Many developers are often on the IRC channel and are more then willing to discuss things relating to bzflag development.

==Coding Policy==
BZFlag has a documented coding policy that is in the DEVINFO file that is included with every source code release.

==Wiki Development Design Templates==
In order to help out developers in building collaborative documents, the wiki has several templates that can be used to setup documents.

'''IdeaDesign''' This template is intended to be used to flesh out an idea or proposed change that has not yet been accepted but is being worked on by multiple people. This is where all new ideas should start.

'''DesignDocument''' Once an idea or change has been approved and made part of the development plan it will be changed to a Design Document. This indicates that the feature can be worked on in the development codebase by any developer.

'''Specification''' If additional documentation is needed for a feature then those documents can use this template. Specifications should also be put into a category or name space with the associated design document overview.

===Notes on Patches===
Some ideas may not be accepted by the development community right away, if the idea proposer wishes to implement the idea or parts of the idea to prove it out then those changes should be submitted to the [http://sourceforge.net/tracker/?group_id=3248&atid=303248 SourceForge Patch Tracker]. This will allow developers and team leaders to review the patch and decide if it should be included in the mainline release. It also lets other use or extend the code changes for private use.

==Resources==
[[SVN]] repository stored on Source Forge.

[[BZFlag Source]] Information on the source code for the game.

[[BZFS API]] Information on the API for plug-in development.

[http://sourceforge.net/tracker/?group_id=3248&atid=303248 SourceForge Patch Tracker] where code changes from new developers are submitted.

[http://sourceforge.net/tracker/?group_id=3248&atid=103248 SourceForge Bug Tracker] where users report bugs or problems in the game.

[http://sourceforge.net/tracker/?group_id=3248&atid=353248 SourceForge Feature Requests] where users request new features ( pending approval).

==Helping Out==
BZFlag can always use new developers. Users that wish to become more involved in the development process are encouraged to join the IRC channel and talk to the developers and players there.

The next step is to submit patches to the patch tracker so the new developer can get the hang of how the codebase works and so that project management can evaluate the coding ability/style of the new developer. The best way to get started is to take a look at the bugs in the Bug Tracker.

If a new developer fits into the project well and is productive they will often be given '''commit access''' to the SVN system so they may make changes directly to the code.

==Versions==
The current shipping version is based on the 2.4.2 tag '''tags/v2_4_2/''' in svn

The current development version is 2.4.3 and is maintenance for the 2.4.x line, it is located in '''trunk/bzflag''' in svn.

BZFlag Project

2015-04-12T18:45:02Z

JeffM2501:

The Project Administrators are users responsible for maintaining the global network services of the project.

==Current Administrators==
The current administration staff for the SourceForge project includes:
*[[Tim Riker]]
*[[Scott Wichser]]
*[[Jeff Makey]]

[[Category:Concepts]]

Installing on Linux

2015-01-02T21:22:44Z

JeffM2501: Don't use the zip file on linux, use the tarball

There are various packages of BZFlag available to many different distributions.

== Compiling from Source ==
This document is not designed to cover information about compiling.

{{main|Compiling}}

see also [[ubuntu_and_bzflag_2.4]]

== Installing from tarball ==
You extract it and run the install script as root.

tar -vzxf package.tar.gz
cd bzflag-2.4.2
./configure --prefix=/install/path
make
sudo make install

== Installing using a package manager ==
This depends on your distribution. Different distributions use different package managers.

To understand the command lines please understand:
$ ''indicates a user shell''
# ''indicates a root shell''

$ sudo ''is replaceable by'' #

=== Graphical Package Managers ===
Search for "BZFlag" and install it. 
BZFlag will most likely be sorted to the Games category.

=== Fedora / Red Hat / Mandriva / SUSE ===
$ sudo yum install bzflag

For the server package:
$ sudo yum install bzflag-server

=== Native RPM ===
$ sudo rpm -ivh bzflag.x86.208.rpm

=== Ubuntu / Debian ===
$ sudo apt-get install bzflag

For the server package:
$ sudo apt-get install bzflag-server

=== Other Debian / DPKG ===

If you're only using the DPKG/Apt package manager you will be abled to install your downloaded package with the following command:

# dpkg -i package.deb

Replace package.deb with the particular package you want to install (e.g. bzflag-2.0.13.deb).

Download required packages from here: http://packages.debian.org/sid/bzflag

* bzflag
* bzflag-data
* bzflag-client
* bzflag-server

Please note that you need to resolve any further dependencies yourself, DPKG can't do this for you.

=== Arch ===

# pacman -S bzflag

=== Gentoo ===

# emerge bzflag

== External Links ==
* http://sourceforge.net/projects/bzflag/files/ Official BZFlag file repository on SourceForge
* http://packages.debian.org/sid/bzflag BZFlag-packages for debian sid in the official debian repository

[[Category:Installing]]
[[Category:Tutorials]]

Bz getShotGUID

2014-04-19T22:09:51Z

JeffM2501: Created page with "{{BZFS_API_Doc}} {{BZFS_API_Funcs}} ==Prototype== BZF_API uint32_t bz_getShotGUID (int fromPlayer, int shotID); ==Parameters== {| border="1" cellpadding="20" cellspacing="0" ..."

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API uint32_t bz_getShotGUID (int fromPlayer, int shotID);

==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value description
|-
|fromPlayer
|int
|the player who owns the shot, BZ_SERVER for world weapons
|-
|shotID
|int
|the local ID of the shot for the specified player
|}

==Description==
This API function will return the Globally Unique Identifier(GUID) for the specified shot if it exists, or 0 if it does not.

==Notes==
Shot GUIDs are unique to each shot fired (within a range of over 4 billion shots fired per server session). This ID can be useful to detect unique shots independent of player reload timers.

Bz shotHasMetaData

2014-04-19T22:06:50Z

JeffM2501: Created page with "{{BZFS_API_Doc}} {{BZFS_API_Funcs}} ==Prototype== BZF_API bool bz_shotHasMetaData (int fromPlayer, int shotID , const char* name); ==Parameters== {| border="1" cellpadding="20..."

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API bool bz_shotHasMetaData (int fromPlayer, int shotID , const char* name);
==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value desription
|-
|fromPlayer
|int
|the player who owns the shot, BZ_SERVER for world weapons
|-
|shotID
|int
|the local ID of the shot for the specified player
|-
|name
|const char*
|the name of the MetaData value to check
|}

==Description==
This API function will return true if the specified shot exists and has data stored under the specified name.

==Notes==
Shot MetaData is useful for plug-ins that need to fake extra player shots with server based world weapons. Using MetaData a plug-in can store player or score information with the shot to be used later when the shot hits a target or expires. Shot MetaData is server side only and is unique to each shot fired. Multiple shots with the same ID over time will not contain the same data.

Bz setShotMetaData

2014-04-19T22:05:38Z

JeffM2501: Created page with "{{BZFS_API_Doc}} {{BZFS_API_Funcs}} ==Prototype== BZF_API void_t bz_setShotMetaData (int fromPlayer, int shotID, const char* name, uint32_t value); ==Parameters== {| border="1..."

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API void_t bz_setShotMetaData (int fromPlayer, int shotID, const char* name, uint32_t value);
==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value desription
|-
|fromPlayer
|int
|the player who owns the shot, BZ_SERVER for world weapons
|-
|shotID
|int
|the local ID of the shot for the specified player
|-
|name
|const char*
|the name of the MetaData value to set
|-
|name
|uint32
|the value to associate with the shot
|}

==Description==
This API function will set the specified data and associated it with the specified shot. If the shot does not exist the function will do nothing. Setting data for a name on a shot will replace any previous data that was associated with the name.

==Notes==
Shot MetaData is useful for plug-ins that need to fake extra player shots with server based world weapons. Using MetaData a plug-in can store player or score information with the shot to be used later when the shot hits a target or expires. Shot MetaData is server side only and is unique to each shot fired. Multiple shots with the same ID over time will not contain the same data.

Bz getShotMetaData

2014-04-19T22:03:15Z

JeffM2501: Created page with "{{BZFS_API_Doc}} {{BZFS_API_Funcs}} ==Prototype== BZF_API uint32_t bz_getShotMetaData (int fromPlayer, int shotID, const char* name); ==Parameters== {| border="1" cellpadding=..."

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API uint32_t bz_getShotMetaData (int fromPlayer, int shotID, const char* name);
==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value desription
|-
|fromPlayer
|int
|the player who owns the shot, BZ_SERVER for world weapons
|-
|shotID
|int
|the local ID of the shot for the specified player
|-
|name
|const char*
|the name of the MetaData value to get
|}

==Description==
This API function will return the data associated with the specified name for the specified shot. If the shot does not exist, or does not have any data for the name the function will return 0

==Notes==
Shot MetaData is useful for plug-ins that need to fake extra player shots with server based world weapons. Using MetaData a plug-in can store player or score information with the shot to be used later when the shot hits a target or expires. Shot MetaData is server side only and is unique to each shot fired. Multiple shots with the same ID over time will not contain the same data.

Functions (API)

2014-04-19T21:57:20Z

JeffM2501: /* Shot Type Control */

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
Verify future API functions.
}}

{{BZFS_API_Doc}}

== Overview ==

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.

== Function Groups ==
Functions are broken into a series of groups based on the type of action or information they deal with.

=== Event Registration ===
2.0.x
BZF_API bool [[bz_registerEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
BZF_API bool [[bz_removeEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
2.3+
BZF_API bool [[Register]] ( [[Event(API)|bz_eEventType]] eventType );
virtual void Cleanup() {Flush();}

=== Non-Player Connections ===
2.3+
BZF_API bool [[bz_registerNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_removeNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_sendNonPlayerData]] ( int connectionID, const void *data, unsigned int size );
BZF_API bool [[bz_disconectNonPlayerConnection]] ( int connectionID );
BZF_API unsigned int [[bz_getNonPlayerConnectionOutboundPacketCount]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionIP]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionHost]] ( int connectionID );

=== Player Information ===
==== Player Information ====
2.3+
BZF_API bool [[bz_hasPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_getAdmin]] ( int playerID );
BZF_API bz_eTeamType [[bz_getPlayerTeam]] ( int playerID );
BZF_API const char* [[bz_getPlayerCallsign]] ( int playerID );
BZF_API const char* [[bz_getPlayerIPAddress]] ( int playerID );
BZF_API const char* [[bz_getPlayerFlag]] ( int playerID );
?
BZF_API const char* [[bz_getPlayerReferrer]] ( int playerID );
BZF_API const char* [[bz_getPlayerCustomData]] (int playerID, const char* key );

==== Player State Information ====
2.3+
BZF_API bool [[bz_isPlayerPaused]] ( int playerID );
BZF_API bool [[bz_canPlayerSpawn]]( int playerID );
BZF_API bool [[bz_getPlayerCurrentState]] ( int playerID, bz_PlayerUpdateState &state );
?
BZF_API bool [[bz_getPlayerPosition]] ( int playerID, float pos[3], bool extrapolate );
BZF_API bool [[bz_getPlayerRotation]] ( int playerID, float *rot, bool extrapolate );
BZF_API bool [[bz_getPlayerVelocity]] ( int playerID, float vel[3] );
BZF_API bool [[bz_getPlayerAngVel]] ( int playerID, float *angvel );
BZF_API bool [[bz_getPlayerPhysicsDriver]] ( int playerID, int* phydrv );

==== Player Lists and Records ====
2.3+
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByIndex]] ( int index );
BZF_API bool [[bz_updatePlayerData]] ( [[bz_BasePlayerRecord]] *playerRecord );
BZF_API bool [[bz_freePlayerRecord]] ( [[bz_BasePlayerRecord]] *playerRecord );

BZF_API [[bz_APIIntList]] *[[bz_newIntList]] ( void );
BZF_API [[bz_APIIntList]] *[[bz_getPlayerIndexList]] ( void );
BZF_API bool [[bz_getPlayerIndexList]] ( [[bz_APIIntList]] *playerList );
BZF_API void [[bz_deleteIntList]] ( [[bz_APIIntList]] *l);

Unknown
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByCallsign]] ( const char* name );

==== Player Management ====
2.3+
BZF_API bool [[bz_grantPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_revokePerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_validAdminPassword]] ( const char* passwd );
BZF_API bool [[bz_setPlayerOperator]] ( int playerId );
?
BZF_API bool [[bz_setPlayerSpawnable]]( int playerID, bool spawn );
BZF_API bool [[bz_setPlayerLimboMessage]]( int playerID, const char* text );
BZF_API bool [[bz_setPlayerCustomData]] (int playerID, const char* key, const char* data );

=== Team Management ===
2.3+
BZF_API unsigned int [[bz_getTeamPlayerLimit]] ( bz_eTeamType team );
BZF_API int [[bz_getTeamCount]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamScore]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamWins]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamLosses]] ([[bz_eTeamType]] team );
BZF_API void [[bz_setTeamWins]] ([[bz_eTeamType]] team, int wins );
BZF_API void [[bz_setTeamLosses]] ([[bz_eTeamType]] team, int losses );
BZF_API void [[bz_resetTeamScore]] ([[bz_eTeamType]] team );
BZF_API void [[bz_resetTeamScores]] ( void );
?
BZF_API void [[bz_changeTeam]]( int player, [[bz_eTeamType]] team );

=== Score Management ===
2.3+
BZF_API bool [[bz_setPlayerWins]] ( int playerId, int wins );
BZF_API bool [[bz_setPlayerLosses]] ( int playerId, int losses );
BZF_API bool [[bz_setPlayerTKs]] ( int playerId, int tks );
BZF_API bool [[bz_resetPlayerScore]] ( int playerId );
BZF_API int [[bz_getPlayerWins]] ( int playerId );
BZF_API int [[bz_getPlayerLosses]] ( int playerId );
BZF_API int [[bz_getPlayerTKs]] ( int playerId );
BZF_API float [[bz_getPlayerRank]] ( int playerId );

=== Latency Information ===
2.3+
BZF_API int [[bz_getPlayerLag]] ( int playerId );
BZF_API int [[bz_getPlayerJitter]] ( int playerId );
BZF_API float [[bz_getPlayerPacketloss]] ( int playerId );
BZF_API int [[bz_getIdleTime]] ( int playerId );
BZF_API int [[bz_getPausedTime]] ( int playerId );

=== Permission Group Management ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getGroupList]] ( void );
BZF_API [[bz_APIStringList]]* [[bz_getGroupPerms]] ( const char* group );
BZF_API bool [[bz_groupAllowPerm]] ( const char* group, const char* perm );

=== Chat Messages ===
2.3+
BZF_API bool [[bz_sendTextMessage]] (int from, int to, const char* message);
BZF_API bool [[bz_sendTextMessage]] (int from, [[bz_eTeamType]] to, const char* message);
BZF_API bool [[bz_sendTextMessagef]] (int from, int to, const char* fmt, ...);
BZF_API bool [[bz_sendTextMessagef]] (int from, [[bz_eTeamType]] to, const char* fmt, ...);
?
BZF_API bool [[bz_sendFetchResMessage]] ( int playerID, const char* URL );
BZF_API bool [[bz_sendJoinServer]] ( int playerID, const char* address, int port, int team, const char* referrer, const char* message );
BZF_API bool [[bz_sendLuaData]] ( int dstPlayerID, int dstScriptID, int statusBits, const char* data, int len,
int srcPlayerID = 0, int srcScriptID = 0 );

=== Server Management ===
2.3+
BZF_API bool [[bz_restart]] ( void );
BZF_API void [[bz_shutdown]] ();
BZF_API void [[bz_superkill]] ();
BZF_API void [[bz_gameOver]] ( int playerID, bz_eTeamType = eNoTeam );
BZF_API void [[bz_reloadLocalBans]] ();
BZF_API void [[bz_reloadMasterBans]] ();
BZF_API void [[bz_reloadGroups]] ();
BZF_API void [[bz_reloadUsers]] ();
BZF_API void [[bz_reloadHelp]] ();
BZF_API int [[bz_getPlayerCount]] ( void );
BZF_API bool [[bz_getShotMismatch]] ( void );
BZF_API void [[bz_setShotMismatch]] ( bool value );
?
BZF_API bool [[bz_anyPlayers]] ( void );

=== Rabbit Hunt ===
?
BZF_API void [[bz_newRabbit]] ( int player, bool swap );
BZF_API void [[bz_removeRabbit]] ( int player );

=== Map Management ===
2.3+
BZF_API void [[bz_setClientWorldDownloadURL]] ( const char* URL );
BZF_API const [[bz_ApiString]] [[bz_getClientWorldDownloadURL]] ( void );
BZF_API bool [[bz_saveWorldCacheFile]] ( const char* file );

=== Flag Management ===
2.3+
BZF_API bool [[bz_givePlayerFlag]] ( int playerID, const char* flagType, bool force );
BZF_API bool [[bz_removePlayerFlag]] ( int playerID );
BZF_API void [[bz_resetFlags]] ( bool onlyUnused, bool keepTeamFlags = false );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName|bz_getName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API int [[bz_getPlayerFlagID]] ( int playerID );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3] );
BZF_API bool [[bz_RegisterCustomFlag]] ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

=== Shot Type Control ===
?
BZF_API bool [[bz_setPlayerShotType]] ( int playerId, [[bz_eShotType]] shotType );

=== Shot Management ===
2.4.5+
BZF_API uint32_t [[bz_getShotMetaData]] (int fromPlayer, int shotID, const char* name);
BZF_API void [[bz_setShotMetaData]] (int fromPlayer, int shotID , const char* name, uint32_t value);
BZF_API bool [[bz_shotHasMetaData]] (int fromPlayer, int shotID , const char* name);
BZF_API uint32_t [[bz_getShotGUID]] (int fromPlayer, int shotID);

=== World Weapon Management ===
2.3+
BZF_API bool [[bz_fireWorldWep]] ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API bool [[bz_fireWorldWep]] ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int *shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt, bz_eTeamType shotTeam = eRogueTeam );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

?
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );

=== Global Database Management (BZDB) ===
2.3+
BZF_API double [[bz_getBZDBDouble]] ( const char* variable );
BZF_API [[bz_ApiString]] [[bz_getBZDBString]] ( const char* variable );
BZF_API bool [[bz_getBZDBBool]] ( const char* variable );
BZF_API int [[bz_getBZDBInt]] ( const char* variable );
BZF_API int [[bz_getBZDBItemPerms]] ( const char* variable );
BZF_API bool [[bz_getBZDBItemPesistent]] ( const char* variable );
BZF_API bool [[bz_BZDBItemExists]] ( const char* variable );
BZF_API bool [[bz_setBZDBDouble]] ( const char* variable, double val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBString]] ( const char* variable, const char *val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBBool]] ( const char* variable, bool val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBInt]] ( const char* variable, int val, int perms = 0, bool persistent = false );
BZF_API int [[bz_getBZDBVarList]] ( bz_APIStringList *varList );
BZF_API void [[bz_resetBZDBVar]] ( const char* variable );
BZF_API void [[bz_resetALLBZDBVars]] ( void );

=== Logging ===
2.3+
BZF_API void [[bz_debugMessage]] ( int level, const char* message );
BZF_API void [[bz_debugMessagef]] ( int level, const char* fmt, ... )
BZF_API int [[bz_getDebugLevel]] ( void );

=== Server Administration ===
2.3+
BZF_API bool [[bz_kickUser]] ( int playerIndex, const char* reason, bool notify );
BZF_API bool [[bz_IPBanUser]] ( int bannedByIndex, const char* ip, int duration, const char* reason );
BZF_API bool [[bz_HostBanUser]] ( int bannedByIndex, const char* hostmask, int duration, const char* reason );
BZF_API bool [[bz_IPUnbanUser]] ( const char* ip );
BZF_API bool [[bz_IDUnbanUser]] ( const char* bzID );
BZF_API bool [[bz_HostUnbanUser]] ( const char* hostmask );

BZF_API int [[bz_getLagWarn]] ( void );
BZF_API bool [[bz_setLagWarn]] ( int lagwarn );
BZF_API bool [[bz_pollActive]] ( void );
BZF_API bool [[bz_pollVeto]] ( void );

?
BZF_API bool [[bz_IDBanUser]] ( int bannedByIndex, const char* bzID , int duration, const char *reason );

=== Reporting ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getReports]] ( void );
?
BZF_API unsigned int [[bz_getReportCount]] ( void );
BZF_API const char* [[bz_getReportSource]] ( unsigned int id );
BZF_API const char* [[bz_getReportBody]] ( unsigned int id );
BZF_API const char* [[bz_getReportTime]] ( unsigned int id );
BZF_API bool [[bz_clearReport]] ( unsigned int id );
BZF_API bool [[bz_clearAllReports]] ( void );
BZF_API bool [[bz_fileReport]] ( const char* message, const char* from );

=== Timed Game Management ===
2.3+
BZF_API bool [[bz_setTimeLimit]] ( float timeLimit );
BZF_API float [[bz_getTimeLimit]] ( void );
BZF_API bool [[bz_isTimeManualStart]] ( void );
BZF_API bool [[bz_isCountDownActive]] ( void );
BZF_API bool [[bz_isCountDownInProgress]] ( void );
BZF_API bool [[bz_isCountDownPaused]] ( void );
BZF_API void [[bz_pauseCountdown]] ( const char *pausedBy );
BZF_API void [[bz_resumeCountdown]] ( const char *resumedBy );
BZF_API void [[bz_startCountdown]] ( int delay, float limit, const char *byWho );

=== Custom Text Commands ===
2.3+
BZF_API bool [[bz_registerCustomSlashCommand]] ( const char* command, [[bz_CustomSlashCommandHandler]] *handler );
BZF_API bool [[bz_removeCustomSlashCommand]] ( const char* command );

=== Plug-in Management ===
2.3+
BZF_API int [[bz_getLoadedPlugins]] ( [[bz_APIStringList]] * list );
BZF_API bool [[bz_loadPlugin]] ( const char* path, const char* params );
BZF_API bool [[bz_unloadPlugin]] ( const char* path );
BZF_API const char* [[bz_pluginBinPath]] ( void );
BZF_API bool [[bz_registerCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );
BZF_API bool [[bz_removeCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );

=== Public Server Information ===
2.3+
BZF_API bool [[bz_getPublic]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicAddr]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicDescription]] ( void );
BZF_API int [[bz_getPublicPort]] ( void );
BZF_API void [[bz_updateListServer]] ( void );

=== HTTP Transfer ===
2.3+
BZF_API bool [[bz_addURLJob]] ( const char* URL, [[bz_BaseURLHandler]]* handler = NULL, const char* postData = NULL );
BZF_API bool [[bz_removeURLJob]] ( const char* URL );
?
BZF_API bool [[bz_stopAllURLJobs]] ( void );

=== Callback Functions ===
?
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_callCallback]] ( const char* name, void *param );
BZF_API bool [[bz_callbackExists]] ( const char* name );

=== Inter-Plug-in Communications ===
2.3+
BZF_API bool [[bz_clipFieldExists]] ( const char *name );
BZF_API const char* [[bz_getclipFieldString]] ( const char *name );
BZF_API float [[bz_getclipFieldFloat]] ( const char *name );
BZF_API int [[bz_getclipFieldInt]] ( const char *name );
BZF_API bool [[bz_setclipFieldString]] ( const char *name, const char* data );
BZF_API bool [[bz_setclipFieldFloat]] ( const char *name, float data );
BZF_API bool [[bz_setclipFieldInt]] ( const char *name, int data );
BZF_API bool [[bz_addClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );
BZF_API bool [[bz_removeClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );

=== Game Recording ===
2.3+
BZF_API bool [[bz_saveRecBuf]] ( const char * _filename, int seconds);
BZF_API bool [[bz_startRecBuf]] ( void );
BZF_API bool [[bz_stopRecBuf]] ( void );

=== Map Management ===
==== Map Information ====
?
BZF_API void [[bz_getWorldSize]] ( float *size, float *wallHeight );
BZF_API unsigned int [[bz_getWorldObjectCount]] ( void );
BZF_API [[bz_APIWorldObjectList]]* [[bz_getWorldObjectList]] ( void );
BZF_API void [[bz_releaseWorldObjectList]] ( [[bz_APIWorldObjectList]] *list );
BZF_API unsigned int [[bz_findWorldObject]] ( const char *name );
BZF_API [[bz_APIBaseWorldObject]]* [[bz_getWorldObjectByID]] ( unsigned int id );
BZF_API bool [[bz_getTeleLinkIDs]] ( const char* teleName, int* frontLink, int* backLink );
BZF_API const char* [[bz_getLinkTeleName]] ( int linkIndex );
BZF_API int [[bz_getPhyDrvID]] ( const char* phyDrvName );
BZF_API const char* [[bz_getPhyDrvName]] ( unsigned int phyDrvID );
BZF_API bool [[bz_SetWorldObjectTangibility]] ( int id, const [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API bool [[bz_GetWorldObjectTangibility]] ( int id, [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API void [[bz_ResetWorldObjectTangibilities]] ( void );

==== Map Collisions ====
?
[[bz_eAPIColType]] [[bz_cylinderInMapObject]] ( float pos[3], float height, float radius, [[bz_APIBaseWorldObject]] **object );
[[bz_eAPIColType]] [[bz_boxInMapObject]] ( float pos[3], float size[3], float angle, [[bz_APIBaseWorldObject]] **object );

==== Custom Map Objects ====
2.3+
BZF_API bool [[bz_registerCustomMapObject]] ( const char* object, [[bz_CustomMapObjectHandler]] *handler );
BZF_API bool [[bz_removeCustomMapObject]] ( const char* object );

=== Utility ===
2.3+
BZF_API const char *[[bz_MD5]] ( const char* str );
BZF_API const char *[[bz_MD5]] ( const void* data, size_t size );
BZF_API const char *[[bz_getServerVersion]] ( void );
BZF_API const char *[[bz_getProtocolVersion]] ( void );

=== Misc ===
2.3+
BZF_API bool [[bz_getStandardSpawn]] ( int playerID, float pos[3], float *rot );
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase);
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase, int killerID = -1, const char* flagID = NULL );
BZF_API bool [[bz_sendPlayCustomLocalSound]] ( int playerID, const char* soundName );
BZF_API [[bz_ApiString]] [[bz_filterPath]] ( const char* path );
BZF_API const char *[[bz_format]](const char* fmt, ...)_ATTRIBUTE12;
BZF_API const char *[[bz_toupper]](const char* val );
BZF_API const char *[[bz_tolower]](const char* val );
BZF_API const char *[[bz_urlEncode]](const char* val );
BZF_API [[bz_eGameType]] [[bz_getGameType]]( void );
BZF_API [[bz_eTeamType]] [[bz_checkBaseAtPoint]] ( float pos[3] );
BZF_API int [[bz_APIVersion]] ( void );
?
BZF_API bool [[bz_allowJumping]] ( void );

=== Server Side Players (Development) ===
? (In API for 2.3+, but will crash a server)
BZF_API int [[bz_addServerSidePlayer]] ( [[bz_ServerSidePlayerHandler]] *handler );
BZF_API bool [[bz_removeServerSidePlayer]] ( int playerID, [[bz_ServerSidePlayerHandler]] *handler );

== See also ==
[[BZFS API]]

[[plug-ins]]

[[Category:BZFS_API_Functions]]

Bz fireWorldWep

2014-04-19T18:43:25Z

JeffM2501: /* Prototype */

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototypes==
BZF_API bool bz_fireWorldWep ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt , bz_eTeamType shotTeam = eRogueTeam );

BZF_API bool bz_fireWorldWep ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int *shotID , float dt , bz_eTeamType shotTeam = eRogueTeam );

==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value desription
|-
|flagType
|const char*
|Flag type the world weapon will fire with
|-
|lifetime
|float
|How long the world weapon will "live".
|-
|fromPlayer
|int
|Player ID that fired the shot, or BZ_SERVER.
|-
|*pos
|float
|Position the world weapon will fire from.
|-
|tilt
|float
|The tilt of the weapon in radians.
|-
|direction
|float
|The direction of which to fire the world weapon in radians. (rotation)
|-
|shotID
|int (or int * for second version)
|Shot ID of the world weapon. Each shot is given a unique shot ID for shot tracking. For the second version a pointer to an int that will contain the generated shot ID.
|-
|dt
|float
|Delay time. How many seconds the weapon waits before firing.
|-
|shotTeam
|bz_eTeamType
|Team color of the weapon. (Rogue by default)
|}

==Description==
This API function will fire w worldweapon at the specified location with the specified parameters.

Bz fireWorldWep

2014-04-19T18:43:11Z

JeffM2501:

{{BZFS_API_Doc}}
{{BZFS_API_Funcs}}
==Prototype==
BZF_API bool bz_fireWorldWep ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt , bz_eTeamType shotTeam = eRogueTeam );

BZF_API bool bz_fireWorldWep ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int *shotID , float dt , bz_eTeamType shotTeam = eRogueTeam );

==Parameters==
{| border="1" cellpadding="20" cellspacing="0"
!name
!type
!value desription
|-
|flagType
|const char*
|Flag type the world weapon will fire with
|-
|lifetime
|float
|How long the world weapon will "live".
|-
|fromPlayer
|int
|Player ID that fired the shot, or BZ_SERVER.
|-
|*pos
|float
|Position the world weapon will fire from.
|-
|tilt
|float
|The tilt of the weapon in radians.
|-
|direction
|float
|The direction of which to fire the world weapon in radians. (rotation)
|-
|shotID
|int (or int * for second version)
|Shot ID of the world weapon. Each shot is given a unique shot ID for shot tracking. For the second version a pointer to an int that will contain the generated shot ID.
|-
|dt
|float
|Delay time. How many seconds the weapon waits before firing.
|-
|shotTeam
|bz_eTeamType
|Team color of the weapon. (Rogue by default)
|}

==Description==
This API function will fire w worldweapon at the specified location with the specified parameters.

Functions (API)

2014-04-19T18:42:08Z

JeffM2501: /* World Weapon Management */

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
Verify future API functions.
}}

{{BZFS_API_Doc}}

== Overview ==

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.

== Function Groups ==
Functions are broken into a series of groups based on the type of action or information they deal with.

=== Event Registration ===
2.0.x
BZF_API bool [[bz_registerEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
BZF_API bool [[bz_removeEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
2.3+
BZF_API bool [[Register]] ( [[Event(API)|bz_eEventType]] eventType );
virtual void Cleanup() {Flush();}

=== Non-Player Connections ===
2.3+
BZF_API bool [[bz_registerNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_removeNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_sendNonPlayerData]] ( int connectionID, const void *data, unsigned int size );
BZF_API bool [[bz_disconectNonPlayerConnection]] ( int connectionID );
BZF_API unsigned int [[bz_getNonPlayerConnectionOutboundPacketCount]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionIP]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionHost]] ( int connectionID );

=== Player Information ===
==== Player Information ====
2.3+
BZF_API bool [[bz_hasPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_getAdmin]] ( int playerID );
BZF_API bz_eTeamType [[bz_getPlayerTeam]] ( int playerID );
BZF_API const char* [[bz_getPlayerCallsign]] ( int playerID );
BZF_API const char* [[bz_getPlayerIPAddress]] ( int playerID );
BZF_API const char* [[bz_getPlayerFlag]] ( int playerID );
?
BZF_API const char* [[bz_getPlayerReferrer]] ( int playerID );
BZF_API const char* [[bz_getPlayerCustomData]] (int playerID, const char* key );

==== Player State Information ====
2.3+
BZF_API bool [[bz_isPlayerPaused]] ( int playerID );
BZF_API bool [[bz_canPlayerSpawn]]( int playerID );
BZF_API bool [[bz_getPlayerCurrentState]] ( int playerID, bz_PlayerUpdateState &state );
?
BZF_API bool [[bz_getPlayerPosition]] ( int playerID, float pos[3], bool extrapolate );
BZF_API bool [[bz_getPlayerRotation]] ( int playerID, float *rot, bool extrapolate );
BZF_API bool [[bz_getPlayerVelocity]] ( int playerID, float vel[3] );
BZF_API bool [[bz_getPlayerAngVel]] ( int playerID, float *angvel );
BZF_API bool [[bz_getPlayerPhysicsDriver]] ( int playerID, int* phydrv );

==== Player Lists and Records ====
2.3+
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByIndex]] ( int index );
BZF_API bool [[bz_updatePlayerData]] ( [[bz_BasePlayerRecord]] *playerRecord );
BZF_API bool [[bz_freePlayerRecord]] ( [[bz_BasePlayerRecord]] *playerRecord );

BZF_API [[bz_APIIntList]] *[[bz_newIntList]] ( void );
BZF_API [[bz_APIIntList]] *[[bz_getPlayerIndexList]] ( void );
BZF_API bool [[bz_getPlayerIndexList]] ( [[bz_APIIntList]] *playerList );
BZF_API void [[bz_deleteIntList]] ( [[bz_APIIntList]] *l);

Unknown
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByBZID]] ( int BZID );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByCallsign]] ( const char* name );

==== Player Management ====
2.3+
BZF_API bool [[bz_grantPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_revokePerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_validAdminPassword]] ( const char* passwd );
BZF_API bool [[bz_setPlayerOperator]] ( int playerId );
?
BZF_API bool [[bz_setPlayerSpawnable]]( int playerID, bool spawn );
BZF_API bool [[bz_setPlayerLimboMessage]]( int playerID, const char* text );
BZF_API bool [[bz_setPlayerCustomData]] (int playerID, const char* key, const char* data );

=== Team Management ===
2.3+
BZF_API unsigned int [[bz_getTeamPlayerLimit]] ( bz_eTeamType team );
BZF_API int [[bz_getTeamCount]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamScore]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamWins]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamLosses]] ([[bz_eTeamType]] team );
BZF_API void [[bz_setTeamWins]] ([[bz_eTeamType]] team, int wins );
BZF_API void [[bz_setTeamLosses]] ([[bz_eTeamType]] team, int losses );
BZF_API void [[bz_resetTeamScore]] ([[bz_eTeamType]] team );
BZF_API void [[bz_resetTeamScores]] ( void );
?
BZF_API void [[bz_changeTeam]]( int player, [[bz_eTeamType]] team );

=== Score Management ===
2.3+
BZF_API bool [[bz_setPlayerWins]] ( int playerId, int wins );
BZF_API bool [[bz_setPlayerLosses]] ( int playerId, int losses );
BZF_API bool [[bz_setPlayerTKs]] ( int playerId, int tks );
BZF_API bool [[bz_resetPlayerScore]] ( int playerId );
BZF_API int [[bz_getPlayerWins]] ( int playerId );
BZF_API int [[bz_getPlayerLosses]] ( int playerId );
BZF_API int [[bz_getPlayerTKs]] ( int playerId );
BZF_API float [[bz_getPlayerRank]] ( int playerId );

=== Latency Information ===
2.3+
BZF_API int [[bz_getPlayerLag]] ( int playerId );
BZF_API int [[bz_getPlayerJitter]] ( int playerId );
BZF_API float [[bz_getPlayerPacketloss]] ( int playerId );
BZF_API int [[bz_getIdleTime]] ( int playerId );
BZF_API int [[bz_getPausedTime]] ( int playerId );

=== Permission Group Management ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getGroupList]] ( void );
BZF_API [[bz_APIStringList]]* [[bz_getGroupPerms]] ( const char* group );
BZF_API bool [[bz_groupAllowPerm]] ( const char* group, const char* perm );

=== Chat Messages ===
2.3+
BZF_API bool [[bz_sendTextMessage]] (int from, int to, const char* message);
BZF_API bool [[bz_sendTextMessage]] (int from, [[bz_eTeamType]] to, const char* message);
BZF_API bool [[bz_sendTextMessagef]] (int from, int to, const char* fmt, ...);
BZF_API bool [[bz_sendTextMessagef]] (int from, [[bz_eTeamType]] to, const char* fmt, ...);
?
BZF_API bool [[bz_sendFetchResMessage]] ( int playerID, const char* URL );
BZF_API bool [[bz_sendJoinServer]] ( int playerID, const char* address, int port, int team, const char* referrer, const char* message );
BZF_API bool [[bz_sendLuaData]] ( int dstPlayerID, int dstScriptID, int statusBits, const char* data, int len,
int srcPlayerID = 0, int srcScriptID = 0 );

=== Server Management ===
2.3+
BZF_API bool [[bz_restart]] ( void );
BZF_API void [[bz_shutdown]] ();
BZF_API void [[bz_superkill]] ();
BZF_API void [[bz_gameOver]] ( int playerID, bz_eTeamType = eNoTeam );
BZF_API void [[bz_reloadLocalBans]] ();
BZF_API void [[bz_reloadMasterBans]] ();
BZF_API void [[bz_reloadGroups]] ();
BZF_API void [[bz_reloadUsers]] ();
BZF_API void [[bz_reloadHelp]] ();
BZF_API int [[bz_getPlayerCount]] ( void );
BZF_API bool [[bz_getShotMismatch]] ( void );
BZF_API void [[bz_setShotMismatch]] ( bool value );
?
BZF_API bool [[bz_anyPlayers]] ( void );

=== Rabbit Hunt ===
?
BZF_API void [[bz_newRabbit]] ( int player, bool swap );
BZF_API void [[bz_removeRabbit]] ( int player );

=== Map Management ===
2.3+
BZF_API void [[bz_setClientWorldDownloadURL]] ( const char* URL );
BZF_API const [[bz_ApiString]] [[bz_getClientWorldDownloadURL]] ( void );
BZF_API bool [[bz_saveWorldCacheFile]] ( const char* file );

=== Flag Management ===
2.3+
BZF_API bool [[bz_givePlayerFlag]] ( int playerID, const char* flagType, bool force );
BZF_API bool [[bz_removePlayerFlag]] ( int playerID );
BZF_API void [[bz_resetFlags]] ( bool onlyUnused, bool keepTeamFlags = false );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName|bz_getName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API int [[bz_getPlayerFlagID]] ( int playerID );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3] );
BZF_API bool [[bz_RegisterCustomFlag]] ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

=== Shot Type Control ===
?
BZF_API bool [[bz_setPlayerShotType]] ( int playerId, [[bz_eShotType]] shotType );

=== World Weapon Management ===
2.3+
BZF_API bool [[bz_fireWorldWep]] ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API bool [[bz_fireWorldWep]] ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int *shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt, bz_eTeamType shotTeam = eRogueTeam );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

?
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );

=== Global Database Management (BZDB) ===
2.3+
BZF_API double [[bz_getBZDBDouble]] ( const char* variable );
BZF_API [[bz_ApiString]] [[bz_getBZDBString]] ( const char* variable );
BZF_API bool [[bz_getBZDBBool]] ( const char* variable );
BZF_API int [[bz_getBZDBInt]] ( const char* variable );
BZF_API int [[bz_getBZDBItemPerms]] ( const char* variable );
BZF_API bool [[bz_getBZDBItemPesistent]] ( const char* variable );
BZF_API bool [[bz_BZDBItemExists]] ( const char* variable );
BZF_API bool [[bz_setBZDBDouble]] ( const char* variable, double val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBString]] ( const char* variable, const char *val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBBool]] ( const char* variable, bool val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBInt]] ( const char* variable, int val, int perms = 0, bool persistent = false );
BZF_API int [[bz_getBZDBVarList]] ( bz_APIStringList *varList );
BZF_API void [[bz_resetBZDBVar]] ( const char* variable );
BZF_API void [[bz_resetALLBZDBVars]] ( void );

=== Logging ===
2.3+
BZF_API void [[bz_debugMessage]] ( int level, const char* message );
BZF_API void [[bz_debugMessagef]] ( int level, const char* fmt, ... )
BZF_API int [[bz_getDebugLevel]] ( void );

=== Server Administration ===
2.3+
BZF_API bool [[bz_kickUser]] ( int playerIndex, const char* reason, bool notify );
BZF_API bool [[bz_IPBanUser]] ( int bannedByIndex, const char* ip, int duration, const char* reason );
BZF_API bool [[bz_HostBanUser]] ( int bannedByIndex, const char* hostmask, int duration, const char* reason );
BZF_API bool [[bz_IPUnbanUser]] ( const char* ip );
BZF_API bool [[bz_IDUnbanUser]] ( const char* bzID );
BZF_API bool [[bz_HostUnbanUser]] ( const char* hostmask );

BZF_API int [[bz_getLagWarn]] ( void );
BZF_API bool [[bz_setLagWarn]] ( int lagwarn );
BZF_API bool [[bz_pollActive]] ( void );
BZF_API bool [[bz_pollVeto]] ( void );

?
BZF_API bool [[bz_IDBanUser]] ( int bannedByIndex, const char* bzID , int duration, const char *reason );

=== Reporting ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getReports]] ( void );
?
BZF_API unsigned int [[bz_getReportCount]] ( void );
BZF_API const char* [[bz_getReportSource]] ( unsigned int id );
BZF_API const char* [[bz_getReportBody]] ( unsigned int id );
BZF_API const char* [[bz_getReportTime]] ( unsigned int id );
BZF_API bool [[bz_clearReport]] ( unsigned int id );
BZF_API bool [[bz_clearAllReports]] ( void );
BZF_API bool [[bz_fileReport]] ( const char* message, const char* from );

=== Timed Game Management ===
2.3+
BZF_API bool [[bz_setTimeLimit]] ( float timeLimit );
BZF_API float [[bz_getTimeLimit]] ( void );
BZF_API bool [[bz_isTimeManualStart]] ( void );
BZF_API bool [[bz_isCountDownActive]] ( void );
BZF_API bool [[bz_isCountDownInProgress]] ( void );
BZF_API bool [[bz_isCountDownPaused]] ( void );
BZF_API void [[bz_pauseCountdown]] ( const char *pausedBy );
BZF_API void [[bz_resumeCountdown]] ( const char *resumedBy );
BZF_API void [[bz_startCountdown]] ( int delay, float limit, const char *byWho );

=== Custom Text Commands ===
2.3+
BZF_API bool [[bz_registerCustomSlashCommand]] ( const char* command, [[bz_CustomSlashCommandHandler]] *handler );
BZF_API bool [[bz_removeCustomSlashCommand]] ( const char* command );

=== Plug-in Management ===
2.3+
BZF_API int [[bz_getLoadedPlugins]] ( [[bz_APIStringList]] * list );
BZF_API bool [[bz_loadPlugin]] ( const char* path, const char* params );
BZF_API bool [[bz_unloadPlugin]] ( const char* path );
BZF_API const char* [[bz_pluginBinPath]] ( void );
BZF_API bool [[bz_registerCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );
BZF_API bool [[bz_removeCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );

=== Public Server Information ===
2.3+
BZF_API bool [[bz_getPublic]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicAddr]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicDescription]] ( void );
BZF_API int [[bz_getPublicPort]] ( void );
BZF_API void [[bz_updateListServer]] ( void );

=== HTTP Transfer ===
2.3+
BZF_API bool [[bz_addURLJob]] ( const char* URL, [[bz_BaseURLHandler]]* handler = NULL, const char* postData = NULL );
BZF_API bool [[bz_removeURLJob]] ( const char* URL );
?
BZF_API bool [[bz_stopAllURLJobs]] ( void );

=== Callback Functions ===
?
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_callCallback]] ( const char* name, void *param );
BZF_API bool [[bz_callbackExists]] ( const char* name );

=== Inter-Plug-in Communications ===
2.3+
BZF_API bool [[bz_clipFieldExists]] ( const char *name );
BZF_API const char* [[bz_getclipFieldString]] ( const char *name );
BZF_API float [[bz_getclipFieldFloat]] ( const char *name );
BZF_API int [[bz_getclipFieldInt]] ( const char *name );
BZF_API bool [[bz_setclipFieldString]] ( const char *name, const char* data );
BZF_API bool [[bz_setclipFieldFloat]] ( const char *name, float data );
BZF_API bool [[bz_setclipFieldInt]] ( const char *name, int data );
BZF_API bool [[bz_addClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );
BZF_API bool [[bz_removeClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );

=== Game Recording ===
2.3+
BZF_API bool [[bz_saveRecBuf]] ( const char * _filename, int seconds);
BZF_API bool [[bz_startRecBuf]] ( void );
BZF_API bool [[bz_stopRecBuf]] ( void );

=== Map Management ===
==== Map Information ====
?
BZF_API void [[bz_getWorldSize]] ( float *size, float *wallHeight );
BZF_API unsigned int [[bz_getWorldObjectCount]] ( void );
BZF_API [[bz_APIWorldObjectList]]* [[bz_getWorldObjectList]] ( void );
BZF_API void [[bz_releaseWorldObjectList]] ( [[bz_APIWorldObjectList]] *list );
BZF_API unsigned int [[bz_findWorldObject]] ( const char *name );
BZF_API [[bz_APIBaseWorldObject]]* [[bz_getWorldObjectByID]] ( unsigned int id );
BZF_API bool [[bz_getTeleLinkIDs]] ( const char* teleName, int* frontLink, int* backLink );
BZF_API const char* [[bz_getLinkTeleName]] ( int linkIndex );
BZF_API int [[bz_getPhyDrvID]] ( const char* phyDrvName );
BZF_API const char* [[bz_getPhyDrvName]] ( unsigned int phyDrvID );
BZF_API bool [[bz_SetWorldObjectTangibility]] ( int id, const [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API bool [[bz_GetWorldObjectTangibility]] ( int id, [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API void [[bz_ResetWorldObjectTangibilities]] ( void );

==== Map Collisions ====
?
[[bz_eAPIColType]] [[bz_cylinderInMapObject]] ( float pos[3], float height, float radius, [[bz_APIBaseWorldObject]] **object );
[[bz_eAPIColType]] [[bz_boxInMapObject]] ( float pos[3], float size[3], float angle, [[bz_APIBaseWorldObject]] **object );

==== Custom Map Objects ====
2.3+
BZF_API bool [[bz_registerCustomMapObject]] ( const char* object, [[bz_CustomMapObjectHandler]] *handler );
BZF_API bool [[bz_removeCustomMapObject]] ( const char* object );

=== Utility ===
2.3+
BZF_API const char *[[bz_MD5]] ( const char* str );
BZF_API const char *[[bz_MD5]] ( const void* data, size_t size );
BZF_API const char *[[bz_getServerVersion]] ( void );
BZF_API const char *[[bz_getProtocolVersion]] ( void );

=== Misc ===
2.3+
BZF_API bool [[bz_getStandardSpawn]] ( int playerID, float pos[3], float *rot );
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase);
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase, int killerID = -1, const char* flagID = NULL );
BZF_API bool [[bz_sendPlayCustomLocalSound]] ( int playerID, const char* soundName );
BZF_API [[bz_ApiString]] [[bz_filterPath]] ( const char* path );
BZF_API const char *[[bz_format]](const char* fmt, ...)_ATTRIBUTE12;
BZF_API const char *[[bz_toupper]](const char* val );
BZF_API const char *[[bz_tolower]](const char* val );
BZF_API const char *[[bz_urlEncode]](const char* val );
BZF_API [[bz_eGameType]] [[bz_getGameType]]( void );
BZF_API [[bz_eTeamType]] [[bz_checkBaseAtPoint]] ( float pos[3] );
BZF_API int [[bz_APIVersion]] ( void );
?
BZF_API bool [[bz_allowJumping]] ( void );

=== Server Side Players (Development) ===
? (In API for 2.3+, but will crash a server)
BZF_API int [[bz_addServerSidePlayer]] ( [[bz_ServerSidePlayerHandler]] *handler );
BZF_API bool [[bz_removeServerSidePlayer]] ( int playerID, [[bz_ServerSidePlayerHandler]] *handler );

== See also ==
[[BZFS API]]

[[plug-ins]]

[[Category:BZFS_API_Functions]]

Talk:Flag ideas

2013-05-04T23:25:12Z

JeffM2501: Wiki != discussion

We have flags classified as a "Maybe", but some are Red (Pass), Yellow (Fail), and Grey (which doesn't even mean anything in the legend!). We need some clarification from Riker about what to do with the "Maybes".

- Pine (Bentus)

== Where to put ideas for existing flags? ==

Where do I put ideas for modifications to existing flags? I have this idea that Shield should, when you are hit, make you invincible briefly.

== Disappointed that "Flame Thrower" got rejected ==
I don't think I explained the effect and appearance well enough because the rejection comment is "shockwave does the same thing beter". My intention with this flag is nothing like SW! The idea was to introduce a new sound and accompanying visual, without it being some absurdly complex or uber-deadly change to the game, as so many of the suggestions here seem to be! The shot would be a bit like a thief beam, but slightly longer in duration, say half a second or so (probably server configurable). Its projection length out of the barrel would be similar to thief, or maybe shorter (again, server configurable). To add some realism, if the turret turns while the flame is emitting, it should "snake" slightly, just like a real flame thrower! The flame should never ricochet. -Steve ([[User:Mr Burns|Mr Burns]] 05:17, 27 March 2008 (EDT))

== Hoping someone will see this ==

Hey, all. I know ideas go on the SourceForge page, and I know some of these may be similar to rejected things, but honestly there are TONS of them and while I attempted to read them all I only got about a fourth of the way through before my eyes crossed. I'm not geared mentally for these sorts of trials, and I apologize if this is seen as rude. (I seriously have a hard time, mentally, with these things.)

I'm hoping it won't be too terrible if I lay out some ideas I've had for flags since I first downloaded the game in the early 2000s...

Let's get the one I KNOW is similar to another right out of the way. I've done it differently, so please do give me a chance.

'''Flamethrower''' - The exact way Thief works, but with a kill instead of a flag steal. Short range, but a 'line' instead of a single projectile.

* This is Laser without the constant problem of nuking yourself with a bad angle. It has great benefit (Laser w/o danger), a drawback (Laser w/o range), and it provides a new style of play to master when you get the flag.

'''Landmine''' - Simply a smaller Shockwave on delay, radiating out BEHIND you as you proceed on.

* Before you reject by saying "Shockwave", note that this is the ultimate evasive flag. It's a counter to being chased down by someone, and much less cheap than mashing the jump key to avoid their bullets. Drawback is no forward firing! '''Plus it can kill you if you don't move your butt!'''

'''Mirror''' - Front of tank causes riccochet. Rest of tank is still vulnerable. Only works with normal shots. (No effect against super bullet, laser, shockwave, guided missile, etc.)

* Not related to whether a server has riccochet on or not! The front of your tank bounces projectiles off, that's it. Protects you from face shots, leaving the rest of you open to attack.

'''X-Ray''' - You can see through the closest structure, but only in window area.

* Benefit: X-Ray sight. Drawbacks: Only in window, and only the closest object you're near, like with "Identify", it tracks the proximity. Also, while you're peeping, you'll probably get shot. - However, it's not useless, would be effective for watching Overthruster and Stealth players.

Alternate '''X-Ray''' - You can see through any structure, but only in window area.

* If the proximity thing is too complex or would render it useless, just open it up to all structures. Imagine having the X-Ray flag and going: "WHOA, hey I didn't someone was there!"

'''Gauss Cannon''' - Bullet immediately arrives at terminal point (end of life, or enemy/wall) without traveling.

* Benefit: You're immediately hitting where you aimed. Drawback: If your aim is off, you get NO chance of hitting as bullet travels.

'''Repulsor''' - Tanks within radius are repelled from you.

* This might sound silly at first, but really think about how useful it would be to automatically repell enemies and allies alike. Benefit: They can't get a close shot. Drawback: YOU can't get a close shot. Please really think about the dynamics this would create and how people would learn to use it from both perspectives.

'''Attractor''' - Tanks within radius are drawn to you.

* Opposite of above. I beg you to think about it as a legit feature, not a silly quick thought. Tanks moving toward you quickly, and moving away from you slowly. Benefit is drawing enemies to be shot, drawback is of course drawing them in to shoot you.

* Either of the last two could work or not work on bullets, depending on preference.

'''Sonic Cannon''' - Projecile from the front spreads out in waves in cone shape. Best visual example is the RSS symbol.

* '''This is different enough from Shockwave as it's EASY to avoid killing teammates while also not providing the all-around protection!''' It's a great new benefit/flaw dynamic that BZFlag could really be fun with.

'''Sticky Charge''' - When you hit an enemy tank with a bullet, it "sticks to them" (no graphical representation, though) but they can still fire. After a few moments, they detonate with shockwave effect, giving you the resulting kills.

* I know this is a weird/silly one, but think it over. Benefit: Obvious. Drawback: Takes a few moments, and they (plus others) can easily fire back on you while YOUR shits are just sticking.

'''Quicksand''' - Penalty flag. You get burrowed but can't fire. Anyone can run you over!

* Just a cool concept. Sorry. :X

'''Lightning''' - Randomly bending laser with short range.

* In other words, exactly like lightning. All that would need to be done is to have the existing Laser/Thief line zig-zag randomly as if it were riccocheting within the small area in front of your tank. Benefit: Get tanks to left/right with your crooked, jagged laser. Drawback: It's short range, and random - which makes it tougher to actually aim at one guy.

Alternate '''Lightning''' - Lock on, like Guided Missile, but you fire a bending laser that zaps at your target.

* You get the idea, this is more like real lightning, shooting toward a "lightning rod". Imagine firing this from atop a building like GM. You'd be like a God firing lightning down on mortals! Problem is they might swerve out of the way by a hair, and you're having to lock on before you can do anything useful. (This is like GM + Laser, I know, but think about it?)

That's the tip of the iceberg, but now I'll sit back and see if anyone ever comes here... and if I get yelled at. -- [[Special:Contributions/4.154.6.138|4.154.6.138]] 06:58, 1 May 2013 (UTC) (Mr. Slow)

All of these are rejected ideas for many many reasons --[[User:JeffM2501|JeffM2501]] 23:27, 1 May 2013 (UTC)
:It's actually not possible that these are already all rejected due to the variations that would come into play. Plus I doubt you even checked, some of these are way out there and probably never suggested before. [[Special:Contributions/4.153.8.113|4.153.8.113]] 23:19, 4 May 2013 (UTC)
:: The wiki isn't a discussion board, you can talk about ideas on the forums or IRC. --[[User:JeffM2501|JeffM2501]] 23:25, 4 May 2013 (UTC)

Talk:Flag ideas

2013-05-01T23:27:37Z

JeffM2501:

Functions (API)

2013-03-29T22:45:28Z

JeffM2501: /* Player Lists and Records */

{{DoDoc|
Fill in articles for all API Functions 
Finish updating to 2.3.x 
Verify future API functions.
}}

{{BZFS_API_Doc}}

== Overview ==

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.

== Function Groups ==
Functions are broken into a series of groups based on the type of action or information they deal with.

=== Event Registration ===
2.0.x
BZF_API bool [[bz_registerEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
BZF_API bool [[bz_removeEvent]] ( [[Event(API)|bz_eEventType]] eventType, [[Event(API)|bz_EventHandler]]* eventHandler );
2.3+
BZF_API bool [[Register]] ( [[Event(API)|bz_eEventType]] eventType );
virtual void Cleanup() {Flush();}

=== Non-Player Connections ===
2.3+
BZF_API bool [[bz_registerNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_removeNonPlayerConnectionHandler]] ( int connectionID, [[bz_NonPlayerConnectionHandler]]* handler );
BZF_API bool [[bz_sendNonPlayerData]] ( int connectionID, const void *data, unsigned int size );
BZF_API bool [[bz_disconectNonPlayerConnection]] ( int connectionID );
BZF_API unsigned int [[bz_getNonPlayerConnectionOutboundPacketCount]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionIP]] ( int connectionID );
BZF_API const char* [[bz_getNonPlayerConnectionHost]] ( int connectionID );

=== Player Information ===
==== Player Information ====
2.3+
BZF_API bool [[bz_hasPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_getAdmin]] ( int playerID );
BZF_API bz_eTeamType [[bz_getPlayerTeam]] ( int playerID );
BZF_API const char* [[bz_getPlayerCallsign]] ( int playerID );
BZF_API const char* [[bz_getPlayerIPAddress]] ( int playerID );
BZF_API const char* [[bz_getPlayerFlag]] ( int playerID );
?
BZF_API const char* [[bz_getPlayerReferrer]] ( int playerID );
BZF_API const char* [[bz_getPlayerCustomData]] (int playerID, const char* key );

==== Player State Information ====
2.3+
BZF_API bool [[bz_isPlayerPaused]] ( int playerID );
BZF_API bool [[bz_canPlayerSpawn]]( int playerID );
BZF_API bool [[bz_getPlayerCurrentState]] ( int playerID, bz_PlayerUpdateState &state );
?
BZF_API bool [[bz_getPlayerPosition]] ( int playerID, float pos[3], bool extrapolate );
BZF_API bool [[bz_getPlayerRotation]] ( int playerID, float *rot, bool extrapolate );
BZF_API bool [[bz_getPlayerVelocity]] ( int playerID, float vel[3] );
BZF_API bool [[bz_getPlayerAngVel]] ( int playerID, float *angvel );
BZF_API bool [[bz_getPlayerPhysicsDriver]] ( int playerID, int* phydrv );

==== Player Lists and Records ====
2.3+
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByIndex]] ( int index );
BZF_API [[bz_BasePlayerRecord]] *[[bz_getPlayerByCallsign]] ( const char* name );
BZF_API bool [[bz_updatePlayerData]] ( [[bz_BasePlayerRecord]] *playerRecord );
BZF_API bool [[bz_freePlayerRecord]] ( [[bz_BasePlayerRecord]] *playerRecord );

BZF_API [[bz_APIIntList]] *[[bz_newIntList]] ( void );
BZF_API [[bz_APIIntList]] *[[bz_getPlayerIndexList]] ( void );
BZF_API bool [[bz_getPlayerIndexList]] ( [[bz_APIIntList]] *playerList );
BZF_API void [[bz_deleteIntList]] ( [[bz_APIIntList]] *l);

==== Player Management ====
2.3+
BZF_API bool [[bz_grantPerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_revokePerm]] ( int playerID, const char* perm );
BZF_API bool [[bz_validAdminPassword]] ( const char* passwd );
BZF_API bool [[bz_setPlayerOperator]] ( int playerId );
?
BZF_API bool [[bz_setPlayerSpawnable]]( int playerID, bool spawn );
BZF_API bool [[bz_setPlayerLimboMessage]]( int playerID, const char* text );
BZF_API bool [[bz_setPlayerCustomData]] (int playerID, const char* key, const char* data );

=== Team Management ===
2.3+
BZF_API unsigned int [[bz_getTeamPlayerLimit]] ( bz_eTeamType team );
BZF_API int [[bz_getTeamCount]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamScore]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamWins]] ([[bz_eTeamType]] team );
BZF_API int [[bz_getTeamLosses]] ([[bz_eTeamType]] team );
BZF_API void [[bz_setTeamWins]] ([[bz_eTeamType]] team, int wins );
BZF_API void [[bz_setTeamLosses]] ([[bz_eTeamType]] team, int losses );
BZF_API void [[bz_resetTeamScore]] ([[bz_eTeamType]] team );
BZF_API void [[bz_resetTeamScores]] ( void );
?
BZF_API void [[bz_changeTeam]]( int player, [[bz_eTeamType]] team );

=== Score Management ===
2.3+
BZF_API bool [[bz_setPlayerWins]] ( int playerId, int wins );
BZF_API bool [[bz_setPlayerLosses]] ( int playerId, int losses );
BZF_API bool [[bz_setPlayerTKs]] ( int playerId, int tks );
BZF_API bool [[bz_resetPlayerScore]] ( int playerId );
BZF_API int [[bz_getPlayerWins]] ( int playerId );
BZF_API int [[bz_getPlayerLosses]] ( int playerId );
BZF_API int [[bz_getPlayerTKs]] ( int playerId );
BZF_API float [[bz_getPlayerRank]] ( int playerId );

=== Latency Information ===
2.3+
BZF_API int [[bz_getPlayerLag]] ( int playerId );
BZF_API int [[bz_getPlayerJitter]] ( int playerId );
BZF_API float [[bz_getPlayerPacketloss]] ( int playerId );
BZF_API int [[bz_getIdleTime]] ( int playerId );

=== Permission Group Management ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getGroupList]] ( void );
BZF_API [[bz_APIStringList]]* [[bz_getGroupPerms]] ( const char* group );
BZF_API bool [[bz_groupAllowPerm]] ( const char* group, const char* perm );

=== Chat Messages ===
2.3+
BZF_API bool [[bz_sendTextMessage]] (int from, int to, const char* message);
BZF_API bool [[bz_sendTextMessage]] (int from, [[bz_eTeamType]] to, const char* message);
BZF_API bool [[bz_sendTextMessagef]] (int from, int to, const char* fmt, ...);
BZF_API bool [[bz_sendTextMessagef]] (int from, [[bz_eTeamType]] to, const char* fmt, ...);
?
BZF_API bool [[bz_sendFetchResMessage]] ( int playerID, const char* URL );
BZF_API bool [[bz_sendJoinServer]] ( int playerID, const char* address, int port, int team, const char* referrer, const char* message );
BZF_API bool [[bz_sendLuaData]] ( int dstPlayerID, int dstScriptID, int statusBits, const char* data, int len,
int srcPlayerID = 0, int srcScriptID = 0 );

=== Server Management ===
2.3+
BZF_API bool [[bz_restart]] ( void );
BZF_API void [[bz_shutdown]] ();
BZF_API void [[bz_superkill]] ();
BZF_API void [[bz_gameOver]] ( int playerID, bz_eTeamType = eNoTeam );
BZF_API void [[bz_reloadLocalBans]] ();
BZF_API void [[bz_reloadMasterBans]] ();
BZF_API void [[bz_reloadGroups]] ();
BZF_API void [[bz_reloadUsers]] ();
BZF_API void [[bz_reloadHelp]] ();
BZF_API int [[bz_getPlayerCount]] ( void );
?
BZF_API bool [[bz_anyPlayers]] ( void );

=== Rabbit Hunt ===
?
BZF_API void [[bz_newRabbit]] ( int player, bool swap );
BZF_API void [[bz_removeRabbit]] ( int player );

=== Map Management ===
2.3+
BZF_API void [[bz_setClientWorldDownloadURL]] ( const char* URL );
BZF_API const [[bz_ApiString]] [[bz_getClientWorldDownloadURL]] ( void );
BZF_API bool [[bz_saveWorldCacheFile]] ( const char* file );

=== Flag Management ===
2.3+
BZF_API bool [[bz_givePlayerFlag]] ( int playerID, const char* flagType, bool force );
BZF_API bool [[bz_removePlayerFlag]] ( int playerID );
BZF_API void [[bz_resetFlags]] ( bool onlyUnused, bool keepTeamFlags = false );
BZF_API unsigned int [[bz_getNumFlags]] ( void );
BZF_API const [[bz_ApiString]] [[bz_getFlagName|bz_getName]] ( int flag );
BZF_API bool [[bz_resetFlag]] ( int flag );
BZF_API int [[bz_flagPlayer]] ( int flag );
BZF_API bool [[bz_getFlagPosition]] ( int flag, float* pos );
BZF_API bool [[bz_moveFlag]] ( int flag, float pos[3] );
BZF_API bool [[bz_RegisterCustomFlag]] ( const char* abbr, const char* name, const char* helpString, bz_eShotType shotType, bz_eFlagQuality quality );

=== Shot Type Control ===
?
BZF_API bool [[bz_setPlayerShotType]] ( int playerId, [[bz_eShotType]] shotType );

=== World Weapon Management ===
2.3+
BZF_API bool [[bz_fireWorldWep]] ( const char* flagType, float lifetime, int fromPlayer, float *pos, float tilt, float direction, int shotID , float dt, bz_eTeamType shotTeam = eRogueTeam );
BZF_API int [[bz_fireWorldGM]] ( int targetPlayerID, float lifetime, float *pos, float tilt, float direction, float dt, bz_eTeamType shotTeam = eRogueTeam );

=== Server Time ===
2.3+
BZF_API double [[bz_getCurrentTime]] ( void );
BZF_API void [[bz_getLocaltime]] ( [[bz_Time]] *ts );
BZF_API void [[bz_getUTCtime]] ( [[bz_Time]] *ts );

?
BZF_API float [[bz_getMaxWaitTime]] ( void );
BZF_API void [[bz_setMaxWaitTime]] ( float maxTime );

=== Global Database Management (BZDB) ===
2.3+
BZF_API double [[bz_getBZDBDouble]] ( const char* variable );
BZF_API [[bz_ApiString]] [[bz_getBZDBString]] ( const char* variable );
BZF_API bool [[bz_getBZDBBool]] ( const char* variable );
BZF_API int [[bz_getBZDBInt]] ( const char* variable );
BZF_API int [[bz_getBZDBItemPerms]] ( const char* variable );
BZF_API bool [[bz_getBZDBItemPesistent]] ( const char* variable );
BZF_API bool [[bz_BZDBItemExists]] ( const char* variable );
BZF_API bool [[bz_setBZDBDouble]] ( const char* variable, double val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBString]] ( const char* variable, const char *val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBBool]] ( const char* variable, bool val, int perms = 0, bool persistent = false );
BZF_API bool [[bz_setBZDBInt]] ( const char* variable, int val, int perms = 0, bool persistent = false );
BZF_API int [[bz_getBZDBVarList]] ( bz_APIStringList *varList );
BZF_API void [[bz_resetBZDBVar]] ( const char* variable );
BZF_API void [[bz_resetALLBZDBVars]] ( void );

=== Logging ===
2.3+
BZF_API void [[bz_debugMessage]] ( int level, const char* message );
BZF_API void [[bz_debugMessagef]] ( int level, const char* fmt, ... )
BZF_API int [[bz_getDebugLevel]] ( void );

=== Server Administration ===
2.3+
BZF_API bool [[bz_kickUser]] ( int playerIndex, const char* reason, bool notify );
BZF_API bool [[bz_IPBanUser]] ( int bannedByIndex, const char* ip, int duration, const char* reason );
BZF_API bool [[bz_HostBanUser]] ( int bannedByIndex, const char* hostmask, int duration, const char* reason );
BZF_API bool [[bz_IPUnbanUser]] ( const char* ip );
BZF_API bool [[bz_IDUnbanUser]] ( const char* bzID );
BZF_API bool [[bz_HostUnbanUser]] ( const char* hostmask );

BZF_API int [[bz_getLagWarn]] ( void );
BZF_API bool [[bz_setLagWarn]] ( int lagwarn );
BZF_API bool [[bz_pollActive]] ( void );
BZF_API bool [[bz_pollVeto]] ( void );

?
BZF_API bool [[bz_IDBanUser]] ( int bannedByIndex, const char* bzID , int duration, const char *reason );

=== Reporting ===
2.3+
BZF_API [[bz_APIStringList]]* [[bz_getReports]] ( void );
?
BZF_API unsigned int [[bz_getReportCount]] ( void );
BZF_API const char* [[bz_getReportSource]] ( unsigned int id );
BZF_API const char* [[bz_getReportBody]] ( unsigned int id );
BZF_API const char* [[bz_getReportTime]] ( unsigned int id );
BZF_API bool [[bz_clearReport]] ( unsigned int id );
BZF_API bool [[bz_clearAllReports]] ( void );
BZF_API bool [[bz_fileReport]] ( const char* message, const char* from );

=== Timed Game Management ===
2.3+
BZF_API bool [[bz_setTimeLimit]] ( float timeLimit );
BZF_API float [[bz_getTimeLimit]] ( void );
BZF_API bool [[bz_isTimeManualStart]] ( void );
BZF_API bool [[bz_isCountDownActive]] ( void );
BZF_API bool [[bz_isCountDownInProgress]] ( void );
BZF_API void [[bz_pauseCountdown]] ( const char *pausedBy );
BZF_API void [[bz_resumeCountdown]] ( const char *resumedBy );
BZF_API void [[bz_startCountdown]] ( int delay, float limit, const char *byWho );

=== Custom Text Commands ===
2.3+
BZF_API bool [[bz_registerCustomSlashCommand]] ( const char* command, [[bz_CustomSlashCommandHandler]] *handler );
BZF_API bool [[bz_removeCustomSlashCommand]] ( const char* command );

=== Plug-in Management ===
2.3+
BZF_API int [[bz_getLoadedPlugins]] ( [[bz_APIStringList]] * list );
BZF_API bool [[bz_loadPlugin]] ( const char* path, const char* params );
BZF_API bool [[bz_unloadPlugin]] ( const char* path );
BZF_API const char* [[bz_pluginBinPath]] ( void );
BZF_API bool [[bz_registerCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );
BZF_API bool [[bz_removeCustomPluginHandler]] ( const char* extension, [[bz_APIPluginHandler]] * handler );

=== Public Server Information ===
2.3+
BZF_API bool [[bz_getPublic]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicAddr]] ( void );
BZF_API [[bz_ApiString]] [[bz_getPublicDescription]] ( void );
BZF_API int [[bz_getPublicPort]] ( void );
BZF_API void [[bz_updateListServer]] ( void );

=== HTTP Transfer ===
2.3+
BZF_API bool [[bz_addURLJob]] ( const char* URL, [[bz_BaseURLHandler]]* handler = NULL, const char* postData = NULL );
BZF_API bool [[bz_removeURLJob]] ( const char* URL );
?
BZF_API bool [[bz_stopAllURLJobs]] ( void );

=== Callback Functions ===
?
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_registerCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallback]] *callback );
BZF_API bool [[bz_removeCallBack]] ( const char* name, [[bz_GenericCallbackFunc]] callback );
BZF_API bool [[bz_callCallback]] ( const char* name, void *param );
BZF_API bool [[bz_callbackExists]] ( const char* name );

=== Inter-Plug-in Communications ===
2.3+
BZF_API bool [[bz_clipFieldExists]] ( const char *name );
BZF_API const char* [[bz_getclipFieldString]] ( const char *name );
BZF_API float [[bz_getclipFieldFloat]] ( const char *name );
BZF_API int [[bz_getclipFieldInt]] ( const char *name );
BZF_API bool [[bz_setclipFieldString]] ( const char *name, const char* data );
BZF_API bool [[bz_setclipFieldFloat]] ( const char *name, float data );
BZF_API bool [[bz_setclipFieldInt]] ( const char *name, int data );
BZF_API bool [[bz_addClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );
BZF_API bool [[bz_removeClipFieldNotifier]] ( const char *name, [[bz_ClipFiledNotifier *cb );

=== Game Recording ===
2.3+
BZF_API bool [[bz_saveRecBuf]] ( const char * _filename, int seconds);
BZF_API bool [[bz_startRecBuf]] ( void );
BZF_API bool [[bz_stopRecBuf]] ( void );

=== Map Management ===
==== Map Information ====
?
BZF_API void [[bz_getWorldSize]] ( float *size, float *wallHeight );
BZF_API unsigned int [[bz_getWorldObjectCount]] ( void );
BZF_API [[bz_APIWorldObjectList]]* [[bz_getWorldObjectList]] ( void );
BZF_API void [[bz_releaseWorldObjectList]] ( [[bz_APIWorldObjectList]] *list );
BZF_API unsigned int [[bz_findWorldObject]] ( const char *name );
BZF_API [[bz_APIBaseWorldObject]]* [[bz_getWorldObjectByID]] ( unsigned int id );
BZF_API bool [[bz_getTeleLinkIDs]] ( const char* teleName, int* frontLink, int* backLink );
BZF_API const char* [[bz_getLinkTeleName]] ( int linkIndex );
BZF_API int [[bz_getPhyDrvID]] ( const char* phyDrvName );
BZF_API const char* [[bz_getPhyDrvName]] ( unsigned int phyDrvID );
BZF_API bool [[bz_SetWorldObjectTangibility]] ( int id, const [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API bool [[bz_GetWorldObjectTangibility]] ( int id, [[bz_SolidObjectPassableAtributes]] &atribs );
BZF_API void [[bz_ResetWorldObjectTangibilities]] ( void );

==== Map Collisions ====
?
[[bz_eAPIColType]] [[bz_cylinderInMapObject]] ( float pos[3], float height, float radius, [[bz_APIBaseWorldObject]] **object );
[[bz_eAPIColType]] [[bz_boxInMapObject]] ( float pos[3], float size[3], float angle, [[bz_APIBaseWorldObject]] **object );

==== Custom Map Objects ====
2.3+
BZF_API bool [[bz_registerCustomMapObject]] ( const char* object, [[bz_CustomMapObjectHandler]] *handler );
BZF_API bool [[bz_removeCustomMapObject]] ( const char* object );

=== Utility ===
2.3+
BZF_API const char *[[bz_MD5]] ( const char* str );
BZF_API const char *[[bz_MD5]] ( const void* data, size_t size );
BZF_API const char *[[bz_getServerVersion]] ( void );
BZF_API const char *[[bz_getProtocolVersion]] ( void );

=== Misc ===
2.3+
BZF_API bool [[bz_getStandardSpawn]] ( int playerID, float pos[3], float *rot );
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase);
BZF_API bool [[bz_killPlayer]] ( int playerID, bool spawnOnBase, int killerID = -1, const char* flagID = NULL );
BZF_API bool [[bz_sendPlayCustomLocalSound]] ( int playerID, const char* soundName );
BZF_API [[bz_ApiString]] [[bz_filterPath]] ( const char* path );
BZF_API const char *[[bz_format]](const char* fmt, ...)_ATTRIBUTE12;
BZF_API const char *[[bz_toupper]](const char* val );
BZF_API const char *[[bz_tolower]](const char* val );
BZF_API const char *[[bz_urlEncode]](const char* val );
BZF_API [[bz_eGameType]] [[bz_getGameType]]( void );
BZF_API [[bz_eTeamType]] [[bz_checkBaseAtPoint]] ( float pos[3] );
BZF_API int [[bz_APIVersion]] ( void );
?
BZF_API bool [[bz_allowJumping]] ( void );

=== Server Side Players (Development) ===
? (In API for 2.3+, but will crash a server)
BZF_API int [[bz_addServerSidePlayer]] ( [[bz_ServerSidePlayerHandler]] *handler );
BZF_API bool [[bz_removeServerSidePlayer]] ( int playerID, [[bz_ServerSidePlayerHandler]] *handler );

== See also ==
[[BZFS API]]

[[plug-ins]]

[[Category:BZFS_API_Functions]]

BZFlag SVN

2013-03-18T17:36:53Z

JeffM2501: update to the new URL

BZFlag SVN, is the [http://en.wikipedia.org/wiki/Subversion_(software) Subversion Revision Control System] used by the development team to maintain and store the [[BZFlag Source]] code. The SVN system is hosted by [http://www.sourceforge.net SourceForge] and is accessible by anyone with the proper software. The SVN system replaces the [[BZFlag CVS]] system that was used in the past.

==SVN clients==
To access the source code via SVN , you will need a SVN client. Most unix/linux type operating systems have the command line SVN client as an installable option. Windows users must download the Windows native [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91 SVN command line utility] or a third party SVN client, such as [http://tortoisesvn.tigris.org/ the Tortoise Graphical SVN Client] (highly recommended). SVN is also available to Windows users via [http://cygwin.com/ Cygwin] with SVN and other common Devel tools selected during installation.

==Getting code from SVN Access==
===Command line===
The simplest way to get the bzflag source code is to use the URL for the current ( or TRUNK ) bzflag module.

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag</nowiki>

This will get you the current bzflag source code for the development version.

If you want the SVN code for the 2.0.x compatible version use the URL

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/branches/release_maint/v2_0/bzflag</nowiki>

If you wish to get all of our source code in one step, you can get the entire repository with the command.

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/</nowiki> bzflag

This will get all modules, branches, tags, and subdirs. Beware! This is a very large amount of data (make sure you have at least 2.7 GB of disk space available) and will take a while and will be rather useless, as it is the code for every version of bzflag. Most users will only need the code for one specific version.

The '''best''' way, is to only get the subdir for the module you are interested in. This is much more efficient and suitable for most users. The most common module to get is the bzflag module, as it is the actual game.

Please see the sections below for more information about the URLs to use for branches and modules.

===TortoiseSVN===

Windows users that use the Tortoise Graphical SVN Client simply enter the URL of the SVN path they wish to check out in the field marked ''URL of repository''. For the current version of all modules simply use the /trunk path. Note, if you want your code to be checked out into a new folder, be sure to enter that folder name in the ''Checkout directory'' field.

If you wish to get only a single module subdir, or a revision, simply use the URL specified in the sections below.

==Committing Code to SVN==

Project developers that need write access to the source code to make changes ( or [[commits]] ) need to provide their sourceforge username and password when doing a SVN commit. A sourceforge account is required for developer access, as well as approval from a project administrator.

Please make sure that your svn config file includes the correct [[Auto-props]]. If you get a [[Mime-types]] error, you either didn't enable the correct auto-props setting in your subversion config file or you need to manually set file properties.

===Command Line===
Using the command
svn commit
in a directory that has code changes will commit any changed code back to the repository. The svn client will prompt you for your username and password.

===TortoiseSVN===
Windows users that use the Tortoise Graphical SVN Client can simply choose the SVN commit item, and enter their username and password when prompted.

Tortoise users may set auto-props from the General Settings property page; click the Edit button and paste the auto-props into the correct section, then un-comment the "enable-auto-props = yes" line above it.

==Updating code from SVN to the current version==

===Command Line===
Using the command
svn up
in the directory that has checked out code will cause subversion to update that code to the current version for that branch.

===TortoiseSVN===
Windows users that use the Tortoise Graphical SVN Client can simply choose the SVN update item from their right click menus.

==Reverting local code to the server's version==

===Command Line===
Using the command
svn revert
svn up
in the directory that has checked out code will cause subversion to set flags on all modified local files, then update the code to match the code on the server. NOTE: This has the effect of wiping out all local changes, so use with caution!

===TortoiseSVN===
Right click on the file or directory you would like to revert and from the TortoiseSVN submenu, select '''Revert...'''. The menus is context sensitive, so there must be code that has been modified for the menu choice to be available.

==Module sub directories==

The source code in SVN is broken up into a number of modules for ease of use and management. When requesting the source code from the SVN system a sub-directory may be specified to limit the code that is accessed.

The current SVN modules are:
*bzflag : The main module that includes the game [[BZFlag 2.0.8|client]], [[BZFS|server]], [[plug-ins]], and [[BZAdmin]].
*admin : The [[Master Ban]] list
*bzedit : The linux version of the BZFlag map editor [[BZEdit]]
*bzeditw32 : The windows version of the BZFlag map editor [[BZEditWin32]]
*web : The main website at http://www.bzflag.org
*db : Files related to the website http://my.bzflag.org and the [[Global Registration]] system.
*pybzflag : an abandoned python implementation of BZFlag
*bzworkbench : The source code for [[BZWorkBench]]
*bzwgen: The source code for the automatic city generator.

to get the current version of a module, you would add
/trunk/MODULE_NAME
after the normal SVN URL.

so to get the current version of just the bzflag module, the URL would be

<nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag/</nowiki>

From the command line

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag</nowiki>

==Branches==
Branches in subversion are simply subfolders.
All branches are in the /branches subdirectory off the root level of the SVN tree, listed [http://bzflag.svn.sourceforge.net/viewvc/bzflag/branches/ here].
To get the code in a branch, you simply use the branch URL in your svn client.

To get the 2.0.x branch of the BZFlag module, you'd use the following URL.
svn://svn.code.sf.net/p/bzflag/code/branches/release_maint/v2_0/bzflag/

==Useful Tools==

===Windows===

'''Tortoise Graphical SVN Client''': integrates subversion into the windows explorer shell. http://tortoisesvn.tigris.org/

'''Ankh Subversion''': integrates subversion into Visual C++ as a native source control provider. http://ankhsvn.tigris.org/

'''WinMerge''': visual merge and diff tool for windows. http://winmerge.org/

==See also==
[[Versions]]

==External Links==
[http://sourceforge.net/svn/?group_id=3248 SourceForge SVN Access page]

[http://bzflag.svn.sourceforge.net/viewvc/bzflag/ BZFlag SVN Tree]

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

BZFlag SVN

2013-03-18T17:36:17Z

JeffM2501: update to the new URL

BZFlag SVN, is the [http://en.wikipedia.org/wiki/Subversion_(software) Subversion Revision Control System] used by the development team to maintain and store the [[BZFlag Source]] code. The SVN system is hosted by [http://www.sourceforge.net SourceForge] and is accessible by anyone with the proper software. The SVN system replaces the [[BZFlag CVS]] system that was used in the past.

==SVN clients==
To access the source code via SVN , you will need a SVN client. Most unix/linux type operating systems have the command line SVN client as an installable option. Windows users must download the Windows native [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91 SVN command line utility] or a third party SVN client, such as [http://tortoisesvn.tigris.org/ the Tortoise Graphical SVN Client] (highly recommended). SVN is also available to Windows users via [http://cygwin.com/ Cygwin] with SVN and other common Devel tools selected during installation.

==Getting code from SVN Access==
===Command line===
The simplest way to get the bzflag source code is to use the URL for the current ( or TRUNK ) bzflag module.

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag</nowiki>

This will get you the current bzflag source code for the development version.

If you want the SVN code for the 2.0.x compatible version use the URL

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/branches/release_maint/v2_0/bzflag</nowiki>

If you wish to get all of our source code in one step, you can get the entire repository with the command.

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/</nowiki> bzflag

This will get all modules, branches, tags, and subdirs. Beware! This is a very large amount of data (make sure you have at least 2.7 GB of disk space available) and will take a while and will be rather useless, as it is the code for every version of bzflag. Most users will only need the code for one specific version.

The '''best''' way, is to only get the subdir for the module you are interested in. This is much more efficient and suitable for most users. The most common module to get is the bzflag module, as it is the actual game.

Please see the sections below for more information about the URLs to use for branches and modules.

===TortoiseSVN===

Windows users that use the Tortoise Graphical SVN Client simply enter the URL of the SVN path they wish to check out in the field marked ''URL of repository''. For the current version of all modules simply use the /trunk path. Note, if you want your code to be checked out into a new folder, be sure to enter that folder name in the ''Checkout directory'' field.

If you wish to get only a single module subdir, or a revision, simply use the URL specified in the sections below.

==Committing Code to SVN==

Project developers that need write access to the source code to make changes ( or [[commits]] ) need to provide their sourceforge username and password when doing a SVN commit. A sourceforge account is required for developer access, as well as approval from a project administrator.

Please make sure that your svn config file includes the correct [[Auto-props]]. If you get a [[Mime-types]] error, you either didn't enable the correct auto-props setting in your subversion config file or you need to manually set file properties.

===Command Line===
Using the command
svn commit
in a directory that has code changes will commit any changed code back to the repository. The svn client will prompt you for your username and password.

===TortoiseSVN===
Windows users that use the Tortoise Graphical SVN Client can simply choose the SVN commit item, and enter their username and password when prompted.

Tortoise users may set auto-props from the General Settings property page; click the Edit button and paste the auto-props into the correct section, then un-comment the "enable-auto-props = yes" line above it.

==Updating code from SVN to the current version==

===Command Line===
Using the command
svn up
in the directory that has checked out code will cause subversion to update that code to the current version for that branch.

===TortoiseSVN===
Windows users that use the Tortoise Graphical SVN Client can simply choose the SVN update item from their right click menus.

==Reverting local code to the server's version==

===Command Line===
Using the command
svn revert
svn up
in the directory that has checked out code will cause subversion to set flags on all modified local files, then update the code to match the code on the server. NOTE: This has the effect of wiping out all local changes, so use with caution!

===TortoiseSVN===
Right click on the file or directory you would like to revert and from the TortoiseSVN submenu, select '''Revert...'''. The menus is context sensitive, so there must be code that has been modified for the menu choice to be available.

==Module sub directories==

The source code in SVN is broken up into a number of modules for ease of use and management. When requesting the source code from the SVN system a sub-directory may be specified to limit the code that is accessed.

The current SVN modules are:
*bzflag : The main module that includes the game [[BZFlag 2.0.8|client]], [[BZFS|server]], [[plug-ins]], and [[BZAdmin]].
*admin : The [[Master Ban]] list
*bzedit : The linux version of the BZFlag map editor [[BZEdit]]
*bzeditw32 : The windows version of the BZFlag map editor [[BZEditWin32]]
*web : The main website at http://www.bzflag.org
*db : Files related to the website http://my.bzflag.org and the [[Global Registration]] system.
*pybzflag : an abandoned python implementation of BZFlag
*bzworkbench : The source code for [[BZWorkBench]]
*bzwgen: The source code for the automatic city generator.

to get the current version of a module, you would add
/trunk/MODULE_NAME
after the normal SVN URL.

so to get the current version of just the bzflag module, the URL would be

<nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag/</nowiki>

From the command line

svn co <nowiki>svn://svn.code.sf.net/p/bzflag/code/trunk/bzflag</nowiki>

==Branches==
Branches in subversion are simply subfolders.
All branches are in the /branches subdirectory off the root level of the SVN tree, listed [http://bzflag.svn.sourceforge.net/viewvc/bzflag/branches/ here].
To get the code in a branch, you simply use the branch URL in your svn client.

To get the 2.0.x branch of the BZFlag module, you'd use the following URL.
https://bzflag.svn.sourceforge.net/svnroot/bzflag/branches/release_maint/v2_0/bzflag/

==Useful Tools==

===Windows===

'''Tortoise Graphical SVN Client''': integrates subversion into the windows explorer shell. http://tortoisesvn.tigris.org/

'''Ankh Subversion''': integrates subversion into Visual C++ as a native source control provider. http://ankhsvn.tigris.org/

'''WinMerge''': visual merge and diff tool for windows. http://winmerge.org/

==See also==
[[Versions]]

==External Links==
[http://sourceforge.net/svn/?group_id=3248 SourceForge SVN Access page]

[http://bzflag.svn.sourceforge.net/viewvc/bzflag/ BZFlag SVN Tree]

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

Category:Development

2013-02-10T08:38:48Z

JeffM2501: Add notes on the various dev templates and when each should be used, and point out the patch tracker for submissions of code for new ideas

==Overview==
BZFlag is developed as an open source guided development process involving a number of developers all over the world.

==Organization==
Open source development tends to not have as formal a structure as traditional development, but the bzflag project does have a group of developers that are responsible for various aspects of projet.

===Copyright Maintainer===
Tim Riker (TimRiker) is the copyright holder and intellectual property manager for the project and manages its various legal operations.

===Development Leads===
Scott Wichser (Blast007) and Jeffery Myers (JeffM) are the development leads. They are responsible for the day to day development and planning of the various releases of BZFlag. They maintain the [[BZFlag Source]] Code, [[BZFlag_SVN|SVN]] repository, and ensure that development of the game goes according to the design goals and [[Development_RoadMap]].

===Service Managers===
Scott Wichser (Blast007) and Joe Vano (JoeVano) manage the public services that BZFlag clients and servers use such as the [[List Server]] and [[Global Registration]] System.

====Forum Administrators====
A number of community members maintain the [[BZFlag Forums]] including;

* L4m3r
* DTRemenak
* BRLCAD
* Blast007
* Bryjen
* joevano
* Bullet Catcher
* Constitution

==Communications==
Development communications mostly happens in the [[BZFlag_on_IRC|BZFlag IRC channel]]. There are development mailing lists on the sourceforge site but they are rarely used. Many developers are often on the IRC channel and are more then willing to discuss things relating to bzflag development.

==Coding Policy==
BZFlag has a documented coding policy that is in the DEVINFO file that is included with every source code release.

==Wiki Development Design Templates==
In order to help out developers in building collaborative documents, the wiki has several templates that can be used to setup documents.

'''IdeaDesign''' This template is intended to be used to flesh out an idea or proposed change that has not yet been accepted but is being worked on by multiple people. This is where all new ideas should start.

'''DesignDocument''' Once an idea or change has been approved and made part of the development plan it will be changed to a Design Document. This indicates that the feature can be worked on in the development codebase by any developer.

'''Specification''' If additional documentation is needed for a feature then those documents can use this template. Specifications should also be put into a category or name space with the associated design document overview.

===Notes on Patches===
Some ideas may not be accepted by the development community right away, if the idea proposer wishes to implement the idea or parts of the idea to prove it out then those changes should be submitted to the [http://sourceforge.net/tracker/?group_id=3248&atid=303248 SourceForge Patch Tracker]. This will allow developers and team leaders to review the patch and decide if it should be included in the mainline release. It also lets other use or extend the code changes for private use.

==Resources==
[[SVN]] repository stored on Source Forge.

[[BZFlag Source]] Information on the source code for the game.

[[BZFS API]] Information on the API for plug-in development.

[http://sourceforge.net/tracker/?group_id=3248&atid=303248 SourceForge Patch Tracker] where code changes from new developers are submitted.

[http://sourceforge.net/tracker/?group_id=3248&atid=103248 SourceForge Bug Tracker] where users report bugs or problems in the game.

[http://sourceforge.net/tracker/?group_id=3248&atid=353248 SourceForge Feature Requests] where users request new features ( pending approval).

==Helping Out==
BZFlag can always use new developers. Users that wish to become more involved in the development process are encouraged to join the IRC channel and talk to the developers and players there.

The next step is to submit patches to the patch tracker so the new developer can get the hang of how the codebase works and so that project management can evaluate the coding ability/style of the new developer. The best way to get started is to take a look at the bugs in the Bug Tracker.

If a new developer fits into the project well and is productive they will often be given '''commit access''' to the SVN system so they may make changes directly to the code.

==Versions==
The current shipping version is based on the 2.4.2 tag '''tags/v2_4_2/''' in svn

The current development version is 2.4.3 and is maintenance for the 2.4.x line, it is located in '''trunk/bzflag''' in svn.

Timedctf

2013-02-10T08:30:01Z

JeffM2501: This was shipped, it's not a dev thing anymore

The timedctf plugin will start a timed capture the flag game in which a team must capture another team's flag in a configurable amount of time.

=Description=
* If the time expires before the team captures a flag, all members of the team will be destroyed and the timer will restart for that team.
* If the team captures another team's flag before their time expires, their timer is reset and starts counting down again.
* All 4 teams have individual timers.

There are '''warning messages''' sent to individual teams as their time starts to expire:

* A warning every minute (with time remaining) until the last minute. 
* A warning at 30 seconds before time expires.
* A warning at 20 seconds before time expires.
* A warning at 10 seconds before time expires.

The plugin also monitors the '''balance of teams''' and will disable the timer if teams are uneven. To determine if teams are balanced or not, at least a 75% match is used. This means that even teams would be considered:

These would work:
* 2 vs 2 (100%)
* 3 vs 4 (75%)

These won't:
* 2 vs 4 (50%)
* 1 vs 4 (25%)

The percentage is calculated this way:
smaller team / larger team * 100

If the teams are uneven, capture the flag is disabled; if a player tries to pick up a team flag, it will almost immediately be dropped.

The plugin is set up for all 4 teams (red, green, blue and purple) and will monitor/time all 4 teams. However, it is best suited to 2 team capture the flag type maps in that it only looks for the 75% match between any 2 team sizes. This means that it is possible (on a 4 team ctf map) to have teams considered to be even if:

1 vs 1 vs 3 vs 1 
2 vs 2 vs 8 vs 1 
and so on.

There are also informative messages when the status of the game changes, for example:

If a new player joins/parts that causes team imbalance, a message is sent stating that teams are uneven and timed ctf is disabled. If a new player joins/parts that balances teams out, a message is sent that timed ctf is enabled and how much time there is to capture a flag. And so on...

There are also standard CTF sounds used whenever significant events take place.

Note that the balance of teams will still be monitored when the ctf timer is off, and team flags will be dropped if teams are uneven (as described above). This allows this plugin to be utilized for fair, normal ctf play as well, if the ctf timer is turned off. If both functions (tctf and fairctf) are turned off, the plugin is effectively disabled. If the fair CTF function is disabled and the timed CTF function is enabled, the plugin will check for at least 2 teams
present before allowing timed CTF to take place.

=Usage=

The plugin will allow the time limit to be passed to the plugin through the -loadplugin command line with bzfs. The format is as follows:

"'''-loadplugin <path>timedctf,i'''" where i is the timer value (in minutes)for timed ctf. For example,"-loadplugin plugins/timedctf,7" would start the plugin with the timer set for 7 minutes. The minimum is 1 minute and the maximum is 120 minutes. If no time is specified, the plugin defaults to 5 minutes.

=Server Commands=
The plugin has the following '''administration''' commands available:

/tctftime <iii> - this will change required capture time to <iii> (1-120 minutes). 
/tctfoff - this will disable timed CTF. 
/tctfon - this will enable timed CTF. 
/tctfsoundoff - this will disable timed CTF sounds. 
/tctfsoundon - this will enable timed CTF sounds. 
/tctfstatus - this will return the current status of functions and the current time limit. 
/fairctfoff - this will disable the fair ctf function. 
/fairctfon - this will enable the fair ctf function. 

[[Category:Plug-Ins]]

LogDetail

2013-02-10T08:29:32Z

JeffM2501: This was shipped, it's not a dev thing anymore

logDetail is a standard [[Plug-ins|plug-in]] that is shipped with the [[BZFlag Source|source code]]. It allows the server owner to record nearly everything that happens on a server. logDetail is included in [[BZFlag 2.0.6|v2.0.6]] and later releases.

==Logged Items==
logDetail will log the following events.

* Join/Part with IP
* All Chat, including Private Messages

==Usage==
When logDetail is loaded it will force the logged data to be output to the normal debug stream. Server owners that wish to save his to a file must use the [[Redirect|redirect or pipe]] option on the host OS.

==How to load the plugin==
In the configuration file put:

* -loadplugin /path/to/logDetail.so

While launching [[BZFS]] the part where you declare your configuration file should look like.

* -conf /path/to/conf.conf >> Serverlog

Now the logs will be saved in the same directory as your configuration file.

==History==

[[Category:Plug-Ins]]

CrystalSpace client

2013-02-10T08:29:00Z

JeffM2501: This is an old idea, the info is good but not part of the current development effort

{{IdeaDesign}}

The Crystal Space client was an effort is to provide implement the BZFlag client using the a [http://crystalspace3d.org crystalspace] 3d engine and application framework. Development work never progressed past an inital prototype and was not picked up by the mainline system.

The current version is very experimental but, is compatible with all 2.0.x servers. It will be only available via SVN, using the v2_0_cs_branch.

Currently, the client is playable, does not contain all the features of the stable release. It is not recommended as a playing client, only to be used for development.

That is the plan on the development, subject to change without any prior notification:
[[Image:Crystal001.jpg|thumb|450px|right|Tank redone]]
# Integrate BZFlag client in the Crystal-Space framework, particularly regarding the event handling nature of it. (done)
# Handle the command line interface a la Crystal-Space: (done)
#* Option values separated by '=' instead of ' '
#* Own handling of -help
#* Request of option on the command line using CS API
# Joystick handling done from Crystal Space (done) This is actually having less functionality of native porting, as the force feedback is missing. I'll think I'll revert the joystick change when the work will go further.
# Remove the open GL calls from BZFlag (mostly done)
# Crystal-Space manages mouse and keyboard, as far as possible.(done)
# A world with a fixed sky with sun, the ground, and a wall all around the field. All done in XML using the CS rendering API and a camera.(partially done, missing the real time update, the moon and the stars)
# Reintegrate the 2D element like text and hud (mostly done). Some problem with the text, using bitmap instead of texture, and coordinate system in the 2d renderer.
# Tank models integrated, only a fixed size tank (done)
# Build the world element using CS API (need to fix use of material)
# Add shot
# Add the radar renderer, using a procedural texture.
# Change configuration file using the CS format
# Rework the debugging functionality (like screenshot and FPS) using the bugplug plugin, but controllable with the old way (T for FPS, F5 for screenshot, both configurable from option)
# Build the Menu selection using the [http://www.cegui.org.uk Crazy Eddie GUI]
# Rewrite the collision detection code using the [http://ode.org/ ode] plug-in
# Network layer done using a parallel thread that communicate with the engine
# Ship it! Actual ship should be done continuously during the development, to gain acceptance of the product

The idea is to have at any stage of development a working client, so we can see the product and change the direction of development at an early stage, if that is required, or abandon this idea at all.

Actual work on this project is on the 2.0.x branch, as to not delay the the 2.2 release. If the integration is successful, and the performance is acceptable then we can look into putting this work into a production release. Crystal Space, being a 3rd party library may have limited support for some of the less popular Operating Systems, as such support for those may be more difficult. Crystal Space does support the majority of our popular Operating Systems, including IRIX and Solaris.

All developers are invited to contribute if they have the desire. It is just asked that work be coordinated with the author and originator of the project, [[Alfredo Tupone]].

Strong Authentication

2013-02-10T08:28:03Z

JeffM2501:

{{IdeaDesign}}

{|style="width:100%;margin-top:+1em;background-color:#FF0000;border:1px solid #ccc;"
|<div style="font-size:162%">'''Kerberos authentication was rejected as an implementation system as overly complex with no real benefit over the token system, this document is kept for historical reasons.'''</div>
|}

To use strong auhentication on bzflag an infrastructure based on kerberos should be put in place.

kdc: is the kerberos Key Distribution Center, part of the mit-kerberos5 distribution. It should be unique, possibly with a slave configured, and for bzflag to work it should be configured to serve the realm BZFLAG.ORG . Your system needs to know where KDC is.
So you should write a /etc/krb5.conf on Unix or krb5.ini on windows, with the following content:

[realms]
BZFLAG.ORG = {
kdc = bryjen.bzflag.org
admin_server = bryen.bzflag.org
}

This is temporary and will be changed whenever we decide on where to put it.

On the kerberos database should be created one principal (kerberos user) for any client and one principal for any server that should participate.

* Server principal name should be #port/publicaddr@BZFLAG.ORG (like 5154/bzflag0.gamesunited.de@BZFLAG.ORG)
* Client principal name should be clientName@BZFLAG.ORG (like c3po@BZFLAG.ORG)

When starting a public server it will try to authenticate using the value given in -port -publicaddr and -password

When starting a client, it will authenticate to the server if the bzdb variable: username & password are defined (in the bzfs config file). So write the following lines on your config:

set username yourName

set password yourSecret

If credentials are unmatched, you will be still logged as an untrusted user.

Recordmatch

2013-02-10T08:27:25Z

JeffM2501: This was shipped, it's not a dev thing anymore

Recordmatch is a standard [[Plug-ins|plug-in]] that is shipped with the [[BZFlag Source|source code]]. It allows for match games, such as league matches, to be recorded onto the server to be replayed later. It will automatically record when a game (match) is started, and it will record with a filename given by the current date and time. Recordmatch is included in [[BZFlag 2.0.6|v2.0.6]] and later releases.

==Usage==
Before trying to use this plug-in, [[Replay_Server#Recording_Setup|configure]] bzfs to support recording.

When the recordmatch plug-in is loaded, it waits for a match game to be started. When a game is started, it will create a new file to store the recording, named with the current date and time. When the game is ended, it will stop recording and close the file. The plug-in is loaded in the same way as any other and takes no parameters:

-loadplugin "/path/to/the/plugin/recordmatch"

or with the in game commands if the server is already running:

/loadplugin "/path/to/the/plugin/recordmatch"

The "-loadplugin" syntax is used in the [[sample conf|server configuration]] file or at the command line when invoking a game [[BZFS|server]].

Be sure that you have in the configuration file:
* -time X (Where X is the number of seconds of a match)
* -timemanual

==Commands==
For most match servers for leagues the players will have the following commands:

* /countdown "Will start the match"
* /gameover "Will end the match immediately.
* /timelimit X "Allows player to change the time limit to X, where X is the number of seconds"

==History==
The BZFS API was changed in the development of [[BZFlag 2.0.6|v2.0.6]] to allow for recordings to be started. Recordmatch is the first plug-in to use the newly-added capability.

[[Category:Plug-Ins]]

Mime-types

2013-02-10T08:26:11Z

JeffM2501: This is a development resource not a design document, really it's just instructions on how to setup SVN clients

[[category:Development]]

When a developer commits a new file to the repository, they may get an error about mime types not being set. This is because there is (intentionally) a commit hook set up that verifies that there are mime types set on all files being added to the repository.

Subversion uses file mime-types for lots of useful things like for web interface browsing of the repository. You can either set up your subversion config to [[Auto-props|auto-set mime types]] or you can directly set the mime type on the file before you commit the file using svn propset.

Sean provides a copy of his Subversion configuration that includes property settings for many file types. You can download and install it with this:

'''curl http://bzflag.org/~sean/subversion.config > ~/.subversion/config'''

Once installed, run ''svn revert'' on your new file and then add it again. The properties should be set if the config file is installed properly and it's a recognized file type.

This problem usually looks like this:

[sean@bz (Wed May 28 13:27:55) bzflag]$ svn commit some_new_file.c
Sending some_new_file.c
Transmitting file data ...svn: Commit failed (details follow):
svn: MERGE request failed on '/svnroot/bzflag/trunk/bzflag'
svn: 'pre-commit' hook failed with error output:
/var/local/mastertree/service-svn/hook-scripts/check-mime-type.pl:

bzflag/trunk/bzflag/some_new_file.c : svn:mime-type is not set

Every added file must have the svn:mime-type property set. In
addition text files must have the svn:eol-style property set.

For binary files try running
svn propset svn:mime-type application/octet-stream path/of/file

For text files try
svn propset svn:mime-type text/plain path/of/file
svn propset svn:eol-style native path/of/file

You may want to consider uncommenting the auto-props section
in your ~/.subversion/config file. Read the Subversion book
(http://svnbook.red-bean.com/), Chapter 7, Properties section,
Automatic Property Setting subsection for more help.

[sean@bz (Wed May 28 13:28:55) bzflag]$ svn revert some_new_file.c
Reverted 'some_new_file.c'
[sean@bz (Wed May 28 13:29:55) bzflag]$ curl http://bzflag.org/~sean/subversion.config > ~/.subversion/config
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 10810 100 10810 0 0 30099 0 --:--:-- --:--:-- --:--:-- 81278
[sean@bz (Wed May 28 13:30:55) bzflag]$ svn add some_new_file.c
A some_new_file.c
[sean@bz (Wed May 28 13:31:55) bzflag]$ svn commit some_new_file.c
... no mime type error ...

That said, if one wanted to manually add or change a file's properties:
[sean@bz (Wed May 29 13:50:51) bzflag]$ svn add some_file.odd
A some_new_file.c
[sean@bz (Wed May 29 13:50:51) bzflag]$ svn propset svn:mime-type text/plain some_file.odd
[sean@bz (Wed May 29 13:50:51) bzflag]$ svn propset svn:eol-style native some_file.odd

Quick keys

2013-02-10T08:25:10Z

JeffM2501: This was always just an idea proposal, it should be reviewed and voted on since it mostly affects sportsmanship and chat defaults

{{IdeaDesign}}
Options->Input Settings->[[Key_Mapping|Change Key Mapping]]->Define Quick Keys

This page is a proposal for default quick keys. Having default team messages can increase teamplay(verify).
[[BZFlagWiki:Be_bold|Be bold]] in editing this table. This is not a job for one person. See the discussion for any discrepancies.
When this table looks complete, it ''may'' be included and the design document tag removed.
{|{{Prettytable}}
|- align="center"
| Quick Keys|| Send to All Alt || Send to Team Ctrl
|-
| F1 || Thanks || Defend our base
|-
| F2 || || Our flag is out!
|-
| F3 || ||
|-
| F4 || ||
|-
| F5 || You're Welcome || Attack their base
|-
| F6 || || Their flag is out!
|-
| F7 || ||
|-
| F8 || ||
|-
| F9 || Sorry || Don't shoot tanks on the same team as you please.
|-
| F10 || No problem ||
|-
| F11 || ||
|-
| F12 || Geno gone. || Genocide is held!

|}

LocalAuthentication

2013-02-10T08:24:01Z

JeffM2501: Moved to idea since it's not something we really want to get into, but someone may want to do it as a plugin so keep the info for historical reasons

{{IdeaDesign}}

'''Please note that this proposal has been rejected and is just here for historical reference. Global authentication is the only built in authentication system the project will support'''

A need exists to provide a local version of global authentication, with users, groups, and permissions.

==Overview==
The old local authentication system was not secure, it sent passwords in plain-text as chat messages. This meant that user passwords were stored on the sever in chat logs and easily accessible by anyone. Global Authentication does not send the password directly to a server, but a token. On isolated networks, global authentication is not a valid option.

==Options==
This is a list of authentication options.

===Request Hash Method===
One method is to have a server option (-localAuth) that can be added to the server config. This option is only valid when a server is not set as public. Upon connecting the server will send a password hash request to the client as a new message type. The client will then verify if the server is on the same subnet as itself, if so it will ask the user if they wish to send the password hash to the server, warning them of the issues. The client will then hash up the password ( from the password field ) using a different system then the global auth ( not MD5 ) and send the password as a new message.

The server will NOT log these messages by default and they will happen before the player joins the game.
Questions to answer are:
*Should it be limited to subnets?
*Should there be a system to set "acceptable" lan servers to trust?
*Should there be an option to enter a password just for that one server and the client cache them?

===Legacy As A Plug-In Method===
Another option is to implement the old passDB as a plug-in using a custom slash command. It has the same issues as the old system but becomes more opt in. It can be called "LocalAuth" and even do auto auth based on hostmask/IP if we want to auto op owners. It's simple but does not solve any of the issues with plain-text passwords. This may be enough if everyone is just going to move to global anyway.

==Questions==
*Is this even needed? can LAN users use /password to admin a server? do they really need per user perms?
*Can this be done any way else?
*Can/should we make a little list server that the server can point to, to generate tokens, then ask the players if they trust that server? ( doesn't seem different then trusting the game server really )

2.3 QualityChanges

2013-02-10T08:23:12Z

JeffM2501: Task was completed with 2.4, no longer a design doc but a reference doc

==Overview==
This page describes the changes to the graphics quality system for 2.3

==Goals==
The goals are replicate the graphics quality settings from 2.99.x branch in 2.3. These changes reflect the trend in personal computing towards having better hardware 3d acceleration.

Current "low" and "medium" settings use OpenGL features that are poorly supported in modern ( last 5 years) hardware and actually slow down performance.

==Changes==
The current setting of "medium" will be the new "low", and the current setting of "High" will be the new "medium". Experimental will move down to "high".

High will be the default.

Some settings in high will be defaulted to more modern choices ( stencil instead of stipple for shadows)

==Removals==
Remove requirements for OpenGL 1.0 and 1.1
Remove BSP rendering system
Remove Code fror 3dfx and riva 128
Remove Option for No textures.
Remove Texture filters that don't make sense.
Remove Experimental

[[Category:Graphics]]

2.3 NewShotGraphics

2013-02-10T08:22:37Z

JeffM2501: Task was completed with 2.4, no longer a design doc but a reference doc

==Overview==
This page describes the changes desired to move the new shot graphics from v3 back to 2.3.

==Goals==
The goals are to use the new shot graphics from v2.99.x in 2.3. Two competing shot systems were created in v2.99.x and this project will take the best shot graphics for each shot type.

==Shots==
Trepan's shots will be used for all shot types except for laser, thief and super bullet.

Geolaser will be used for laser and thief.

Geobolt will be used for super bullet.

==GUI==
2 new menu items will be made

1) Menu item for Classic shots or Enhanced shots

2) If shots are set to Enhanced a shot length item will be enabled to set the tail size.

[[Category:Graphics]]

Server Updated Shots

2013-02-10T08:21:38Z

JeffM2501: Remove TODO group, that is what the version planing pages are for

{{DesignDocument}}
This document describes planed changes to shot handling on the client and server.

==Problem==
Shots can not be updated in mid flight. We need the server to be able to modify any shot in flight and have the game clients adapt to the new changes.

==Server Shot State==
To do this, we need the server to have an accurate/authoritative representation of the shots in the game. We need to move the shot strategies over from the client into libGame so they can be tracked by both the players and the server. Shots are '''time stamped''' with a server clock so syncing the states should not be too hard.

It would also be up to the server to send out endshots to all clients. The game client should never send an actual endshot.

==Generic Shot Updates==
A new [[MsgShotUpdate]] will be created that can send a new time stamp, position, vector, and lifetime for any shot. Any client that receives this message needs to find the shot, delete the old shot path, create a new shot path/strat with the starting position, vectors, and times, then plot the shot position forward to the current server time. This may make shots "pop" as they update if there is a discrepancy, but all states will be valid. This prevents clients from having to provide GM shot updates, and lets the server do non standard shot dynamics such as gravity well, and enforcing shot ends in a predictive manner. Shot updates should be exposed to the [[BZFS_API]]

==Guided Missile Update Changes==
The [[MsgGMUpdate]] will be removed. A new message 'MsgLockon' will be added. This message will simply tell the server who the player wishes to lock on to, and notify locked players that they are locked on to. The shot updates will come from the server with a generic [[MsgShotUpdate]].

==Reload Slot From the server==
The reload shot slots will be made to be set by the server on a per player basis using a new [[MsgShotAmmo]] message. This message will tell each player how many shot slots they have and what there reload times are. This will be sent out on each flag update and spawn. It will be exposed to the API.

==Shot ID==
Shot IDs should be separate from the slot. The client should take all newly fired shots and assign them a temporary shot ID until it gets the shot back from the server. At this time it would replace the shot ID with a valid server ID to be used with shot updates at a later date. The local client should send it's temporary shot ID when sending a new MsgShotBegin and be passed that local ID back in the verification message. When the server sends the shot back to the local player, it should recompute the shot path from the new data as if it was a remote path, as the server may have modified it. All local shots can go into one big list on the client, as they will have unique IDs.
===Parted Players===
Players that part will have there shots asigned to the server player, and the shots will become world weapons.

==GM Behavior==
A clarification of the GM behavior is as follows:
*Having The GM flag confers 2 linked abilities to a tank
**The ability to generate GM type shots
**The ability to set a lock on target.
*All live GM shots in the world will always track to the current lock on target for the player they belong to. This behavior is regardless of the target set when a GM is fired.
*A tank can only lock onto a single target at a time. When a new lock is set, it overrides all previous locks.
*When a tank has no lock on target GMs are unguided and will fly along there last vector.
*When the flag is dropped ( ether manually, or by death) The tank looses the ability to set a lock target.
*When a tank dies the current lock on target is cleared for all live GMS, and shots will be unguided.
===Changes from 2.0.x===
The only real change this makes is that the last shot fired from a shot limited GM unable to acquire a target after launch. If the shot is launched locked, it will track.

MapView

2013-02-10T08:20:56Z

JeffM2501: Remove TODO group, that is what the version planing pages are for

{{DesignDocument}}

==Overview==
Map view is an idea to provide more information to players in the HUD to help with dodging shots. It is a cleaner design then what has previously been called "full screen radar"

==Problem==
Given BZFlag's dependence on 2d game-play, it has become increasingly common for some players to use larger and larger radar views in order to get more visual information about the top down view of shots. This information is useful in lining up long shots and for getting out of the way of incoming shots. In order to maintain a clean UI the size of the radar and chat panel in the game limited so that they do not "Crowd out" the 3d view and minimize it's importance. There are gaps in the useful size of the radar, 20 to 30% is useful when the 3d view is needed, full screen is useful when aligning up shots, but sizes like 80 and 90% are rarely useful since they fall in-between the 2 useful cases. On some smaller screens there may not be enough visual information in the limited radar screen for a person's preference. Also in many cases a large radar is only useful when it is made transparent, as a solid background will block the 3d view.

There is a need for a new way to display radar like information for the identification of shot trajectory, while still maintaining a clean UI and not minimizing the importance of the 3d view.

==New Map Mode==
MapView is a new radar mode that will change how the map data is drawn. When MapView is enabled (from key events) the normal radar panel border will not be drawn and the radar data will be drawn as an overlay on the 3d view. This will allow the use of the full screen for radar-like data but allow the 3d view to show. The user will be able to configure an opacity for the map view background that will default to 0% (invisible) to 25%(smokey). There is no point in going to higher capacities as they would block out the 3d view an make it useless. A new BZDB variable will provide an offset for the center of the map view to the center of the screen in the vertical axis. This will allow the user to configure the map view so it does not interfere with other elements.

This arrangement also lets the chat bar extend across the entire screen instead of being tied to the size of the radar panel. Optionally the user can configure the chatbar to be hidden if they do not want it.

===Implementation===
====Keys====
There should be 3 key events, MapViewOn, MapViewOff, and MapViewToggle. The default key bindings should bind only to MapViewToggle, the other 2 modes are to be used by people that want to bind them to key-up and down events to provide a "momentary" button to show the map view instead of a toggle.
====Drawing====
MapView should use the majority of the normal radar drawing modes, except for showing the "fancy tank" at the origin. Drawing will also enforce a transparent background on the map and not use any of the radar opacity settings. It should also have 2 major modes that control the rotation of the map drawn, one for fixed Y+ as "up" and one that makes the tanks' current direction as "up". These settings should be bzdb vars and are not expected to change during game-play. A separate "mapZoom" should also be used to set the scale of the map view independent of the normal radar view.

===Sample Image===
[[Image:MockUPMapview.png|400px|thumb]]
This is a mock-up of what the idea should look like. It shows the map not getting in the way of the 3d view.

[[Category:Enhancements]]

Image Cache Enhancements

2013-02-10T08:20:38Z

JeffM2501: Remove TODO group, that is what the version planing pages are for

{{DesignDocument}}

==Overview==
There are several enhancements we can make to our image caching system.
===Tracker Items===
https://sourceforge.net/tracker/index.php?func=detail&aid=3602336&group_id=3248&atid=353248

==Image Download Confirm==
It would be nice to be able to ask the end user if they wish to add a specific server to the allowed downloads. Children who are running with a locked access file should not be asked. The message should be similar to the message for SSL sites with self signed keys in browsers.

==Force Reload==
In order for a server to use dynamically generated images it must be able to tell clients to reload the image. This has several challenges.

# The client would have to store a hash for the image (may already be done)
# The client would have to know the URL for every image in order to recheck the hash
# Curl would need to tell us if the hash is different from the one on disk
# Curl would need to download the image in the background and not disrupt network play
# The texture system must be able to reload an individual texture from disk with out affecting the frame rate in a bad way.

Some of these challenges may already have solutions, some may need threading or other time management systems to implement properly.

Group Management System

2013-02-10T08:20:06Z

JeffM2501: Remove TODO group, that is what the version planing pages are for

{{DesignDocument}}

A need exists to let users manage their own user groups. At present a forum administrator is needed to add or modify groups. This is not optimal.

==Overview==
A web system needs to be made that allows a user to register an "organization" and manage a number of user groups tied to that organization.

==Concepts==
*'''Organization''': organizations are unique name spaces that are registered by a single user. The contain a number of user groups. An organization may be a game server, a group or network of servers, or a league.
*'''User Group''': user groups contain a list of users that are members of the group, they are managed by a group moderator.
*'''Founder''': the user who registers an organization and can add co-founders and can create/change/delete groups
*'''Managers''': the users that are assigned to a group and can add/remove/approve/deny users for that group.

==Implementation==
This describes a desired implementation.
===Web Interface===
A web page system should be created that allows users to create and manage organizations. Organization must have unique names. If an organization name exists at creation time, the user requesting the new organization should be notified that the name is unavailable. A user should not be able to create an organization that has the same name as any user other than himself. Organizations must keep a link to their founder account, so that we have a contact e-mail for the organization. The founder can add additional co-founders that can do everything except add/remove the founder and other co-founders.

Organization administrator can create any number of user groups. User group names need to only be unique in the organization they belong to. User groups can have any number of members, pulled from the BZFlag user database. The group membership should store the BZID of the user to allow for name changes. Founders should be able to create, destroy, and rename user groups.

Groups should also have a description field that can be edited by any founder, to identify the group. All members of the group should be able to see this description. When a user is added to a group they should be notified as well. Groups shall be either ''private'' or ''public''. A ''private'' group is one where only members of that group can see the group and its members. A ''public'' group is one in which the group and the names of its members are visible to all.

Groups shall also have a 'membership policy' setting which determines how new members can join the group. There will be three options for the membership policy. An Open group is one in which anyone can join, and a Closed group is one in which only the Founder or one of the groups managers can add new members. The third option is 'By Request', which means that any user can request to be a member of the group, and if they are a member then they can remove themselves at any time. A Founder or group manager must Approve or Deny a request to join a 'By Request' group.

For more details on the requirements of the Group Management System see [[Group management system functional requirements]]

===Local Server Setup===
All groups from the local server will be handled in the format of '''OrganizationName.UserGroupName'''. This will fit our current naming convention.

===List Server===
The list server will parse the organization and user group names out of the group requests, and process them as it does now, pulling data from the new system.

===System Administration===
A reserved organization should have global administration permissions, to manage all organizations and user groups if needed

==Reserved Names==
*'''BZFlag:''' this organization is for global management of the system.
*'''Developers:''' this organizations is for developers.
*'''Local:''' this organization is reserved for local server groups and should not exist.

==Conversion From phpbb Groups==
The existing user groups on BZBB are already mostly in the SERVER.GROUP format. We should be able to convert each server into an organization and assign it an owner. The few groups that are left over should be able to be manually ported to the new system. Since the names of most groups will not change, game servers will still work with the new system.

There will be a few difficulties in this process. First, there are already several groups using the BZFLAG organization. If that organization is intended to be reserved, that will need to be handled first.

The second issue will be handling groups with multiple leaders, or organizations that don't have a consistent set of leaders (as in, ORG.GROUP1 and ORG.GROUP2 have leaders that do not overlap). This probably won't be a huge issue for most organizations, but it will still be something that has to be handled.

[[Category:Enhancements]]

Talk:Death and Shot Effects

2013-02-10T08:19:14Z

JeffM2501: moved Talk:2.3 NewEffects to Talk:Death and Shot Effects: some effects were not implemented and are road mapped for later revs.

==Flags==
The idea is the flag you are shot with not the flag you have so some ideas don't make sense. such as OO, why would it turn the tank it shot into bricks? Same for bad flags.

--[[User:JeffM2501|JeffM2501]] 12:52, 26 May 2011 (EDT)

Death and Shot Effects

2013-02-10T08:19:09Z

JeffM2501: moved 2.3 NewEffects to Death and Shot Effects: some effects were not implemented and are road mapped for later revs.

{{DesignDocument}}

==Overview==
2.4 should have some graphical punch to help people upgrade.

==Graphical Missile==
GM can now show a graphical missile.

==GM Trails==

A new 'Smoke' option has been added for GMs, it looks pretty sweet.
<gallery>
image:Gm_smoke_rocket.jpg
</gallery>

==Death effects==
Death effects have been changed so that we can have different effects based on death types.
The following is a list of ideas.

===Standard===
Have tank make explosions, fall apart in a pile then burn

===Steamroller===
Have tank squish flat and burn.

===Laser===
* Have tank glow then fade out, no explode
* Blinding white flash, then have tank glow then fade out, no explode. Wireframe?

===Super Bullet===
Current "rings" explosion

===Flag Capture===
Capping team's flag sprouts out of the top of tank and team colored confetti shoots out around before fade out. No explode.

===Genocide===
Skulls around tank as it falls apart then burns with skull/crossbones smoke.

===Phantom Zone===
* Like geno, but with ghost texture.
* Tank goes 2d in YZ falls over then shatters, Superman 2 style

===Water Death===
Tank slowly scale in Z with bubbles floating up

===Burrow===
* Tank Parts fly straight up in the air.
* Tank sinks into the ground and leaves a tombstone.
* Tank sinks into the ground and leaves a rabbit hole.

===Machine Gun, Rapid Fire===
Tank parts fly away, all using bullet's trajectory.

===High Speed, Agility===
Tank Parts fly away, using reverse of bullet's trajectory.

=== Shockwave===
Tank parts fly a short distance, and stop in mid-air before falling.

===Oscillation===
Tank turns into bricks.

===Bad Flags===
Similar to flag capture.

===Death Driver===
Electrical flashes around tank then char to black before fade with smoke.

===Server Kill===
Tank floats up and slowly fades out in a halo of light

===Guided Missile===
* Missile impact erupts into a small mushroom cloud, both tank an missile parts scatter out from point of impact
* leave scorch marks on ground/buildings that fades out slowly over time.

GSoC: LibBZW

2013-02-10T08:17:14Z

JeffM2501: Move to SOC 2008 group

''libBZW is a proposed library that will encompass current and future [[BZW]] functionality, replacing independant implementations in various applications, including bzfs.''
==Implementation==
libBZW will be implemented as a static library within [[BZFlag]]. Applications/builds depending on libBZW should be within the BZFlag tree as well for sanity's sake (i.e. [[BZFS]] will depend on libBZW, and is within /bzflag/src).

==Features==
*BZW file parsing

==Functionality==
libBZW will initially contain methods and functionality from the following sources:
Just so I can keep track of what files I will need initially, obtained via grep, primitive list.
Need to add summaries of functionality desired to be copied/reproduced/replicated from each file. --Lukstr
*bzflag/
**src/
***bzfs/
****'''bzfs.cxx''' -- ''Read worlds (via stream/blob or filename), retrieve WorldInfo''
****'''BZWReader.h'''
****'''BZWReader.cxx'''
****'''BZWError.cxx'''
****'''BZWError.h'''
****'''CmdLineOptions.cxx'''
***bzflag/
****'''World.cxx'''
**tools/
***modeltool/
****'''modeltool.cxx''' -- ''Creating/writing bzw files''
*bzwworkbench/
**src/
***model/
****'''BZWParser.cpp''' -- ''Cleaner parser than bzfs?''
****'''Model.cpp'''
**include/
***model/
****'''BZWParser.h'''
****'''Model.h'''

==API==

[[Category: Summer Of Code 2008]]

MapView

2013-02-10T08:16:18Z

JeffM2501: Still a valid idea that nobody has shot down.

GSoC: Webadmin 2008

2013-02-10T08:12:34Z

JeffM2501: Add link to SOC 2008 specific category

This is [[User:BugQ|bugQ]]'s proposal for [[GSoC]] 2008, which may change with the minds of those involved.

See bugQ's development blog to check and discuss the project's progress: http://planet-soc.com/blog/89

==Overview==
'''webadmin''' will be a web-based control interface for [[BZFS]]. As opposed to the existing Javascript/HTML [https://bzflag.svn.sourceforge.net/svnroot/bzflag/trunk/bzflag/misc/bzfs_conf.html tool] for generating config files, this interface will let the server owner control the server directly via a standard web browser.

==Design==
The use of a browser with a live server will allow additional administration and configuration tasks that are not available with a simple config.
These tasks include:
* Editing all config-related files
* Saving configuration on server-side
* Reading and clearing logs
* Controlling and checking the status of the server process.

=== Initial Limitations===
Optimally the tool could be developed to a point where it was able to control nearly every aspect of the server. The primary focus of this initial design interface will be ease of use and security. Portability is also a major secondary concern.

==Proposed Features==

=== File editing===
An example feature lacking in <tt>bzfs_conf.html</tt> is the ability to edit and save the several other config-related files, like badwords and helpmsg, from within the browser.
This is reasonable, since Javascript can't usually write to disk, but for this project, it's a necessity. It could be as simple as a text field, but a more sophisticated interface might be useful, such as a table of banned IP addresses with a custom input form and buttons to remove addresses from the list. Depending on the of complexity and layout of these, a separate page for the editing interface for each file might also be warranted. On the other hand, the daemon will overwrite a few files on exit for the things that can be changed by server commands, like the banlist, so a better option for those might be to let the user issue commands to the server from the web interface, which would give control over other parts of the server, as well.

=== Plugins ===
The user should be able to choose from plugins and maps in pre-defined folders, and upload custom maps. Depending on the relative difficulty, maps might be validated on upload or BZFS will check them on startup. (Although it would be interesting to do the same for plugin files, there probably wouldn't be any nice way of keeping it secure.)

==Code==
Javascript will be used sparingly, in places where it makes the interface easier to use. Since not all users allow Javascript, of course, any client-side input validation will be mirrored on the server side. If time allows, and if it would add to the usability of the tool in certain areas, some use of asynchronus Javascript messages through XMLHttpRequest might be explored. However, the entire interface must lose no functionality where user scripting is unavailable.

There should also be very few external tools used in this project, so that it can be deployed as widely as possible. It could be written in PHP or another common scripting language, but that would require whatever language chosen to be present on the host machine. Since BZFlag itself is written in C++, using that language would eliminate the dependency. It would also allow the admin interface to be implemented as a plug-in, using the in-port HTTP feature of the BZFS API, which would likely make it more convenient to deploy. However, in order to ease development, a scripting language may be used to create a working prototype which would then be a blueprint to rewrite the tool in C++.

==Development==
[[User:BugQ|BugQ]] will be carrying out tests on the config files generated by the tool as well as hosting a test server for others to try and give comments on. Suggestions on unnecessary or possible new features should be added to the talk page.

[[Category: Summer Of Code 2008]]

Google Summer of Code: 2008

2013-02-10T08:12:22Z

JeffM2501: Add link to SOC 2008 specific category

The 2008 Google Summer of Code was announced on February 25, 2008. BZFlag has been accepted again this year as a mentoring organization. Given our enormously successful participation in the program in 2007, we're very excited to be participating again and we're very happy to see the applications that were submitted. BZFlag accepted student project proposals from March 24 until April 7 ending at 5:00 PDT (0:00 April 8 GMT). Further information on our proposal ideas are below. Hints and tips on [[Google_Summer_of_Code|getting started, preparing a submission, and the application process]] were available. '''''Accepted student proposals will be announced here and on the Google Summer of Code homepage on April 21 at around 12:00 PM PDT (19:00 GMT).'''''

= Promotion Flyers =

{|align="right"
|[[Image:BZGSoC2008_small.gif|thumb|left|512px]]
|}

Provided below is a promotional flyer to help spread the word about our involvement with the Google Summer of Code. Flyers are available in various languages that we have mentors for so that students from all over the globe can be informed about the program. While many developers can converse fluently in other languages, English is still expected for most developer discussions. Feel free to distribute the flyer around your local colleges and universities.

* English ([http://my.bzflag.org/gsoc/BZGSoC2008.pdf PDF]) ([http://my.bzflag.org/gsoc/BZGSoC2008.png PNG])
* Deutsch | German ([http://my.bzflag.org/gsoc/BZGSoC2008_de.pdf PDF]) ([http://my.bzflag.org/gsoc/BZGSoC2008_de.png PNG])
* Español | Spanish ([http://my.bzflag.org/gsoc/BZGSoC2008_es.pdf PDF]) ([http://my.bzflag.org/gsoc/BZGSoC2008_es.png PNG])

High praise and special thanks to Harry Keller (aka Saturos) for designing our 2008 GSoC flyer.

= Proposal Ideas =

While there are lots of [[Ideas]] floating around of varying utility to the game, the ideas listed below are the specific areas that we are predominantly interested in seeing worked on as part of the GSoC. Please note that students are also welcome and encouraged to apply with their own ideas. They should run those ideas by one of the developers beforehand to make sure they are consistent with the scope and focus of the project, though, as there are some ideas which will not be accepted regardless of the quality of the application and applicant. We've additionally provided several project ideas important to BZFlag development that we would very much like to see proposals for, shown in following.

== Suggest your own idea ==
BZFlag is always open to new development ideas and is under constant improvement. If you are familiar with BZFlag's current capabilities and would like to propose some new enhancement, we'd be happy to hear about. Please discuss any new ideas with the existing core developers (on our IRC channel), if only to make sure the ideas are in-line with the spirit and constraints of the game.

== Cheat preventions ==
This task involves making BZFlag more robust towards preventing various cheats from working in the game. This task implicitly requires adding protections on the server, moving game logic from the client to the server, and/or adding heuristics and other measures for detecting and dealing with cheat clients. The student should have a strong grasp of the variety of BZFlag cheats that are available. Please go into detail about which cheats you're interested in preventing and how you intend to employ those preventive measures. For information on known cheats, check out the [[Known Cheats]] wiki page.

== Global authentication daemon ==
The goal of this project would be to provide global account management system daemon that the client and servers would communicate with for account, group membership, and profile information. This effort preferably be written in C++, would need to talk to an LDAP server for persistent storage on the backend, and allow chaining across multiple daemons for data replication and failover service. The daemon would need to provide a well structured simple communications API that the game client and game servers can securely talk to.

== BZWorkBench world editor enhancement ==
As a participant in last year's program, Jude Nelson started work on BZWorkBench. It is a world file editor with a very solid foundation but much work still remains to be done, including a cross-platform GUI, mesh support, and other editor features. Ideally, two students would work on this. For example, one student could focus on improving the GUI's workflow and ease-of-use, and another could focus on finishing the back-end object manipulation.
The current GUI does not conform to a specific HIG, nor does its usability resemble many other 3D editors; this should change. The back-end still lacks support for many of the objects added in BZFlag 2.0, such as Meshes, texture matrices, dynamic colors, etc.

== Enhanced server listing ==
The game client includes a simplistic listing of publicly available servers. This task would involve significantly enhancing the listing section in BZFlag to allow for various sortings (e.g. ping time, country, name, etc), favorites, recently used, specific additional information on specific servers, and all existing information. The task would involve coming up with a user-friendly design that is fully keyboard-accessible. It could leverage external gui toolkits, use BZFlag's existing gui library, and/or extend the existing capabilities. The focus would be on creating an intuitive and informative listing enhancement within the constraints of the gaming interface.

== Modularization of game logic ==
Much of the game logic is presently mixed in with BZFlag's graphics code. This lack of organization make it difficult to find code when necessary, and does not allow bzfs, bzrobots, or other tools to utilize the game logic. The game code should be modularized into [[DevelopmentGoals#libGame|libgame]] so that all that is left in the client code is the graphics subsystem. This will also ease the possible future integration of a 3D graphics engine.

== Dead Reckoning and other Networking Enhancements ==
The basic idea is to improve BZFlag's networking by performing dead reckoning on the server along with context-sensitive packet delivery culling. Much work has gone into the game towards moving more and more of the game state to the server, but there is additional migration and protocol changes required. Similarly, network utilization can be optimized by not relaying certain packets (like miniscule position updates to distant players) based on the current game state. Some useful background reading for this task include "[http://www.research.ibm.com/netgames2005/papers/aggarwal.pdf Fairness in Dead-Reckoning based Distributed Multi-Player Games (pdf)]" and "[http://www.sigcomm.org/sigcomm2004/workshop_papers/net610-aggarwal.pdf Accuracy in Dead-Reckoning Based Distributed Multi-Player Games (pdf)]".

== Enhanced cross-platform multiple display support ==
Add the ability to effectively manage multiple display environments from within the game allowing for the detection, alignment/orientation specification, and resolution parameters for each display via menu options as well as proper full-screen and/or windowed support. An additional feature could involve allowing the user to dedicate a display to the various primary gui elements (the 3D environment, the radar, and the chat console). BZFlag's current context management is mostly handled by SDL or other platform-specific modules, so this could be taken into consideration. There's also the possibility of our move to an integrated graphics engine would similarly impact how multidisplay contexts are created and managed.

== Enhanced Statistics system ==
The goal of this idea would be to extend the existing web based statistics system to be more robust.

Features could include:

*Better integration with the list server.
*Use of a plug-in or server based stat "push" system instead of the current "pull" system.
*Better publishing of stats
*Publishing of recorded stat data to other sites.
*Better tracking of registered and unregistered players
*Tracking of leagues and individual match games.
*Generalizing the stats system to be used in other games/projects.

== Integrated BZFS web interface ==
The BZFlag game server, BZFS, could benefit from having a browser-accessible http/https interface for viewing server statistics, setting various parameters, and otherwise controlling the server daemon while it is running. Similar to how your network router has a web interface for changing configuration parameters, this idea is simply to create this interface in a maintainable and portable manner. Please go into detail on how exactly you'd go about doing this.

== Network Testing and Simulation Environment ==
This task should provide a controlled testing environment for simulating network behavioral characteristics, including the ability to change virtual network parameters to induce different network conditions of lag and packet loss. This environment should provide a viewer capability to observe interactions of BZFlag clients being tested from the perspective of the player, the server, and third-party observers. This simulation framework should work with the client and server directly so that testing of actual changes may be performed in a stand-alone environment.

== Cross server communications system ==
This task would be the design and implementation of a server spanning chat system. It would allow players from one server to send chat messages to players on other servers. It should also be able to be used to allow players to know where there friends or "buddies" are playing if they are online. The system should tie into the central user name registration system. Added benefits would be the use of existing protocols or applications, such as Jabber or IRC, if they can be integrated cleanly. Support for using off-line apps for chat and friends list access as well as server management would be a plus.

== In-game profile management ==
BZFlag allows players to specify a callsign and team in addition to other player characteristics and preferences. This enhancement would focus on allowing the user to specify and manage multiple profiles from within the game. Profiles could be linked together and should be presented in an intuitive manner (proposal should highlight how you'd go about achieving that). The profiles would need to associate with global account information as well.

= Mentors =
The mentors for 2008 are;
* Sean Morrison (brlcad/learner)
* Daniel Remenak (DTRemenak/Erroneous)
* Jeffrey Myers (JeffM/JeffM2501)
* Julio Jiménez Borreguero (Manu/jujibo)
* Scott Wichser (Blast/Blast007)
* David Wollner (JB diGriz)
* Joe VanOverberghe (Donny_Baker)
* James Lawrence (spldart)

= Thanks & Appreciation =

Thank you to the following individuals in the BZFlag community that helped prepare GSoC-related marketing materials:

* Harry Keller (aka Saturos)
* Julio Jiménez Borreguero (aka jujibo aka Manu)
* Dexter Mason (aka whodaman)
* Sean Morrison (aka learner aka brlcad)
* Jeffrey Myers (aka JeffM)

[[Category: Development]]
[[Category: Summer Of Code 2008]]

Radar Marker

2013-02-10T08:10:06Z

JeffM2501: /* Contents */ merge in Radar Annotations since it's just a subset of the markers

{{DesignDocument}}
==Overview==
A radar marker is a generic radar specific object controlled by the server. It is used to flag things such as the location of team flags, and hunted targets. There is also a [[Radar Marker(object)|proposed map object]] that would allow maps to define arbitrary markers in the map.

==Contents==
The object will contain a sub-type and associated data.

The client will then display each subtype on the radar view only. Unknown sub-types will be ignored.
All 3d point data would be in world space, with the objects being drawn in Z order ( lowest to highest ) in orthographic projection with the map.

The object should also include a text label as an option.

==Uses==
By taking the maker logic off of the server, we can make the logic be more customizable by the servers' game logic and plug-ins. Addin an option to tie a marker to the location of a specific moving object (tank) would allow for a number of gameplay variations.

==Implementation==
The client would only need to know how to draw a number of generic marker types ( various shapes ) in a server defined color. The server would simply send a marker message to the client with postional data ( and an attachment object if desired ). The client would then not need to know what this marker is, but simply store it and draw it every frame. Some radar marker types could also have HUD marker components ( flag and hunt ), this should be optional.

By using a separate message system for the markers that is not tied to the map file, the game can send out dynamic updates to the markers while the game is running. This can allow for additional game play modes such as domination, where the controlled base is flagged on the radar with the appropriate color.

[[category:proposed changes]]

Network Protocol

2013-02-10T08:08:01Z

JeffM2501: Isn't really a design document but a set of incomplete references, goes into other categories

{{Inaccurate}}

= 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 motto can be anything,
including the email address for human players (e.g. username@hostname).
BZFlag players can choose `anonymous' instead of their motto. 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:Development]]
[[Category:Concepts]]

Karma System

2013-02-10T08:06:57Z

JeffM2501: move to IdeaDesign

{{IdeaDesign}}

The Karma System is a proposed player reputation system. At present the "Karma" portion of the system is unimplemented.

==Overview==
The "Karma" system is a proposed player reputation tracking system put forward by [[Tim Riker]]. It's goal is to provide information to users about the behaviors and past actions of other players. Good and helpful players would receive positive "Karma" points, while poor or disruptive players would receive negative points. Servers would have the option of limiting the actions, or outright blocking of players who did not meet some minimum Karma point total.

==Objectives==
There are two main objectives of the system:
*prevent misuse of callsigns
*solve cheating issues on the social level

==Player Database==
The player database keeps entries for registered players. Each entry must at
least contain the player's callsign, email address and some data to allow
for authentication. This data must be accessible by [[public]] [[BZFS]] servers so
that these can screen joining players. Any changes require private key signed
updates.

The player database system is implemented as part of the [[Global Registration]] system that is part of the BZFlag [[List Server]].

==Karma System==
With the karma system, a rating ''the so-called karma'' is assigned to each registered player in the database. This value should represent the player's reputation within the community, i.e. well-known and nice players should have a high karma value whereas known cheaters will hopefully get a low value.

BZFlag servers can access this information and for example prevent people with too bad karma from joining the server. Players must have some means to rate other players, thus modifying their karma. It is important that the karma system is balanced and robust against abuse.

==Implementation==
The player database, registration , and authentication systems are currently in place as part of the [[Global Registration]] system. They have been implemented since [[BZFlag 2.0.0|v2.0.0]] of the software.

===karma system===
* A new player starts with a neutral karma value, I guess 0 is a natural starting point :-). Karma might be an integer of a floating point value.
* Each BZFlag server can be configured to require a minimum karma value for each player. When a player does not meet this criterion, he will be rejected. Hopefully, this reduced cheating on these 'high quality' servers. Of course there should also be some servers which are open to everyone, otherwise new players could never play and increase their karma. Server admins should balance reasons for specifying a low karma threshold, and thus allowing everyone to play on their server or requiring very high karma and possible improve the quality of people playing, but at the cost of ruling out many players and possibly having a very empty server.
* the server could also be configured with a minimum admin karma. Players that meet the criteria would be able to change server options, kick players etc. We may want multiple levels of admin access.
* There must be a convenient way for a player to rate another player. I guess it's best to be able to do this in-game. Should rating just be done by using +/- resp. up/down? Or by giving a value from -5 to 5? For this to be easy, the player to be rated must be selected in some way. How? A player should be able to see the rank he has given other players easily. Perhaps even on the scoreboard.
* When doing ratings in-game, either the client or the server must send messages to the list server. It's probably best if the client sends a signed update to the server and the server forwards it (with game updates as well) to the list server and then updates the rated player info if the list server verifies the signed update packet. The signature is required so that the list server can verify the source of the ranking. Servers might otherwise fake ratings.
* Should karma value and/or individual ratings be publicly visible / visible to the player himself? Tim thinks so. Players should be able to see who has ranked them, but not what rank they have been given. They should be able to see all the players they have ranked at what rank they have given them. They should also be able to see any player's rank including their own.
* The karma value of a player must be calculated as a function of all individual ratings from other players. This must be done in a 'fair' way that is robust against misuse. A possible misuse would be a player A registering a lot of identities and giving a low rating to player B with all of his identities. So, ratings must be weighted by karma and player age. This must be designed very carefully, so I suggest stealing this from somewhere. It will be necessary to store the resulting karma value for each player as well as every rating given.
* Do we want or need some privileged players whose ratings have more weight? This might be needed to get the system started.

==Basic rules for karma adjustment==
*A user can only have one karma value per other player. This can be changed at any point
*Impact is determined by these factors:
**Current rating
**Assignment tendency (neutral = more impact, all good or all bad = less impact) [keep in mind that some users will ONLY rate players whom they like]
**Player age - long-time players will have more influence
**Playing time - people who spend their lives in BZFlag should have more power

==Possible implementation==
[[David Trowbridge]] submitted the following proposal:
Store the entire karma network as a weighted directed graph. Weights along
the edges should go from -5 to 5 or some other range specifying the karma
adjustment from one player to another. Each node would also have a weight,
calculated from the other factors listed above (age, time, etc). When a
karma adjustment is made, a walk of the graph is done, computing everbody's
new karma (if someone near the root gets modded up, it could have repercussions
through the entire tree, strengthening the adjustments they themselves
have made). Nodes furthest from the root (note: the 'root' would be someone
completely trusted, like the [[Project Administrators]]) have the lowest karma.

With this scheme, bad accounts could be deleted by the same type of algorithm as used for Advogato's trust metric, setting up a supersink and cutting away all bad nodes, thus preventing abuse.

==Other database items==

The karma system would use a central server (or servers) to store the data. [[Tim Riker]] imagines that this system would include other useful bits like player ladder ranks, league membership, league ranks, map ranks, etc. It may contain gpg signatures, ssh public keys, or perhaps the karma server is a certificate authority for ssl keys and server keys and player keys are authenticated there. The player keys could actually be presented to the users's browser and use that information to log in to the karma website.

==Karma Web Site==
The website would show overall ranks for players on the trust scale and probably also ladder ranks, live servers, server stats, player stats, etc. A player would need to authenticate to edit settings. This page would show everyone this player has ranked and the rank they currently have. These would be highlighted to show if those players have ranked this player too. There would be a separate list of people that have ranked this player colored to show if this player has also ranked them. The actual ranks are not shown to encourage fair ranking.

==History==
The Karma System was the original impetus for the the [[Global Registration]] System that is in use today. The user management and database for this system was chosen to be the user database used by the [[BZFlag Forums]]. This is seen as a limitation by some developers, as modification and extension of the [http://www.phpbb.com PHPBB] that the forums are based on has proved to be difficult. Current development ideas revolve around moving the [[List Server]] to a more distributed system and separating it from the forum system, as well as incorporating a karma or other reputation system.

The lack of development work on the proposed karma system for such a long time, has led it to be somewhat of an 'in joke' with the development community, representing desired features that have gone dormant or do not seem likely to be completed.

==See also==
[[Global Registration]]

[[List Server]]

[[BZFS]]

==External Links==
*http://Advogato.org/ - free software group trust metrics
*http://keyserver.kjsl.com/~jharris/ka/current/ - GPG trust matrix analysis
*http://ggz.sourceforge.net/ - possible platform, not planned at present

GSoC: BZWGen revisited

2013-02-10T08:06:06Z

JeffM2501: move to IdeaDesign

{{IdeaDesign}}

This is a two part project that aims to address two main issues of BZWGen, accessibility and universality.

Accessibility has been probably the main reason that BZWGen didn't get much attention -- using the program required downloading a separate program and compiling it's sources, then running it and setting it up to work with bzfs. On the other side, getting the program to produce different results requires the knowledge of a language that however documented is not straightforward for the user.

Universality addresses the fact that BZWGen would more accurately be called now a City Generator, despite the fact that the underlying engine could do much more. Furthermore, some of the ideas I initially had for 2007 were never even touched. The second (bigger) part of this years project would be to present an accessible way for the program to generate a broad choice of outputs.

== Deliverables ==

The aim of the project is to provide a revised version of BZWGen that will work both as a standalone app and a plugin to bzfs. As a side effect, a common protocol will be presented for handling world-generating plugins.

The generator itself will be severely enhanced to provide a much wider array of output, and to allow a first time user to do much customization without the need of reading much documentation. Additionally textures and data files for the extended generator capabilities will be provided as well.

=== Streamlining ===

To pluginize BZWGen a common interface for generators will be established, which will take care of supplying the generator with necessary data. In case of bzfs data will be read from a config file. The existing map generator will then also be pluginized, an in the future, replaced by a config file for BZWGen that ideally mimics it's behavior.

=== Documentation update ===

As the system currently is somewhat mysterious to people, I'd like to provide better documentation on the L-system generator, including an illustrated tutorial on writing your own rules.

=== Config file layer ===

L-systems are hardly transparent for someone not used to them. However I didn't intend them as the main modification tool. Above the low-level L-system layer there should be a lot more readable "template" file layer, that decides what will be generated on a given map zone. What now is treated as command line parameters for BZWG will then be placed in the template file, along with the ability to use different texture sets, and load custom L-system sets.

=== Generation zones ===

The L-system based approach that BZWG uses now is just one of the features I intended for it. To smoothly blend multiple generation tools a system of splitting the map into zones is needed. Each zone will have generation parameters supplied via config files. Zones will be not limited to rectangles as is the case now, but any arbitrary polygon.

=== Road placement algorithm rewrite ===

The current subdivision method will be left intact as an option, but thanks to the custom shaped generation zones, the original intent of the L-system based road placement generator will be implemented. Apart for generating roads it will be able to do a custom territory split of a given map.

=== Extensions ===

Some of the planned extensions to the generator itself are listed below:

* scatter algorithms -- expands on the existing bzfs map generator to allow a finer control on scattering, like the control of scattered objects, control over where objects may be scattered, and control over their size and orientation. Higher level example -- scattering of L-system generated buildings.

* template based building -- a way to control the placement of other generation algorithms -- constructs the map out of a predefined template, where the template parts will be filled with the given generation result, or a preprepared map-tile.

* block-connected building -- the map is build out of pre-prepared chunks of geometry that follow the defined rules for connection. This is the way that map generation works in contemporary 3d RPG games -- dungeons are constructed from preprepared components randomly connected. The approach is suitable for overland structures as well.

* procedural objects -- as time will allow BZWG will be equipped with procedural generators for various real-world objects, for example trees and foliage. Priority is set on items that can be used in the scatter algorithm.

== Project schedule ==

The existing blog ( http://bzflag.chaosforge.org/ ) will be used to report progress. Posts will be made at least twice weekly during the main program timeframe. Having the experience of last year, I hope to organize my time a lot better this year, and get a lot more accomplished.

=== Phase 1 -- May 26 - July 1 ===

==== May 26 - June 15 ====
* bzwgen compiles and works as a plugin for bzfs
* bzwgen's existing codebase is cleaned up
* a detailed schedule and plan for the rest of GSoC is prepared and accepted
* design for the template layer and other promised features
* reevaluation of bzflags collision code
* alternative ruleset/textureset to show the current capabilities

==== June 16 - June 28 ====
* implementation of double-linked graph based network for usage for both the road network algorithm and the new zoning algorithm
* implementation of an alternative ad-hoc non-orthogonal road layout generator and making it work with the existing grammar (especially rewriting zones to be non-quad)

==== June 30 - July 6 ====
* scatter generator
* primitives and custom mesh consolidation
* procedural meshes (extension of grammar if needed)
* reconstructing the existing generator as a compile option

=== Phase 2 -- July 6 - August 11 ===

==== July 6 - July 14 ====
* setting up a test server, promotion on the forum, and outside
* refining the road layout algorithm to be less chaotic, and more realistic
* config file layer

==== July 14 - July 20 ====
* extentending the config file layer with full templating capabilities
* documentation and tutorial for the existing config/template system
* sample interesting template/config files, more media

==== July 21 - July 27 ====
* extension of the grammar system to allow more Mueller-quality buildings (I think I found a solution for that)

==== July 28 - August 3 ====
* block-connected building system based on the mesh import feature
* sample data for both "internal" and "external" effects
* additional template files, and documentation for this and previous weeks features

==== July 4 - August 11 ====
* bringing it all together, and merging with BZFlag core as much as the devs allow

=== Phase 3 -- August 11+ ===

Cleanup time for the GSoC finalization. Once that is done, I hope that there will be some RFE's from the community that I will be happy to implement.

BZFS2 prototype

2013-02-10T08:05:23Z

JeffM2501: move to IdeaDesign

{{IdeaDesign}}
''This is an overview of the BZFS2 prototype released 4/22/2007.''
''This document describes a proof of concept rewrite of BZFS, it does not represent the current state of any release or version of the main project code.''
==The New Paradigms==
'''Channel''' - Channels are for transmitting various data at different priorities and with different rights. Players 'tune in' and 'tune out' of channels depending on the state they are in and the rights that are conferred to them.

The channel model has a super channel which every client is connected to immediately upon connecting to the server. Then, there are one or more game channels where the game is actually played, and any game-related data is sent within this channel. There is at least one admin channel which authenticated users are tuned in to for admin-specific data.

'''Group''' - The new security model is a layered grouping model. All entities (players, channels, other groups), are within a group, and rights for any entity depend on the rights of a group and all it's ancestor groups.

'''Task''' - Tasks can be running tasks or timed tasks, and can be registered either from the server, or from plug-ins.
==Networking==
Networking is now separate from player data. The base class is Client (Similar to the NetConnectedPeer), with children LocalClient and RemoteClient (RelayClient is planned). The Client abstracts the network implementation away from the server. RemoteClient uses basic sockets, ENetRemoteClient will use ENet, SDLRemoteClient will use SDL-Net.

Message are queued and directed by the Channel. Broadcast messages are broadcast to clients tuned to the channel. Only messages broadcast on the super channel are guaranteed to reach every connected client.

'''Relay Servers''' - One method of handling latency over long distances is a relay server, which clients local to the this relay connect to it, and the relay connects to the main server. Messages both ways are batched and fewer packets are sent between a relay and the main than between the main and a direct client player.
==Game State==
This server engine is designed to allow game state to be kept by the server in an abstracted form. How this will be implemented is yet to be decided.
==Plug-ins==
Several functions that are part of the current BZFS have been removed to be implemented as plug-ins instead. This includes admin functions and voting. This means the server would be packaged with several default plug-ins that add core functionality.

==API==
Additional API is required to support the admin function plugin, and allow plug-ins to register tasks and commands. By and large, the API does remain the same.

Template:IdeaDesign

2013-02-10T08:05:02Z

JeffM2501: add template for design docs for ideas for new features that aren't yet in the roadmap.

{|style="width:100%;margin-top:+.7em;background-color:#99ccff;border:1px solid #ccc;"
|[[Image:Picture_Frame.png]]
||'''This page contains a design document for an possible enhancement or feature. It is a work of collaborative design and has not been accepted as a development goal at this time. The final implmented feature if any may differ from the information on this page. If you are not part of the development or design group, please post comments and suggestions on the talk page and not in the middle of the design.'''
|} 
<includeonly>[[Category:Unapproved Development Ideas]]</includeonly>
<noinclude>Adding this template to a page will automatically add the page to the [[:Category:Unapproved Development Ideas|Category:Unapproved Development Ideas]] page. To use this template add '''<nowiki>{{IdeaDesign}}</nowiki>''' to at the top of the page you are creating/editing.</noinclude>

BZFS2 prototype

2013-02-10T08:02:12Z

JeffM2501: Fix categories

{{DesignDocument}}
''This is an overview of the BZFS2 prototype released 4/22/2007.''
''This document describes a proof of concept rewrite of BZFS, it does not represent the current state of any release or version of the main project code.''
==The New Paradigms==
'''Channel''' - Channels are for transmitting various data at different priorities and with different rights. Players 'tune in' and 'tune out' of channels depending on the state they are in and the rights that are conferred to them.

The channel model has a super channel which every client is connected to immediately upon connecting to the server. Then, there are one or more game channels where the game is actually played, and any game-related data is sent within this channel. There is at least one admin channel which authenticated users are tuned in to for admin-specific data.

'''Group''' - The new security model is a layered grouping model. All entities (players, channels, other groups), are within a group, and rights for any entity depend on the rights of a group and all it's ancestor groups.

'''Task''' - Tasks can be running tasks or timed tasks, and can be registered either from the server, or from plug-ins.
==Networking==
Networking is now separate from player data. The base class is Client (Similar to the NetConnectedPeer), with children LocalClient and RemoteClient (RelayClient is planned). The Client abstracts the network implementation away from the server. RemoteClient uses basic sockets, ENetRemoteClient will use ENet, SDLRemoteClient will use SDL-Net.

Message are queued and directed by the Channel. Broadcast messages are broadcast to clients tuned to the channel. Only messages broadcast on the super channel are guaranteed to reach every connected client.

'''Relay Servers''' - One method of handling latency over long distances is a relay server, which clients local to the this relay connect to it, and the relay connects to the main server. Messages both ways are batched and fewer packets are sent between a relay and the main than between the main and a direct client player.
==Game State==
This server engine is designed to allow game state to be kept by the server in an abstracted form. How this will be implemented is yet to be decided.
==Plug-ins==
Several functions that are part of the current BZFS have been removed to be implemented as plug-ins instead. This includes admin functions and voting. This means the server would be packaged with several default plug-ins that add core functionality.

==API==
Additional API is required to support the admin function plugin, and allow plug-ins to register tasks and commands. By and large, the API does remain the same.

[[Category:Unapproved Development Ideas]]

GMS: Register Group Namespace

2013-02-10T08:00:44Z

JeffM2501: Move to spec

{{Specification}}

== Introduction ==
The purpose of this use case is to describe the process used to register (create) a new group namespace (organisation).

[[Image:UseCase_Register_Group_Namespace-sml.png|Use Case diagram]]

The diagram shows the requirements and rules the use case is responsible for (via the <<realize>> stereotype).

== Pre-conditions ==
None

== Post conditions ==
A new group namespace has been created with the actor identified as its founder.

== Requirements and rules realized ==
* ''RQ1 Namespace names must be unique'' 
The system shall prevent a namespace name from being registered if one with the identical name already exists.

* ''BR1 Prevent the use of reserved namespaces'' 
The system shall prevent a namespace from being registered if it is identical to that of a reserved name.

* ''RQ2 Namespace names cannot be identical to a player name other than that of the founder'' 
The system shall prevent a namespace name from being registered if it is identical to that of a registered player other than the one the actor has logged in with.

* ''RQ3 The player who registers a namespace shall be its founder'' 
The system shall grant founder status to the player who first registers the namespace.

* ''RQ4 Only registered players shall be permitted to register a namespace'' 
The system shall prevent unregistered players from registering a new namespace.

== Flow of events ==
The flow of events describes the main actor actions and system responses in the execution of the use case.

[[Image:Activity_Register_Group_Namespace-sml.png|Activity diagram showing flow of events]]

== Messages ==
<properties>
Step:= EX-1
Condition:= Unregistered player
Message Number:= Err 1
Message Text:= You must log-in with your BZFlag call sign (user name) in order to register a new namespace.
</properties>

----

<properties>
Step:= EX-2
Condition:= Invalid namespace name
Message Number:= Err 2
Message Text:= The namespace name is not valid. It must be unique and cannot be the same as another BZFlag user name.
</properties>

----

<properties>
Step:= BF-4
Condition:= Successfully added new namespace
Message Number:= Msg 1
Message Text:= The namespace has been registered successfully.
</properties>

[[:Category:Group Manager]]

GMS: View Groups

2013-02-10T08:00:20Z

JeffM2501: Move to spec

{{Specification}}

== Introduction ==
This use case describes the process of viewing the groups the actor is associated with. These are groups the actor is a member of, or those they are the group manager of, and those which they have created. The actor can also retrieve a member list from those groups.

[[Image:UseCase_View_Groups-sml.png|Use case diagram of viewing groups]]

== Pre-conditions ==
None

== Post conditions ==
The list of groups the actor is in has been displayed to the actor.

== Requirements and rules realized ==
'''RQ5 Private groups are hidden from players''' 
The system shall prevent players from viewing the group name and members of private groups they are not a member of. 
* ''BR2 Members of private groups'' 
A member of a private group can see who the other members of that group are. 
* ''BR3 Public groups visible to all players'' 
The group name and members of public groups can be viewed by all players 

'''RQ6 Founders able to view all groups and members''' 
The founder, and any co-founders, of a group namespace shall be able to view all groups and group members associated to that namespace. 

'''RQ7 Group managers can view the list of members''' 
The system shall enable group managers to view the list of members in any group they manage.

'''RQ32 Display groups and roles''' 
The system shall display the groups a player is in, the roles which have been assigned to them, and the groups the actor has created. 
* ''BR39 Separate roles from membership'' 
The system shall display the roles a player has separately from the groups they are a member of. 
* ''BR12 Sort results in ascending alphabetical order'' 
The system shall sort the result set into ascending alphabetical order using namespace, then group name. 

== Flow of events ==
The flow of events describes the main actor actions and system responses in the execution of the use case.

[[Image:Activity_View_Groups-sml.png|Activity diagram of viewing groups]]

== Messages ==
<properties>
Step:= EX-1
Condition:= Player not in any groups
Message Number:= Msg 3
Message Text:= No groups found: you are not a member of any groups.
</properties>

[[:Category:Group Manager]]

GMS: Search for Player

2013-02-10T08:00:02Z

JeffM2501: Move to spec

{{Specification}}

== Introduction ==
This use case describes the process a group manager will use to search for a player, during the process of adding a player to one or more groups they manage.

[[Image:UC_Search_for_player.png|Use Case diagram]]

The diagram shows the requirements and rules the use case is responsible for (via the <<requirement>> stereotype).

== Pre-conditions ==
None

== Post conditions ==
The system has displayed details of the player the actor has indicated.

== Requirements and rules realized ==
'''RQ21 Search for player''' 
The system shall enable managers to search for players matching a callsign (name) they provide. 
* ''BR9 Search for exact match then partial'' 
The system shall use the criteria supplied by the actor to search for an exact match. If no exact matches are found then the system shall use a partial match method to find names which are similar. 

'''RQ22 Result set contents''' 
For each player found, the system shall display information in rules BR31 and BR32. 
* ''BR10 Indicate partial match separately'' 
The system shall indicate exact matches and partial matches separately. 
* ''BR29 Sort result set'' 
The system shall sort the result set into ascending alphabetical order using callsign (name). 
* ''BR31 Result list summary'' 
For each player found, the system shall display the player's callsign (name), rank, and the date the callsign was registered. 
* ''BR32 Result detail '' 
The system shall display the following information about the player the actor indicates: the player's callsign (name), rank, the date the callsign was registered, their avatar, and their signature. 

== Flow of events ==
The flow of events describes the main actor actions and system responses in the execution of the use case.

[[Image:Activity_Search_for_Player.png|Activity diagram showing flow of events]]

== Messages ==
<properties>
Step:= EX-1
Condition:= Invalid search criteria or no callsign provided
Message Number:= ERR-1
Message Text:= Please provide a player callsign to search for.
</properties>

[[:Category:Group Manager]]

GMS: Search for Groups

2013-02-10T07:59:42Z

JeffM2501: Move to spec

{{Specification}}

== Introduction ==
This use case describes the process a player will use to search for a group.

[[Image:UC_Search_Groups.png|Use Case diagram]]

The diagram shows the requirements and rules the use case is responsible for (via the <<requirement>> stereotype).

== Pre-conditions ==
None

== Post conditions ==
The system has returned a result set of groups.

== Requirements and rules realized ==
'''RQ5 Players cannot view group name and members of private groups they are not a member of''' 
The system shall prevent players from viewing the group name and members of private groups they are not a member of. 
* ''BR8 Namespaces are publicly visible'' 
* ''BR13 The group name and members of public groups can be viewed by all players'' 

'''RQ9 Search for group''' 
The system shall enable players to search for groups matching a namespace and a group name they provide. 
* ''BR14 Use wildcard for groupname if empty'' 
If no value is provided for the group name then search for any group belonging to the provided namespace. 
* ''BR9 Search for exact match then partial match'' 
The system shall use the criteria supplied by the actor to search for an exact match of namespace and group. If no exact matches are found then the system shall use a partial match method to find names which are similar. 
* ''BR13 Only namespace mandatory'' 
The system shall require a value for the namespace. A value for the group name is optional. 
* ''BR16 Reserved namespaces cannot be searched '' 
The system shall not search for groups within Reserved namespaces. 

'''RQ12 Result set contents''' 
For each group found, the system shall display the name of the group, the group description and the membership policy of the group. 
* ''BR15 Private groups are excluded from results'' 
The system shall exclude private groups from all search results. 
* ''BR10 Indicate partial match separately'' 
The system shall indicate exact matches and partial matches separately. 
* ''BR11 Indicate group membership policy'' 
The system shall indicate which groups have an open membership policy, and which have a by-request membership policy. 
* ''BR6 Closed groups'' 
The system shall prevent any player from joining, or requesting to join, a public group with a closed membership policy. 

'''RQ13 Result set formatting''' 
The system shall format the display of the result set according to the following rules: BR12 
* ''BR12 Sort results in ascending alphabetical order'' 
The system shall sort the result set into ascending alphabetical order using namespace, then group name. 

== Flow of events ==
The flow of events describes the main actor actions and system responses in the execution of the use case.

[[Image:Activity_Search_Groups.png|Activity diagram showing flow of events]]

== Messages ==
<properties>
Step:= EX-1
Condition:= Invalid search criteria
Message Number:= ER-1
Message Text:= Cannot complete the search: the search criteria are invalid, or contain a reserved name.
</properties>

----

<properties>
Step:= AF-1
Condition:= No groups found
Message Number:= MSG-1
Message Text:= No groups matching the criteria you provided were found.
</properties>

[[:Category:Group Manager]]

GMS: Remove co-founder

2013-02-10T07:59:20Z

JeffM2501: Move to spec

{{Specification}}

== Introduction ==
This use case describes the process a founder will use to remove a co-founder from a namespace.

[[Image:UC_Remove_co-founder.png|Use Case diagram]]

The diagram shows the requirements and rules the use case is responsible for (via the <<requirement>> stereotype).

== Pre-conditions ==
None

== Post conditions ==
The system has withdrawn the co-founder role from the player indicated by the actor.

== Extended Use Cases ==
[[View Groups]]

== Requirements and rules realized ==
'''RQ31 Founders manage co-founders''' 
The system shall prevent any player other than the founder of a namespace, from assigning or removing co-founders from that namespace. 

'''RQ26 Notify founder changes''' 
The system shall notify a namespace founder of any changes according to rules: BR36, BR38 
* ''BR38 Changes to namespaces'' 
The system shall notify the namespace founders and co-founders when a co-founder has been assigned or removed from a namespace. 

'''RQ19 Notify players of changes in membership''' 
The system shall notify a player if they have been added to, or removed from any group or granted or forfeited any role. 
* ''BR28 Player notification format'' 
The system shall use a forum private message, email message, and a message displayed on the 'my groups' page to alert players of changes to their membership and roles. 

== Flow of events ==
The flow of events describes the main actor actions and system responses in the execution of the use case.

[[Image:Activity_Remove_co-founder.png|Activity diagram showing flow of events]]

== Messages ==
<properties>
Step:= EX-1
Condition:= Actor is not a founder or co-founder of any namespace
Message Number:= ERR-1
Message Text:= You cannot make changes to a namespace because you are not a founder/co-founder.
</properties>

----

<properties>
Step:= AF-1
Condition:= Selected player is a co-founder of selected namespace
Message Number:= MSG-1
Message Text:= Player <player name> is not a co-founder of the <namespace name> namespace
</properties>

----

<properties>
Step:= BF-12
Condition:= Successfully removed co-founder.
Message Number:= MSG-2
Message Text:= Successfully removed player <player name> as co-founder of <namespace name> namespace.
</properties>

[[:Category:Group Manager]]