Documentation.

[python-bulletml.git] / bulletml / impl.py

diff --git a/bulletml/impl.py b/bulletml/impl.py
index fcb3aab..3326cec 100644 (file)
--- a/bulletml/impl.py
+++ b/bulletml/impl.py
@@ -14,6 +14,8 @@ from bulletml import parser
 
 PI_2 = math.pi * 2
 
 
 PI_2 = math.pi * 2
 

+__all__ = ["Action", "Bullet"]
+

 class Action(object):
     """Running action implementation."""
 
 class Action(object):
     """Running action implementation."""
 


@@ -227,7 +229,24 @@ class Action(object):
         return created
 
 class Bullet(object):
         return created
 
 class Bullet(object):

-    """Simple bullet implementation."""
+    """Simple bullet implementation.
+
+    Attributes:
+    x, y - current X/Y position
+    px, py - X/Y position prior to the last step
+    mx, my - X/Y axis-oriented speed modifier ("acceleration")
+    direction - direction of movement, in radians
+    speed - speed of movement, in units per frame
+    target - object with .x and .y fields for "aim" directions
+    vanished - set to true by a <vanish> action
+
+    Contructor Arguments:
+    x, y, direction, speed, target - same as the attributes
+    actions - internal action list
+    parent - parent of actions, None for manually-created bullets
+    rank - game difficulty, 0 to 1
+
+    """

 
     def __init__(self, x=0, y=0, direction=0, speed=0, target=None,
                  actions=(), parent=None, rank=None):
 
     def __init__(self, x=0, y=0, direction=0, speed=0, target=None,
                  actions=(), parent=None, rank=None):


@@ -254,7 +273,7 @@ class Bullet(object):
 
     @property
     def aim(self):
 
     @property
     def aim(self):

-        """Angle to the target."""
+        """Angle to the target, in radians."""

         if self.target is None:
             return self.direction
         else:
         if self.target is None:
             return self.direction
         else:


@@ -264,6 +283,9 @@ class Bullet(object):
     def finished(self):
         """Check if this bullet is finished running.
 
     def finished(self):
         """Check if this bullet is finished running.
 

+        A bullet is finished when it has vanished, and all its
+        actions have finished.
+

         If this is true, the bullet should be removed from the screen.
         (You will probably want to cull it under other circumstances
         as well).
         If this is true, the bullet should be removed from the screen.
         (You will probably want to cull it under other circumstances
         as well).


@@ -283,7 +305,10 @@ class Bullet(object):
         self._actions = []
 
     def replace(self, old, new):
         self._actions = []
 
     def replace(self, old, new):

-        """Replace an active action with another."""
+        """Replace an active action with another.
+
+        This is mostly used by actions internally to queue children.
+        """

         try:
             idx = self._actions.index(old)
         except ValueError:
         try:
             idx = self._actions.index(old)
         except ValueError:


@@ -294,8 +319,10 @@ class Bullet(object):
     def step(self):
         """Advance by one frame.
 
     def step(self):
         """Advance by one frame.
 

-        This updates the direction, speed, x, y, px, and py members,
-        and may set the vanished flag.
+        This updates the position and velocity, and may also set the
+        vanished flag.
+
+        It returns any new bullets this bullet spawned during this step.

         """
         created = []
 
         """
         created = []
 


@@ -308,10 +335,3 @@ class Bullet(object):
         self.y += self.my - math.cos(self.direction) * self.speed
 
         return created
         self.y += self.my - math.cos(self.direction) * self.speed
 
         return created

-
-    @classmethod
-    def FromDoc(cls, doc, params=(), x=0, y=0, speed=0, direction=0,
-                target=None, rank=0.5):
-        """Construct a bullet from top-level actions in a document."""
-        actions = [act(params, rank) for act in doc.top]
-        return cls(x, y, direction, speed, target, actions, rank=rank)