Documentation.

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

diff --git a/bulletml/impl.py b/bulletml/impl.py
index a056d6c..3326cec 100644 (file)
--- a/bulletml/impl.py
+++ b/bulletml/impl.py
@@ -14,6 +14,8 @@ from bulletml import parser
 
 PI_2 = math.pi * 2
 
+__all__ = ["Action", "Bullet"]
+
 class Action(object):
     """Running action implementation."""
 
@@ -73,10 +75,13 @@ class Action(object):
             self.owner.speed += self.speed
 
         if self.direction_frames > 0:
+            # The Noiz implementation was a little weird here, I think
+            # there was a bug in it that prevented it from working if
+            # the frame count was 1. I'm still not sure what the aim
+            # check is supposed to do, exactly.
             self.direction_frames -= 1
-            if self.direction_frames <= 0:
-                if self.aiming:
-                    self.owner.direction += self.owner.aim
+            if self.aiming and self.direction_frames <= 0:
+                self.owner.direction += self.owner.aim
             else:
                 self.owner.direction += self.direction
 
@@ -224,7 +229,24 @@ class Action(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):
@@ -251,7 +273,7 @@ class Bullet(object):
 
     @property
     def aim(self):
-        """Angle to the target."""
+        """Angle to the target, in radians."""
         if self.target is None:
             return self.direction
         else:
@@ -261,6 +283,9 @@ class Bullet(object):
     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).
@@ -280,7 +305,10 @@ class Bullet(object):
         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:
@@ -291,8 +319,10 @@ class Bullet(object):
     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 = []
 
@@ -305,10 +335,3 @@ class Bullet(object):
         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)