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.


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:

If running on Windows, you'll need: * 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 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//> - 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 <> - 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:

  • - Script that should be bound to your mothership. Handles

messages sent by the client with the "msg" command. * - 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. * - 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,, and located in example_scripts/ for more examples of the ship APIs.