Commits

Andrew Peterson  committed 9d27a6c

Add documentation for Universe and Celestial modules.

  • Participants
  • Parent commits 5b0f946
  • Branches comments

Comments (0)

Files changed (2)

File pyshipcommand/celestial.py

+""" Celestial Module
 
+Defines all non-player Astral Bodies that can be found in the Universe.
+"""
 from random import randrange, uniform
 from math import pi, pow
 
 from logging import getLogger
 log = getLogger('pyshipcommand.celestial')
 
+# Resource Spawn Ratios, these should eventually be pulled
+# from a config or database.
 PLANET_CRYSTAL_RATIO = 0.1
 
 
 class CelestialBody(Circle):
+	""" Base class containing common attributes amongst all Bodies. """
+
 	def __init__(self, pos, size):
+		""" Initialize Astral Body.
+
+		Args:
+			pos(Point) - Initial Position
+			size(scalar) - Radius
+		"""
 		Circle.__init__(self, pos, size)
 		id_gen = getUtility(IAllocator, "IdGenerator")
 		self.id = id_gen.allocate()
 		self._resources = self._genResources()
 
 	def getContainer(self):
+		""" Return `Container` holding currently available Resources. """
 		return self._resources
 
 	def _getVolume(self):
+		""" Calculate geometric volume of the body. """
 		return int((4.0/3.0)*pi*pow(self.radius, 3))
 
 	def _genResources(self):
+		""" Override to determine Resource allocation for this body. """
 		return None
 
 #end CelestialBody
 
 class Sun(CelestialBody):
+	""" Ball of gas burning billions of miles away. """
 	def __init__(self, pos):
 		CelestialBody.__init__(self, pos, randrange(50, 100))
 
 #end Sun
 
 class Planet(CelestialBody):
+	""" Body that mostly contains Metals and Crystals and forms around Suns. """
 	def __init__(self, orbit):
 		pos = orbit.pointOnCircle(uniform(0.0, 2.0*pi))
 		CelestialBody.__init__(self, pos, randrange(20, 40))
 #end Planet	
 
 class Asteroid(CelestialBody):
+	""" Rocky body mostly containing Metals. Forms anywhere in space. """
 	def __init__(self, pos):
 		CelestialBody.__init__(self, pos, randrange(10, 20))
 

File pyshipcommand/universe.py

+""" Universe Module
 
+The Universe handles the creation and management of all Celestial Bodies,
+as well as provide the spatial partioning API used to query nearby Entities,
+including Player Ships.
+"""
 from zope.interface import implements
 from djlib.utils import IManager
 
 PLANETS_PER_SUN = (2, 5)
 PLANET_ORBIT_DIST = (300, 500)
 
-
-
 INITIAL_SIZE = 10000
 EMPIRE_EMPIRE_DIST = 1000
 EMPIRE_CELEST_DIST = 200
 
 
-
 class Universe(object):
+    """ Universe containing static Celestial Bodies and dynamic Player Ships.
+
+    A Global Manager that can be accessed by any script using the zope.component
+    system. Since Player ships can move, they are stored in a separate Spatial
+    Tree, to allow for more optimal lookups of static Celestial Bodies.
+    """
     implements(IManager)
 
     def __init__(self):
-    	
-    	# Initialize QuadTree
+    	# Initialize Exanding QuadTree
     	halfSize = INITIAL_SIZE/2
     	self.dyn_tree = ExpandingRectTree(Rect.fromSides(-halfSize, -halfSize, halfSize, halfSize))
         self.static_tree = ExpandingRectTree(Rect.fromSides(-halfSize, -halfSize, halfSize, halfSize))
 
     @log_method(log)
     def load(self, filename):
+        """ Load the Universe from a persistent database. """
     	log.info("Loading Universe from %s", filename)
 
 
     @log_method(log)
     def addDynamic(self, entity):
+        """ Add a moveable entity to the Spatial Tree. """
     	if not isinstance(entity, Entity):
     		raise TypeError()
 
 
     @log_method(log)
     def addStatic(self, entity):
+        """ Add a static entity to the Spatial Tree. """
         if not isinstance(entity, Entity):
             return TypeError()
 
 
     @log_method(log)
     def getDynamicInRange(self, pos, dist):
+        """ Return all dynamic entities within a certain distance from a point in space.
+
+        Args:
+            pos(Point) - Point in Universe
+            dist(scalar) - Inclusion distance from `pos`
+        """
         # rough entity lookup through the RectTree
         bounds = Rect.fromSides(pos.x-dist, pos.y-dist, pos.x+dist, pos.y+dist)
         rough = self.dyn_tree.getData(bounds)
 
+        # refine lookup based on actual distance calculate
         return [entity for entity in rough if pos.distanceApart(entity.getPosition()) <= dist]
 
 
     @log_method(log)
     def getStaticInRange(self, pos, dist):
+        """ Return all static entities within a certain distance from a point in space.
+
+        Args:
+            pos(Point) - Point in Universe
+            dist(scalar) - Inclusion distance from `pos`
+        """
         # rough entity lookup through the RectTree
         bounds = Rect.fromSides(pos.x-dist, pos.y-dist, pos.x+dist, pos.y+dist)
         rough = self.static_tree.getData(bounds)
 
+        # refine lookup based on actual distance calculate
         return [entity for entity in rough if pos.distanceApart(entity.getPosition()) <= dist]
 
 
     @log_method(log)
     def getAllInRange(self, pos, dist, type_ = None):
-
+        """ Return both static and dynamic entities within a certain distance.
+
+        An iterable of strings can be specified to filter results based on class.
+        Examples:
+            type_ = ("Ship", "Asteroid")
+            type_ = "Sun"
+
+        Args:
+            pos(Point) - Point in Universe
+            dist(scalar) - Inclusion distance from `pos`
+            type_(iterable of str, Optional) - Filter results based on class name.
+                Defaults to None, returning all Entities.
+        """
         entities = []
         if not type_ or "Ship" in type_:
             entities = self.getDynamicInRange(pos, dist)
 
     @log_method(log)
     def getAllStatic(self):
+        """ Return all static entities. """
         return self.static_tree.getData()
 
 
     @log_method(log)
     def getById(self, id):
+        """ Lookup entity by unique GUID. """
         return self.entity_by_id.get(id)
 
 
     @log_method(log)
     def findNewEmpire(self):
+        """ Locate a valid placement for a new Player Empire.
 
+        Empires need to be placed a safe distance from Celestial Bodies and
+        other player empires.
+        """
         pos = None
         bounds = self.dyn_tree.rect.sides()
         while True:
 
     @log_method(log)
     def theBigBang(self):
-    	
+        """ Generate all initial Celestial Bodies.
+
+        Suns are generated with a random number of planets surround them.
+        Asteroids are randomly placed throughout Space. There are currently
+        no checks to ensure Bodies do not overlap.
+        """
         # Only called during initialization.
         bounds = self.static_tree.rect.sides()