事件: step
功能说明： 用于执行智能体的移动
引用函数：
    size()  - BIF
    get()   - BIF
    step()
--------------------------------------
for (int i = 0; i < combatSatSwarms.size(); i++) {  // 遍历所有combatSatSwarms个体
  combatSatSwarms.get(i).step();  // 每个个体都执行一遍step()函数，让它们动起来
}

事件: collectData
功能说明： 用于收集红方和蓝方兵力数量变化数据
引用函数：
    size()  - BIF
    get()   - BIF
    add()   - BIF
--------------------------------------
for (int i = 0; i < combatSatSwarms.size(); i++) {  // 遍历所有combatSatSwarms个体
  if(combatSatSwarms.get(i).color==rectRed.getFillColor()){ // 判断这个个体的颜色是否为红色
    if(combatSatSwarms.get(i).type==RD){  // 判断这个个体的类型是否为RD
      forceRDVar += 1;  // 如果是RD，则本循环中 forceRDVar 加1 
      }
  	else if(combatSatSwarms.get(i).type==RK){ // 判断这个个体的类型是否为RK
      forceRKVar += 1;  // 如果是RK，则本循环中 forceRKVar 加1 
    }
    
  }
  else if(combatSatSwarms.get(i).color==rectBlue.getFillColor()){// 判断这个个体的颜色是否为蓝色
    if(combatSatSwarms.get(i).type==BD){  // 判断这个个体的类型是否为BD
      forceBDVar += 1;  // 如果是BD，则本循环中 forceBDVar 加1
    }
  	else if(combatSatSwarms.get(i).type==BK){ // 判断这个个体的类型是否为BK
      forceBKVar += 1;  // 如果是BK，则本循环中 forceBKVar 加1
    }    
  }
}
forceRed.add(forceRDVar,forceRKVar);  // 向数据集 forceRed 添加参数
forceBlue.add(forceBDVar,forceBKVar); // 向数据集 forceBlue 添加参数
// 把变量清零，为下次事件触发时记录数据做准备
forceRDVar = 0;
forceRKVar = 0;
forceBDVar = 0;
forceBKVar = 0;

Function: injectTeam()
Input: 
    1. color [Color]
    2. type [TypeOption]
    3. minX [double]
    4. w [double]
    5. minY [double]
    6. h [double]
    7. meanHeadig [double]
    8. teamSize [double]
    9. hitPoint [double]
    10. deathRange [double]
Constant:
    1. teamSize [int]
Output: void
-----------------------------------------------------------

for (int i = 0; i < teamSize; i++) {  // 遍历所有combatSatSwarms个体
    CombatSatSwarm css = add_combatSatSwarms(); // 设置类 CombatSatSwarm 的实例 css
  
	//setup team color
	css.set_color(color); // 设置颜色
	
	//setup team type
	css.set_type(type); // 设置类型
	css.set_hitPoint(hitPoint); // 设置HP
	css.set_deathRange(deathRange); // 设置杀伤距离
  
	//setup initial position, speed, heading
	css.set_initX(uniform(minX, minX + w)); // 设置初始 X 轴位置
	css.set_initY(uniform(minY, minY + h)); // 设置初始 Y 轴位置
	css.set_initHeading(meanHeading); // 设置初始方向角
}

// 调用 injectTeam() 函数来生成 红蓝双方对抗兵力，输入参数的顺序严格按照 
// injectTeam() 给定的输入参数顺序写
injectTeam(rectRed.getFillColor(),  RD, width/2-width/8, width/8,  0, 
          height/4,   0,       swarmSizeRD,hitPointRD,deathRangeD);
//injectTeam(rectRed.getFillColor(),  RK, width/2-width/8, width/8,  0,
//           height*3/4, 0,       swarmSizeRK,hitPointRK,deathRangeK);
injectTeam(rectBlue.getFillColor(), BD, width/2+width/8, width/8,  0,
          height/4,   Math.PI, swarmSizeBD,hitPointBD,deathRangeD);
//injectTeam(rectBlue.getFillColor(), BK, width/2+width/8, width/8,  0,
//        height*3/4, Math.PI, swarmSizeBK,hitPointBK,deathRangeK);

// 把数据写入至 excel文件 data 中。
// 注意 data 为命名好的excel文件，根据自己命名的不同，也可以写成其他名字
data.writeDataSet(forceRed,1,2,1);
data.writeDataSet(forceBlue,1,2,3);

Function: attack()-选择是否加速或者减速
Input: null
Constant:
    1. attacking [boolean]
    2. speed [double]
    3. enemiesX [double]
    4. enemiesY [double]
    5. enemiesSpeed [double]
Output: void
Function call:
    1. speedUp()
    2. slowDown()
-----------------------------------------------------------
attacking = true; // animation only
turnToward(enemiesX, enemiesY); // 修改航向，使自己能够朝向敌人
if (enemiesSpeed > speed) { // 如果敌人比自己速度快，加速
  speedUp();
}
else if (enemiesSpeed < speed) { // 如果敌人比自己速度慢，减速
  slowDown();
}

Function: avoidCollision()-避免碰撞友军
Input: null
Constant:
    1. x [boolean]
    2. y [double]
    3. heading [double]
    4. nearestFriend [Boid]
Output: void
Function call:
    1. speedUp()
    2. slowDown()
    3. turnAway()
    4. cos()-BIF
    5. sin()-BIF
-----------------------------------------------------------
// 如果周围没有敌人，而且附近友军过于距离过于接近
CombatSatSwarm b = nearestFriend;

if (b == null)
  return;
turnAway(b.x, b.y);   // 计算该智能体 heading
double dx = b.x - x;  // 计算该智能体离初始位置 X 轴距离之差
double dy = b.y - y;  // 计算该智能体离初始位置 Y 轴距离之差
if (cos(heading) * cos(b.heading) + sin(heading) * sin(b.heading) > 0) { // 相同方向
  if (dx * cos(heading) + dy * sin(heading) < 0) { // 该智能体在其他智能体后面
    slowDown(); // 减速
  } else { // 该智能体在其他智能体前面
    speedUp();  // 加速
  }
} else {  // 往相反方向走
  if (dx * cos(heading) + dy * sin(heading) < 0) { // 用朝向角来控制避碰方向
    slowDown(); // 减速
  }
}

Function: avoidWalls()-避免碰撞墙面
Input: null
Constant:
    1. x [boolean]
    2. y [double]
    3. heading [double]
    4. width [double]
    5. height [double]
    6. sensorRange [double]
Output: void
Function call:
    1. speedUp()
    2. slowDown()
    3. cos()-BIF
    4. sin()-BIF
-----------------------------------------------------------
// 避免碰撞墙面
double dxr = width - x; // 离墙面 X 轴距离
double dyd = height - y; // 离墙面 Y 轴距离

if (cos(heading) > 0) { // 往右走
  if (sin(heading) < 0) { // 往右-上走
    if (dxr < sensorRange) { // 探测距离小于距离右边的墙面 X 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / dxr); i++) turnLeft(); // 左转
    } else if (y < sensorRange) { // 探测距离小于距离上边的墙面 Y 轴距离 
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / y); i++) turnRight();  // 右转
    } 
  } else { // 往右-下走
    if (dxr < sensorRange) { // 探测距离小于距离右边的墙面 X 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / dxr); i++) turnRight();  // 右转
    } else if (dyd < sensorRange) { // 探测距离小于距离下边的墙面 Y 轴距离 
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / dyd); i++) turnLeft(); // 左转
    }
  }
} else { // 往左走
  if (sin(heading) < 0) { // 往左-上走
    if (x < sensorRange) { // 探测距离小于距离左边的墙面 X 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / x); i++) turnRight(); // 右转
    } else if (y < sensorRange) { // 探测距离小于距离下边的墙面 Y 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / y); i++) turnLeft(); // 左转
    } 
  } else { // 往左-下走
    if (x < sensorRange) { // 探测距离小于距离左边的墙面 X 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / x); i++) turnLeft(); // 左转
    } else if (dyd < sensorRange) { // 探测距离小于距离下边的墙面 Y 轴距离
      slowDown(); // 减速
      for (int i = 0; i < 1 + (int) (sensorRange / dyd); i++) turnRight(); // 右转
    } 
  }
}

Function: decide()
Input: null
Constant:
    1. speed [boolean]
    2. friendsNumber [double]
    3. nearestFriend [Boid]
    4. enemiesNumber [double]
    5. nearestEnemies [Boid]
    6. dead [boolean]
    7. attacking [boolean]
Output: void
Function call:
    1. isDead()
    2. restart()-BIF
    3. attack()
    4. retreat()
    5. avoidCollision()
    6. hangOutWithFriends()
    7. avoidwalls()
-----------------------------------------------------------
attacking = false; // 先不攻击
if (isDead()) { // 死了没，死了就置0
  speed = 0;
  dead = true;
  death.restart(20);  // 20ms(?)后重置death事件
} else { // 要是没死
  if (enemiesNumber > 0) { // 如果附近有敌人，这个参数在senseFlock()里面给出
    double friendsToEnemies = (friendsNumber + 1) / (double)enemiesNumber; // 友军/敌人之比
    if (friendsToEnemies > attackConstant) { // 友军多于敌人
      attack(); // 攻击
    } else if (friendsToEnemies < retreatConstant) { // 友军少于敌人
      retreat(); // 撤退
    }
  } else if (nearestFriend != null) { // 没有敌人，友军距离过近
    avoidCollision(); // 避碰
  } else { // 没有敌人，周围没有友军
    hangOutWithFriends();
  }
  // 避免碰撞墙面
  avoidWalls();
}

Function: hangOutWithFriends()-周围没有敌人也没有友军的随机游走
Input: null
Constant:
    1. speed [boolean]
    2. friendsNumber [double]
    3. friendsX [double]
    4. friendsY [double]
Output: void
Function call:
    1. speedUp()
    2. slowDown()
    3. turnLeft()
    4. turnRight()
-----------------------------------------------------------
if (friendsNumber > 0) { // 如果周围有友军
  turnToward(friendsX, friendsY);  // 判断向左还是向右移动
  if (friendsSpeed > speed) { // 友军速度大于己方速度
    speedUp();  // 加速
  } else if (friendsSpeed < speed) {  // 友军速度小于己方速度
    slowDown(); // 减速
  }
} else { // 如果周围没有友军
  slowDown(); // 减速
  if (uniform() < 0.5) // 50%的概率向左，50%的概率向右
    turnLeft();
  else
    turnRight();
}

Function: isDead()-判断是否死亡
Input: null
Constant:
    1. deathRangeNumber [boolean]
Output: true or false
Function call: null
-----------------------------------------------------------
// 如果HP归零，则代表死亡
if (hitPoint == 0){
    return true;
}else{
    return false;
}

Function: isFriend()-判断是否为友军
Input: 
    1. b [Boid]
Constant: null
Output: color.equals(b.color)
Function call: 
    1. color.equal()
-----------------------------------------------------------
// 比对颜色是否一致，颜色一致即为友军
return color.equals(b.color);

Function: isInRange()-判断是否在范围内
Input: 
    1. b [Boid]
    2. range [double]
Constant: 
    1. x [double]
    2. y [double]
Output: dx * dx + dy * dy < range * range
Function call: null
-----------------------------------------------------------
double dx = b.x - x;
double dy = b.y - y;
// 在范围内，则返回1；不在范围内，则返回0
return dx * dx + dy * dy < range * range;

Function: move()-移动
Input: null
Constant: 
    1. heading [double]
    2. speed [double]
    3. x [double]
    4. y [double]
    5. traceX [double[]]
    6. traceY [double[]]
    7. dt [double]
    8. width [double]
    9. height [double]
Output: null
Function call: 
    1. length()-BIF
-----------------------------------------------------------
// 根据计算出来的 heading 更新坐标位置
x += speed * dt * cos(heading);
y += speed * dt * sin(heading); 
// 避免触碰边界
if (x > width)
  x -= width;
else if (x < 0)
  x += width;
if (y > height)
  y -= height;
else if (y < 0)
  y += height;
// 用来显示当前的轨迹（动画效果）
for (int i = traceX.length - 1; i > 0; i--) {
  traceX[i] = traceX[i-1];
  traceY[i] = traceY[i-1];
}
traceX[0] = x;
traceY[0] = y;

Function: retreat()-撤退
Input: null
Constant: 
    1. enemiesX [double]
    2. enemiesY [double]
Output: null
Function call: 
    1. turnAway()
    2. speedUp()
-----------------------------------------------------------
// 远离敌人，并加速
turnAway(enemiesX, enemiesY);
speedUp();

Function: senseFlock()-探测友军或者敌军
Input: null
Constant: 
    1. flock [Flock]
    2. heading [double]
    3. speed [double]
    4. x [double]
    5. y [double]
    6. friendsNumber [double]
    7. friendsX [double]
    8. friendsY [double]
    9. nearestFriend [Boid]
    10. enemiesNumber [double]
    11. enemiesX [double]
    12. enemiesY [double]
    13. nearestEnemy [Boid]
    14. friendsHeading [double]
    15. friendsSpeed [double]
    16. deathRangeNumber [double]
    17. enemiesHeading [double]
    18. enemiesSpeed [double]
    19. sensorRange [double]
    20. collisionRange [double]
    21. deathRange [double]
Output: null
Function call: 
    1. isFriend()
    2. isInRange()
    3. Math.sqrt-BIK
    4. size()-BIF
    5. get()-BIF
-----------------------------------------------------------
friendsNumber = 0;                  // 假设友方数量为0
double totalFriendsX       = 0.0;
double totalFriendsY       = 0.0;
double totalFriendsSpeed   = 0.0;
double totalFriendsHeading = 0.0;

enemiesNumber = 0;                  // 假设敌方数量为0
double totalEnemiesX       = 0.0;
double totalEnemiesY       = 0.0;
double totalEnemiesSpeed   = 0.0;
double totalEnemiesHeading = 0.0;

nearestFriend = null;               // 假设周围没有友军
nearestEnemy  = null;               // 假设周围没有敌人
deathRangeNumber = 0;               // 死亡数

double distanceToFriend = collisionRange; // 与友军的距离是避碰距离

for (int i = 0; i < flock.boids.size(); i++) {
  CombatSatSwarm b = flock.boids.get(i); // Main中的第i个combatSatSwarm

  if (b.dead || b == this) // 如果是友军或者自己
    continue;
  if (isFriend(b)) { // 如果是友军
    // 判断它是否为距离最近的友军
    if (isInRange(b, distanceToFriend)) { 
      nearestFriend = b;
      distanceToFriend = Math.sqrt((b.x - x) * (b.x - x) + (b.y - y) * (b.y - y));
    } 
    if (isInRange(b, sensorRange)) { // 这个被认作友军的智能体在探测范围内，则友军数加1
      friendsNumber++;
      totalFriendsX += b.x;
      totalFriendsY += b.y;
      totalFriendsSpeed   += b.speed;
      totalFriendsHeading += b.heading;
    }
  } else {
    if (isInRange(b, deathRange)) { // 这一段意思就是假如一个智能体接近另一个智能体，则HP-1
      deathRangeNumber++;
      b.hitPoint -= 1;              // HP-1
      if (b.hitPoint < 0){          // HP=0，则认为死亡
      	b.hitPoint = 0;
      }
    }
    if (isInRange(b, sensorRange)) { // 这个被认作敌军的智能体在探测范围内，则敌军数加1
      enemiesNumber++;
      totalEnemiesX += b.x;
      totalEnemiesY += b.y;
      totalEnemiesSpeed   += b.speed;
      totalEnemiesHeading += b.heading;
    }
  }
}

if (friendsNumber == 0) { // 如果周围没有友军，把参数用自己的参数替代了
  friendsHeading = heading;
  friendsSpeed   = speed;
  friendsX = x;
  friendsY = y;
} else { // 否则不能
  friendsHeading = totalFriendsHeading / friendsNumber;
  friendsSpeed   = totalFriendsSpeed / friendsNumber;
  friendsX = totalFriendsX / friendsNumber;
  friendsY = totalFriendsY / friendsNumber;
}

if (enemiesNumber == 0) { // 如果周围没有敌军，把参数用自己的参数替代了
  enemiesHeading = heading;
  enemiesSpeed   = speed;
  enemiesX = x;
  enemiesY = y;
} else { // 否则不能
  enemiesHeading = totalEnemiesHeading / enemiesNumber;
  enemiesSpeed   = totalEnemiesSpeed / enemiesNumber;
  enemiesX = totalEnemiesX / enemiesNumber;
  enemiesY = totalEnemiesY / enemiesNumber;
}

Function: slowDown()-减速
Input: null
Constant: 
    1. minimumSpeed
    2. speed
    3. acceleration
    4. dt
Output: null
Function call: 
    1. limitMin()-BIF
-----------------------------------------------------------
speed = limitMin(minimumSpeed, speed - acceleration * dt);

Function: speedUp()-加速
Input: null
Constant: 
    1. minimumSpeed
    2. speed
    3. acceleration
    4. dt
Output: null
Function call: 
    1. limitMax()-BIF
-----------------------------------------------------------
speed = limitMax(speed + acceleration * dt, maximumSpeed);

Function: step()
Input: null
Constant: 
    1. dead
Output: null
Function call: 
    1. senseFlock()
    2. decide()
    3. move()
-----------------------------------------------------------
if (! dead) { 
  /* 
  这是整个函数的关键部分，分为三步，
  1. 探测友军和敌军
  2. 决策下一步的动作
  3. 移动 
  */
  senseFlock();
  decide();
  move();
}

Function: turnAway()-远离其他智能体
Input: 
    1. xPos [double]
    2. yPos [double]
Constant: 
    1. x [double]
    2. y [double]
    3. heading [double]
Output: null
Function call: 
    1. turnLeft()
    2. turnRight()
    3. sin()-BIF
    4. cos()-BIF
-----------------------------------------------------------
double dx = xPos - x;
double dy = yPos - y;

if (cos(heading) * dy - sin(heading) * dx > 0)
  turnLeft();
else
  turnRight();

Function: turnLeft()-左转
Input: null
Constant: 
    1. heading [double]
    2. dt [double]
    3. turnAngle  [double]
Output: null
Function call:
    1. Math.PI-BIK
-----------------------------------------------------------
heading = (heading - turnAngle * dt) % (2 * Math.PI);

Function: turnRight()-右转
Input: null
Constant: 
    1. heading [double]
    2. dt [double]
    3. turnAngle  [double]
Output: null
Function call:
    1. Math.PI-BIK
-----------------------------------------------------------
heading = (heading + turnAngle * dt) % (2 * Math.PI);

Function: turnToward()-计算 heading
Input:  
    1. xPos [double]
    2. yPos [double]
Constant: 
    1. x [double]
    2. y [double]
    3. heading [double]
Output: null
Function call:
    1. turnLeft()
    2. turnRight()
    3. sin()-BIF
    4. cos()-BIF
-----------------------------------------------------------
double dx = xPos - x;
double dy = yPos - y;

if (cos(heading) * dy - sin(heading) * dx < 0)
  turnLeft();
else
  turnRight();