In this document:

Important!

This code is not complete or tested. It has not been released as a finished product. It is not supported by the author, nor is the author liable for anything you may experience while using the code.

You should NOT run this code unless you have a reasonable knowledge of computer programming and internet servers. This is not finished software. It has no documentation. No user interface. There is no support. And it will produce unexplained errors.

You should NOT run this code on any mission-critical machine. It will cause excessive CPU usage at times. It probably leaks memory. It may cause the operating system to become unstable. It may expose you to additional security risks.

While all reasonable attempts have been made to secure the code against malicious attacks, it is conceivable that it might be hacked to expose the host's computer. (Theoretically a command sequence might be executed via the in-game robot which somehow runs as code in its own right, much like "; drop database" in a mySQL-powered webform - I simply haven't examined this in enough detail to ensure it isn't possible, although the most obvious exploits have been countered.)

Requirements

Parts of the script were originally intended to work with Hardwar UIM06 only (basic server maintenance and information, not detailed statistics), however I only ever extensively ran it using Smurph's Enhanced2 file. It is highly recommended you use the most recent Enhanced2 (earlier versions may fail due to a change in the way the REPORT function worked).

The script can be downloaded from http://www.capsu.org/hardwar/hs3/download.html.

Setup

The game, webserver and script are all assumed to run on the same machine. Hardwar must be installed and listed in the registry correctly. There are no specific checks on this - you will get meaningless errors about path "" not being found, and such like if the game isn't there. Only one game can be monitored per machine.

Copy the contents of html subdirectory to your webserver. The .css and .ico file should be left in the root (or whatever directory you intend to place the HS3 output). The images should be in a subdirectory called images.

Most settings are held in the registry, in HKEY_CURRENT_USER\Software\Refinery\hardman\Config\HS3. None of the code for editing these was ever written (although the script will create an entry using defaults when it finds none). So you should first run setup.reg, and then use regedit to make changes. Change at least:

Note that the passwords are not currently encrypted, so are exposed to any application on the machine. There are many different settings, which are explained by running py/_ini.py.

The Terminal Server port must be open on Hardwar (9001 by default). However, this value is not displayed on the web pages by default. It is recommended that you block access to the port from the internet via a firewall.

It is highly recommended that you let HS3 start a new game, rather than applying the script to an existing game. However, an existing game should work. If my reading of the code is correct, HS3 will always default to running and restarting the most recently saved game it finds in the main Hardwar directory. When it creates a new game, it will use the name default.sav. You can safely copy other game saves into subdirectories.

Running hs3.py (or hs3.py -m or hs3.py --monitor) will start the script monitoring the Hardwar server. This:

To add the in-game robot "H", you should run a second instance of the script, using hs3.py -b or hs3.py --bot. This can be started at any time, however to avoid accidentally creating duplicate Hs in the Hardwar game (some sort of bug related to pilot creation while the game is loading), it is best to wait until the game has started before launching the robot. This allows users to interact with H - see the user guide - http://www.capsu.org/hardwar/hs3/h_user_guide.html.

Two further text files, allow further information to be fed into the system:

Each pilot may be listed in special.txt as one or more of:

You may need to tweak your webserver to serve up .wml files (WAP output) correctly. For example, to configure Apache 2.x, you may need to add the following lines to httpd.conf:

AddType text/vnd.wap.wml wml
AddType image/vnd.wap.wbmp wbmp
AddType text/vnd.wap.wmlscript wmls
AddType application/vnd.wap.wmlc wmlc
AddType application/vnd.wap.wmlscriptc wmlsc

Brief Code Overview

Firstly, to anyone that isn't familiar with Python - there are no bracers - these are achieved using tabbed indents. The .py files are viewable in any text editor, and are self-compiling when run. Most classes and functions are documented using """text""" at the top of each section - Python can be used to process all this information.

Unlike the language, my organisation and implementation of it is not easy to follow. I started to break code into modules (the "py" directory) but didn't get very far. Everything else is in hs3.py. Most of the main components are in classes, although take care, because some classes reference functions within other classes. XML is read via parser classes, which aren't quite as easy to follow. The use of XML may seem curious now - it is slow given the volume of data, and its processing causes CPU spikes. However, when I first started writing the code, the amount of data collected was minimal, and a proper database backend seemed excessive. The most confusing parts are the telnet code (I don't fully understand telnet) and server restarting code (I don't fully understand computer process behaviour).

The most manic is the code for the robot H, which needs a complete re-write into a more structured form - it started as a few lines and endlessly had functions added. Since H can't respond to names with spaces in them (Hardwar Terminal Server flaw), this part fo the code was largely ignored. H occupies a separate process because the code isn't currently multi-threaded - it can only do one thing at a time. Indeed, I think H itself is still prone to failure when commands are sent in the few milliseconds that it is processing information and not listening for commands.

I'd love to be able to explain this in detail, but it has been a year since I last looked at it, and parts didn't make much sense then. If you can get any value out of it, then feel free to alter, modify or distribute it as part of another application. If you use a substantial part of it, you should provide adequate credit. If you do distribute any of the code, you must accept liability for any errors within it.

Tim ("timski") Howgego
http://www.capsu.org/hardwar/hs3/
29 July 2006