Page 1 of 2

PassTheFlag 1.0.6 released

Posted: Wed Sep 15, 2010 1:52 pm
by FiringSquad
Fixed some bugs and added more flexibility when specifying which flags are passable.

Test Servers: BZWorldCup HIX HIX Funmatch server - Only available to members of the GU Spawnlist

Thanks to Zaphod & Upsetter for hosting these for me.

See ChangeLog below for details:

If there are any more bugs then I will try to get them fixed ASAP. If you happen to find something, then please just add details here or PM me.
I don't anticipate any major further enhancements to this plug-in, but if somebody needs something for a map they are working on, let me know and I'll see what I can do to help.

So far the response has been very good and people seem happy with the extra play value it adds.

I hope you all enjoy it and that mapmakers can make use of it.

I certainly learned a lot about BZFlag while doing this.

I may try to get this running on Vers 3. Hopefully in a way that can be included as part of the main trunk and that will support Windows Servers.
I'll wait until things settle down first though, in case further development or bug-fixing is required.


- F.S.


Code: Select all

PassTheFlag plugin version 1.0.6  (Oct. 14 2010)

* Published under version 3 of the GNU LESSER GENERAL PUBLIC LICENSE
* This package is free software;  you can redistribute it and/or modify it under the terms of the license found in the file named lgpl.txt that should have accompanied this file.
* Also available at at the time this was created

PassTheFlag plugin allows the user to throw the flag they are currently holding.
Created by FiringSquad with thanks to mrapple for help with the API.

This current version will not compile under Windows as I access headers other than the "bzfsAPI.h" which contain items that are not exported from the Windows bzfs.
There may be ways around this, but for the moment servers on the Windows platform will not be supported for this plugin.

Plugin command Line:
  -loadplugin PLUGINNAME[,nopermsneeded][,teamflags|customflags=[V,QT,...]][,passwhiledying|pass2nontkiller|pass2anykiller][,maxwait=<0.0 .. 3.0>][,mwmodify][,dist=<0.0 .. 20.0>][,jboost=<0.0 .. 5.0>][,steps=<0 .. 20>][,debugaccess=<pwd>],

  The options are available to set things other than the default values.
  nopermsneeded - gives everybody permission to adjust config - primarily used for testing - user not notified of setting
  Specifying "teamflags" will pass only team flags, \"customflags\" lets you specicify specific flags default is all flags. You need to enclose the selection in '[' and ']' characters".
  passwhiledying is equivalent to /fpass passondeath=on
  pass2nontkiller is equivalent to /fpass passondeath=hurt
  pass2anykiller is equivalent to /fpass passondeath=hurt and /fpass hurt=killr
  mwmodify will enable "/fpass maxwait" command from modifying the value
  debugaccess must be the last entry. If specified the password can be used to allow any client with Admin privileges to get debug messages and modify the mwmodify value
  (e.g. "...jboost=2.0,debugaccess=1,steps=5,SpyHole" would mean the client would have to enter "/fpass debugaccess=1,steps=5,SpyHole" to get debug access

  The options do not have to be added at loadplugin time, but if they are added then they need to added in the order shown above.

  Example:   -loadplugin PassTheFlag,teamflagsonly,dist=6.0,steps=5                is fine
  but        -loadplugin PassTheFlag,dist=6.0,teamflagsonly,steps=5                will result in an error.

In-game commands:

FPass commands: [help|stat|off|on|immediate|reset|allflags|teamflags|[customflags|toggleflags]={V,QT,...}|dist=< 0.0 .. 20.0>|steps=<0 .. 20>...|fmsg=[off|all|player]|passondeath=[on|off|hurts]|hurt=[killr|nontker]|jboost=< 0.2 .. 5.0>|debugaccess=<pwd>

  /fpass:                      displays command options
  /fpass stat:                 displays the current settings
  /fpass help:                 displays a description of the basic concepts and then displays current settings and command options
  /fpass [on|off|immediate]:   enables/disables flag passing - immediate will forget any fancy stuff and just send the flag flying every time (enabled by default, requires COUNTDOWN permission)
  /fpass reset                 sets everything back to the values set up at loadplugin time (not default values, requires Admin)
  /fpass fmsg=[on|off|player]: turns on/off the "Pass Fumbled" message  (player by default, requires Admin)
  /fpass steps=0 .. 20:        Sets the number of attempts made to find a safe flag-landing.  (5 by default, requires Admin)
  /fpass dist=0.0 .. 20.0:     Sets how far the flag should travel.  (6.0 by default, requires Admin)
  /fpass jboost=0.2 .. 5.0:    Sets how far extra the flag should travel while jumping. Note values below 1.0 reverse the jumping/falling rule  (6.0 by default, requires Admin)
  /fpass [allflags|teamflags]  Specifies that all flags or only team flags may be thrown. (allflags by default, requires Admin)
  /fpass customflags={...}     Allows you to specify a custom set of flags that may be passed (requires Admin)
  /fpass toggleflags={...}     Enables/Disables passing of the flags in the list depending on their current status (requires Admin)
  /fpass passondeath=[on|off|hurts]:  Controls what will happen if the user is killed while holding a flag. Kills by a non-player will result in a normal drop. (off by default, requires Admin)
  /fpass hurt=[killr|nontker]  Sets the definition of "hurts" option. Pass to killer or pass only if not a TK (nontker by default, requires Admin)
  /fpass maxwait=0.0 .. 3.0    Sets the maximum number of seconds I will wait before processing a FlagDropEvent. If I have heard nothing from the client, then I assume that it is a normal pass. Default 0.1 seconds.
  /fpass debugaccess=<pwd>     If password matches the one in loadplugin EXACTLY then debug messages will be sent to the client and the client will have access to maxwait

    Essentially the flag flies in the direction you are traveling and the faster you go the further it flies.
    You can even send it backwards and through walls.
    The distance the flag flies is configurable and is based on the "dist" value.
    Jumping effects the distance too. If you are rising the flag will go "jboost" times as far if you are falling then it will "1/jboost" as far. Of course, jumping is likely to result in you being
    shot as you land.
    I should probably adjust this to take account of how close to the jump zenith the player is when deciding on how to apply the "jumpboost", as this will give greater control by the player rather
    than the simple cut-off point between rising and falling, but that's for another day.
    If the landing position of the flag is unsafe, then it is considered a fumble.
    Depending on the configuration, the plugin may try to find a safe location closer to you.
    It does this by cutting the distance into "steps" intervals and checking them for a safe landing starting from the furthest one.
    If no safe location is found then a standard drop occurs.

    It takes a bit of getting used to, but there is a definite skill in getting the flag to fly to where you want and it was this requirement for a level of skill that I was looking for.
    I had considered options like locking on a player and passing to them, but that could result in instant caps etc. and I don't think that would add anything to gameplay.

    The speed the flag travels at is effected by gravity, BZDB_FLAGALTITUDE & BZDB_SHIELDFLIGHT

    I added the "passondeath" option after I saw some frustration when a player kills the flag-carrier but the flag flies away anyway.
    Also some strangeness occurred when a player died because of a Cap or was kicked.
    Now passing will never occur unless the death is at the hands of another player.
    passondeath=off will just result in the flag always just being dropped.
    passondeath=on will send the flag on its way depending on the movement of the player when killed.
    passondeath=hurts will just result in the flag being dropped or passed towards the killer, depending on how "hurt" is configured.
    It is intended that other forms of pain could be added later. e.g. flies away from teambase or longer pause to spawn. Though I will wait to hear from map-makers before adding such options.

    This passondeath was quite complex to add. The problem is that the client sends the "Drop Flag" message before it send the "I Died" message.
    This meant that I had to delay processing the "Drop Flag" event to allow the client to send me further information.
    If I hear nothing in "maxwait" seconds from this client, then I will assume a pass was wanted. I make this assumption as normally long waits only occur when there is no info to send.
    Being dead is info. :-)
    If allowed on the loadplugin command, this maxwait can be adjusted from the client using the "/fpass maxwait" command.
    This will allow server owners to tweak the value until they are happy that it works well and then they can set the value in stone at loadplugin time.

    There was a problem where I get a bz_ePlayerUpdateEvent generated by another plugin in response to the flag-drop event. I assumed, wrongly, that the event came from the client and so the server
    would have enough info to make an informed choice. I now ignore any bz_ePlayerUpdateEvent generate less than 1/25 of a second after the flag drop event.

        The command-line parser of bzfs had problems dealing with plugin parameters in braces so I had to use the square brackets. Unfortunately this causes confusion for the BNF notation in the help,
        but it couldn't be helped and other suitable characters would cause similar difficulties. I left the braces for the in-games commands since those users might not be as technically minded.
        While this might cause some confusion, having different formats for command-line and in-game, I think it's an acceptable compromise.

Code: Select all

1.00.0  (2010-09-15)
  *) Initial Version

1.00.1  (2010-09-15)
  *) Added <assert.h> and included support for passing TeamFlags only

1.00.2  (2010-09-16)
  *) Added support for passondeath and hurt
  *) Added fmsg=player support and made it default
  *) Added a help option
  *) Added LGPL licensing info
  *) Cleaned up code and used snprintf to prevent possible buffer overflows
  *) Added comments
  *) added code to postpone handling the flagdrop event until we have better data
  *) added maxwait support to allow tweaking of delay

1.00.3  (2010-09-22)
  *) Fixed a bug with the "passondeath=hurts" option
  *) added "nopermsneeded" as a loadplugin option  (primarily used for testing)
  *) renamed "passondeath" loadplugin option to "passwhiledying" to avoid confusion with "/fpass passondeath="
  *) fixed a bug where "/fpass stat" always displayed incorrect information for "[on|off|immediate] settings

1.00.4  (2010-09-24)
  *) Removed an infinite loop

1.00.5  (2010-10-06)
  *) Added support for "customflags" and "toggleflags"
  *) Fixed a bug that prevented burrowed tanks from passing their flag
  *) Fixed a bug where DirectMessageBuffer was being damaged by sending a FlagUpdate message. Now using local buffer instead.
  *) Set default maxwait to 0.1f

1.00.6  (2010-10-14)
  *) Fixed a bug in the loadplugin customflags command

Re: PassTheFlag

Posted: Wed Sep 15, 2010 3:39 pm
by FiringSquad
I should probably prevent passing by a burrowed tank or fix the validation to allow them to pass above their current level, but that can wait for a later version.

Re: PassTheFlag

Posted: Wed Sep 15, 2010 4:06 pm
by Runic
I haven't tried the plug-in. It seems like an interesting idea though.


- thrown flags should NOT be able to be thrown through walls. Instead it should hit the wall, bounce back off of the wall and fall to the ground.

- if the tank is turning (while inAir or onGround) at the time the flag is thrown a slightly curved flight path would be in order. (curve should be in the opposite direction of the tanks turning)

Re: Flag passing through walls

Posted: Wed Sep 15, 2010 4:33 pm
by FiringSquad
It would be nice to bounce flags off walls and I admit that passing through a solid wall looks weird, but I was going with the "Documented bug = feature" approach. ;-)
Passing through Teleporters should probably be supported too, but these features would require considerable effort to implement and I'm not even sure it's possible from within a plugin.
This plugin will probably be implemented in a completely different way in version 3, so I suspect that I will not have the time to add these features for version 2.

If anybody else would like to try, then they are, of course, welcome to modify my code.

Re: PassTheFlag

Posted: Wed Sep 15, 2010 5:21 pm
by Bullet Catcher
Runic wrote:if the tank is turning (while inAir or onGround) at the time the flag is thrown a slightly curved flight path would be in order. (curve should be in the opposite direction of the tanks turning)
That isn't how thrown objects move in the real world. BZFlag already has its own set of unrealistic physics, of course, but I see no point in deliberately adding to the mess.

Re: PassTheFlag

Posted: Wed Sep 15, 2010 5:49 pm
by FiringSquad
Version 1.0.0 is currently installed on
You can get a feel for how the plug-in works there but to get the full effect you would need jumping too.

Thx Zaphod.

Re: PassTheFlag

Posted: Wed Sep 15, 2010 7:27 pm
by blast
Please also specify what license the plugin is released under. Since it is based off another plugin (correct?) I believe the code should be licensed the same unless you have some other agreement with the copyright holder.

Re: PassTheFlag

Posted: Wed Sep 15, 2010 10:31 pm
by FiringSquad
I basically looked at the plugins that came with the BZFlag source and used the original HTF plugin as a template for creating this one (although since they are all very similar, I could have used any of them). I believe there is even an automatic plugin generator, that creates the basic framework where you then need to just fill in the functionality.

I personally do not wish to have any claim whatsoever on any of the code, so whatever license benefits the BZ community most is fine with me.
I would be grateful if you could inform me which license might be most appropriate and how I should include it in the code to be compatible with existing licenses used here.
Coming from a commercial programming environment, the myriad of open source licenses are a little beyond me. :-)


Posted: Thu Sep 16, 2010 12:04 am
by FiringSquad
I intend to add an option passondeath=[on|off|base] which will control what happens when a flag-holder is shot.
on: will pass as if the player just dropped the flag
off: will just drop the flag without passing
base: will pass the flag in the direction away from holders base. Rogues will just drop the flag in this case.

I should probably add a help option that explains the basics of passing.
I should probably also add some sort of radius value for flags to help prevent them being placed somewhere this is impossible to reach, especially for random maps. But I would need to do a little research for that. Any advice is welcome.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 12:39 am
by mrapple
As for the license thing, public domain seems to suit your needs best.

I agree with the pass on death option, however i think on and off should be sufficient and base wouldn't be needed.

Help would be nice. Maybe when you type /fpass you get a help message, not stats? In the help message could be something about /fpass stats to get information about current settings.

About the radius thing, chances of this are little to none, but, I can understand how it might happen. Not necessary, but would be a cool add-on.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 1:13 am
by blast
LGPL is probably most appropriate if it was based on the HoldTheFlag plugin that is in the BZFlag source. And you automatically have "claim" to the code you wrote, at least in some countries such as the US. Copyright is automatic in the United States.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 7:36 am
by zaphod
I simply just love it F.S.!
this is for me a long awaited extension to this game that opens a whole new range of possibilities for a complete new game-play-style
and new concepts for map-making! (yes ::: team-work goes for sniping&camping!)
plus adding a certain level of skill to pass the flag to a mate gives it another extra and all the settings can be done easily in-game.
without any server hacks or modification needed ::: all these makes it an excellent work!
thank you so much for all the sweat and time you put into this!!!

try it on a football-field and practice the "barcelona-style" on


Re: PassTheFlag

Posted: Thu Sep 16, 2010 7:45 am
by blast
Also, this plugin will not work on Windows if anyone wonders.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 6:52 pm
by FiringSquad
blast wrote:Also, this plugin will not work on Windows if anyone wonders.
That's interesting.
Will it compile?
What happens?
I don't have the Development Environment set up on windows atm. so it might take me a while to sort that out.
To get a solution more quickly I might need somebody to accept a special version from me with lots of debug messages in it.
The only possible problem I see in the code is my use of std::vector
I'm not sure how this is implemented in VisualC, although it should be standard.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 11:51 pm
by mrapple
It wont compile due to the fact we're using stuff outside the standard API.

Re: PassTheFlag

Posted: Thu Sep 16, 2010 11:51 pm
by blast
Well, on Windows, you can't access functions that haven't been exported. So only the API functions could be accessed from a plugin, and raw access to bzfs data and functions would be prevented. Our Linux (and other) build system may be set up that way in the future.

Re: PassTheFlag

Posted: Fri Sep 17, 2010 1:26 am
by FiringSquad
OK I'll include info about that in the sources.
As for the build settings, I'm hoping this plugin will become obsolete in version 3 as it can be achieved in another way there IIRC.
I intend to make some enhancements and clean up the code adding license details etc. over the week-end. I'll add this information too.

I'd forgotten about the lack of support for weak-linking in Visual-C++.
I can understand why it would be prudent to restrict the plug-ins to the explicitly exposed interface.
I'm pretty sure there's a way around this though by resolving the procpointers during bz_Load().
Anyway, I'm not going to worry about that for the time being.
I guess that means this plug-in will never be part of the standard trunk then. :wink: :roll:

Re: PassTheFlag

Posted: Fri Sep 17, 2010 2:18 am
by mrapple
FiringSquad wrote:As for the build settings, I'm hoping this plugin will become obsolete in version 3 as it can be achieved in another way there IIRC.
How so? I didn't hear of any new flag flying code :shock:

Re: PassTheFlag

Posted: Fri Sep 17, 2010 2:46 am
by FiringSquad
You'd better hurry up and write it then, before it's too late. :-)

Re: PassTheFlag

Posted: Fri Sep 17, 2010 10:17 am
by blast
FiringSquad wrote:I guess that means this plug-in will never be part of the standard trunk then. :wink: :roll:
Not in the current state, no. If you extended the bzfs API to handle everything you needed, then sure.

Re: PassTheFlag

Posted: Fri Sep 17, 2010 2:05 pm
by FiringSquad
That sounds very reasonable.
I'll wait until the development of this plugin settles down and then try do achieve the same effect with as little modification to the bzfsAPI as possible, while still providing routines that could be useful to other developers rather than specific to this plugin.
It will probably be about a month before I get around to it, but given that my first version did actually modify this API, it shouldn't take me too long to achieve once I start.
Hopefully it will be accepted.

Re: PassTheFlag

Posted: Fri Sep 17, 2010 2:10 pm
by blast
And if you do tweak the API, do it for trunk, not 2.0.x.

Re: PassTheFlag

Posted: Sat Sep 18, 2010 8:39 am
by FiringSquad
I'm about to release version 1.0.2
But before I do, I'd like to get some feedback from developers who understand the API far better than me, namely most of you :-).
If you are interested, I posted some information about my concerns in Plug-in Development, here

Re: PassTheFlag 1.0.2 released

Posted: Mon Sep 20, 2010 11:35 pm
by FiringSquad
Details for 1.0.2, including downloads, added to initial post above.

Re: PassTheFlag 1.0.2 released

Posted: Wed Sep 22, 2010 2:27 pm
by FiringSquad
Getting details of "passondeath=hurts" not working correctly.

I hope to test this later today and see what the problem is.