/// <summary>
/// <para>
/// Method used to command your creature to start eating another creature.
/// You can only eat one target creature per round, and a single call to
/// BeginEating will only attack a target creature in the upcoming tick.
/// Calling BeginEating multiple times in the same turn will only result
/// in your creature eating the target specified in the last call to
/// BeginEating.
/// </para>
/// <para>
/// Eating is asynchronous so you'll need to handle the EatCompleted event
/// in order to get the status of the bite. A single bite might not
/// produce enough energy for your creature so you'll have to make multiple
/// bites against the same target until it is completed eaten.
/// </para>
/// </summary>
/// <param name="targetOrganism">
/// OrganismState of the creature you wish to eat.
/// </param>
/// <exception cref="System.ArgumentNullException">
/// Thrown if the targetOrganism parameter is null.
/// </exception>
/// <exception cref="AlreadyFullException">
/// Thrown if your creature is not hungry enough to eat.
/// </exception>
/// <exception cref="NotVisibleException">
/// Thrown if the creature had disappeared from your creature's view.
/// </exception>
/// <exception cref="NotWithinDistanceException">
/// Thrown if your creature is not within eating distance.
/// </exception>
/// <exception cref="ImproperFoodException">
/// Thrown if a Carnivore tries to eat a plant or a Herbivore tries to eat an Animal
/// </exception>
/// <exception cref="NotDeadException">
/// Thrown if a Carnivore tries to eat a creature that isn't dead yet.
/// </exception>
public void BeginEating(OrganismState targetOrganism)
{
if (targetOrganism == null)
{
throw new ArgumentNullException("targetOrganism", "The argument 'targetOrganism' cannot be null");
}
if (State.EnergyState > EnergyState.Normal)
{
throw new AlreadyFullException();
}
// Get an up to date state -- this organism may be an old state
var currentOrganism = World.LookForNoCamouflage(targetOrganism);
if (currentOrganism == null)
{
throw new NotVisibleException();
}
if (!WithinEatingRange(currentOrganism))
{
throw new NotWithinDistanceException();
}
// Make sure it is edible
if (State.AnimalSpecies.IsCarnivore)
{
if (currentOrganism is PlantState)
{
throw new ImproperFoodException();
}
if (currentOrganism.IsAlive)
{
throw new NotDeadException();
}
}
else
{
if (currentOrganism is AnimalState)
{
throw new ImproperFoodException();
}
}
var actionID = GetNextActionID();
var action = new EatAction(ID, actionID, targetOrganism);
lock (PendingActions)
{
PendingActions.SetEatAction(action);
InProgressActions.SetEatAction(action);
}
}
/// <summary>
/// Helper function used to fire eat events.
/// </summary>
/// <param name="e">The eat event arguments.</param>
/// <param name="clearOnly">Only clear the action, don't fire the event.</param>
private void OnEatCompleted(EatCompletedEventArgs e, bool clearOnly)
{
if (InProgressActions.EatAction != null &&
e.ActionID == InProgressActions.EatAction.ActionID)
{
InProgressActions.SetEatAction(null);
}
if (!clearOnly && EatCompleted != null)
{
EatCompleted(this, e);
}
}