Source

pyShipCommand / README

Full commit

pyShipCommand
----------------------------
pyShipCommand is intended to be a persistent multiplayer SBS (Script Based 
Strategy) Game set in Space. There is no direct control over any of the units 
and the game progresses through Python AI Scripts written by each player. This 
allows the game to continue to run 24/7 without any direct player involvement.


Installation
----------------------------
This game was written for Python 2.7 and has not yet been tested for Python 3+. 
So far, I have not been able to get it to install correctly using virtualenv, 
but it may help to install the dependencies manually instead of relying on pip.

To run the game you must install the following dependencies:
* Twisted: http://twistedmatrix.com/trac/wiki/Downloads
* Zope Interface: http://pypi.python.org/pypi/zope.interface#download
* Zope Component: http://pypi.python.org/pypi/zope.component#download
* PyGame: http://pygame.org/download.shtml
* OcempGUI: http://sourceforge.net/projects/ocemp/files/ocempgui/0.2.9/

If running on Windows, you'll need:
* PyWin32: http://sourceforge.net/projects/pywin32/files/pywin32/

to install with virtualenv try the following:

    virtualenv env
    # alternatively use requirements-gui.txt in the line below to install gui
    # scripts
    pip install -r requirements.txt 
    python setup.py install

Starting the Server
-----------------------------
Since pyShipCommand was written to be a multiplayer game, you'll have to start 
the server first before being able to connect using the gui_client. It will 
automatically load and existing player scripts in finds in the "player-scripts" 
directory. Currently, there is **NO SERVER PERSISTENCE**, so expect any Ships to 
be deleted if you shutdown the server.

To start the server after install, just use:
    $ pyship-server


Running the GUI Client
---------------------------

The GUI Client allows you to connect to the server using a username/password, 
and will render the current state of the server. There are also a few "admin" 
commands that can be entered into the EditBox to communicate with the server.

To start the GUI client use the following command:
    $ pyship-gui

If your server is not running, then there will be nothing for the client to 
connect to.

When you first connect, the server will create you a "Mothership" (Command 
Center) in the center of your view. This will be your starting and has the 
capability of producing more ships.

There are a few test credentials hard coded into the server code (but set up to 
be transitioned to an actual db). The main one is user:'admin', 
password:'password'. This account has admin privileges and all ships for all 
players are sent to the client.

Client Commands
----------------------------

import <path//to//scriptname.py> - Imports a script from anywhere in the filesystem to the current player's cscript directory. Once imported, the script is tracked by the Script Manager and can be uploaded to the server.

upload <scriptname.py> - Uploads a python script with the given 
<scriptname> (must have .py extension) located in the current player's cscript directory. 
This script can later be bound to a ship to control its behavior.

ship create <x> <y> - Admin command to create a ship for the player at <x,y>. 
Defaults to <0,0> if no coordinates are given.

ship script <ship id> <scriptname> - Binds the <scriptname> (no extension) to 
the player ship matching the <ship id>. The ship id is rendered next to the ship 
in the GUI.

ship move <ship id> <x> <y> - Sets the ship's target location to <x, y>

ship orbit <ship id> <x> <y> <d> - Sets the ship's target to an orbital 
trajectory <d> distance around position <x, y>. The <x> component can be 
substituted with a ship id, to orbit around another ship.

ship follow <ship id> <target id> <d> - Sets the ship's target to follow <d> 
distance behind ship matching the <target id>.

msg <message> - Allows you to send messages to your "Mothership". The Mothership 
must have a bound script capable of receiving and processing these messages.


Ship Scripts
---------------------------

There are two sample ship scripts and one player module available. these are 
located in the scripts folder:

* mship_cmd.py - Script that should be bound to your mothership. Handles 
messages sent by the client with the "msg" command.
* ship_cmd.py - Script that should be bound to normal ships. Uses the tracker 
player module to determine what nearby ships are friends or enemies. It will 
attack enemies.
* tracker.py - Example of a "player module", can be imported by other ship 
scripts. This must be uploaded to the server before any other scripts can import 
it.

Ship API:

ship - Object injected into the ship scripts namespace to represent the ship the script is currently bound to.

ship.getData() - Returns a mutable object that can be used store persisting data between subsequent runs of that script.

ship.log(<msg>) - Allows scripts to write debug information into the ship's log to be sent to the client.

ship.getEquipment(<name>) - Gain access to the equipment API for retrieving information about the current universe.

Please see mship_cmd.py, ship_cmd.py, and tracker.py located in example_scripts/ for more examples of the ship APIs.