UGH stats

UGH stats is a stats collector system for Unreal one. I have kicked this project off after public demand and offer the full source as freeware. It is up to other people to make use of the stats or to ask what other stats they want collected. There are limits, and I do not intend to update or work on this project very often.

UGH stats consists of 2 programs.

1. A UScript mutator that collects stats and sends them over TCP/IP to a listening stats server
2. A listening stats server, this can be any self-written program that can parse GameSpyProtocol messages using TCP/IP

The UScript mutator sends its data load at the end of every match. The stats server takes them and whatever it wants with them. The UScript mutator must be installed on all server that want stats evaluated, the listening server only needs to be installed on ONE machine somewhere in the world! You don't need one listening server per Unreal server.

For demonstration purposes and because I am such a nice person, I have written a small java program as a listening server that creates logfiles out of the received data streams. This simple server can run on any java-capable machine and can handle an infinite number of attached Unreal servers.

UScript mutator

Any Unreal/UT that runs UTeamFix 10C or newer.

Why only UTF 10C and newer? What if I want to run EDM!

Short answer: I don't care, you get all this for free so don't complain!

Long answer:
I know that some people prefer one over the other, although what many people have continuously failed to realize is, that EDM and UTF are not competing to one another. As a matter of fact there is EDM code in UTF and there are also UTF code parts in EDM. WOW surprised?

The 2 things you should understand are, that first off, EDM and UTF have different goals in their original design. That was also why the mods could not be merged. The 2nd, and much more important fact to note is, that the original Unreal base classes are so flawed and limited in their abilities, that it would take very bad programming approaches and a lot of effort to make it work without UTF 10. Both EDM and UTF have so far improved the engine with many more basic features that it would be a shame to throw these features away.

I'm pretty sure Smartball could write an equal mutator for EDM with ease, but if you ask him if he'd do it, you would probably get the same reply as his away message on AIM... and who could blame him :P

Listening Server

The listening server can be any standalone server program that was written to parse GameSpyProtocol type messages over TCP/IP.

For ease of getting started, I provide one simple java server called "netecho". It requires a java virtual machine to run and write access to the directory it runs in. netecho will put all the data it receives into text logfiles, in pretty much the same way it receives them from a server. These logfiles can be parsed by scripts etc...

It would be possible to not write any logfiles at all but to take the data and put it in a database right away. You can write your own listening server in whatever programming language you desire to do the task.

Why even bother with writing logfiles with a java program? Well, Unreal can write logfiles too, but they are always UNICODE and appending is not possible. With an outside program, you are free to program whatever you want whereas Unreal has its limits. Thus, the interface on the UScript side was to be made as simple and as versatile as possible. That's exactly the result. The mutator transmits its data, what you do with it then, is entirely up to you!

The UScript and the listening servers were designed for simplicity and efficiency - not security. You are strongly advised to strictly firewall filter the port you run the listening server on and explicitely allow ONLY those IPs to contact it of which you know exactly Unreal servers are running at.

Installing the mutator

Put the files UGH.int and UGH.u into your Unreal servers' system diretctory/ies - make as many copies as you have system directories from which you have servers running. Do NOT add UGH to server packages!

Installing the listening server (netecho)

If you write your own serverprogram, you will know yourself what todo to run it, so this section will deal with the cheap netecho java server.

Running the mutator

Start your Unreal server with the additional mutator UGH.UGHstats.

Example (one mutator):
Unreal.exe DMElsinore?Game=UTeamFix.TeamGameFix?mutator=UGH.UGHstats -server log=server.log

Remember that if you already run another mutator, just add the new mutator with a comma separated, for example:
Unreal.exe DMElsinore?Game=UTeamFix.TeamGameFix?mutator=UTFmut_jbpfatboy.jbpfatboy,UGH.UGHstats -server log=server.log

Running netecho

Assuming you have only netecho at your disposal (*cough*) here is how to run it.

Make sure your java CLASSPATH includes the current directory - that would be the dot
.
- otherwise you will get a class not found error when trying to run it. I added a small batch file called cp.bat for Windows machines, which you can execute to TEMPORARILY add the current directory to the class path. If you use it you will have to re-use it every time you open a new DOS-box to run netecho. It's better to permanently add the dot to your classpath using the computer environment settings.

If, when trying to start netecho, you get a java.lang.UnsupportedClassVersionError error, this means that your java virtual machine is older than the compiled code was created for. You can try to recompile the sources using the command javac netecho.java to get executable binaries for your virtual machine then. If this does not help, get a newer java virtual machine from the sun site!

Go to your console, or a command prompt, get yourself into the directory where you unzipped all the netecho files into, and start the program with the following parameters indicated in [brackets]:
java netecho [port] [delim] [delimreplacement] [serverdatakey] [mapdatakey]

Replace everything inside [brackets] with meaningful values, only the last 2 are optional, here is what all the parameters mean:

port: is the network port the program will listen for incoming connections.
delim: is the data/key delimeter (or separator) character which separates a key (identifier) from its value (GameSpy uses the backslash btw). What you put here will be used in the logfiles netecho creates.
delimreplacement: should the data contain any [delim] characters, of course this would screw up the data evaluation. So, the program will replace any [delim] characters found inside data with the character you want.
serverdatakey: OPTIONAL, defaults to shortname - this is which data netecho looks for as part of the filename for logfiles (see below...)
mapdatakey: OPTIONAL, defaults to mapname - another piece of data netecho looks for in the datastream to make up the log filename (see below...)

Netecho's procedure

I will now show an example session of netecho. Assuming it and java was installed properly... This is how your command prompt could look like after 2 maps have run on your unreal server...

In this example, I have run the netecho using the comma as key/data separator (delimeter) and the dot (.) as replacement should the data contain any accidental commas. I have played for 2 maps on my server, maps being Healpod and Burak, note that the filename here contains the real map filename, not the mapname, because I also used mapfilename as data key instead of the default mapname.

UGHstats UScript mutator

The settings of the UScript mutator can be found here:

Build 1 (March 2006)

1. Initial release...

Build 2 (2006-08-07)

1. UGHlink now has trim() function and isWhiteSpaceFunction
2. trim() used on ping data, this cleans away spaces around the data

Build 3 (2006-08-25)

1. bugfix: UGHlink class was not properly checking for specs (reported by Smartball)