Commits

Andrew Peterson  committed 5b0f946

Add documentation to the Game Module.

  • Participants
  • Parent commits a8e6bc8
  • Branches comments

Comments (0)

Files changed (1)

File djlib/game.py

+""" Game Module
 
+Provides framework for defining and handling of global Game objects and
+state transitions. Using this framework will provide a simple template for
+control how the game updates and transitions between different modes.
+"""
 
 class GameClass:
-    
+    """ Global Class encapsulating the entire game.
+
+    GameClass should be use as the base of all game logic and data.
+    """
     def __init__(self):
         self.curr_state = None
         self.running = False
         self.known_states = {}
 
     def initialize(self):
+        """ Perform any one-time Game initialization and allow for updates.
+
+        Override to initialize log running Game Systems that are needed until
+        Game Shutdown.
+        """
         self.running = True
 
     def update(self):
+        """ Control how the game updates each frame.
+
+        Override to implement your own processing order and to added Systems
+        specific to your Game.
+        """
         if self.curr_state:
             self.curr_state.processInput()
             self.curr_state.update()
             self.curr_state.render()
 
     def changeState(self, state_class, *args):
+        """ Switch to a new GameState, allowing for proper clean-up of old State.
+
+        GameClass will continue to track all known GameStates and reuse previous
+        created GameState objects until closeState(...) is called.
+
+        Args:
+            state_class(GameState class) - Class used to create new State object
+            args(tuple, Optional) - Arguments used to initialize new state through
+                                    GameState.enter(...)
+        """
         assert(state_class)
 
         if self.curr_state:
         self.curr_state.enter(*args)
 
     def closeState(self, state_class):
-
+        """ Fully shutdown and remove a GameState from the GameClass. """
         # Look for state in known states
         if state in self.known_states:
             # shutdown and remove from list
         return False
 
     def shutdown(self):
+        """ Clean-up all known GameStates and disable future updates.
+
+        Should only be called while existing the application.
+        """
         self.running = False
 
         # Leave the current state we are in
         state = {}
 
     def getActiveState(self):
+        """ Return currently active GameState. """
         return self.curr_state
         
 #end GameClass
 
 class GameState:
+    """ Framework class to aid in defining and transitioning the lifecycle
+    of a Real-time application.
+
+    Methods should be overridden to define the initialization, transition, and
+    cleanup of this part of the Game Lifecycle. GameState objects will persist
+    and be reused until GameClass.closeState() is called, allowing for states
+    to persist data between transistions, yet still clean up any uneeded
+    resources.
+
+    Lifecycle:
+        initialize - Called the first time the game switches to this state
+        |- enter - Called each time the game switches *to* this state
+        ||- processInput - Called on every GameClass Update
+        ||- update - Called on every GameClass Update
+        ||- render - Called on every GameClass Update
+        |-leave - Called each time the game switches *from* this state
+        shutdown - Called when state is closed and deleted or by GameClass.shutdown()
+    """
 
     def __init__(self):
         self.gc = None
         """Called the first time the game is changed to this state
            during the applications lifecycle."""
 
-    def enter(self):
-        """Called every time the game is switched to this state."""
+    def enter(self, *args):
+        """Called every time the game is switched to this state.
+
+        Args:
+            args(tuple, Optional) - Arguments can be provided during the state
+                                    transistion to help define the context of the
+                                    switch.
+        """
 
     def processInput(self):
         """Called during normal update/render period for this state
     def changeState(self, state_class, *args):
         """Shortcut for this state to initiate transfer to a new state."""
         self.gc.changeState(state_class, *args)
+
 #end GameState