API_DOCS: Flag controll functions

[JeffM]

I know I'm horrible about keeping updated docs on API functions, so I figure I'd try to keep them here, so at least we have a somewhat "live" set of docs that people can use. Maybe every so often someone who is better at the English then I can go and update the real docs from this info.

So here we go.

I've added some new API functions for more info and control over the flags in a game to both 2.1 and 2.0.x.

All flags are addressed by a flagID. This id is a number from 0 to the total number of flags in the game.

Code: Select all

BZF_API unsigned int bz_getNumFlags( void );

Returns the total number of flags in the game.

Code: Select all

BZF_API const bz_ApiString bz_getName( int flag );

Returns the flag abbreviation code for the specified flag.

Code: Select all

BZF_API bool bz_resetFlag ( int flag );

Reset ("zaps") the specified flag, if the flag is on a player, the player looses the flag.

Code: Select all

BZF_API int bz_flagPlayer ( int flag );

Returns the player ID of the player who has the specified flag. If the flag is on the uncarried then the ID will be -1;

Code: Select all

BZF_API bool bz_getFlagPosition ( int flag, float* pos );

Copys the the current position of the specified flag into pos ( float pos[3]). If the flag is carried, the last known position of the player is used.

2.0.x.

Code: Select all

BZF_API bool bz_moveFlag( int flag, float pos[3] );

Reset ("zaps") the specified flag, but also sets it's spawn point, if the flag is on a player, the player looses the flag, and the flag is STILL moved to the specified point.

2.1.x.

Code: Select all

BZF_API bool bz_moveFlag( int flag, float pos[3], bool reset = true );

Moves the specified flag. If the flag is carried, it is drooped. If reset is true, the flag is also "zapped" to the new location.

The 2.0.x API version uses bzApiString instead of bz_ApiString.

These changes are in CVS right now. Please let me know if you have any questions or problems.

[meeba]

Thank you for this, Jeff! Most useful indeed.

[LouMan]

Yes, absolutely. Already used them

Thanks so much!

[JeffM]

if you need anymore just let me know

[Theme97]

How about a bz_setFlagPosition()?

[JeffM]

I've been looking into that, it's a little more complex.

[JeffM]

added, BZF_API bool bz_moveFlag ( int flag, float pos[3] ) to the descriptions. It is in both 2.0.x and 2.1 cvs as of now.

*note*
for 2.0.x, moving a flag, forces it to be reset, and it will appear to be "zapped", but it'll spawn where you want it to. In 2.1.x you can just move it.

[Enigma]

Can there be a standard way to deal with flag names? bz_BasePlayerRecord has currentFlag, which is a string that is similar to "Red team flag" or "Low Gravity (+LG)," while bz_getName returns "R*" for the red flag and "LG" for the low gravity flag.