A (hopefully) simple guide to getting ready to develop for volity on a windows box

This post contains the aforementioned Step 0: preparing to develop Volity games using python, and developing UI files for same, on a Windows box.

Part 1: Download all necessary software.

You will need the following software packages to develop using python:

• A python interpreter (and if you're like me, an integrated development environment to develop in).  I went for the Activestate freely downloadable version because I knew where to find it and knew it would be a low-maintenance install process, but the canonical Windows version is at www.python.org.  Python.org's Windows version is also packaged in an installer and should not present any difficulty with respect to installation or configuration either (though I have yet to test it).

-- See http://www.python.org for download

• The python Volity framework, which includes:

1. The Volity game server source code in Python (currently the file volity-162.tar.gz)
2. The script that sets up and initializes the Volity game server (currently volityd.py)
3. The Zymb library, which the Volity Game server uses to communicate with the outside world

-- See http://www.eblong.com/zarf/volity/index.html (which also has sample code for games you can use to test your setup) and  http://www.eblong.com/zarf/zymb/index.html (for zymb) for downloads.

• A program capable of extracting unix/linux zip (.gz) files.  I downloaded 7-zip for this purpose.  Its interface is a bit odd (it is like a parallel universe version of Windows Explorer), but it'll do the job.  A recent version of WinZip will also do this, but I was too cheap to get and register it.
  

-- see http://www.7zip.org for downloads

• The volity testbench software, which will allow you to view and test your SVG User interface files.

-- See http://www.volity.org/projects/gamut/releases/latest/ to download testbench.

• A recent version of the Java Runtime Environment to run testbench with; if you already have Gamut installed, you should have this already.  Even if you don't have Gamut installed you may be OK here. 

-- See http://java.sun.com if you want to go looking for the latest version of Java

You may want to download the following additional software:

• Inkscape is a drawing program which has been designed specifically to use the SVG format which Volity uses (and extends).  Inkscape does not implement the interactive extensions Volity uses to create user interfaces, but it does allow you to create graphics, then examine and extract the underlying XML text used to store the graphics you have drawn.  You can then bring this text over into your UI files; your UI will then be able to draw the corresponding SVG graphics using the text you added to the file. 

-- See http://www.inkscape.org for download.

Part 2: Unzip and Install stuff

Install python.  Install your .gz capable unzipper, if needed.  Install Java, if needed.  Unzip the Zymb and Volity .gz files.  Extract the testbench.jar file from thedownloaded file and put it somewhere.

Part 3: Set up the python code to run

Find Python's Library folder.  (It will most likely be something along the lines of C:\python24\Lib (which is what mine was).)  Copy the zymb and volity folders from your unzipping in the previous step into this folder.  I also copied the volityd.py loader file here as well.

Part 3b: Handle some windows-specific issues in the python code

If you're developing under windows, (as I am) a little patching is currently necessary, at least until a couple of changes propagate through the python volity framework.  This step will hopefully become optional very soon.

The first change is required is necessary because sockets, as I understand it, behave in a non-standard way on Windows compared to anywhere else in the known computing universe.  (Bill Gates, if you're reading this, it's all *your* fault!!)  To be specific, there is a Windows-specific error that has to be explicitly ignored.  To patch for this, open the tcp.py file in the Lib\zymb\ folder, and find line 129. 

It should say:

if (errnum == errno.EAGAIN)

You should change this to:

if (errnum == errno.EAGAIN or errnum == errno.WSAEWOULDBLOCK)

(Python is indentation-sensitive, so be sure that you leave the indentation as is when you do this.)

The other thing I had to do when setting up and testing was compensate for my python implementation's lack of an SSL module, and for that the volity code itself has to be patched.  There will be a command line switch in a future version of the framework files - because you wouldn't necessarily want to operate that way consistently, but if you need to boot volity for testing on a PC, you just plain need to get things running.  (Aside: I've gone looking for a canonical SSL module for python 2.4 for Windows and failed to find one - which is part of what delayed this post, BTW.  Successfully finding and setting up an SSL module for python 2.4 would also solve this second issue.)

The edit you'll need is on line 83 of volent.py in the code in the volity folder.  It should say:

        self.conn = jabber.client.JabberAuthResource(self.jid, self.password, host=host)

To unilaterally disable SSL (as was necessary to get the framework running for me), you would change this to:

        self.conn = jabber.client.JabberAuthResource(self.jid, self.password, host=host, secure=jabber.client.SECURE_NONE)
 
Once these issues are corrected in a future release - It was the framework's author that heard me out and suggested these changes, so you know they'll be in an upcoming update - no patching should be necessary.

Part 4: Get the Python stuff running

In this step, you test to ensure you can run the framework - and a sample game server - successfully.

What I did for testing purposes was to create a subfolder in the lib folder called games, and move the python files for whatever games I wanted to test into that folder so that python cound find them easily. Once I did that (and in combination with my previous setup steps), I could open a DOS window, change folders to the Lib folder (where I have everything set up) and type:

python volityd.py --jid [redacted]@volity.net --password [Redacted] --game games.rps.RPS

... where [redacted] replaces things that I don't want you to see.  :-)

You can also create a shortcut to do the same thing, as long as you ensure that python and volityd.py are both findable by Windows when it goes looking.  A well-behaved version of python handles this automatically for python; I set the folder to start in to where volityd.py was, and everything worked fine.

While I'm talking about all of this, I should mention that, until you start registering your referees (more on this later), you have to terminate instances of them running in python by navigating to their window and pressing ctrl-c.  This is very useful knowledge to have.  :-)

Part 5: Get the Java testench stuff working

Set up a shortcut to run testbench with the UI framework you wish to develop.

This is straightforward enough to be done in a shortcut also.  I used this for my shortcut's target:

C:\WINDOWS\system32\java.exe -jar Testbench.jar test.svg

Then I set the folder to start in to the location of the test svg file, and everything worked well.

Next steps:

Currently, referees are generally debug the most easily by getting the UI running first and testing in that way, although Volity's

maintainers have show in interest in getting something released that allows for direct debugging.  Until then, anyway, the next

step is to start iterative development of the UI and get it working.  I've already done a bit of that, and intend to do a bit more

of that soon.  Hopefully you'll be seeing some of the fruits of that labor in a new post next weekend.