Question(s) regarding: bz_triggerFlagCapture()

It's mainly if the documentation should be updated, similar to bz_eAllowCTFCaptureEvent, which notes that killTeam will be made to work in 2.6.x. of BZFlag.

Otherwise it creates the assumption that said function may be used as easily as in the bz_eFlagGrabbedEvent, shown as the following:

    int playerHoldingFlag = grabData->playerID;
    bz_eTeamType flagTeam = flagToTeamValue(grabData->flagType);

    // Proceeding, if we have a team flag.
    if (flagTeam != eNoTeam) {
        bz_eTeamType playerTeam = bz_getPlayerTeam(grabData->playerID);
        // If we have an actual team, we may be ready to score.
        if ((playerTeam == eRedTeam) || (playerTeam == eGreenTeam) || (playerTeam == eBlueTeam) || (playerTeam == ePurpleTeam)) {
            // Checking if teams are not the same, if they are not, we trigger a score change at this point, as well as anything else specified.
            if (flagTeam != playerTeam) {
                // View custom functions for details of code.
                bz_triggerFlagCapture(playerHoldingFlag, playerTeam, flagTeam);
                resetPlayer(playerHoldingFlag);
                //bz_incrementPlayerWins(playerHoldingFlag, bz_getTeamCount(flagTeam));
            }
        }
    }

While in reality, it's more likely to wind up as the following when attempting to use other events:

  switch (eventData->eventType) {
    case bz_eAllowCTFCaptureEvent: {
      bz_AllowCTFCaptureEventData_V1* allowCapData = (bz_AllowCTFCaptureEventData_V1*)eventData;
      if (bz_getPlayerTeam(allowCapData->playerCapping) == allowCapData->teamCapped) {
        allowCapData->allow = false;
        basePoint = bz_checkBaseAtPoint(allowCapData->pos);
        if (basePoint != eNoTeam) {
            bz_resetFlag(bz_getPlayerFlagID(allowCapData->playerCapping));
            cappingPlayer = allowCapData->playerCapping;
            cappingTeam = bz_getPlayerTeam(allowCapData->playerCapping);
            alive = 1;
            //
            bz_givePlayerFlag(cappingPlayer, teamToFlagType(basePoint), true);
        }
      }
    }break;

    case bz_eCaptureEvent: {
      bz_CTFCaptureEventData_V1* capData = (bz_CTFCaptureEventData_V1*)eventData;
      if (capData->playerCapping == cappingPlayer) {
        if (capData->teamCapping == cappingTeam) {
            //bz_killPlayer(capData->playerCapping, true, BZ_SERVER);
            cappingPlayer = -1;
            alive = -1;
            cappingTeam = eNoTeam;
            basePoint = eNoTeam;
        }
      }
    }break;

    case bz_eTickEvent: {
      if ((cappingPlayer != -1) && (alive == 1)) {
        int flagID = bz_getPlayerFlagID(cappingPlayer);
        if (flagID != -1) {
            bz_eTeamType flagTeam = flagToTeamValue(bz_getFlagName(flagID).c_str());
            if (flagTeam != basePoint) {
                bz_resetFlag(flagID);
                bz_givePlayerFlag(cappingPlayer, teamToFlagType(basePoint), true);
            }
        } else {
            bz_givePlayerFlag(cappingPlayer, teamToFlagType(basePoint), true);
        }
        bz_triggerFlagCapture(cappingPlayer, cappingTeam, basePoint);
      }
    }break;

    case bz_ePlayerPartEvent: {
      bz_PlayerJoinPartEventData_V1* partData = (bz_PlayerJoinPartEventData_V1*)eventData;
      int player = partData->playerID;
      if (player == cappingPlayer) {
        alive = -1;
        cappingPlayer = -1;
        cappingTeam = eNoTeam;
        basePoint = eNoTeam;
      }
    }break;

      case bz_ePlayerDieEvent: {
      bz_PlayerDieEventData_V2* deathData = (bz_PlayerDieEventData_V2*)eventData;
      if ((deathData->playerID == cappingPlayer) && (cappingPlayer != -1)) {
        alive = -1;
      }
    }break;

    case bz_ePlayerSpawnEvent: {
      bz_PlayerSpawnEventData_V1* spawnData = (bz_PlayerSpawnEventData_V1*)eventData;
      if ((spawnData->playerID == cappingPlayer) && (cappingPlayer != -1)) {
        alive = 1;
        bz_givePlayerFlag(cappingPlayer, teamToFlagType(basePoint), true);
      } 
    }break;

    default:{ 
    }break;
  }

There is no info which specifies that the player must hold the team flag from the capped team for the function to work. (Which would make it confusing for anyone who may try to use it.)

Personally I'd appreciate it, if it were possible to trigger flag captures regardless of player alive/dead status, same as flag held or flagless status. (If it is not planned for the future.)

BZFlag-Dev / bzflag

Question(s) regarding: bz_triggerFlagCapture() #319