From 7ffb03574d79049fc13fc08412b4f62ad309874d Mon Sep 17 00:00:00 2001
From: Charles <Charles@92bb83a3-7c8f-8a45-bc97-515c4e399668>
Date: Wed, 21 Apr 2010 19:26:22 +0000
Subject: [PATCH] Documented the sample monster.

git-svn-id: https://bd85.net/svn/cs3505_group@123 92bb83a3-7c8f-8a45-bc97-515c4e399668
---
 CarFire/CarFire/CarFire/SaberMonster.cs | 80 ++++++++++++++++++++++---
 1 file changed, 73 insertions(+), 7 deletions(-)

diff --git a/CarFire/CarFire/CarFire/SaberMonster.cs b/CarFire/CarFire/CarFire/SaberMonster.cs
index 06fd127..c2932ee 100644
--- a/CarFire/CarFire/CarFire/SaberMonster.cs
+++ b/CarFire/CarFire/CarFire/SaberMonster.cs
@@ -8,6 +8,9 @@ using Microsoft.Xna.Framework.Graphics;
 
 namespace CarFire
 {
+    /// <summary>
+    /// A type for the states of an artificually intelligent entity.
+    /// </summary>
     public enum AiState
     {
         Standing,
@@ -19,14 +22,31 @@ namespace CarFire
     }
 
 
+    /// <summary>
+    /// An example monster.  This can serve as a starting place for
+    /// creating other monsters.  This one just follows a path.
+    /// </summary>
     public class SaberMonster : IMonster
     {
+        /// <summary>
+        /// Construct this type of monster.  This constructor is called
+        /// by the map when the game requests entities.
+        /// </summary>
+        /// <param name="identifier">The single character ID.</param>
+        /// <param name="position">The initial position on the map.</param>
+        /// <param name="info">More parameters.</param>
+        /// <param name="game">The game object reference.</param>
         public SaberMonster(char identifier, Point position, Dictionary<string, string> info, Game game)
         {
             mId = identifier;
             mMotion = new MovementManager(position);
+
+            // We need to keep the game reference in order to get the grid when we
+            // need to find paths.
             mGame = game;
 
+            // Get the speed of the monster.  If not set in the map, it defaults to
+            // whatever the default of MovementManager is... 1 I think.
             string speedString;
             if (info.TryGetValue("speed", out speedString))
             {
@@ -46,10 +66,16 @@ namespace CarFire
                 }
             }
 
+            // Start doing something...
             StartPacing();
         }
 
 
+        /// <summary>
+        /// Call this to switch the monster AI state to pacing and set up
+        /// the initial paths.  The monster will start following the path it
+        /// was defined with in the map file.
+        /// </summary>
         public void StartPacing()
         {
             mState = AiState.Pacing;
@@ -57,6 +83,7 @@ namespace CarFire
             if (mIdlePath.Count == 0) return;
 
             // Determine the best (closest) waypoint to start at.
+            // We may not be on the path, so we have to walk to get on it.
             mIdlePathIndex = 0;
             int closest = int.MaxValue;
             for (int i = 0; i < mIdlePath.Count; i++)
@@ -69,6 +96,7 @@ namespace CarFire
                 }
             }
 
+            // Find the path to get to the closest waypoint.
             PathFinder pathFinder = new PathFinder(mGame.Grid);
             mPath = new List<Point>(32);
             mPath.Add(Coordinates);
@@ -81,6 +109,8 @@ namespace CarFire
         {
             if (mPathIndex >= mPath.Count)
             {
+                // We're done with the current path, so find the path to
+                // the next waypoint... forever.
                 mIdlePathIndex++;
                 PathFinder pathFinder = new PathFinder(mGame.Grid);
                 mPath = new List<Point>(32);
@@ -90,6 +120,9 @@ namespace CarFire
                 mPathIndex = 0;
             }
 
+            // We need to make sure out direction is set to the next cell
+            // we want to be.  If our current coordinates match that, we need
+            // to change our direction to get to the next cell.
             if (mPath[mPathIndex % mPath.Count] == mMotion.Coordinates)
             {
                 mPathIndex++;
@@ -102,6 +135,9 @@ namespace CarFire
 
         #region IMonster Members
 
+        /// <summary>
+        /// I don't know what this is for.
+        /// </summary>
         public bool visible
         {
             get { throw new NotImplementedException(); }
@@ -112,11 +148,22 @@ namespace CarFire
 
         #region ICharacter Members
 
+        /// <summary>
+        /// Load the monster's content.  This is called by the map when
+        /// the game requests the entities.
+        /// </summary>
+        /// <param name="contentManager">The zaphnod.</param>
         public void LoadContent(ContentManager contentManager)
         {
             mTexture = contentManager.Load<Texture2D>("menuItem");
         }
 
+        /// <summary>
+        /// Update the monster's state.  This should be called by the game
+        /// every "frame" (whenever the game is updating its state).  In this
+        /// simple monster, all we need to do is update the motion manager.
+        /// </summary>
+        /// <param name="timeSpan"></param>
         public void Update(TimeSpan timeSpan)
         {
             if (mState == AiState.Pacing)
@@ -125,24 +172,42 @@ namespace CarFire
             }
         }
 
+        /// <summary>
+        /// Draw the monster.  We just ask the map for our screen position,
+        /// passing it the position which the motion manager keeps track of.
+        /// </summary>
+        /// <param name="spriteBatch">The </param>
         public void Draw(SpriteBatch spriteBatch)
         {
             Rectangle position = mGame.State.Map.GetRectangleFromCoordinates(mMotion.Position);
             spriteBatch.Draw(mTexture, position, Color.White);
         }
 
+        /// <summary>
+        /// A monster should keep track of its health.  This one doesn't.
+        /// </summary>
         public int Health
         {
             get { throw new NotImplementedException(); }
         }
 
+        /// <summary>
+        /// This monster is invincible.
+        /// </summary>
+        /// <param name="amount"></param>
         public void causeDamageTo(int amount)
         {
             throw new NotImplementedException();
         }
 
+        /// <summary>
+        /// Get the smoothed position.
+        /// </summary>
         public Vector2 Position { get { return mMotion.Position; } }
 
+        /// <summary>
+        /// Get the grid coordinates.
+        /// </summary>
         public Point Coordinates { get { return mMotion.Coordinates; } }
 
         #endregion
@@ -155,16 +220,17 @@ namespace CarFire
         char mId;
         MovementManager mMotion;
 
-        List<Point> mIdlePath = new List<Point>();
-        int mIdlePathIndex;
+        List<Point> mIdlePath = new List<Point>();      // List of waypoints that we got from the map.
+        int mIdlePathIndex;                             // Index to the waypoint we're heading for.
 
-        List<Point> mPath;
-        int mPathIndex;
-        Direction mPathDirection;
+        List<Point> mPath;              // List of cells in the path between the position between where
+                                        // we started and the waypoint we're heading for.
+        int mPathIndex;                 // Index to the cell we're heading for.
+        Direction mPathDirection;       // The direction between our current position and the place we're going.
 
-        AiState mState;
+        AiState mState;                 // What is the monster doing?
 
-        Texture2D mTexture;
+        Texture2D mTexture;             // Obvious.
 
         #endregion
     }
-- 
2.45.2