Add comments and docstrings.

Author: AceFire6

config.py

@@ -1,28 +1,20 @@
-SCREEN_WIDTH = 600
-SCREEN_HEIGHT = 600
+SCREEN_WIDTH = 600  # The width of the formation designer and simulation
+SCREEN_HEIGHT = 600  # The height of the formation designer and simulation
 
-DEBUG = False
-
-MAX_SPEED = 2
-VISION_RANGE = 150
-COLLISION_RANGE = 20
+MAX_SPEED = 2  # Max speed of a unit
+VISION_RANGE = 150  # The vision range of a unit
+COLLISION_RANGE = 20  # The collision range of a unit
 
+# Colour definitions for easy referencing
 WHITE = (255, 255, 255)
 RED = (255, 0, 0)
 CYAN = (0, 100, 200)
 GREEN = (0, 100, 0)
 
+# The priority and order the forces are applied in.
 FORCE_PRIORITY_LIST = (
     'avoidance', 'formation',
 )
 
-AV_WEIGHT = 0.5
-F_WEIGHT = 0.6
-
-
-def debug_print(*args):
-    if DEBUG:
-        string = ''
-        for item in args:
-            string += ' ' + str(item)
-        print string
+AV_WEIGHT = 0.5  # The weighting of avoidance behaviours
+F_WEIGHT = 0.6  # The weighting of the formation behaviour

enemy.py

@@ -1,15 +1,20 @@
-from boid import Boid
+from unit import Unit
 from vec2d import Vec2d
 
 
-class Enemy(object, Boid):
+class Enemy(object, Unit):
+    """Enemy class. Based on the Unit class."""
     def __init__(self, start, end):
-        Boid.__init__(self, start, None, None)
+        """Create an Enemy with the path from start to end."""
+        Unit.__init__(self, start, None, None)
         self._start = Vec2d(start.x, start.y)
         self._end = end
         self._target = end
 
     def apply_velocity(self, **kwargs):
+        """Calculate the required velocity to head towards the current target.
+        Apply the velocity and regenerate the vertices.
+        """
         if self.position.get_distance(self._target) < 30:
             if self._target == self._start:
                 self._target = self._end
@@ -22,4 +27,5 @@ def apply_velocity(self, **kwargs):
         self.generate_vertices()
 
     def update(self, **kwargs):
+        """Overridden update method. Just applies velocity."""
         self.apply_velocity()

formation.py

@@ -1,10 +1,16 @@
 from vec2d import Vec2d
-from boid import Boid
+from unit import Unit
 from waypoint import Waypoint
 
 
 class Formation(object):
+    """Formation that handles all units it manages. Used to handle unit
+    placement and waypoint updating.
+    """
     def __init__(self, filename=None):
+        """Create a formation. If a filename is specified, the formation
+        is loaded from there, otherwise, the file has to be specified later.
+        """
         self.waypoint = None
         self._center = Vec2d(0, 0)
         self._direction = Vec2d(0, 0)
@@ -14,6 +20,9 @@ def __init__(self, filename=None):
             self.parse_formation_file(filename)
 
     def parse_formation_file(self, open_file):
+        """Open and parse the given formation file. Set up all the required
+        variables for movement and units and their waypoints.
+        """
         if open_file:
             self._center = Vec2d(eval(open_file.readline()))
             self._direction = Vec2d(eval(open_file.readline()))
@@ -22,34 +31,54 @@ def parse_formation_file(self, open_file):
                 self.waypoints.append(Waypoint(Vec2d(eval(line)), self.center))
 
     def set_waypoint(self, waypoint_pair_or_x, y=None):
+        """Set the formations waypoint. Either using a tuple, or by specifying
+        the x and y coordinates as separate arguments.
+        """
         if y is None:
             self.waypoint = Vec2d(waypoint_pair_or_x)
         else:
             self.waypoint = Vec2d(waypoint_pair_or_x, y)
 
     def set_center(self, center_pair_or_x, y=None):
+        """Set the center of the formation.Either using a tuple, or by
+        specifying the x and y coordinates as separate arguments.
+        """
         if y is None:
             self.waypoint = center_pair_or_x
         else:
             self.waypoint = Vec2d(center_pair_or_x, y)
 
     def gen_and_get_boids(self):
-        return [Boid((position + self.center), waypoint, self)
+        """Generate all the units in the formation based on their relative
+        positions and the formation center. Give them a waypoint managed by
+        the formation. Return a list.
+        """
+        return [Unit((position + self.center), waypoint, self)
                 for position, waypoint in zip(self.positions, self.waypoints)]
 
     @property
     def center(self):
+        """Return a Vec2D with the center for drawing purposes."""
         return Vec2d(int(self._center[0]), int(self._center[1]))
 
     @property
     def direction(self):
+        """Get the direction. _direction is its location relative to the
+         formation's center. Return Vec2D.
+         """
         return self._direction + self._center
 
     @property
     def facing(self):
+        """Return the Vec2D vector describing the facing of the formation."""
         return self.direction - self._center
 
     def update(self):
+        """Update the formation. If the center of the formation is too far
+        from its waypoint, movement is started. The formation always moves
+        toward direction, however, it rotates to face the waypoint. This allows
+        for a more realistic looking movement/rotation.
+        """
         if self.waypoint and (self._center.get_distance(self.waypoint) > 10):
             acceleration = self.facing.normalized()
             to_waypoint = self.waypoint - self._center

formation_designer.py

@@ -5,30 +5,35 @@
 import math
 
 
-boundaries = True
-center = None
+center = None  # The center of the formation
+# The vector direction - center is the direction the formation is facing
 direction = None
 
 
 def add_tuple(t1, t2):
+    """Add each element of tuple t1 and t2 and return a tuple."""
     return tuple((t1[i] + t2[i]) for i in range(len(t1)))
 
 
 def with_center(placed_units):
+    """Return the list of the non-relative version of the placed_units."""
     global center
     return [add_tuple(placed_unit, center) for placed_unit in placed_units]
 
 
 def distance_to(point1, point2):
+    """Calculate the distance between point1 and point2 and return a float."""
     return math.sqrt((point2[0] - point1[0])**2 + (point2[1] - point1[1])**2)
 
 
 def close_to(point, placed_units):
+    """Get all units close to point and return a list of these units."""
     return [unit for unit in placed_units
             if distance_to(point, unit) < config.COLLISION_RANGE + 10]
 
 
 def get_closest(point, close_units):
+    """Find the unit closest to point and return the closest tuple."""
     if close_units:
         closest = close_units[0]
         dist = distance_to(point, closest)
@@ -43,6 +48,7 @@ def get_closest(point, close_units):
 
 
 def get_closest_and_dist(point, close_units):
+    """Get the closest unit and the distance to it and return tuple."""
     closest = get_closest(point, close_units)
     if closest:
         return closest, distance_to(point, closest)
@@ -51,18 +57,17 @@ def get_closest_and_dist(point, close_units):
 
 
 def events(placed_units):
-    global boundaries, center, direction
+    """Event section of the game loop. Handle user input. Return boolean."""
+    global center, direction
 
     for event in pygame.event.get():
-        if event.type == pygame.QUIT:
+        if event.type == pygame.QUIT:  # Program window quit button press
             return False
-        elif event.type == pygame.KEYDOWN:
+        elif event.type == pygame.KEYDOWN:  # Key pressed event
             if event.key == pygame.K_ESCAPE:
                 return False
-            elif event.key == pygame.K_SPACE:
-                boundaries = not boundaries
             elif event.key == pygame.K_s and (pygame.key.get_mods() &
-                                              pygame.KMOD_CTRL):
+                                              pygame.KMOD_CTRL):  # Save
                 options = {
                     'filetypes': [('Formations', '.fm')],
                     'initialfile': 'formation1.fm',
@@ -75,7 +80,7 @@ def events(placed_units):
                         save_file.write(str(placed_unit) + '\n')
                     save_file.close()
             elif event.key == pygame.K_o and (pygame.key.get_mods() &
-                                              pygame.KMOD_CTRL):
+                                              pygame.KMOD_CTRL):  # Open
                 options = {
                     'filetypes': [('Formations', '.fm')],
                     'title': 'Open formation'}
@@ -87,12 +92,11 @@ def events(placed_units):
                         print line
                         placed_units.append(eval(line))
                     open_file.close()
-        elif event.type == pygame.MOUSEBUTTONDOWN:
+        elif event.type == pygame.MOUSEBUTTONDOWN:  # Mouse Event
             states = pygame.mouse.get_pressed()
-            config.debug_print("STATES:", states)
             mouse_pos = pygame.mouse.get_pos()
             close_units = close_to(mouse_pos, with_center(placed_units))
-            if states == (1, 0, 0): # Left click - Add
+            if states == (1, 0, 0):  # Left click - Add
                 if not center:
                     center = mouse_pos
                     return True
@@ -103,7 +107,7 @@ def events(placed_units):
                 if not close_units:
                     placed_units.append((mouse_pos[0] - center[0],
                                          mouse_pos[1] - center[1]))
-            elif states == (0, 0, 1): # Right click - Delete
+            elif states == (0, 0, 1):  # Right click - Delete
                 if close_units:
                     closest = get_closest(mouse_pos, close_units)
                     print (center[0] - closest[0], center[1] - closest[1])
@@ -113,7 +117,8 @@ def events(placed_units):
 
 
 def render(screen, placed_units):
-    global boundaries, center
+    """Render section of game loop. Handle unit drawing."""
+    global center
     screen.fill((0, 0, 0))
     colour = config.WHITE
     closest_to_mouse, dist = get_closest_and_dist(pygame.mouse.get_pos(),
@@ -128,16 +133,18 @@ def render(screen, placed_units):
     for unit in with_center(placed_units):
         if unit == closest_to_mouse and dist <= config.COLLISION_RANGE + 10:
             colour = config.RED
-        if boundaries:
-            pygame.draw.circle(screen, colour, unit,
-                               config.COLLISION_RANGE + 10, 1)
+        pygame.draw.circle(screen, colour, unit,
+                           config.COLLISION_RANGE + 10, 1)
         pygame.draw.circle(screen, colour, unit,
                            2, 0)
         colour = config.WHITE
     pygame.display.flip()
 
 
 def main():
+    """Main game loop. Runs through every step of the game loop until the
+    event section returns false.
+    """
     pygame.init()
     pygame.display.set_caption('Formation Designer')
     screen = pygame.display.set_mode(

main.py

@@ -6,76 +6,79 @@
 import pygame
 from vec2d import Vec2d
 
-boids = []
-enemies = []
-formation = None
-enemy_start = None
+units = []  # Units in the formation
+enemies = []  # Enemies added by the user
+formation = None  # The formation being used
+enemy_start = None  # The start point of the current enemy path
 
 
 def events():
-    global boids, enemies, formation, enemy_start
+    """Event section of game loop. Handle user input. Return boolean."""
+    global units, enemies, formation, enemy_start
     for event in pygame.event.get():
-        if event.type == pygame.QUIT:
+        if event.type == pygame.QUIT:  # Program window quit button press
             return False
-        elif event.type == pygame.KEYUP:
+        elif event.type == pygame.KEYUP:  # Key pressed event
             if event.key == pygame.K_r:
-                boids = []
+                units = []
                 enemies = []
                 formation = None
                 enemy_start = None
             elif event.key == pygame.K_ESCAPE:
                 return False
             elif event.key == pygame.K_o and (pygame.key.get_mods() &
-                                              pygame.KMOD_CTRL):
+                                              pygame.KMOD_CTRL):  # Open file
                 options = {
                     'filetypes': [('Formations', '.fm')],
                     'title': 'Open formation'}
                 formation = Formation(tkFileDialog.askopenfile('r', **options))
-                boids = formation.gen_and_get_boids()
-        elif event.type == pygame.MOUSEBUTTONDOWN:
+                units = formation.gen_and_get_boids()
+        elif event.type == pygame.MOUSEBUTTONDOWN:  # Mouse event
             states = pygame.mouse.get_pressed()
-            config.debug_print("STATES:", states)
             mouse_pos = pygame.mouse.get_pos()
-            if states == (1, 0, 0): # Left click
+            if states == (1, 0, 0):  # Left click - set enemy path
                 if not enemy_start:
                     enemy_start = mouse_pos
                 else:
                     enemies.append(Enemy(Vec2d(enemy_start), Vec2d(mouse_pos)))
                     enemy_start = None
-            elif states == (0, 0, 1): # Right click
+            elif states == (0, 0, 1):  # Right click - set waypoint
                 if formation:
                     formation.set_waypoint(mouse_pos)
     return True
 
 
-def loop(obstacles=None):
-    global boids, formation
+def update(obstacles=None):
+    """Update the formation and units."""
+    global units, formation
     if formation:
         formation.update()
-    for boid in boids:
+    for unit in units:
         if obstacles:
-            boid.update(boids, obstacles)
+            unit.update(units, obstacles)
         else:
-            boid.update(boids)
+            unit.update(units)
     for enemy in enemies:
         enemy.update()
 
 
 def render(screen):
-    global boids, formation
+    """Render section of game loop. Handle drawing."""
+    global units, formation
     screen.fill((0, 0, 0))
     if formation:
         pygame.draw.circle(screen, (0, 100, 200), formation.center, 5, 0)
-    for boid in boids:
-        pygame.draw.polygon(screen, boid.colour, boid.vertices)
+    for unit in units:
+        pygame.draw.polygon(screen, unit.colour, unit.vertices)
     for enemy in enemies:
         pygame.draw.polygon(screen, config.RED, enemy.vertices)
     pygame.display.flip()
 
 
 def main():
+    """Main game loop. Loop until events returns false."""
     pygame.init()
-    pygame.display.set_caption("Boids - Prototype")
+    pygame.display.set_caption("Reactive Formations")
     screen = pygame.display.set_mode(
         (config.SCREEN_WIDTH, config.SCREEN_HEIGHT))
     running = True
@@ -88,7 +91,7 @@ def main():
         clock.tick(60)
         pygame.time.wait(1)
         running = events()
-        loop(enemies) if enemies else loop()
+        update(enemies) if enemies else update()
         render(screen)
 
 if __name__ == "__main__":