Commits

Andrew Peterson  committed 4568819

Add documention to base GUIClient scripts.

  • Participants
  • Parent commits d56ccd8
  • Branches comments

Comments (0)

Files changed (3)

File pyshipcommand_gui/__init__.py

-
+""" pyship-gui Entry Point
+
+Main entry point for the pyShipCommand GUI application.
+This is mainly responsible for initialize the main GameClass and
+it's subsystems. This is also where the main game loop is defined
+and started. After that, any major updates are usually controlled
+by the current GameState.
+"""
 # Install threadedselectreactor to integrate with ocempGUI
 from twisted.internet._threadedselect import install as reactor_install
 reactor_install()
 DEFAULT_SERVER_STEP = 1.0
 
 class GUIGameClass(GameClass):
+    """ Main GameClass for the Client GUI.
+
+    Used to store stateless game data and provide access to major systems.
+    Actual game logic is implemented in the various GameStates that can be
+    switched to through this GameClass.
+    """
 
     def __init__(self):
         GameClass.__init__(self)
         self.dfont = None
 
     def initialize(self):
+        """ Intializes pygame and creates rendering systems. """
 
         # Init pygame and create main rendering surface
         pygame.init()
         GameClass.initialize(self)
 
     def update(self):
+        """ Control how the game updates each frame. """
         # Add any global/game specific updates here
         self.fpsClock.tick()
         self.time = pygame.time.get_ticks()
         self.time_step = self.fpsClock.get_rawtime()/1000.0
 
+        # Rely on the base GameClass implementation for input/update/render.
         GameClass.update(self)
 
     def shutdown(self):
+        """ Clean up gamestates and disconnect from server. """
         GameClass.shutdown(self)
 
         self.client.disconnect()
         pygame.quit()
 
     def quit(self):
+        """ Initiate shutdown procedure. """
         # tell systems to shut down
         # normally we would just set self.running to False
-        # but our update loop is based on the Twisted Reactor
+        # but our update loop is based on the Twisted Reactor.
         # Use pygame to give it the QUIT signal
         e = pygame.event.Event(pygame.QUIT)
         pygame.event.post(e)
 #end GUIGameClass
 
 def main(argv=sys.argv[1:]):
+    """ Main Entry Point
+
+    Apply any script options and initialize the actual GameClass.
+    Update loop is registered and then logic is passed off to the
+    current GameState until shutdown procedures are initiated.
+    """
     from argparse import ArgumentParser, FileType
 
     # Argument parsing
 
     # MAIN GAMECLASS
     game = GUIGameClass()
-    
-    #shipImg = resource_stream('pyshipcommand_gui', 'assets/raptor.png')
-    #shipImg = pygame.image.load(shipImg)
-    #shipImg = shipImg.convert_alpha()
-    #ship_view.SHIP_IMG = pygame.transform.rotozoom(shipImg, -90, 0.25)
-
-    #cmdImg = resource_stream('pyshipcommand_gui', 'assets/command.png')
-    #cmdImg = pygame.image.load(cmdImg)
-    #ship_view.MSHIP_IMG = cmdImg.convert_alpha()
-
-    # Manually connect
-    #client.connect(SERVER_ADDR, SERVER_PORT)
-    #client.login(DEFAULT_USER, DEFAULT_PASS)
 
     # Initialize
     game.initialize()

File pyshipcommand_gui/client.py

+""" Client Module
 
+Client-side support for client/server communication.
+Currently using Twisted Perspective Broker as an underlying RPC mechanism,
+and defines the API that the server has access to.
+
+Jelly (Network Pickle) classes are provided by the common
+`pyshipcommand.network` module.
+"""
 # SYSTEM
 
 # ADDITIONAL LIBRARIES
 log = getLogger('pyshipcommand.gui.client')
 
 class BaseClient(PBClient):
+    """ Base Client to share common functionality. """
+
     def __init__(self):
         PBClient.__init__(self)
 
     def remote_print(self, msg):
+        """ Relay some server-side messages to console. """
         print msg
 #end BaseClient
 
 class RegisterClient(BaseClient):
+    """ Temporary Client used for registering new users.
+
+    Has almost no remote API and automatically disconnects ones a new account
+    has been communicated to the Server.
+
+    See pyshipcommand.network for PBClient callback info.
+    """
 
     def login(self, username, password):
         self.username = username
         BaseClient.disconnect(self)
 #end RegisterClient
 
+# For security reason, all networked classes must be defined as jellyable in
+# the module that defines the remote API.
 pb.setUnjellyableForClass(NetShip, NetShip)
 pb.setUnjellyableForClass(NetInit, NetInit)
 pb.setUnjellyableForClass(NetScript, NetScript)
 pb.setUnjellyableForClass(NetCelestialBody, NetCelestialBody)
 class GUIClient(BaseClient, pb.Referenceable):
+    """ Main GUI Client Interface
+
+    All network communication APIs must be defined here.
+    Methods prepended with `remote_` are accessible via the Server through
+    the Twisted Perspective Broker system.
+
+    See pyshipcommand.network for PBClient callback info.
+    Remote Calls are usually handled by pyshipcommand.players.Player
+    """
     
     def __init__(self, gameclass):
         BaseClient.__init__(self)
     def exit(self):
         self.gc.quit()
 
+
     # SERVER COMMUNICATION
+
     def info(self):
+        """ Local relay to obtain current player info from server. """
         self.server.callRemote("info")
 
     def giveScript(self, name, source):
-        self.server.callRemote("giveScript", name, source)
+        """ Local relay for sending player script to server.
 
-    def addShip(self, pos):
-        self.server.callRemote("addShip", NetVector.fromVector(pos))
-
-    def moveShip(self, ship_id, target_pos):
-        self.server.callRemote("moveShip", ship_id, NetVector.fromVector(target_pos))
-
-    def orbitShip(self, ship_id, target_pos, radius):
-        self.server.callRemote("orbitShip", ship_id, NetVector.fromVector(target_pos), radius)
-
-    def followShip(self, ship_id, target_id, dist):
-        self.server.callRemote("followShip", ship_id, target_id, dist)
+        Args:
+            name(str) - Unique name for new script
+            source(str) - Full source code of script
+        """
+        self.server.callRemote("giveScript", name, source)
 
     def scriptShip(self, ship_id, script_name, action):
+        """ Local relay for binding player script to a ship on the server.
+
+        Args:
+            ship_id(int) - GUID of ship to bind script to
+            script_name(str) - Unique name of script already on server
+            action(str) - 'upgrade' will attempt to retain ship data,
+                          'reboot' will purge any existing data
+        """
         self.server.callRemote("scriptShip", ship_id, script_name, action)
 
     def giveMessage(self, msg):
+        """ Local relay for sending a direct message to player Mothership. """
         self.server.callRemote("giveMessage", msg)
 
     def giveChat(self, msg):
+        """ Local relay for sending a chat message to server. """
         self.server.callRemote("giveChat", msg)
 
     def getPlayers(self):
+        """ Local relay for retreiving connected player list from server. """
         self.server.callRemote("getPlayers")
 
     def getClientInit(self, cb):
+        """ Local replay for retreiving client initialization data from server.
+
+        Args:
+            cb(callable) - Deferred callback to handle client init data. """
         dfr = self.server.callRemote("getClientInit")
         dfr.addCallback(self.setClientInit)
         dfr.addCallback(cb)
 
+
+    # ADMIN COMMUNICATION
+    # Only available for Players defined as Admins on the server.
+
+    def addShip(self, pos):
+        self.server.callRemote("addShip", NetVector.fromVector(pos))
+
+    def moveShip(self, ship_id, target_pos):
+        self.server.callRemote("moveShip", ship_id, NetVector.fromVector(target_pos))
+
+    def orbitShip(self, ship_id, target_pos, radius):
+        self.server.callRemote("orbitShip", ship_id, NetVector.fromVector(target_pos), radius)
+
+    def followShip(self, ship_id, target_id, dist):
+        self.server.callRemote("followShip", ship_id, target_id, dist)
+
+
     # CLIENT CALLBACKS
 
     def remote_updateShips(self, net_ships):
+        """ Receive ship updates from server. """
         # Sanity check
         if not net_ships:
             return
             state.updateShips(net_ships)
 
     def remote_log(self, log):
+        """ Receive ship log data from server. """
         for l in log:
             print l
 
     def remote_showText(self, text):
+        """ Receive text to be shown to player in the GUI. """
         # We only send text when in ViewerState
         state = self.gc.getActiveState()
         if isinstance(state, ViewerState):
             state.delayedText(text, 5000)
 
     def setClientInit(self, init_data):
+        """ Process GUIClient related data from client init data. """
         # Load player scripts
         self.scripts.setActivePlayer(init_data.player)
         log.info("Scripts: %s", self.scripts.getScriptList())

File pyshipcommand_gui/rect_test.py

-
+""" Standalone script to test local RectTree optimized rendering. """
 import pygame, sys
 from pygame.locals import *